Module

NAME

OpenMPT::Bindings::Module - OOP wrapper around libopenmpt module handles

SYNOPSIS


use OpenMPT::Bindings::Module;
use OpenMPT::Bindings::Types;

my $mod = OpenMPT::Bindings::Module.from-file('track.xm');
say $mod.title;
say $mod.duration;

# Get 16-bit signed interleaved stereo — pipe straight to aplay
my ($frames, $blob) = $mod.read-interleaved-stereo(48000, 1024);

# Or get separate left/right float blobs
my ($count, $left, $right) = $mod.read-float-stereo(48000, 512);

$mod.set-position(30);

# Use CTL type dispatch
say $mod.get-ctl('play.tempo_factor', :type(Numeric));

# Library class methods
say OpenMPT::Bindings::Module.library-version;
my $result = OpenMPT::Bindings::Module.probe-file-header($data, $data.bytes);

DESCRIPTION

Wraps the opaque openmpt_module* handle from libopenmpt. Provides methods for loading tracker modules, rendering PCM audio (stereo, mono, quad, interleaved, CArray and Blob variants), querying metadata, controlling playback, managing CTL parameters, and probing file headers. Library-level class methods give access to version info and supported extensions.

ATTRIBUTES

handle

has Pointer[void] $.handle;

The raw openmpt_module* pointer.

data

has Blob $.data;

The original file data loaded from disk or passed to from-blob. Libopenmpt copies the data internally; this is kept for convenience.

CONSTRUCTION

from-blob

method from-blob(Blob $data, :%ctls --> ::?CLASS)

Create a module from an in-memory Blob of module data. Optional %ctls hash of initial CTL parameters.

from-file

method from-file(Str $path, :%ctls --> ::?CLASS)

Read a file from disk and create a module from its contents.

LIBRARY CLASS METHODS

These are called on the class, not on an instance:

method library-version(--> uint32)
    method core-version(--> uint32)
    method library-string(Str $key --> Str)
    method supported-extensions(--> List)
    method is-extension-supported(Str $extension --> Bool)
    method probe-file-header-get-recommended-size(--> Int)
    method probe-file-header(Blob $data, uint64 $filesize, uint64 $flags = OPENMPT_PROBE_FILE_HEADER_FLAGS_DEFAULT --> OpenMPTProbeResult)
    method probe-file-header-without-filesize(Blob $data, uint64 $flags = OPENMPT_PROBE_FILE_HEADER_FLAGS_DEFAULT --> OpenMPTProbeResult)

library-version and core-version return the libopenmpt version as a packed uint32 (major << 24 | minor << 16 | patch). library-string returns e.g. the URL or version string. supported-extensions returns a list of file extensions libopenmpt can handle. probe-file-header checks whether raw bytes look like a supported module format — returns an OpenMPTProbeResult enum value.

DESTRUCTION

The module handle is freed automatically when the object is garbage-collected via DESTROY.

AUDIO RENDERING

All render methods return a List where the first element is the count of frames actually produced, followed by the buffer(s). The caller is responsible for checking that the returned count matches the requested frame count (the buffer may contain silent padding at end of song).

Note: Standard render methods allocate a new Blob on every call (alloc + memcpy). For performance-sensitive hot paths, use the raw pointer variants (/Low-overhead rendering (raw pointer variants)) instead to avoid allocation entirely.

Note: Module instances share internal render buffers between method calls. Concurrent read-* or write-* calls from multiple threads on the same instance will race on these buffers and produce undefined output. Use separate Module instances per thread for concurrent rendering.

read-float-stereo

method read-float-stereo(int32 $rate = 48000, size_t $frames = 1024 --> List)

Returns ($count, $left, $right) as Blob of F32_LE bytes ($count × 4 bytes each channel).

read-interleaved-float-stereo

method read-interleaved-float-stereo(int32 $rate = 48000, size_t $frames = 1024 --> List)

Returns ($count, $buf) where $buf is a Blob of interleaved F32_LE L/R samples ($count × 8 bytes).

read-float-mono

method read-float-mono(int32 $rate = 48000, size_t $frames = 1024 --> List)

Returns ($count, $buf) of float mono samples as Blob (F32_LE, $count × 4 bytes).

