furumi-ng/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