XM Player

A tool for reading and playing FastTracker 2 XM music files in a web browser.

Written in 2016 by William de Beaumont

To the extent possible under law, the author(s) have dedicated all copyright and related and neighboring rights to this software to the public domain worldwide. This software is distributed without any warranty.

You should have received a copy of the CC0 Public Domain Dedication along with this software. If not, see http://creativecommons.org/publicdomain/zero/1.0/ .

Introduction

This is a tool for reading and playing music files in the XM format in a web browser. XM is the format originally used by the DOS program FastTracker 2, and is based on the older MOD format. Years ago I used SoundTracker (a Unix clone of FT2) to write a bunch of music in this format. I wanted to write a web-based player to use on my website to play my old music, and to document the format itself more thoroughly than I'd seen elsewhere.

online demo

Features

• Load from local file or from a URL. The URL must be served from the same domain as the player, or the target of the URL must explicitly allow CORS requests. You can use this to load files from The Mod Archive, for example.
• Display practically all the information in the XM file as HTML, with units. Even the effects columns in the pattern have tooltips explaining each effect (even if the player doesn't implement that effect).
• Play most XM files recognizably (if not completely accurately).
• Optionally scroll to the currently playing pattern row (if the "Show patterns" checkbox is checked before loading the file).
• Play individual patterns, instruments, and samples.
• Loop songs and individual patterns.
• Render and save songs to .wav files.
• Click the stop button at the top right to stop playing any sound.
• Tested in Firefox and Chrome. May also work in Safari, Opera, and Edge (not IE, or Opera Mini). I'm going by caniuse.

Bugs

• Loading large files can be very slow (10s of seconds), mostly due to layout of the pattern tables. Uncheck the "show patterns" checkbox to speed it up.
• Slight lag between patterns, especially noticeable in songs that make extensive use of jumps to make the pattern display do crazy things.
• Occasional larger hiccups in the middle of patterns, especially in songs with many channels playing at once.
• Certain sliding effects (volume slide, panning, porta?) should happen only on some ticks in a row (fine on first tick, non-fine on other ticks), but xm-player applies them across the whole row, so the rate is wrong for non-standard tempos, and the effect is smoother than what FT2 would do.
• The Fxx effect sets the tempo/BPM for events yet to be scheduled, but doesn't update previously-scheduled future events whose timing depends on these parameters (e.g. volume/panning envelopes).
• The ECx "note cut" effect actually cuts the note, when it should just set the volume to 0 so the note can be resurrected by later commands (such as a "new" note with a tone porta)
• On Firefox (tested on version 84.0.2), the instrument volume fadeout setting doesn't work properly; the note stays at full volume until it would have faded out completely, and then cuts off. This is due to a bug in the implementation of the linearRampToValueAtTime method from the Web Audio API, represented by Firefox bugs 1567777 and 1171438. It's likely this affects other things involving volume ramps, like vibrato and envelopes, but the fadeout setting is how I noticed it. I'm not hopeful the bug will be fixed soon (as of 2021), since it was first reported 6 years ago and the last activity on the bug reports was 2 years ago.

Unimplemented XM features

• Amiga frequency table (linear used instead, and makes esp. portamentos sound wrong in songs set to use Amiga table)
• Ping-pong loops (forward loops used instead)
• Effects:
  • 7xy Tremolo (oscillating volume)
  • E3x Glissando (discrete pitch slide)
  • E5x Set note finetune (ditto)
  • E6x Pattern loop
  • E7x Set tremolo (oscillating volume) waveform
  • E8x either "set note panning position" (like 8xx) or "sync" (like Wxx)
  • EEx Pattern delay
  • Lxx Set volume envelope position
  • Pxy Panning slide
  • Rxy Retrigger + volume slide
  • Txy Tremor (interrupting volume)
  • Wxx Sync

See effects.md for a complete comparison table of the effects supported by FT2, MT, and this software.

Some other ways to play XM files

• MikMod: cross-platform, plays many formats

• In a web browser:

  • jsxm: very similar to mine, but:

    • sounds more faithful to FT2
    • displays less information from the file (just the title, the patterns as they play, and the instrument names and waveforms)
    • uses the Web Audio API merely as a place to stuff PCM samples into, rather than taking full advantage of its relevant features (perhaps that was the right decision, given the results)
    • requires drag-and-drop to open local files, rather than an "open" dialog window

  • chiptune2.js: emscripten port of the library behind OpenMPT

• Editors:

  • FastTracker 2: DOS, the original
  • MilkyTracker: cross-platform
  • SoundTracker: Unix, no longer maintained
  • OpenMPT: Windows-only

XM format resources

• FT2.DOC from the FastTracker 2 download above, documents usage of FT2 as well as the list of effects, but not their representation in the file format.
• The XM 2.04 format documentation (ftp://ftp.modland.com/pub/documents/format%5fdocumentation/FastTracker%202%20v2.04%20%28.xm%29.html) documents the file format, but has fewer details about the effects. It's also written by one of the authors of FT2, but was then extended and corrected (!) by others.
• The MilkyTracker Manual is similar in spirit to FT2.DOC, but goes into a little more detail (but still frustratingly lacks units on many of the effect parameters).
• A1k0n's blog post on writing jsxm has the most useful explanation of ticks, rows, note periods/frequencies, speed/tempo, and BPM (units!). These things are defined half-heartedly, if at all, in the other documents, and can be confusing (e.g. a beat is four rows, except when it isn't...). It also has a reasonable introduction to other basic tracker concepts I was already familiar with. It deliberately has almost no information on specific effects, though.
• One of the XM files I had lying around used an effect not documented in any of the above documentation: Wxx. I found out it's not supported by FT2 at all, but is supported by the BASS player, and is used to trigger a synchronization callback. It's documented in these places:
  • The BASS changelog, which is how I found it.
  • The documentation for BASSMOD_MusicSetSync, which sets up the callback (Wxx is buried in the text).