Savage Mod Player

🌐 Sprache / Language: English · Deutsch

Native macOS tracker player for MOD, S3M, XM, and IT — powered by an independent Swift replay engine.

A self-contained tracker module player led by its native macOS app:

1. Native macOS app (Savage Mod Player.app) — a SwiftUI desktop application built on AVAudioEngine/AVAudioSourceNode with true real-time oscilloscopes and VU meters. It plays ProTracker and multichannel MODs (6/8/… channels, including 6CHN/8CHN/FLT8), 15-sample Soundtracker modules, ScreamTracker 3 (.s3m), FastTracker II (.xm), and Impulse Tracker (.it) — and ships with a Quick Look plugin: pressing the space bar on a .mod/.s3m/.xm/.it file in Finder opens a playable audio preview.
2. Bonus HTML5 player (savage-mod-player.html) — a tiny single HTML file (under 60 KB) that runs straight from the file system with a double click, no web server required. It deliberately focuses on classic 4-channel ProTracker MODs.

Not a libopenmpt wrapper: the native app parses, sequences, synthesizes, and mixes MOD/S3M/XM/IT itself in Swift. It does not link or ship libopenmpt, libxmp, libmodplug, DUMB, or another module replay library. openmpt123 is used only as an optional external reference during development and testing.

Neither variant bundles any module files. Songs are loaded via drag & drop or the file dialog.

---

Download

Ready-made builds of the macOS app are available as notarized DMGs on the releases page. Download the DMG, open it, and drag the app into your Applications folder.

The HTML5 player needs no download beyond the repository itself: simply open savage-mod-player.html in a browser.

---

Installing the Quick Look plugin

The Quick Look plugin is embedded in the app bundle (Contents/PlugIns/) — there is nothing to install separately:

1. Drag the app from the DMG into /Applications.
2. Launch the app once (this is when macOS registers the bundled Quick Look extension).
3. Select a .mod, .s3m, .xm, or .it file in Finder and press the space bar — the preview shows the macOS audio player with play, scrubbing, and volume. It renders up to the first 60 seconds, then caches that preview for unchanged files so later openings are immediate. Unsupported files show their parser error instead of an endless loading indicator.

If no preview appears:

• Reload the Quick Look service: run qlmanage -r in Terminal, then open the preview again.
• Check the registration: pluginkit -m -p com.apple.quicklook.preview | grep -i savage should list an entry; if it does not, launch the app once or copy it to /Applications again.
• Note on .mod and VLC: if VLC (or another app that registers .mod as an audio/video type) is installed, macOS may intercept .mod files with its built-in media preview before third-party plugins are consulted — a Quick Look system limitation. The extension also claims the verified VLC identifiers for .s3m, .xm, and .it.

---

Features

• Independent native replay engine: project-owned Swift parsers, sequencer, instrument/voice engines, effects, filters, resampling, and mixer. There is no third-party module decoder hidden behind the UI.
• Format support (macOS app): ProTracker MOD, multichannel MOD (xCHN/xxCH/CD81/OKTA/FLT8), 15-sample Soundtracker, ScreamTracker 3 (.s3m), FastTracker II (.xm), and Impulse Tracker files through cmwt=0x0216 (.it) in sample or instrument mode. IT support includes 64 pattern channels, a preallocated 256-voice NNA pool, compressed 8/16-bit mono/stereo samples, envelopes, filters, effects, sustain loops, and compatibility flags. The HTML5 player deliberately stays compact and plays 4-channel MODs.
• Quick Look preview (macOS app): the bundled Quick Look plugin renders and caches up to the first 60 seconds of .mod/.s3m/.xm/.it files with the player engine, then shows the native audio player with play and scrubbing in Finder (space bar). Unsupported files show a readable reason.
• Drag & drop: drop individual .mod/.s3m/.xm/.it files, entire folders (recursively), or Zip/7-Zip archives onto the player.
• Automatic playlist: a configurable autoplay folder (macOS app: Settings, Cmd+,) is scanned at startup and loaded as a playlist; without configuration, an audio/ subfolder next to the player or the app is used.
• Hierarchical playlist: folders and archives appear as a collapsible tree. Folders start collapsed, the path to the playing track expands automatically, and playback and shuffle run across all folders.
• Archives as folders (macOS app): Zip and 7-Zip archives are extracted invisibly to a temporary directory (cleaned up on quit) and shown in the playlist like regular folders.
• Playlist handling: a single click on a playlist entry loads and starts the track. When a song ends, the playlist can advance automatically.
• Real-time oscilloscopes:
  • A true stereo master-mix oscilloscope fed straight from the audio render path.
  • Separate per-channel scopes (dynamic channel count) visualizing the actual waveforms from the synthesizer render block.
• Multiple themes:
  • Dark: graphite/black palette with good contrast and muted accent colors.
  • Light: a classic, bright macOS-like style with sober contrast.
