Benben(1)

Name
Benben - Playback and render audio files

SYNOPSIS

benben [options] <files/playlists/directories/URLs...>

DESCRIPTION

Benben is a fast and efficient command line audio player and audio converter for Linux and other Unix-like systems with an oldschool-inspired interface. It supports multiple formats, and is especially suited to people who organize their music in folders, and for those who prefer to use terminals instead of GUIs. It supports the following input formats:

•   Uncompressed VGM <https://vgmrips.net/> (.vgm)

•   GZip compressed VGM (.vgz)

•   ZStandard compressed VGM (.vgzst)

•   BZip2 compressed VGM (.vgb)

•   MPEG-1 Layer III (.mp3)

•   MPEG-1 Layer II (.mp1)

•   MPEG-1 Layer I (.mp1)

•   Ogg Vorbis

•   Opus

•   FLAC

•   General MIDI (.mid)

•   MUS (.mus)

•   All module formats supported by libxmp <https://github.com/libxmp/libxmp/>

•   Commodore 64 SID (.sid)

•   RIFF WAVE (.wav)

•   QOA, the Quite OK Audio format

•   Extended QOA Format (XQA)

•   WavPack

•   Sun Au (.au)

•   XSPF playlists

•   JSPF playlists

•   Doom WAD files

    When rendering to files (that is, converting audio files), the bit depth defaults to 16. This can be changed using --bit-depth. Support bit depths for integer PCM output are 8, 16, and 24. Supported bit depths for IEEE Float output are 32 or 64. The default bit depth for --float is 32 and the default when not using --float is 16.

    The --bit-depth argument has no effect when just playing back audio; the audio is always rendered as 32-bit float data.

    Pressing h while the program is playing will display the keys that can be used to control the program during playback.

OPTIONS

  General Options

--help, -h
    Show help information.

--version, -v
    Show version information.

--long-version
    Show verbose version information.

--scan-only
    Only scan files, then exit.

--recurse
    Recursively look for files.

--no-recurse
    Do not recursively look for files.

--dump-config
    Generates a fresh configuration file and prints it to standard output, then exits.

--basedir x
    Load configuration data and themes from an alternate directory.

--no-song-configs
    Do not load any song-specific config files.

--remote
    Start up a UNIX domain socket for remote control.

--remote-socket x
    Put the socket for --remote in an alternate location.

--list-themes
    Lists all available themes.

--theme x, -T x
    Use a specific theme.

--ui x
    Use a specific user interface. Use --ui list to see a list of available user interfaces. The default is original.

--no-listnebrainz, -L
    Never submit to ListenBrainz.

  TCP Driver Options

--tcp-driver-host x
    The host to connect to when using the TCP audio driver. Default: localhost

--tcp-driver-port x

The port to connect to when using the TCP audio driver.
    Default: 6969

--tcp-driver-format x
    The audio format to transmit to when using the TCP audio driver (use 'list' to see a list of formats; default: float32)

  Sound Options

--driver x, -d x
    Selects the audio driver to use. Use --driver list to see a list of available drivers. The default is any.

--alsa-device x
    Use a specific ALSA device (ignored if not using the ALSA driver. Default: "default").

--volume x, -v x
    Sets the output volume. The valid range is 0.0 to 3.0, default is 1.0.

--sample-rate x, -S x
    Sets the output sample rate, in hertz. Valid range is 8000 to 48000, default is 44100.

--replay-gain x
    Set the ReplayGain mode (MP3 only; use list to see a list of values; default: disabled)

--resampler x
    Sets the resampler mode. Use 'list' to see a list of modes. Default: linear.

--no-eq, -e
    Start with the equalizer disabled. The equalizer can still be toggled during playback with the e key.

--soft-clipping, -c
    Start with soft clipping enabled on the output. This can still be toggled during playback with the c key.

--no-soft-clipping, -C
    Start with soft clipping disabled on the output. This can still be toggled during playback with the c key.

--soft-clipping-oversampling x
    Changes the amount of oversampling applied when doing soft-clipping. Default: 1.

--soft-clipping-mode x
    Sets the type of resampler to use for oversampling when soft clipping is enabled (default: linear). Uses the same values as --resampler.

--stereo-enhancer, -t
    Start with the stereo enhancer effect enabled. This can still be toggled during playback with the s key.

--stereo-enhancement x, -E x
    Sets the stereo enhancement amount when the stereo enhancer is enabled. The valid range is 0.0 (nearly monaural) to 1.5 (very wide). The default is 0.5, which is equivalent to not having the effect enabled. If the stereo enhancer is not enabled, this does nothing.

--dc-filter
    Start with the DC offset filter enabled.

--no-dc-filter
    Start with the DC offset filter disabled.

--reverb, -r
    Start with the reverb effect enabled. This can still be toggled during playback with the r key.

--no-reverb, -R
    Start with the reverb effect disabled. This can still be toggled during playback with the r key.

