libxm

A small XM (FastTracker II Extended Module) player library. Main features:

Small size in mind; many features can be disabled at compile-time, or are optimized out by the compiler if not used.
Timing functions for synchronising against specific instruments, samples or channels.
Samples can be loaded and altered at run-time, making it possible to use libxm with softsynths or other real-time signal processors.

Written in C11 and released under the WTFPL license, version 2.

Size

The playback routine (assuming the non-portable .libxm format is loaded, see libxmize below) fits in under 7KiB of compressed machine code.

xzcrush libxmtoau
for x in *.xm; do libxmize $x $x.libxm; done
rename .xm.libxm .libxm *.xm.libxm
ls *.{xm,libxm} | xargs -n 1 -P 16 xz -9ekf
wc -c *.*xm *.*xm.xz libxmtoau.crushed

 6810919 an-dream.libxm
 5585551 an-dream.xm
  109423 cerror-expatarimental.libxm
   49240 cerror-expatarimental.xm
  282590 drozerix_-_crush.libxm
  121346 drozerix_-_crush.xm
  581955 heritage.libxm
  438340 heritage.xm

 2855496 an-dream.libxm.xz
 2876184 an-dream.xm.xz
    4180 cerror-expatarimental.libxm.xz
    4820 cerror-expatarimental.xm.xz
   36060 drozerix_-_crush.libxm.xz
   37276 drozerix_-_crush.xm.xz
  201348 heritage.libxm.xz
  201200 heritage.xm.xz

    6833 libxmtoau.crushed

Binaries crushed with xzcrush.

`libxmize` and the non-portable format

The libxmize binary can convert a standard .xm file to a non-standard, non-portable representation of that module. The file generated by libxmize is usually a lot larger than the original module, but has better compressibility.

In addition, the non-portable format:

requires less code to load (xm_create_context_from_libxmize() instead of xm_create_context()) and thus can be used to produce smaller binaries. (See the size section above.)
requires significantly less memory to play back modules (only kilobytes thanks to mmap(), see libxmtoau for an example).

The data generated by libxmize will not be readable:

On a different CPU architecture
On a different libxm commit
On a libxm compiled with another compiler
On a libxm compiled with a different compiler version
On a libxm compiled with different options or CFLAGS

Examples

Some example programs are provided.

libxm.js is a very simple XM player/visualiser that runs in a browser (emscripten port).
xmgl is a simple music visualiser that uses OpenGL and JACK for very precise audio synchronisation. See a demo here: https://www.youtube.com/watch?v=SR-fSa7J698
xmprocdemo: see README
xmtoalsa is a simple player that uses the ALSA library. It produces xmp-like output while playing. Use xmtoalsa --help (or check the source) to see the full usage.
```
./xmtoalsa --random **/*.xm
```
xmtowav will play a module and output a .wav file.
```
./xmtowav my_module.xm my_module.wav
```
xmtoau will play a module and output a .au file to standard output.
```
mpv <(./xmtoau my_module.xm)
```
libxmtoau is similar to xmtoau, except that it loads non-portable files generated by libxmize.
xmbench is a benchmark program.

