benben

benben [options] [files|directories|playlists]

benben is a fast and efficient command-line audio player and audio converter for Linux and other Unix-like systems with an oldschool-inspired terminal interface. It is written almost entirely in Common Lisp and is designed for users who organize their music in folders and prefer terminal-based tools over graphical interfaces.
benben supports a wide range of audio formats including MP3, Ogg Vorbis, Opus, FLAC, WavPack, WAV, QOA, Sun Au, General MIDI, MUS, Commodore 64 SID, Doom WAD files, and all module/tracker formats supported by libxmp. It has extensive VGM (Video Game Music) format support with chip emulation for over 30 sound chips including YM2612, YM2151, YM2610, NES APU, HuC6280, QSound, and Sega MultiPCM, powered by the SatouSynth library.
The player provides multiple audio output backends (ALSA, libout123, libao) and supports TCP audio streaming. Built-in audio effects include soft clipping with configurable oversampling, a parametric equalizer with arbitrary band count, stereo enhancement, reverb (mverb and zita types with presets), and a DC offset filter. It supports ReplayGain/RVA for volume normalization.
The rendering mode can convert audio files to WAV or Au format in parallel using multiple CPU cores, with options for normalization, configurable bit depth, and floating-point output. XSPF and JSPF playlists are supported, along with ListenBrainz scrobbling and Matrix protocol integration for now-playing updates.
The multi-threaded UI is built on S-Lang and features customizable themes, banner animations, a VU meter, and full keyboard controls. A minimal headless UI is also available for resource-constrained systems or remote control via the companion remote-benben tool over UNIX domain sockets. SID files support song selection syntax using the @ notation (e.g., file.sid@1-3).
benben is command-line only with no file browser by design; users specify files, directories, or playlists as arguments.

-h, --help

Display help information and exit

Show brief version details and exit

Display verbose version information and exit

Scan files only, then terminate

Search subdirectories recursively

Disable recursive subdirectory searching

Generate a fresh configuration and output to stdout

Load configuration and themes from an alternate directory

Enable UNIX domain socket for remote control

Specify alternate socket location for remote control

Display all available themes

Use the specified theme

Select user interface: original or minimal

Disable ListenBrainz submission

Select audio driver (alsa, out123, ao, any)

Use a specific ALSA device (default: default)

Set output volume from 0.0 to 3.0 (default: 1.0)

Set output sample rate in Hz from 8000 to 48000 (default: 44100)

Set ReplayGain mode: disabled, mix, or album

Set resampler mode

Start with equalizer disabled

Start with soft clipping enabled

Start with soft clipping disabled

Oversampling amount when soft clipping is enabled (default: 1)

Enable stereo enhancer effect

Set stereo enhancement amount from 0.0 to 1.5 (default: 0.5)

Enable DC offset filter

Disable DC offset filter

Enable reverb effect

Disable reverb effect

Set reverb unit type: mverb or zita

Use an alternate reverb preset (default: gm-default)

Set reverb amount from 0.0 to 1.0 (default: 0.5)

Loop count; 0 for infinite looping (default: 1)

Loop entire queue when finished

Disable queue looping

Randomize playback queue

Begin playback in a paused state

Fade-out duration in seconds (default: 5)

Display supported VGM chip emulators and exit

Be strict with GD3 tags during VGM loading

Enable pseudo-stereo for YM2612 emulator

Force 2SID/3SID playback as monaural

Default SID song length in seconds (default: 180)

Specify SoundFont file for MIDI playback

Render files to WAV or Au format instead of playing

Suppress non-error messages during rendering

Normalize rendered files to 0 dBFS peak

Render to Au format instead of WAV

Output IEEE floating-point data when rendering

Set bit depth: 8, 16, 24, 32, or 64 (default: 16 for PCM, 32 for float)

Output directory for rendered files

Overwrite existing rendered files

Number of parallel rendering jobs (default: CPU core count)

TCP host to connect to (default: localhost)

TCP port to connect to (default: 6969)

Audio format for TCP transmission (default: float32)

Configuration is stored in $XDG_CONFIG_HOME/benben/benben.yaml (typically ~/.config/benben/benben.yaml) in YAML format. Command-line options override configuration file settings.
Key configuration sections include audio driver and buffer settings, playback defaults (volume, sample rate, loop count, fade-out), audio effects (equalizer bands, soft clipping, stereo enhancer, reverb type and presets, DC filter), VGM emulator preferences (chip cores, GD3 language, pseudo-stereo), MIDI settings (soundfont path, reverb, chorus, voice filter type), C64/SID settings (ROM paths, chip model, songlength database), UI customization (theme, banner style and animation, display preferences), and integration tokens for ListenBrainz and Matrix.
Song-specific configuration files can be placed in $XDG_CONFIG_HOME/benben/song-configs/ as **song-config-*.yaml files, each containing a match** key with glob patterns to apply settings to particular files.
Themes are stored in $XDG_CONFIG_HOME/benben/themes/ as theme-\<name\>.yaml files and support 8-bit ANSI, 24-bit RGB, and hex color notation.

The configuration file format is considered unstable and may change until version 1.0. MIDI playback requires a SoundFont file to be specified. SID song length accuracy depends on having the HVSC songlength database configured; without it, songs default to 180 seconds. The sample rate is limited to a range of 8000 to 48000 Hz. benben has no built-in file browser and requires explicit file or directory arguments. For 24-bit terminal color support, the COLORTERM environment variable may need to be set to truecolor.

benben was created by Remilia Scarlet as a personal project, originally written in the Crystal programming language. Development began around 2023, with the v0.4.0 release announced on March 7, 2024 at VGMRips. The VGM chip emulation was built on the author's YunoSynth library, an OOP rewrite of VGMPlay's sound emulator code. In January 2025, work began on porting benben from Crystal to Common Lisp, with the Lisp-based v0.7.0 becoming the author's daily music player by April 2025. The VGM library was rewritten as SatouSynth for the Lisp version. Version 0.7.1 was released on November 6, 2025. The project is licensed under the GNU Affero General Public License v3 and hosted in a Fossil repository.

mpv(1), ffmpeg(1), sox(1), aplay(1), cmus(1), moc(1)