--reverb-type x
    Set the type of reverb unit that is used. You can use --reverb-type list to see a listing of valid types. The default is mverb. See the EFFECTS section for more details.

--reverb-preset x
    Changes the reverb unit's parameters to an alternate preset. You can use --reverb-preset list to see a listing of valid types for the selected reverb unit. The default is gm-default. See the EFFECTS section for more details.

--reverb-amount x, -r x
    The amount of reverb to apply to the output. Valid range is 0.0 to 1.0 default is 0.5. This does nothing if the reverb is disabled.

  Playback Options

--loop x, -l x
    The number of times to loop during playback and rendering; a value of 0 means to loop indefinitely. A value of 0 cannot be used when rendering to a file. Only certain formats support looping.

--repeat, -p
    Go back to the first song after the last one has finished playing.

--no-repeat, -P
    Do not go back to the first song after the last one has finished playing. This is mainly meant for overriding the config file setting.

--shuffle
    Randomizes the playback queue before starting playback.

--start-paused
    Start the program in a 'paused' state.

--fadeout-seconds x
    How many seconds to fade out (certain formats only, default: 5)

  VGM Options

--vgm-chip-info
    Displays a list of supported VGM chip emulators, then exits.

--vgm-strict-gd3-loading
    Be strict about GD3 tags when loading the VGM. This disables parallel file checking at startup.

--vgm-dmg-boost-wave-chan
    Boost the WAVE channel in the DMG emulator core.

--vgm-no-dmg-boost-wave-chan
    Do not boost the WAVE channel in the DMG emulator core.

--vgm-ym2612-pseudo-stereo
    Enable the pseudo-stereo effect for the YM2612 emulator core.

--vgm-no-ym2612-pseudo-stereo
    Disable the pseudo-stereo effect for the YM2612 emulator core.

  C64 SID Options

--sid-mono
    Force 2SID and 3SID files to playback as monaural.

--sid-def-length x
    Change the default length for SID songs (in seconds) without length information. Default: 180.

  MIDI Options

--midi-soundfont x
    Use a specific SoundFont for all MIDI files.

--midi-reverb-type x
    Sets the type of reverb for MIDI files. This doesn't affect other formats. Default: mverb (Use --midi-reverb-type list to see valid types).

  Rendering Options

--render, -n
    Tells Benben to render files to WAV (or Au) rather than play them back. Each input file is rendered to its own destination file, where the output name matches the original filename. This renders to WAV by default.

--quiet, -Q
    Don't print any messages or progress, except errors.

--normalize, -N
    Normalize each rendered file so that it's peak is zero dBFS.

--float, -F
    Output files will contain IEEE Floating Point data instead of integer PCM data.

--cue x
    Write a CUE file for the rendered files.

--au, -A
    Render to Au instead of WAV.

--bit-depth x, -b x
    Set the bit depth for the output files. Valid bit depths are 8, 16, 24, 32, and 64. The default is 16 when rendering integer PCM data, and 32 when rendering IEEE floating point data.

--outdir x, -o x
    Where to save the rendered files.

--overwrite
    Overwrite existing files when rendering.

--jobs x
    The number of parallel rendering jobs to use. This is only meaningful when rendering more than one input file. This must be at least 1, and the default is equal to the number of logical CPU cores.

EFFECTS

Benben supports a few optional effects that can be applied during playback: reverberation ("reverb") and stereo enhancement. The reverb effect applies a smoothed "decay" to the sound, similar to what you would hear within a large hall. This can add a lot of depth to the output sound.

The stereo enhancement effect makes sounds appear more "wide". If the sound is mono to begin with, it won't do anything. But, if the input file is in stereo, then this can make the song sound wider than it really is. This is achieved through a phase shifting effect.

Finally, a DC offset filter removes any DC bias <https://en.wikipedia.org/wiki/DC_bias> immediately after applying soft clipping, and before applying any other effects.

FILES

~/.config/benben/benben.yaml The user-specific configuration file.

~/.config/benben/song-configs/song-confg-*.yaml Song-specific configuration files.

~/.config/benben/themes/theme-*.yaml Theme files.

AUTHORS

Benben is written by Remilia Scarlet. Additional information can be found in the README.

COPYRIGHT

Benben is Copyright (C) 2023-2025 Remilia Scarlet. Benben is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License along with this program. If not, see <https://www.gnu.org/licenses/>

Please check the licenses folder in the SatouSynth repository for additional licenses that cover the various emulator cores in SatouSynth: <https://nanako.mooo.com/fossil/satousynth/>

SEE ALSO

•   <https://chiselapp.com/user/MistressRemilia/repository/benben/wiki?name=Configuration+File+Format>

•   <https://chiselapp.com/user/MistressRemilia/repository/benben/wiki?name=Theme+Format>

•   <https://chiselapp.com/user/MistressRemilia/repository/benben/>

Author
Remilia Scarlet <remilia@posteo.jp>

Copyright
Copyright (C) 2023-2025 Remilia Scarlet, Creative Commons BY-NC-SA 4.0