XMrs — SoundTracker file format library

A no_std-friendly Rust library to read, edit and serialize SoundTracker data — with pleasure.

Because "Representation is the Essence of Programming".

Supported formats

Historical module files — imported into xmrs's in-memory Module model:

The umbrella feature import enables all of them at once (and is on by default together with std).

The Module model

xmrs exposes one editor-friendly data model, regardless of what was loaded:

Module ─┬─ Instrument ─┬─ InstrDefault ─┬─ Sample (with loop & sustain-loop)
        │              │                ├─ Envelope (volume / panning / pitch)
        │              │                ├─ Vibrato
        │              │                └─ InstrMidi
        │              ├─ InstrEkn       (Euclidean-rhythm instrument)
        │              ├─ InstrMidi      (MIDI instrument)
        │              ├─ InstrOpl       (Yamaha OPL)
        │              ├─ InstrSid       (MOS6581 SID voice)
        │              └─ InstrRobSid ── InstrSid  (Rob Hubbard-style)
        └─ Pattern ─ Row ─ TrackUnit ─┬─ TrackEffect
                                      └─ GlobalEffect

Two companion fields on Module describe where the data came from and how it should play back:

• ModuleFormat — purely metadata (Xm, S3m, It, Mod, Unknown). Useful for the UI and for export.
• PlaybackQuirks — orthogonal switches for each historical replay quirk (FT2 pitch-slide overflow, S3M period clamp, arpeggio LUT, pattern-loop resume, tremor state, …). Importers populate them to match the source format; modules authored from scratch default to a clean, quirk-free playback.

This separation lets an editor compose any subset of historical behaviours without having to lie about which tracker the module "came from".

Loading a file

use xmrs::prelude::*;

let bytes = std::fs::read("song.xm")?;

// Auto-detect: tries XM → S3M → IT → MOD.
let module = Module::load(&bytes)?;

// Or target a specific format:
let module = Module::load_xm(&bytes)?;

println!("{} — {} patterns", module.name, module.pattern.len());

Format-specific constructors are also available: Module::load_mod, load_xm, load_s3m, load_it. SID is imported via its own entry point, xmrs::import::sid::sid_module::SidModule::load, and is not part of the auto-detect path.

Serialization

Module derives serde::Serialize / Deserialize, so you can round-trip it through any serde codec.

Examples

Run from the xmrs crate directory:

# Dump any supported module file:
cargo run --features=demo --example xmrs -- -f path/to/song.xm

# Dump an XI (Fast Tracker II instrument) file:
cargo run --example xmi

# Exercise the bundled SID parsers (Rob Hubbard tunes):
cargo run --example sid

Cargo features

Defaults: ["std", "import"].

no_std builds

With std disabled, exactly one math backend is required — the crate refuses to compile otherwise:

# libm backend:
cargo build --no-default-features --features "libm import" --release

# micromath backend (smaller, less precise):
cargo build --no-default-features --features "micromath import" --release

Embedded / footprint-sensitive builds

If you're targeting tight flash budgets, don't ship the importers. Parse modules on a host machine, serialize with bincode 2.x (alloc feature) — optionally compressed with flate2 — and load the resulting blob on-device. You end up with a much smaller binary that still manipulates the full Module model.

License

MIT © Sébastien Béchet. See LICENSE.