xmkit

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.

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

Module Related Procedures

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.

Pattern Related Procedures

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.

Instrument Related Procedures

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.

Sample Related Procedures

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")

0.1.0 Initial Release

chickadee » xmkit

Identifier search