• PAL & NTSC clocks: switchable Paula clocking (3.546 MHz PAL vs. 3.580 MHz NTSC) for Paula-based MOD formats; the control is hidden for formats with their own frequency model.
• Volume & stereo separation: psychoacoustic (quadratic) volume scaling and adjustable stereo separation (bleed from 0% mono to 100% hard panning).
• Hi-fi resampling: switchable linearly interpolated sample playback for a smoother sound (can be disabled for the original 8-bit crunch).
• WAV & stem export: export the entire song to a stereo WAV file, or export individual instrument samples as WAV.
• Full keyboard control: space bar for play/pause, left/right arrows for song positions, up/down arrows to switch songs in the playlist.

---

Controls & display explained

The transport buttons speak for themselves, but the tracker-specific readouts and toggles carry a bit of Amiga history. Every item below is also available as a tooltip in the app — hover over a control and wait a moment for the explanation to appear. Since tooltips take a few seconds to show and are easy to miss, they are collected here as well.

Header readouts

• CH (used channels): counts the pattern channels that actually contain notes, instruments, volume data, or effects; reserved empty channels are not included. The tracker grid and channel oscilloscopes show exactly these channels while retaining their original channel numbers, so IT's reserved 64-channel capacity and gaps do not create empty columns or a needless scrollbar.
• BPM (beats per minute): playback tempo. The Amiga standard is 125. Adjustable with −/+; a song can also change its own tempo via effects. Switching songs sets the new module's header value.
• SPD (speed): ticks per pattern row (Amiga standard 6). Lower = rows advance faster, higher = slower. Together with BPM this sets the effective speed.
• PAT (pattern position): the current pattern and the total in the song's play order. A pattern is a block of notes (usually 64 rows); the song plays them in this sequence.

Clock (shown next to the master oscilloscope for Paula-based MOD formats only)

• PAL (3.546 MHz Paula clock): as on European Amigas — the reference pitch and speed for most modules.
• NTSC (3.580 MHz Paula clock): as on US Amigas — modules sound slightly higher and run a little faster than with PAL.

Sound options

• LED filter: the Amiga's switchable low-pass filter at ~3.2 kHz that rolls off the highs — the duller original sound, as when the power LED was lit on a real Amiga.
• Hi-Fi interpolation: smooths samples during resampling (softer sound). Turned off it sounds like the original hardware — raw 8-bit audio with audible aliasing.
• Stereo separation: 100% = hard Amiga panning (channels fully left/right), 0% = mono. In between, crosstalk is blended in to reduce headphone fatigue. Most audible on headphones; barely noticeable on laptop speakers.
• Loop mode: what happens when the song ends — continue the playlist, repeat the song, or stop.

Transport & navigation

• Shuffle: when on, track changes and song ends jump randomly through the playlist; when off, the playlist plays in order.
• −15 s / +30 s: skip backward/forward (row-accurate; approximate across tempo changes).
• Position slider: pick a spot in the song — also works while stopped, in which case Play starts from there.

---

Technical background

Synthesis & Paula emulation

The audio engine simulates the Amiga Paula hardware behavior:

• Clocking: the clock generator uses the PAL Paula frequency of 3,546,894.6 Hz. The pitch factor is derived from the ratio to the current audio output rate.
• Stereo panning: Amiga-style hardware panning (channels 1 and 4 left, channels 2 and 3 right) with adjustable software blending to avoid headphone fatigue.
• Effects: faithful playback of all standard ProTracker commands, including arpeggio (0x0), slides (0x1/0x2), tone portamento (0x3), vibrato (0x4), volume slides (0xA), position jump (0xB), volume set (0xC), pattern break (0xD), extended effects (0xE such as loop, cut, note delay, retrigger), and tempo control (0xF).

For ScreamTracker 3 the engine switches to the ST3 period model (C2Spd-based periods against the 14.3 MHz ST3 clock) instead of Amiga Paula periods; the ProTracker effect set is extended with S3M specifics (fine/extra-fine slides with effect memory, tremor, fine vibrato, global volume).

For FastTracker II the engine runs a dedicated instrument voice model: linear frequency table (exponential frequency from linear periods), multi-sample instruments with keymaps, volume and panning envelopes (sustain and loop, interpolated per tick), key-off with volume fadeout, auto-vibrato with sweep, and ping-pong sample loops. The XM effect set including the volume column and per-channel effect memory is translated onto the shared DSP core.

For Impulse Tracker the engine separates 64 logical pattern channels from a preallocated pool of 256 playback voices. It implements sample and instrument mode, NNA/DCT/DCA, 120-note sample maps, IT 2.14/2.15 compression, stereo and sustain loops, pitch/pan/filter envelopes, resonant per-voice filters, sample vibrato, surround, IT effect memory, and the Old Effects/Compatible Gxx profiles. OpenMPT-created IT files additionally use structured XTPM/STPM parsing, classic/alternative/modern tempo formulas, stored preamp and mix settings, restart position, extended filter range, and the applicable PCM PlayBehaviour flags.

