chickadee » xmkit

xmkit

Description

The xmkit egg provides a toolbox for extracting information from eXtended Module (XM) files.

Requirements

Those wishing to build the documentation files locally will need scm2wiki, and optionally manual-labor.

Documentation

General Notes

xmkit preserves some quirks of XM terminology when it comes to indices. Specifically, indices for pattern tracks and instruments start at 1, whereas everything else uses 0-based indexing.

The order list, pattern list, or song structure is called sequence in xmkit.

Type Predicates

xm:module? xprocedure
xm:pattern? xprocedure
xm:instrument? xprocedure
xm:sample? xprocedure
xm:is-valid-xm-file? filenameprocedure

Determines whether the given file is a well-formed eXtended Module, by validating the header and performing integrity checks.

xm:u8vector->module u8vprocedure

Constructs an xm:module record from a u8vector.

xm:file->module filenameprocedure

Construct an xm:module record from an .xm file

xm:module-name xmprocedure

Returns the module name.

xm:tracker-name xmprocedure

Returns the tracker identifier string.

xm:song-length xmprocedure

Returns the song (sequence) length.

xm:restart-position xmprocedure

Returns the restart position.

xm:number-of-tracks xmprocedure

Returns the number of tracks (channels).

xm:number-of-patterns xmprocedure

Returns the number of patterns.

xm:number-of-instruments xmprocedure

Returns the number of instruments.

xm:use-linear-frequency-table? xmprocedure

Check whether the module uses linear or Amiga frequencies. Returns true if using a linear table.

xm:default-tempo xmprocedure

Returns the default tempo.

xm:default-bpm xmprocedure

Returns the default BPM.

xm:sequence xmprocedure

Returns the sequence (order list) as a list.

xm:sequence-ref xm posprocedure

Returns the position pos in the sequence of xm.

xm:pattern-used? xm patternprocedure

Check if the given pattern is used in xm. A pattern is considered used if it is linked in the sequence at least once.

xm:patterns xmprocedure

Extract the module's patterns. Returns a list of xm:pattern records.

xm:pattern-length patternprocedure

Returns the number of rows in the given pattern. Accepts either a raw pattern (xm:data) or unpacked pattern as input.

xm:pattern-rows patternprocedure

unpack the given pattern into a list of rows, where each row is a list containing values for note, instrument, volume, fx command, and fx param

xm:pattern-tracks patternprocedure

unpack the given pattern into a list of tracks, where each track is a list of rows containing note, instrument, volume, fx command, and fx parameter values

xm:pattern-notes patternprocedure

Return the note values of the given pattern, sorted in rows.

xm:pattern-instruments patternprocedure

Return the instrument values of the given pattern, sorted in rows.

xm:pattern-volumes patternprocedure

Return the volume values of the given pattern, sorted in rows.

xm:pattern-volumes-normalized patternprocedure

Return the volume values of the given pattern, sorted in rows. Volumes are normalized to the 0..#x40 range, and volume effects are discarded.

xm:pattern-volume-fx pattern #!rest effectsprocedure

Return the volume effects in the given pattern, sorted in rows. Optionally, the output can be filtered to include only the given effects. effects can be any combination of '+x, '-x', Dx', Lx', 'Mx, 'Px, 'Rx, 'Sx, 'Ux, and 'Vx.

xm:pattern-fx pattern #!rest effectsprocedure

Return the effect command/parameter value pairs in the given pattern. The output can optionally be filtered to return only the given effects. For example,

