furumi-ng/docs/CHIPTUNE.md

Chiptune Support Implementation Plan

Overview

Add playback support for tracker/chiptune module formats (MOD, XM, S3M, IT, MPTM) to the Furumi web player. The implementation consists of two parts:

1. Server-side — lightweight metadata parser in pure Rust (zero external dependencies)
2. Client-side — playback via libopenmpt WebAssembly using AudioWorklet API

Supported Formats

Format	Extension	Origin
MOD	.mod	Amiga ProTracker
XM	.xm	FastTracker II
S3M	.s3m	Scream Tracker 3
IT	.it	Impulse Tracker
MPTM	.mptm	OpenMPT

Part 1: Server-Side Metadata Parser

Rationale

libopenmpt must NOT be a server dependency. All tracker formats store metadata at fixed byte offsets in their headers, making manual parsing trivial. Reading the first ~400 bytes of a file is sufficient to extract all available metadata.

Extracted Fields

• Title — song name embedded in the module header
• Channels — number of active audio channels
• Patterns — number of unique patterns in the module
• Message — song message/comment (IT/MPTM only)

Note: none of these formats have a dedicated "artist" field. Author information, when present, is typically found in the IT/MPTM song message.

Binary Format Reference

MOD

Offset	Size	Field
0	20	Song title (space/null padded)
952	128	Pattern order table
1080	4	Signature (determines channel count)

Channel count is derived from the 4-byte signature at offset 1080:

• M.K., M!K!, FLT4, 4CHN → 4 channels
• 6CHN → 6, 8CHN / OCTA → 8
• xCHN → x channels, xxCH → xx channels

Pattern count = max value in the order table (128 bytes at offset 952) + 1.

XM

All multi-byte values are little-endian.

Offset	Size	Field
0	17	Magic: "Extended Module: "
17	20	Module name
58	2	Version number
68	2	Number of channels
70	2	Number of patterns

S3M

Offset	Size	Field
0x00	28	Song title (null-terminated)
0x1C	1	Signature byte (0x1A)
0x24	2	Pattern count (LE u16)
0x2C	4	Magic: "SCRM"
0x40	32	Channel settings

Channel count = number of entries in channel settings (32 bytes) that are not 0xFF.

IT

Offset	Size	Field
0x00	4	Magic: "IMPM"
0x04	26	Song title (null-terminated)
0x26	2	Pattern count (LE u16)
0x2E	2	Special flags (bit 0 = message attached)
0x36	2	Message length
0x38	4	Message file offset
0x40	64	Channel panning table

Channel count = number of entries in channel panning (64 bytes) with value < 128.

Song message: if special & 1, read message_length bytes from message_offset. Uses \r (0x0D) as line separator.

MPTM

Parsed identically to IT. Detection:

• Legacy: magic tpm. instead of IMPM
• Modern: magic IMPM with tracker version (offset 0x28) in range 0x0889..=0x0FFF

Integration Points

• browse.rs — add tracker extensions to the audio file whitelist
• meta.rs — add a chiptune metadata branch that runs before Symphonia (which does not support tracker formats); return title, channel count, pattern count, and message
• stream.rs — serve tracker files as-is (no server-side transcoding); these files are typically under 1 MB

Implementation Notes

• Zero external crate dependencies — only std::io::Read + std::io::Seek
• Read at most the first 1084 bytes for header parsing (MOD needs offset 1080 + 4 byte sig)
• For IT/MPTM messages, a second seek to message_offset is needed
• All strings should be trimmed of null bytes and trailing whitespace
• Expected code size: ~200–300 lines of Rust

Part 2: Client-Side Playback via libopenmpt WASM

Rationale

Browsers cannot decode tracker formats natively. libopenmpt compiled to WebAssembly decodes modules into PCM samples which are then rendered through the Web Audio API. Client-side decoding keeps the server dependency-free and enables interactive features (pattern display, channel visualization) in the future.

libopenmpt WASM Source

Use the chiptune3 library (npm: chiptune3, by DrSnuggles) which bundles libopenmpt as a self-contained AudioWorklet-compatible ES6 module.

Package contents:

File	Size	Purpose
chiptune3.js	~4 KB	Main API (load, play, pause, seek)
chiptune3.worklet.js	~12 KB	AudioWorklet processor glue
libopenmpt.worklet.js	~1.7 MB	libopenmpt WASM + JS (single-file bundle)

Available via jsDelivr CDN or can be vendored into the project.

If a newer libopenmpt version is needed, the official project provides source tarballs with an Emscripten build target:

make CONFIG=emscripten EMSCRIPTEN_TARGET=audioworkletprocessor

This produces a single ES6 module with WASM embedded inline (SINGLE_FILE=1), which is required because AudioWorklet contexts cannot fetch separate .wasm files.

Playback Architecture

┌──────────────────────────────────────────────────────────┐
│  player.html                                             │
│                                                          │
│  Format detection (by file extension)                    │
│  ┌─────────────────────┐  ┌────────────────────────────┐ │
│  │ Standard audio       │  │ Tracker module             │ │
│  │ (mp3/flac/ogg/...)   │  │ (mod/xm/s3m/it/mptm)      │ │
│  │                      │  │                            │ │
│  │ <audio> element      │  │ fetch() → ArrayBuffer      │ │
│  │ src=/api/stream/path │  │     ↓                      │ │
│  │                      │  │ libopenmpt WASM decode     │ │
│  │                      │  │     ↓                      │ │
│  │                      │  │ AudioWorkletProcessor      │ │
│  │                      │  │     ↓                      │ │
│  │        ↓             │  │ AudioContext.destination    │ │
│  └────────┼─────────────┘  └────────────┼───────────────┘ │
│           └──────────┬──────────────────┘                 │
│                      ↓                                    │
│              Player controls                              │
│         (play/pause/seek/volume)                          │
│              MediaSession API                             │
└──────────────────────────────────────────────────────────┘

Integration Points

• player.html — detect tracker format by extension; use chiptune3 API instead of <audio> element for tracker files; unify transport controls (play/pause/seek/volume) across both playback engines
• WASM assets — serve chiptune3.js, chiptune3.worklet.js, and libopenmpt.worklet.js via a static file endpoint or embed them inline
• mod.rs (routes) — add endpoint for serving WASM assets if not embedded

Player Integration Details

The player must abstract over two playback backends behind a common interface:

play(path)    — start playback (auto-detect engine by extension)
pause()       — pause current playback
resume()      — resume current playback
seek(seconds) — seek to position
setVolume(v)  — set volume (0.0–1.0)
getDuration() — total duration in seconds
getPosition() — current position in seconds
isPlaying()   — playback state
onEnded(cb)   — callback when track finishes

For tracker modules, getDuration() and getPosition() are provided by libopenmpt's get_duration_seconds() and get_position_seconds() APIs.

Considerations

• Tracker files are small (typically < 1 MB) — fetch the entire file before playback; no streaming/range-request needed
• AudioWorklet requires a secure context (HTTPS or localhost)
• The WASM bundle is ~1.7 MB — load it lazily on first tracker file playback
• MediaSession API metadata should display module title from /api/meta response