Compatibility messages are capability-based. cwtv identifies the creating tracker while cmwt controls required IT semantics; a newer OpenMPT creator version alone is not a warning. Metadata, dormant MIDI flags, unused plugin definitions, and marker-like bytes inside PCM remain silent. A warning is shown only when a pattern in the played order list actually reaches an unsupported sound-affecting feature, with its instrument, channel, plugin slot, or chunk ID where available. savage-cli --info exposes the complete structured diagnosis.

Known Impulse Tracker limitations

• IT structures through cmwt=0x0216 and known PCM-relevant OpenMPT IT extensions are supported. MPTM is detected but remains a separate unsupported format.
• The player is deliberately not a VST/AudioUnit host and does not emit external MIDI. Embedded MIDI macros are limited to the common cutoff/resonance filter macros. These paths warn only when they are actually triggered.
• Deprecated OpenMPT bug-emulation modes for pre-1.17 swing, the superseded old pattern-loop/jump rule, imprecise legacy ping-pong overshoot, and proprietary envelope release nodes are not emulated. They produce a feature-specific warning only if used.
• Extended IT patterns from 1 through 1,024 rows and up to 240 patterns are accepted. Deleted pattern references in the order list are skipped like OpenMPT.

Architecture

Layer	macOS (Swift)	Bonus HTML5 player
Parser	ModuleLoader plus project-owned MOD/S3M/XM/IT parsers (SavageModPlayerCore)	modplayer.js
DSP / mixer	Project-owned sequencer and DSP via AVAudioSourceNode, up to 64 logical channels / 256 IT voices	mod-player-worklet.js (AudioWorklet)
UI	SwiftUI + Canvas	vanilla JS + CSS grid
Quick Look	quicklook/PreviewProvider.swift (appex, offline WAV render)	—

---

Build

macOS app

bash build_app.sh                 # → "Savage Mod Player.app" (incl. Quick Look appex)

Besides the app itself, build_app.sh compiles the Quick Look extension (quicklook/) and places it inside the app bundle under Contents/PlugIns/.

At startup the app fills the playlist from the autoplay folder configured in the Settings window (Cmd+,). If none is set, it looks for an audio/ directory next to the application and automatically loads any .mod/.s3m/.xm/.it files (or mod.* files) found there. These files are local test data only and do not belong in the git repository.

For release builds, build_app.sh automatically signs with the Developer ID Developer ID Application: Daniel Mueller (9QSWKSR4NQ) if it is available in the keychain. Local unsigned builds are possible with SIGN_APP=0 bash build_app.sh.

Bonus HTML5 player

python3 build.py                  # → savage-mod-player.html (under 60 KB)
python3 build.py --no-min         # without minification

The generated single-file variant savage-mod-player.html is part of the repository so the compact player can be used directly without a local build.

DMG (for releases)

bash build_dmg.sh                 # → build/Savage Mod Player.dmg
bash build_dmg.sh --notarize      # sign, notarize, and staple the DMG

The DMG contains a Retina-compatible background image (1x/2x TIFF via tiffutil). Notarization expects a keychain profile, by default SavageModPlayerNotary. It can be created once interactively:

xcrun notarytool store-credentials SavageModPlayerNotary

Tests

swift test
swift test --filter MultiFormatTests
node Tests/js/worklet-timing.mjs
python3 tools/reference_compare.py --output-dir /tmp/savage-it-reference audio/example.it

The suite covers the parsers (all MOD variants, S3M, XM, IT, synthetic and real files), DSP timing, sequencing, the Quick Look plugin's offline WAV renderer, and the parity between the Swift and browser DSP implementations. The optional reference harness compares the native renderer with the pinned openmpt123 build and reports duration, signal levels, envelope correlation, lag, onset matching, and spectral similarity without using libopenmpt as a production backend.

---

Publishing to GitHub

bash publish_github.sh --dry-run --release
bash publish_github.sh --release

The publishing script sets origin to https://github.com/DanielMuellerIR/savage_modplayer.git, blocks accidentally tracked audio and release artifacts, and with --release creates the matching GitHub release entry with the DMG asset.

Origin

The ProTracker engine was first developed in the sister project FraktalLab as a custom TypeScript/AudioWorklet implementation (AmiModPanel / utils/modplayer, no libopenmpt). For this project it was ported to a native Swift engine built on AVAudioSourceNode, then expanded with project-owned S3M, XM, and IT parsers, sequencing, effects, and voice handling. The original web implementation remains as the compact single-file bonus player. Bundled module files are not part of this repository.

License

WTFPL (Do What The Fuck You Want To Public License) — see LICENSE.