townengine/third-party/libxm/README.md

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`](https://gitlab.com/artefact2/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](https://artefact2.github.io/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](./examples/xmprocdemo/README.md)

* `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):

* [Cerror - Expatarimental](http://modarchive.org/module.php?136603)
* [Lamb - Among the stars](http://modarchive.org/module.php?165819)
* [Raina - Cyberculosis](http://modarchive.org/module.php?165308)
* [Raina - Slumberjack](http://modarchive.org/module.php?148721)
* [Strobe - One for all](http://modarchive.org/module.php?161246)
* [Strobe - Paralysicical death](http://modarchive.org/module.php?65817)

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](http://www.milkytracker.org/docs/MilkyTracker.html#effects)
  of effects;

* All the people that helped on `#milkytracker` IRC;

* All the
  [libxm](https://github.com/Artefact2/libxm/graphs/contributors)
  contributors.