https://github.com/artefact2/libxm
A small XM (FastTracker II Extended Module) player library.
https://github.com/artefact2/libxm
demoscene fasttracker mod module tracker xm
Last synced: 5 months ago
JSON representation
A small XM (FastTracker II Extended Module) player library.
- Host: GitHub
- URL: https://github.com/artefact2/libxm
- Owner: Artefact2
- License: wtfpl
- Created: 2013-05-23T18:47:33.000Z (over 12 years ago)
- Default Branch: master
- Last Pushed: 2025-05-08T19:15:54.000Z (5 months ago)
- Last Synced: 2025-05-08T20:26:45.737Z (5 months ago)
- Topics: demoscene, fasttracker, mod, module, tracker, xm
- Language: C
- Homepage:
- Size: 1.38 MB
- Stars: 151
- Watchers: 8
- Forks: 16
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- License: COPYING
Awesome Lists containing this project
README
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.
* Should be fairly portable (only dependency is `libm`). Big-endian compatible
(tested on s390x). The example programs mostly target Linux.
Written in C23 and released under the WTFPL license, version 2.
Building
========
* Build the library:
~~~
cmake -DCMAKE_BUILD_TYPE=RelWithDebInfo -Bbuild -Ssrc
make -C build
~~~
* Build a specific example:
~~~
cmake -DCMAKE_BUILD_TYPE=RelWithDebInfo -Bbuild -Sexamples/FOO
make -C build-FOO
~~~
* To build a shared library and link dynamically, use
`cmake -DBUILD_SHARED_LIBS=ON`.
* To see a list of build options, use `cmake -L` or `cmake-gui`.
* To use libxm in your program, put these lines in the `CMakeLists.txt` of your project, then `#include `:
~~~
add_subdirectory(/path/to/libxm/src libxm_build)
target_link_libraries(my_stuff PRIVATE xm)
~~~
Size
====
`libxmtoau` can be compiled (with all playback features enabled) and
[crushed](https://gitlab.com/artefact2/xzcrush) to about **4741 bytes** (Linux
x86_64).
~~~
cmake -DCMAKE_BUILD_TYPE=MinSizeRel -DXM_DEFENSIVE=OFF -DXM_LIBXM_DELTA_SAMPLES=OFF -DXM_LINEAR_INTERPOLATION=OFF -DXM_RAMPING=OFF -DXM_STRINGS=OFF -DXM_SAMPLE_TYPE=float -Bbuild-libxmize -Sexamples/libxmize
make -C build-libxmize libxmtoau
strip -R .eh_frame_hdr -R .eh_frame build-libxmize/libxmtoau
xzcrush build-libxmize/libxmtoau
~~~
If you are using libxm to play a single module (like in a demo/intro), disable
features as suggested by `libxmize` to save a few more bytes.
Examples
========
* [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, GLFW and JACK for very
precise audio synchronisation. See a demo here:
* `xmprocdemo`: a simple non-interactive demo that plays back a single module
with procedurally generated samples. Somewhat optimized for size. ([Dream
Candy](https://modarchive.org/module.php?178565) by Drozerix, public domain.
Thank you Drozerix for the great music!)
* `libxmize` converts a `.xm` module to the libxm format. It is highly
non-portable and is meant for static linking and sizecoding (loading code is
much shorter and libxm format compresses better).
* `libxmtoau` reads standard input (a file generated by `libxmize`) and
writes a .AU file to standard output. Somewhat optimized for size, see [size
section](#Size) above. You can test it with, for example,
`libxmize file.xm | libxmtoau | mpv -`.
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)
Known issues
------------
See [GitHub issues](https://github.com/Artefact2/libxm/issues?q=is%3Aissue%20state%3Aopen%20label%3Abug).
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 , for writing the `modfil10.txt` file;
* Matti "ccr" Hamalainen , 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/manual/MilkyTracker.html#effects)
of effects;
* Vladimir Kameñar, for writing `The Unofficial XM File Format Specification`;
* All the people that helped on `#milkytracker` IRC;
* All the
[libxm](https://github.com/Artefact2/libxm/graphs/contributors)
contributors.