(xm:pattern-track-fx my-xm 0 1 '1xx '2xx '3xx)

will only return portamento effects. All common effects (0xx, 1xx, .. Fxx) are supported, as well as the extended effects (E0x, E1x, .. EFx), and the fine portamento effects (X1x, X2x).

xm:pattern-fx-cmds pattern #!rest effectsprocedure

Return the effect command values of the given pattern, sorted in rows. Optionally, the output can be filtered to only include the given effects. See xm:pattern-fx for details.

xm:pattern-fx-params pattern #!rest effectsprocedure

Return the effect parameters of the given pattern, sorted in rows. Optionally, the output can be filtered to only include the parameters of the given effects. For extended and fine porta effects, the effect subcommand is included in the output. See xm:pattern-fx for details.

xm:pattern-row-ref pattern iprocedure

Get row i of the given pattern as a nested list of track values.

xm:pattern-track-ref pattern iprocedure

Return track i of the pattern as a nested list of values. Note that track indices are 1-based, in line with XM terminology.

xm:pattern-track-notes pattern iprocedure

Extract the note column of track i in the given pattern.

xm:pattern-track-instruments pattern iprocedure

Extract the instrument column of track i in the given pattern.

xm:pattern-track-volumes pattern iprocedure

Extract the volume column of track i in the given pattern.

xm:pattern-track-volumes-normalized pattern iprocedure

Extract the volume column of track i in the given pattern, and normalize volumes to the 0..#x40 range, omitting volume column fx.

xm:pattern-track-volume-fx pattern i #!rest effectsprocedure

Extract the volume effects of track i in the given pattern. The output can optionally be filtered to return only the given effects. See xm:pattern-volume-fx for details.

xm:pattern-track-fx pattern i #!rest effectsprocedure

Extract the effect command/parameter columns of track i in the given pattern. The output can optionally be filtered to return only the given effects. See xm:pattern-fx for details.

xm:pattern-track-fx-cmds pattern i #!rest effectsprocedure

Extract the effect command column of the given track i in the given pattern. The output can optionally be filtered to return on the effects. See xm:pattern-fx for details.

xm:pattern-track-fx-params pattern i #!rest effectsprocedure

Extract the effect paramter column of track i in the given pattern. The output can optionally be filtered to return only the parameters of the given effects. For extended/fine porta effects, the effect subcommand is inlcuded in the output. See xm:pattern-fx for details.

These procedures will generally return 0 or null if the given instrument has no samples.

xm:instrument-name instrprocedure

Returns the instrument name.

xm:instrument-number-of-samples instrprocedure

Returns the number of samples in the given instrument.

xm:instrument-has-samples? instrprocedure

Returns #t if the given instrument contains samples, else #f.

xm:instrument-sample-map instrprocedure

Sample to note mapping for all notes. Returns a list.

xm:instrument-volume-env-length instrprocedure

Returns the length of the volume envelope.

xm:instrument-volume-envelope instrprocedure

Returns the volume envelope as a list of offset/value pairs.

xm:instrument-volume-sustain-point instrprocedure

Returns the volume envelope sustain point.

xm:instrument-volume-loop-start instrprocedure

Returns the volume envelope loop start point.

xm:instrument-volume-loop-end instrprocedure

Returns the volume envelope loop end point.

xm:instrument-volume-type instrprocedure

Returns the volume envelope configuration byte.

xm:instrument-volume-env-on? instrprocedure

Returns #t if the volume envelope is enabled.

xm:instrument-volume-env-sustain? instrprocedure

Returns #t if volume envelope sustain is enabled.

xm:instrument-volume-env-loop? instrprocedure

Returns #t if volume envelope looping is enabled.

xm:instrument-volume-fadeout instrprocedure

Returns the instrument volume fadeout setting.

xm:instrument-panning-env-length instrprocedure

Returns the length of the panning envelope.

xm:instrument-panning-envelope instrprocedure

Returns the panning envelope as a list of offset/value pairs.

xm:instrument-panning-sustain-point instrprocedure

Returns the panning envelope sustain point.

xm:instrument-panning-loop-start instrprocedure

Returns the panning envelope loop start point.

xm:instrument-panning-loop-end instrprocedure

Returns the panning envelope loop end point.

xm:instrument-panning-type instrprocedure

Returns the panning envelope configuration byte.

xm:instrument-panning-env-on? instrprocedure

Returns #t if the panning envelope is enabled.

xm:instrument-panning-env-sustain? instrprocedure

Returns #t if panning envelope sustain is enabled.

xm:instrument-panning-env-loop? instrprocedure

Returns #t if panning envelope looping is enabled.

xm:instrument-vibrato-sine? instrprocedure

Returns #t if using sine waveform vibrato

xm:instrument-vibrato-square? instrprocedure

Returns #t if using square waveform vibrato

xm:instrument-vibrato-saw? instrprocedure

Returns #t if using saw waveform vibrato

xm:instrument-vibrato-inverse-saw? instrprocedure

Returns #t if using inverse saw waveform vibrato

xm:instrument-vibrato-depth instrprocedure

Returns the instrument vibrato depth.

xm:instrument-vibrato-rate instrprocedure

Returns the instrument vibrato rate.

xm:instrument-vibrato-sweep instrprocedure

Returns the instrument vibrato sweep setting.

xm:instruments xmprocedure

Returns a list of raw instrument data blocks

xm:instrument-ref xm iprocedure

Returns the instrument at the given index i. This uses 1-based indexing, in line with the way indexing is done in XM.

xm:instrument-sample-ref xm instr smpprocedure

Returns the sample at index smp of the instrument at index instr. instr uses 1-based indexing, in line with the way indexing is done in XM.

xm:sample-length sampleprocedure

Returns the number of sample points, not the number of bytes.

xm:sample-name sampleprocedure

Returns the sample name.

xm:sample-loop-start sampleprocedure

Returns the sample loop start position.

xm:sample-loop-length sampleprocedure

Returns the sample loop length.

xm:sample-loop-type sampleprocedure

Returns the sample loop type byte.

xm:sample-loop-enabled? sampleprocedure

Returns #t if sample looping is enabled.

xm:sample-loop-forward? sampleprocedure

Returns #t if using forward type looping. Correctly handles "invalid" flag settings produced by MPT 1.09.

xm:sample-loop-ping-pong? sampleprocedure

Returns #t if using ping-pong type looping.

xm:sample-16bit-data? sampleprocedure

Returns #t if the sample data uses 16-bit values.

xm:sample-volume sampleprocedure

Returns the volume setting.

xm:sample-finetune sampleprocedure

Returns the finetune setting.

xm:sample-panning sampleprocedure

Returns the panning position.

xm:sample-relative-note sampleprocedure

Returns the relative note setting.

xm:samples instrprocedure

Returns a list of the given instrument's samples, preserving the original order.

xm:sample-ref instr iprocedure

Returns the sample at index i. This uses 1-based indexing, in line with the way indexing is done in XM.

xm:sample->dpcm sampleprocedure

Retrieves the raw XM sample data in internal DPCM format.

xm:sample->pcm sampleprocedure

Retrieves the internal sample data and convert it to standard RAW PCM.

xm:export-sample sample filenameprocedure

Extract the sample data of given sample and export as a little-endian, signed, mono PCM RAW file with 8-bit or 16-bit data depending on input sample data type.

Examples

Extract the notes of pattern 1 to a list of rows

(xm:pattern-notes (xm:pattern-ref (xm:file->module "myxm.xm") 1))

Export sample 0 in instrument 2 to a RAW PCM file

(xm:export-sample (xm:instrument-sample-ref (xm:file->module "myxm.xm")
                                            2 0)
                  "my-sample.raw")

Author

(c) 2019 Michael Neidel

License

MIT

Version History

Contents »