cli-modplayer
Play tracker music in your terminal
What is this?
A terminal-based player for MOD tracker files. Runs on Linux, plays your .mod, .xm, .s3m, and .it files with a live pattern view like the old ProTracker days.
Shows notes scrolling past, VU meters for each channel, FFT spectrum analyzer, and a real-time oscilloscope. Everything runs in your terminal.
Quick features
- File browser - pick files without typing paths
- Pattern view with notes scrolling in real-time
- VU meters and spectrum analyzer (20 bands, 20Hz-20kHz)
- Oscilloscope showing left and right channel waveforms
- Audio effects - bass boost, echo, reverb, flanger, phaser, chorus
- Export to WAV, MP3, or FLAC with your effects baked in
- Volume control that saves to config
- Module info overlay - see all instruments and messages
- About page with project details
Get it running
You need these packages (Debian/Ubuntu example):
sudo apt install g++ cmake libopenmpt-dev portaudio19-dev
Optional for export formats:
sudo apt install libmp3lame-dev libflac-dev
Build it:
cmake -S . -B build
cmake --build build
Run it:
./build/cli-modplayer
# or
./build/cli-modplayer /path/to/song.mod
How to use it
What's new in 1.3.0
Added About page (press A) with ASCII art, version info, and credits. Module info overlay (press N) now shows everything without limits - all instruments and messages with proper scrolling using arrow keys, j/k, or PageUp/PageDown. Module info and export dialogs dim the background now and info window adapts to content size. Fixed playhead centering (was off by one), export thread doesn't hold mutex for entire duration anymore, arrow keys work properly in overlays, and info shows actual content height. Added file browser that starts when you run the program without arguments - shows only module files (.mod, .xm, .s3m, .it) with file sizes, navigate with arrow keys or j/k, Enter to select, Backspace for parent directory, Home/End to jump around, PgUp/PgDn to scroll fast, Q to quit. Built real-time oscilloscope with separate left (cyan) and right (green) waveforms using 512 samples per channel, updates live from audio stream and sits next to the FFT spectrum analyzer. Renamed project from cli-tracker to cli-modplayer so the executable is now called cli-modplayer. Added FileBrowser class for filesystem stuff, update_waveform() method in Player for capturing audio data, waveform_left and waveform_right fields in TransportState with thread-safe buffer handling. FFT spectrum analyzer with 20 logarithmic bands, audio effects (Bass Boost, Echo, Reverb, Flanger, Phaser, Chorus), export to WAV/MP3/FLAC