read-stereo

method read-stereo(int32 $rate = 48000, size_t $frames = 1024 --> List)

Returns ($count, $left, $right) as Blob of S16_LE bytes ($count × 2 bytes each channel).

read-interleaved-stereo

method read-interleaved-stereo(int32 $rate = 48000, size_t $frames = 1024 --> List)

Returns ($count, $buf) where $buf is a Blob of interleaved S16_LE L/R samples ($count × 4 bytes). This is the most convenient format for piping to aplay(1) or writing WAV data.

read-mono

method read-mono(int32 $rate = 48000, size_t $frames = 1024 --> List)

Returns ($count, $buf) of int16 mono samples as Blob (S16_LE, $count × 2 bytes).

write-interleaved-stereo-s16-to-handle

method write-interleaved-stereo-s16-to-handle(IO::Handle $fh, int32 $rate = 48000, size_t $frames = 1024 --> Int)

Writes interleaved stereo S16_LE frames directly to $fh and returns the frame count. Avoids an intermediate Blob allocation; prefer this over read-interleaved-stereo + $fh.write in hot paths.

Low-overhead rendering (raw pointer variants)

method read-interleaved-stereo-raw(int32 $rate = 48000, size_t $frames = 1024 --> List)
    method read-interleaved-float-stereo-raw(int32 $rate = 48000, size_t $frames = 1024 --> List)

These return a Pointer[void] into an internal pre-allocated buffer instead of allocating a new Blob on every call. Returns ($count, Pointer[void], $bytes). The pointer is valid only until the next render call on the same module.

Quad rendering — float

method read-float-quad(int32 $rate = 48000, size_t $frames = 1024 --> List)
    method read-interleaved-float-quad(int32 $rate = 48000, size_t $frames = 1024 --> List)

read-float-quad returns ($count, $fl, $fr, $rl, $rr) as Blob of F32_LE bytes ($count × 4 bytes each channel).

Quad rendering — int16

method read-quad(int32 $rate = 48000, size_t $frames = 1024 --> List)
    method read-interleaved-quad(int32 $rate = 48000, size_t $frames = 1024 --> List)

Same layout as the float quad variants but with S16_LE Blob bytes ($count × 2 bytes each channel).

METADATA

get-metadata

method get-metadata(Str $key --> Str)

Returns the metadata value for $key, or Str (type object / undef) if the key is not present. Common keys: title, artist, type, type_long, message, tracker, date, warnings, originaltype, originaltype_long, container, container_long.

title, artist, type, module-message, tracker, date, warnings, type-long, originaltype

Shorthand accessors for common metadata keys.

method title(   --> Str)
    method artist(  --> Str)
    method type(    --> Str)
    method module-message( --> Str)
    method tracker( --> Str)
    method date(    --> Str)
    method warnings-str(--> Str)
    method type-long(    --> Str)
    method originaltype( --> Str)

metadata-keys

method metadata-keys(--> List)

Returns a list of all available metadata key strings for this module.

MODULE INFORMATION

Counts

method num-subsongs(    --> Int)
    method num-channels(    --> Int)
    method num-orders(      --> Int)
    method num-patterns(    --> Int)
    method num-instruments( --> Int)
    method num-samples(     --> Int)
    method restart-order(Int $subsong --> Int)
    method restart-row(Int $subsong   --> Int)

Names

method subsong-name(Int $idx    --> Str)
    method channel-name(Int $idx   --> Str)
    method order-name(Int $idx     --> Str)
    method pattern-name(Int $idx   --> Str)
    method instrument-name(Int $idx --> Str)
    method sample-name(Int $idx    --> Str)

Pattern / Order Access

method order-pattern(Int $order --> Int)
    method is-order-skip(Int $order --> Bool)
    method is-order-stop(Int $order --> Bool)
    method is-pattern-skip(Int $pat --> Bool)
    method is-pattern-stop(Int $pat --> Bool)
    method pattern-num-rows(Int $pat --> Int)
    method pattern-rows-per-beat(Int $pat --> Int)
    method pattern-rows-per-measure(Int $pat --> Int)
    method get-pattern-cell(Int $pat, Int $row, Int $ch, Int $cmd --> Int)
    method format-pattern-cell(Int $pat, Int $row, Int $ch, Int $cmd --> Str)
    method highlight-pattern-cell(Int $pat, Int $row, Int $ch, Int $cmd --> Str)
    method format-pattern-row(Int $pat, Int $row, Int $ch, size_t $width, Int $pad --> Str)
    method highlight-pattern-row(Int $pat, Int $row, Int $ch, size_t $width, Int $pad --> Str)

