zeozeozeo/jslibxm

A JavaScript .XM file (FastTracker II Extended Module) player using libxm with emscripten.

jslibxm - simple JavaScript API for libxm

Live demo

jslibxm is a JavaScript .XM file (FastTracker II Extended Module) player using libxm with emscripten.

• Very small: ~69,9 kB in size for the minified version
• Easy to use API (see examples)
• Fast

Usage

To use this in your project,

1. Add the script to your HTML file:

<script src="https://cdn.jsdelivr.net/gh/zeozeozeo/jslibxm@master/dist/jslibxm.min.js"></script>

2. In your JavaScript, add a function that will be called once the module loads:

libxm.onload = function () {
    // create a new XM module
    var xm = new XMModule(); // sample rate is 48000 by default

    // load a module, you can use a URL string, File or an Int8Array
    var url =
        "https://api.modarchive.org/downloads.php?moduleid=41760#elw-sick.xm";
    xm.load(url, function (err) {
        if (err) {
            // this condition will run
            // if there was an an error
            console.error(err);
            return;
        }
        // module is loaded, start playing the song
        xm.resume();
    });
};

WARNING: In most browsers, the AudioContext will only start playing audio when the user interacts when the page (e.g. clicks a button).

For more examples, look inside the examples folder.

Documentation

function XMModule(sampleRate = 48000, onfillbuffer, onxmdataupdate)

Main constructor. Returns itself.
 * sampleRate - how much samples to generate and play per second
 * onfillbuffer - will be called each time when filling new audio buffer
 * onxmdataupdate - will be called each time when XMModule.xmdata updates

XMModule.load(input, callback)

Loads an XM module into the context.
 * {(File|string|Int8Array)} input - loads the module from file, URL or Int8Array.

 * {Function} callback<err> - callback function after module load.

 * Callback has 1 parameter (error) - false if loaded successfully, string if not.

Example:

xm.load(input, function (err) {
    if (err) {
        // this condition will run
        // if there was an an error
        console.error(err);
        return;
    }
    // module is loaded
});

XMModule.xmdata

XMModule.xmdata is an array containing all of the events that happening while filling the previous audio buffer.

...unfinished, look into the source code

Building

To build libxm with emscripten,

1. Clone the repository with submodules git clone --recurse-submodules [email protected]:zeozeozeo/jslibxm.git
2. Download and install emscripten and add it to PATH
3. cd into the directory and run make. For more information on building libxm, see this
4. If everything went successfully, the lib folder will have libxm.js, which is code generated by emscripten
5. If you also have uglifyjs installed, you can minify the source code for distribution by running uglifyjs lib/libxm.js src/jslibxm.js -o dist/jslibxm.min.js. The dist folder will contain the minified code for libxm.js and jslibxm.js in one file, jslibxm.min.js.