Here are some interesting modules, most showcase unusual or advanced tracking techniques (and thus are a good indicator of a player's accuracy):

Status

Effects

 Status |##| Eff | Info | Description
--------+--+-----+------+------------------------------
DONE    |00|  0  |      | Arpeggio
DONE    |01|  1  |  (*) | Porta up
DONE    |02|  2  |  (*) | Porta down
DONE    |03|  3  |  (*) | Tone porta
DONE    |04|  4  |  (*) | Vibrato
DONE    |05|  5  |  (*) | Tone porta+Volume slide
DONE    |06|  6  |  (*) | Vibrato+Volume slide
DONE    |07|  7  |  (*) | Tremolo
DONE    |08|  8  |      | Set panning
DONE    |09|  9  |      | Sample offset
DONE    |10|  A  |  (*) | Volume slide
DONE    |11|  B  |      | Position jump
DONE    |12|  C  |      | Set volume
DONE    |13|  D  |      | Pattern break
DONE    |14|  E1 |  (*) | Fine porta up
DONE    |--|  E2 |  (*) | Fine porta down
        |--|  E3 |      | Set gliss control
DONE    |--|  E4 |      | Set vibrato control
DONE    |--|  E5 |      | Set finetune
DONE    |--|  E6 |      | Set loop begin/loop
UNTESTED|--|  E7 |      | Set tremolo control
DONE    |--|  E9 |      | Retrig note
DONE    |--|  EA |  (*) | Fine volume slide up
DONE    |--|  EB |  (*) | Fine volume slide down
DONE    |--|  EC |      | Note cut
DONE    |--|  ED |      | Note delay
DONE    |--|  EE |      | Pattern delay
DONE    |15|  F  |      | Set tempo/BPM
DONE    |16|  G  |      | Set global volume
DONE    |17|  H  |  (*) | Global volume slide
DONE    |20|  K  |      | Key off              (Also note number 97)
DONE    |21|  L  |      | Set envelope position
DONE    |25|  P  |  (*) | Panning slide
DONE    |27|  R  |  (*) | Multi retrig note
DONE    |29|  T  |  (*) | Tremor
DONE    |33|  X1 |  (*) | Extra fine porta up
DONE    |--|  X2 |  (*) | Extra fine porta down

Volume effects

 Status |  Value  | Meaning
--------+---------+-----------------------------
DONE    | $10-$50 | Set volume (Value-$10)
DONE    | $60-$6f | Volume slide down
DONE    | $70-$7f | Volume slide up
DONE    | $80-$8f | Fine volume slide down
DONE    | $90-$9f | Fine volume slide up
DONE    | $a0-$af | Set vibrato speed
DONE    | $b0-$bf | Vibrato
DONE    | $c0-$cf | Set panning
DONE    | $d0-$df | Panning slide left
DONE    | $e0-$ef | Panning slide right
DONE    | $f0-$ff | Tone porta

Known issues

Only loads FastTracker II-compatible XM files.
Loading a bogus file (that yet has a valid 60-byte header) will probably result in a segmentation fault.
Big endian architectures are not yet supported.

Tests

Some test XM files are in the tests directory. Their goal is to test a certain feature against regressions. A summary of tests (and what they are supposed to test) is in the table below.

     Test                      |     Status     |     Tested against     | Extras
-------------------------------+----------------+------------------------+------------------------------------------------
amiga.xm                       | FAIL           | MilkyTracker, xmp      | Should sound identical.
arp-slow.xm                    | FAIL           | MilkyTracker, OpenMPT  | Should sound identical.
autovibrato-turnoff.xm         | PASS           | MilkyTracker           | Same pitches should be heard twice in a row.
fadeout-speed.xm               | PASS           | MilkyTracker           | Should sound identical.
finetune.xm                    | PASS           | MilkyTracker           | Left and right channels should sound identical.
ghosts.xm                      | FAIL           | MilkyTracker           | Left and right channels should sound identical.
multiretrig-volume.xm          | PASS           | FT2, OpenMPT           | Should sound identical.
note-delay-ghost.xm            | PASS           | MilkyTracker, FT2      | Should sound identical.
note-delay-retrig.xm           | PASS           | MilkyTracker           | Should sound identical.
panning-law.xm                 | PASS           | MilkyTracker, FT2clone | Should sound identical.
pattern-loop-quirk.xm          | PASS           | MilkyTracker           | Should play the same notes at the same time.
pos_jump.xm                    | PASS           | Milkytracker, OpenMPT  | Only one beep should be heard.
ramping.xm                     | PASS           | MilkyTracker           | If XM_RAMPING is ON, no loud clicks should be heard.
ramping2.xm                    | PASS           | MilkyTracker           | If XM_RAMPING is ON, no loud clicks should be heard.
retrig-vol-fade.xm             | PASS           | MT, FT2clone, OpenMPT  | Should sound identical.
tone-portamento.xm             | PASS           | MilkyTracker           | Should sound identical.
tremolo.xm                     | PASS           | MilkyTracker           | Should sound identical.
tremor.xm                      | PASS           | MilkyTracker           | Should sound identical.
vibrato.xm                     | PASS           | MilkyTracker           | Should sound identical.
vibrato-slow.xm                | PASS           | OpenMPT                | Should sound identical.
vibrato-octave.xm              | PASS           | FT2clone, OpenMPT      | Should sound identical.

Thanks

Thanks to:

Thunder kurttt@sfu.ca, for writing the modfil10.txt file;
Matti "ccr" Hamalainen ccr@tnsp.org, for writing the xm-form.txt file;
Mr.H of Triton and Guru and Alfred of Sahara Surfers, for writing the specification of XM 1.04 files;
All the MilkyTracker contributors, for the thorough documentation of effects;
All the people that helped on #milkytracker IRC;
All the libxm contributors.

9.4 KiB Raw Blame History