Use OpenMPTCommandIndex enum values for $cmd: OPENMPT_MODULE_COMMAND_NOTE, OPENMPT_MODULE_COMMAND_INSTRUMENT, OPENMPT_MODULE_COMMAND_VOLUMEEFFECT, OPENMPT_MODULE_COMMAND_EFFECT, OPENMPT_MODULE_COMMAND_VOLUME, OPENMPT_MODULE_COMMAND_PARAMETER.

PLAYBACK CONTROL

select-subsong

method select-subsong(Int $idx --> Bool)

Select a subsong by index. Dies with X::OpenMPT::Bindings on failure.

subsong

method subsong(--> Int)

Returns the currently selected subsong index.

set-repeat-count

method set-repeat-count(Int $n --> Bool)

Set repeat count. -1 loops forever, 0 plays once, 1 plays twice, etc. Dies with X::OpenMPT::Bindings on failure.

repeat-count

method repeat-count(--> Int)

Returns the current repeat count.

POSITION / DURATION

duration

method duration(--> Num)

Total duration in seconds.

position

method position(--> Num)

Current playback position in seconds.

set-position

method set-position(Numeric $sec --> Num)

Seek to a given time in seconds. Returns the new actual position.

set-position-order-row

method set-position-order-row(Int $order, Int $row --> Num)

Seek to a specific pattern order and row. Returns the new position in seconds.

time-at-position

method time-at-position(Int $order, Int $row --> Num)

Returns the time in seconds at the given pattern order and row.

RENDER PARAMETERS

mastergain

method mastergain(--> Int)

Returns the master gain in millibel.

set-mastergain

method set-mastergain(Int $val --> Bool)

Set master gain in millibel. Dies with X::OpenMPT::Bindings on failure.

stereo-separation

method stereo-separation(--> Int)

Returns stereo separation as a percentage.

set-stereo-separation

method set-stereo-separation(Int $val --> Bool)

Set stereo separation percentage. Dies with X::OpenMPT::Bindings on failure.

interpolation-filter-length

method interpolation-filter-length(--> Int)

Returns the interpolation filter length.

set-interpolation-filter-length

method set-interpolation-filter-length(Int $val --> Bool)

volume-ramping-strength

method volume-ramping-strength(--> Int)

Returns the volume ramping strength. A value of -1 means the libopenmpt default.

set-volume-ramping-strength

method set-volume-ramping-strength(Int $val --> Bool)

PLAYBACK STATUS

method current-bpm(               --> Num)
    method current-speed(             --> Int)
    method current-tempo(             --> Num)
    method current-order(             --> Int)
    method current-pattern(           --> Int)
    method current-row(               --> Int)
    method current-playing-channels(  --> Int)
    method current-sequence(          --> Int)   # requires libopenmpt 0.9+
    method current-channel-vu-mono(Int $ch        --> Numeric)
    method current-channel-vu-left(Int $ch        --> Numeric)
    method current-channel-vu-right(Int $ch       --> Numeric)
    method current-channel-vu-rear-left(Int $ch   --> Numeric)
    method current-channel-vu-rear-right(Int $ch  --> Numeric)

CTL INTERFACE

get-ctl

method get-ctl(Str $key, :$type = Str --> Any)

Get a CTL value. $type controls the return type:

Bool — returns Bool
Int — returns Int
Numeric — returns Numeric (floating-point)
Str (default) — returns Str (text)

set-ctl

method set-ctl(Str $key, $value --> Bool)

Set a CTL value. $value is dispatched by its Raku type:

Bool — calls ctl_set_boolean
Int — calls ctl_set_integer
Numeric — calls ctl_set_floatingpoint
Str — calls ctl_set_text

ctl-keys

method ctl-keys(--> List)

Returns a list of all supported CTL key strings for this module.