Outdated egg!
This is an egg for CHICKEN 4, the unsupported old release. You're almost certainly looking for the CHICKEN 5 version of this egg, if it exists.
If it does not exist, there may be equivalent functionality provided by another egg; have a look at the egg index. Otherwise, please consider porting this egg to the current version of CHICKEN.
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
[procedure] (xm:module? x)[procedure] (xm:pattern? x)
[procedure] (xm:instrument? x)
[procedure] (xm:sample? x)
Module Related Procedures
[procedure] (xm:is-valid-xm-file? filename)Determines whether the given file is a well-formed eXtended Module, by validating the header and performing integrity checks.
[procedure] (xm:u8vector->module u8v)Constructs an xm:module record from a u8vector.
[procedure] (xm:file->module filename)Construct an xm:module record from an .xm file
[procedure] (xm:module-name xm)Returns the module name.
[procedure] (xm:tracker-name xm)Returns the tracker identifier string.
[procedure] (xm:song-length xm)Returns the song (sequence) length.
[procedure] (xm:restart-position xm)Returns the restart position.
[procedure] (xm:number-of-tracks xm)Returns the number of tracks (channels).
[procedure] (xm:number-of-patterns xm)Returns the number of patterns.
[procedure] (xm:number-of-instruments xm)Returns the number of instruments.
[procedure] (xm:use-linear-frequency-table? xm)Check whether the module uses linear or Amiga frequencies. Returns true if using a linear table.
[procedure] (xm:default-tempo xm)Returns the default tempo.
[procedure] (xm:default-bpm xm)Returns the default BPM.
[procedure] (xm:sequence xm)Returns the sequence (order list) as a list.
[procedure] (xm:sequence-ref xm pos)Returns the position pos in the sequence of xm.
[procedure] (xm:pattern-used? xm pattern)Check if the given pattern is used in xm. A pattern is considered used if it is linked in the sequence at least once.
Pattern Related Procedures
[procedure] (xm:patterns xm)Extract the module's patterns. Returns a list of xm:pattern records.
[procedure] (xm:pattern-length pattern)Returns the number of rows in the given pattern. Accepts either a raw pattern (xm:data) or unpacked pattern as input.
[procedure] (xm:pattern-rows pattern)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
[procedure] (xm:pattern-tracks pattern)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
[procedure] (xm:pattern-notes pattern)Return the note values of the given pattern, sorted in rows.
[procedure] (xm:pattern-instruments pattern)Return the instrument values of the given pattern, sorted in rows.
[procedure] (xm:pattern-volumes pattern)Return the volume values of the given pattern, sorted in rows.
[procedure] (xm:pattern-volumes-normalized pattern)Return the volume values of the given pattern, sorted in rows. Volumes are normalized to the 0..#x40 range, and volume effects are discarded.
[procedure] (xm:pattern-volume-fx pattern . effects)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.
[procedure] (xm:pattern-fx pattern . effects)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).
[procedure] (xm:pattern-fx-cmds pattern . effects)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.
[procedure] (xm:pattern-fx-params pattern . effects)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.
[procedure] (xm:pattern-row-ref pattern i)Get row i of the given pattern as a nested list of track values.
[procedure] (xm:pattern-track-ref pattern i)Return track i of the pattern as a nested list of values. Note that track indices are 1-based, in line with XM terminology.
[procedure] (xm:pattern-track-notes pattern i)Extract the note column of track i in the given pattern.
[procedure] (xm:pattern-track-instruments pattern i)Extract the instrument column of track i in the given pattern.
[procedure] (xm:pattern-track-volumes pattern i)Extract the volume column of track i in the given pattern.
[procedure] (xm:pattern-track-volumes-normalized pattern i)Extract the volume column of track i in the given pattern, and normalize volumes to the 0..#x40 range, omitting volume column fx.
[procedure] (xm:pattern-track-volume-fx pattern i . effects)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.
[procedure] (xm:pattern-track-fx pattern i . effects)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.
[procedure] (xm:pattern-track-fx-cmds pattern i . effects)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.
[procedure] (xm:pattern-track-fx-params pattern i . effects)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.
Instrument Related Procedures
These procedures will generally return 0 or null if the given instrument has no samples.
[procedure] (xm:instrument-name instr)Returns the instrument name.
[procedure] (xm:instrument-number-of-samples instr)Returns the number of samples in the given instrument.
[procedure] (xm:instrument-has-samples? instr)Returns #t if the given instrument contains samples, else #f.
[procedure] (xm:instrument-sample-map instr)Sample to note mapping for all notes. Returns a list.
[procedure] (xm:instrument-volume-env-length instr)Returns the length of the volume envelope.
[procedure] (xm:instrument-volume-envelope instr)Returns the volume envelope as a list of offset/value pairs.
[procedure] (xm:instrument-volume-sustain-point instr)Returns the volume envelope sustain point.
[procedure] (xm:instrument-volume-loop-start instr)Returns the volume envelope loop start point.
[procedure] (xm:instrument-volume-loop-end instr)Returns the volume envelope loop end point.
[procedure] (xm:instrument-volume-type instr)Returns the volume envelope configuration byte.
[procedure] (xm:instrument-volume-env-on? instr)Returns #t if the volume envelope is enabled.
[procedure] (xm:instrument-volume-env-sustain? instr)Returns #t if volume envelope sustain is enabled.
[procedure] (xm:instrument-volume-env-loop? instr)Returns #t if volume envelope looping is enabled.
[procedure] (xm:instrument-volume-fadeout instr)Returns the instrument volume fadeout setting.
[procedure] (xm:instrument-panning-env-length instr)Returns the length of the panning envelope.
[procedure] (xm:instrument-panning-envelope instr)Returns the panning envelope as a list of offset/value pairs.
[procedure] (xm:instrument-panning-sustain-point instr)Returns the panning envelope sustain point.
[procedure] (xm:instrument-panning-loop-start instr)Returns the panning envelope loop start point.
[procedure] (xm:instrument-panning-loop-end instr)Returns the panning envelope loop end point.
[procedure] (xm:instrument-panning-type instr)Returns the panning envelope configuration byte.
[procedure] (xm:instrument-panning-env-on? instr)Returns #t if the panning envelope is enabled.
[procedure] (xm:instrument-panning-env-sustain? instr)Returns #t if panning envelope sustain is enabled.
[procedure] (xm:instrument-panning-env-loop? instr)Returns #t if panning envelope looping is enabled.
[procedure] (xm:instrument-vibrato-sine? instr)Returns #t if using sine waveform vibrato
[procedure] (xm:instrument-vibrato-square? instr)Returns #t if using square waveform vibrato
[procedure] (xm:instrument-vibrato-saw? instr)Returns #t if using saw waveform vibrato
[procedure] (xm:instrument-vibrato-inverse-saw? instr)Returns #t if using inverse saw waveform vibrato
[procedure] (xm:instrument-vibrato-depth instr)Returns the instrument vibrato depth.
[procedure] (xm:instrument-vibrato-rate instr)Returns the instrument vibrato rate.
[procedure] (xm:instrument-vibrato-sweep instr)Returns the instrument vibrato sweep setting.
[procedure] (xm:instruments xm)Returns a list of raw instrument data blocks
[procedure] (xm:instrument-ref xm i)Returns the instrument at the given index i. This uses 1-based indexing, in line with the way indexing is done in XM.
Sample Related Procedures
[procedure] (xm:instrument-sample-ref xm instr smp)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.
[procedure] (xm:sample-length sample)Returns the number of sample points, not the number of bytes.
[procedure] (xm:sample-name sample)Returns the sample name.
[procedure] (xm:sample-loop-start sample)Returns the sample loop start position.
[procedure] (xm:sample-loop-length sample)Returns the sample loop length.
[procedure] (xm:sample-loop-type sample)Returns the sample loop type byte.
[procedure] (xm:sample-loop-enabled? sample)Returns #t if sample looping is enabled.
[procedure] (xm:sample-loop-forward? sample)Returns #t if using forward type looping. Correctly handles "invalid" flag settings produced by MPT 1.09.
[procedure] (xm:sample-loop-ping-pong? sample)Returns #t if using ping-pong type looping.
[procedure] (xm:sample-16bit-data? sample)Returns #t if the sample data uses 16-bit values.
[procedure] (xm:sample-volume sample)Returns the volume setting.
[procedure] (xm:sample-finetune sample)Returns the finetune setting.
[procedure] (xm:sample-panning sample)Returns the panning position.
[procedure] (xm:sample-relative-note sample)Returns the relative note setting.
[procedure] (xm:samples instr)Returns a list of the given instrument's samples, preserving the original order.
[procedure] (xm:sample-ref instr i)Returns the sample at index i. This uses 1-based indexing, in line with the way indexing is done in XM.
[procedure] (xm:sample->dpcm sample)Retrieves the raw XM sample data in internal DPCM format.
[procedure] (xm:sample->pcm sample)Retrieves the internal sample data and convert it to standard RAW PCM.
[procedure] (xm:export-sample sample filename)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
- 0.1.0 Initial Release