1.1 Introduction

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.

Benben is written almost entirely in the Crystal programming language.

1.2 Supported Input Formats

• VGM files
  • - Uncompressed (.vgm)
  • - GZip compressed (.vgz)
  • - ZStandard compressed (.vgzst)
  • - BZip2 compressed (.vgb)
• MPEG-1
  • - MPEG-1 Layer III (.mp3)
  • - MPEG-1 Layer II (.mp2)
  • - MPEG-1 Layer I (.mp1)
• Ogg Vorbis
• Opus
• FLAC
• General MIDI (.mid, .rmi)
• MUS (.mus)
• All module formats supported by libxmp
• Commodore 64 SID (.sid)
• RIFF WAVE (.wav)
• QOA, the Quite OK Audio format
• WavPack
• Sun Au (.au)

1.3 Supported Output Formats

• RIFF WAVE (.wav), PCM or IEEE float samples
• Sun Au (.au), PCM or IEEE float samples
• QOA, the Quite OK Audio format
• WavPack

1.4 History

Before Benben...

Before Benben ever existed, Remilia started work on a port of a SoundFont synthesis library called MeltySynth¹ from C# to Crystal. Her port of this software was called ². As part of her port, she included a simple command line player called midi123, which was very bare bones and was intended to be nothing more than an example/test player for the library. However, it quickly grew to be more than a simple example and eventually became a standalone command-line player for General MIDI files.

About a year later, Remilia started to work on creating a VGM playback library called YunoSynth³ for native Crystal. This was partially a port of vgmplay⁴ from C, and partially an object-oriented rewrite. Similar to midi123, and using its code as a base, Remilia also created a companion command-line player for YunoSynth called Benben.

The first few version of Benben only played VGM files (or their compressed variants), and used raw ANSI console commands to draw its interface. Starting with v0.3.0, Benben moved to an interface built with S-Lang (more accurately, her own Crystal bindings to S-Lang). Remilia also found herself continually wishing that Benben could play other formats so that she wouldn’t have to switch between audio players, and so beginning with v0.5.0, Benben became a general-purpose music player that supports multiple input formats.

2.1 Playing Files

Benben is a command line program. To play a file, simply pass it as an argument to Benben:

benben coolsong.mp3

Multiple files can also be specified, one after another. They will be played in the order that you list them:

benben coolsong1.mp3 other-directory/coolsong2.flac coolsong3.vgm

If you specify a directory, then Benben will play all files in that directory in alphabetical order. It will not recurse into any subdirectories, however.

benben directory-with-music/

Playlists in XSPF⁵ or JSPF⁶ format can also be used. These can be passed in like any other file, and their contents will be queued up in the same order that the playlist specifies.

benben cool-mix.xspf

Finally, you can mix and match any of these methods as you see fit:

benben cool-mix.xspf coolsong1.flac /directory/with/music/

2.2 User Interface

During playback, a progress bar will be displayed at the bottom. It will look something like this:

[EsCr-] 1/1, 1 of 2: |*****************---------------------|  45% [02:20/05:09]

The characters to the left in brackets indicate the state of various effects and other pieces of information. These are, in order from left to right:

‘E’

EQ is on.

‘e’

EQ is off.

‘S’

Stereo enhancer is on.

‘s’

Stereo enhancer is off.

‘C’

Soft clipping is on.

‘c’

Soft clipping is off.

‘R’

Reverb is on.

‘r’

Reverb is off.

‘+’

A song-specific config was found for the current song and loaded. See Song-specific Config Files

‘-’

A song-specific config was not found for the current song. See Song-specific Config Files

Next to these characters will be the current track, a slash, and then total number of tracks. Following this is the loop information (e.g. ‘1 of 2’ means “currently in the first loop out of two”). When the loop information displays as ‘1 of *’, then the song is looping indefinitely. Note that for VGM files, if the song does not have any loop information in it, then this will always read as ‘1 of 1’.

2.3 Keyboard Input

The program will respond to various keys during playback. These are listed below, and you can also press the h key to see them while Benben is running.

n

Go to the next file in the playback queue. If the --repeat option is used and you are already on the last item in the queue, then Benben will loop back to the first item. See Command Line Options

p

Go to the previous file in the playback queue. If you are already on the first item, Benben will simply restart the playback of that item.

t

Toggle the displayed GD3 tag language. Only works for VGM files.

i

Toggle the interpolation mode. Only for module/tracker formats.

c

Toggle soft clipping on and off.

e

Toggle the EQ effect on and off.

s

Toggle the stereo enhancer effect on and off.

r

Toggle the reverb effect on and off.

a

Raise the volume.

z

Lower the volume.

]

Increase the number of times the song loops. Not all formats support this.

[

Increase the number of times the song loops. Not all formats support this.

q

Quit the program.

R

Redraws the entire screen.

S

Toggles the “stop after current song” behavior. When stopping after the current song, Benben will exit once the current song finishes playing or you hit n to move to the next file.

C

Reloads all song-specific configuration files. See Song-specific Config Files

T

Reloads the current theme from disk.

>

Seeks forward a bit. Not all formats support this.

<

Seeks backwards a bit. Not all formats support this.

x

Toggles the chorus effect. This only works for General MIDI files.

I

Show extended information about the currently applied effects and resampler.

space

Pause/unpause playback.

P

Toggle repeat of the entire song queue.

4.1 Playing SID Songs

To play all songs in a SID file, simply pass it in on the command line like usual:

benben CYBERNOID.SID

Selecting a single song out of a SID file is also possible, for example to select the second song in a SID:

benben LAST_NINJA_2.SID@2

you can also select a set of individual songs:

benben ROBOCOP3.SID@2,4,7

Finally, a range of songs can also be selected:

benben COMMANDO.SID@1-3

All of these techniques are also possible from playlist files.

4.2 SID Songlength Database

SID files are unusual in that they do not contain information about how long a song is. This is remedied by use of a songlengths database. This is an INI-format file that simply stores length information about known SID files. The High Voltage SID Collection site has an up-to-date songlengths database file available for download that will cover nearly all known SID files, and is the recommended way to inform Benben about the length of SID songs.

To use a database, first download it and place it somewhere on your computer. Then open up your Benben configuration file and add this line, replacing the path with the path of the file you just downloaded. Note that you may already have a c64 section; if you do, add the song-length-db line under your existing section, otherwise create a new c64 section. See Configuration

c64:
  song-length-db: /path/to/your/Songlengths.txt

If a song is not found in the database, or if you do not use a songlength database, then Benben will instead play the song using a “default” song length. This length is 180 seconds by default, but can be configured to a different length in your configuration file. See Configuration

c64:
  default-song-length: 300  # This value is in seconds

You can also change this on command line using --sid-def-length. See Command Line Options

4.3 ROM Files

Benben will play most SID files without issue out-of-the-box. However, a few SID files may require dumps of various ROM chips from a Commodore 64, specifically the KERNAL, BASIC, and CHARGEN ROMs. You should be able to find these with a bit of clever Internet searching. Once you have downloaded these, place the relevant options into Benben’s configuration file. See Configuration

c64:
  kernal-rom: /home/remilia/doc/c64/kernal
  basic-rom: /home/remilia/doc/c64/basic
  chargen-rom: /home/remilia/doc/c64/chargen

5.1 Example Configuration File

buffer-size: 256
audio-driver: pulseaudio
sample-rate: 44100
fadeout-seconds: 5
repeat-playlist: false
render-jobs: 8
main-volume: 1.0
max-loops: 1
resampler: sincbest
replay-gain: album
tcp-driver-format: f32
remote: true

enable-stereo-enhancer: false
stereo-enhancement-amount: 1.1
no-soft-clipping: false
soft-clipping-oversampling: 4
reverb-type: mverb
reverb-enabled: false
reverb-amount: 0.369

vgm:
  preferred-gd3-lang: toggle_prefer_english

modules:
  default-panning: 69
  interpolation: spline
  fade-out-songs: false

midi:
  soundfont: "/home/remilia/doc/soundfonts/sc-55.sf2"
  reverb-enabled: true
  reverb-type: mverb

c64:
  song-length-db: /home/remilia/doc/c64-songlengths.txt
  default-song-length: 180
  kernal-rom: /home/remilia/.local/share/sidplayfp/kernal
  basic-rom: /home/remilia/.local/share/sidplayfp/basic
  chargen-rom: /home/remilia/.local/share/sidplayfp/chargen
  default-c64-model: ntsc
  default-sid-model: mos6581
  sampling-method: ResampleInterpolate

ui:
  animations-enabled: true
  theme: [plum, smooth-neon, blue-phosphor, phosphor, semi-retro, remilia]
  banner: [graffiti, stronger]

equalizer-enabled: true
equalizer-disabled-during-rendering: true
equalizer:
  post-gain: 0.0
  low-shelf:
    frequency: 80.0
    gain: 2.0
    bandwidth: 1.0
  bands:
    - frequency: 105.0
      gain: 2.78
      bandwidth: 0.6
    - frequency: 275.0
      gain: -6.0
      bandwidth: 0.2
    - frequency: 6000.0
      gain: 1.5
      bandwidth: 1.0
  high-shelf:
    frequency: 9001.0
    gain: 1.4
    bandwidth: 0.9

5.2 Configuration Options

• Main Options
• VGM Config Block
• Emulator Config Block
• UI Config Block
• Modules Config Block
• MIDI Config Block
• C64 Config Block
• Equalizer Config Block

5.3 Song-specific Config Files

In addition to the main config file, you can specify alternative configurations for specific song files or directories. These are matched using globbing⁸. When Benben notices you are playing a song file that matches one of these song-specific configurations, it will use the settings in that file to temporarily override your main configuration settings (the command line can still override everything, however). This lets you easily create settings specific to entire groups of songs. For example, I normally have the equalizer enabled, but I have specific settings for one album that disables the equalizer.

Song-specific config files reside in:

On Linux/Unix

$XDG_CONFIG_HOME/benben/song-configs/ (this usually means ~/.config/benben/song-configs/).

The filename for every song-specific configuration file must start with song-config- and end in .yaml. For example, song-config-x68k-eq.yaml.

Song-specific config files follow the same basic format as the main configuration file, with a few changes. The most important change is that song-specific config files have an additional key, match, that lets you specify one or more patterns that will be used to match files. For example, the file song-config-x68k-eq.yaml on my system has this line at the very top:

match:
  - /mnt/nanako/vgms-and-mods/VGMs/X68000/**/*.vg?

This specifies that any VGM file in any subdirectory under /mnt/nanako/vgms-and-mods/VGMs/X68000/ gets this song-specific config applied to it during playback. Any songs that don’t match this pattern (or any pattern in any other song-specific config files I may have) use the settings in the main config file.

Any keys within a song-specific configuration file will override the main configuration settings (command line arguments still override everything). Keys that are missing from the song configuration file will be filled in with the values from the main configuration file, or the defaults.

Song configuration files are almost identical to the normal configuration file format, except they ignore the following keys:

• audio-driver
• buffer-size
• render-jobs
• sample-rate
• ui
• repeat-playlist
• resampler
• seek-time
• equalizer

All other keys are valid. See Main Options

You can use benben --dump-song-config to print a new config to standard output that you can then modify as you wish.

5.4 Example Song-Specific Config File

match:
  - /mnt/nanako/vgms-and-mods/VGMs/X68000/**/*.vg?

equalizer:
  post-gain: 0.0
  low-shelf:
    frequency: 80.0
    gain: 2.7
    bandwidth: 1.8
  bands:
    - frequency: 105.0
      gain: 2.98
      bandwidth: 0.9
    - frequency: 275.0
      gain: -6.0
      bandwidth: 0.2
    - frequency: 6000.0
      gain: 1.5
      bandwidth: 1.0
  high-shelf:
    frequency: 9001.0
    gain: 1.4
    bandwidth: 0.9

6.1 Specifying a Theme

The theme to use is specified in your main configuration file in the ui-config section (See Configuration):

ui-config:
  theme: default

You can also change the theme on the command line:

benben --theme smooth-neon coolfile.mp3

The name of the theme depends on its filename. As mentioned previously, the filename of each theme must use the format theme-<theme name>.yaml. So for example, a theme stored in a file named theme-dark-custom.yaml is named “dark-custom” and can be specified using benben --theme dark-custom.

To see a list of available themes, use the --list-themes argument. See Command Line Options

6.2 Theme File Format

Note that color values can be expressed multiple ways. See Color Values

• Color Values
• My Theme Isn’t Working!

export COLORTERM=truecolor

6.3 Example Theme File

bg-color: 0
fg-color: 250
header-color: 255
err-color: 196
cur-song-color: 201
prev-song-color: 242
next-song-color-1: 244
next-song-color-2: 239
next-song-color-3: 236
song-queue-box-color: 250
song-queue-header-color: 99

progress-bar-char: "*"
progress-bar-space-char: "-"
progress-bar-colors: [[170, 170, 170]]

vu-clip-color: 196
vu-clipped-channel-time: 1
vu-bar-character: "\u25A0"
vu-tip-character: "\u25B6"
vu-colors:
  - 105
  - 117
  - 119
  - 190
  - 206
  - 161

7.1 Using The remote-benben Program

The remote-benben program allows full control of Benben. The program will connect to the default socket automatically. There is currently one option, --socket, which lets you connect to an alternate UNIX domain socket. You can get help by passing the --help option to the program.

The basic usage of remote-benben is:

remote-benben [options] <command>

To see a list of all commands, use this:

remote-benben cmd-help

Here are various examples of how to use the program. This is not an exhaustive list of commands:

$ remote-benben next  # Go to the next song

$ remote-benben prev  # Go to the previous song

$ remote-benben pause  # Toggle whether or not Benben is paused

$ remote-benben loop-up  # Increase number of times the song loops

$ remote-benben title  # Get the title of the currently playing track

7.2 remote-benben Commands

General Commands

cmd-help

Displays a listing of all commands.

help

Same as cmd-help.

exit

Tells Benben to exit.

ver

Returns Benben’s version information.

proto-ver

Returns the version of the Benben Remote Protocol that’s in use.

Control Commands

next

Go to the next track.

prev

Go to the previous track.

ff

Seek forwards.

rw

Seek backwards.

lang

Toggles the displayed tag language (if applicable to the currently playing song).

vol-up

Increases the volume.

vol-down

Decreases the volume.

pause

Toggles whether or not Benben is paused or playing.

stop-after

Toggles the “stop after current track” setting.

Effect Commands

eq

Toggles the equalizer on or off.

soft-clip

Toggles soft-clipping on or off.

stereo

Toggles the stereo enhancer on or off.

reverb

Toggles the reverb effect on or off.

interp

Toggles the interpolation type (if the format supports interpolation).

chorus

Toggles the chorus effect on or off (if the format supports it).

Looping Commands

loop-up

Increase the number of times the song will loop.

loop-down

Decrease the number of times the song will loop.

cur-loop

Returns the current playback loop.

max-loops

Returns the current maximum number of playback loops.

repeat

Toggles repeating of the entire song queue.

Track Info Commands

track

Returns the current track number (that is, the current track’s position in the song queue).

num-tracks

Returns the total number of tracks in the song queue.

format

Returns the current track’s format.

format-num

Returns the current tracks’ numerical format identifier.

track-len

Returns the length of the track.

track-pos

Returns the current playback position of the track.

all-tracks

Returns detailed information about all tracks in the song queue. The data returned is serialized using JSON.

Tag Info Commands

Not all formats have tag information, or have different information that what you can request. So, asking for the “genre” may actually return something other than the track’s genre, depending on the format. For example, module files map the number of patterns to the genre field. The program understands this and will display the result correctly.

title

Returns the song title.

artist

Returns the track’s artist.

album

Returns the track’s album.

date

Returns the track’s release date.

genre

Returns the track’s genre.

Other Commands

stop-after?

Returns whether or not the “stop after current track” setting is currently enabled. A return value of false means that this is disabled.

status

Returns the status of the player. This may return one of the following values: Paused (Benben is paused), Frame (Benben is playing), Fadeout (Benben is playing and is fading out the current song), Tails (Benben is playing and is in-between tracks), Done (Benben is about to move to a new track).

8.1 Sample Foramts

f64

64-bit IEEE floating point samples. Overkill in nearly all cases. This transmits eight bytes per sample of audio.

f32

32-bit IEEE floating point samples. The default format, and what Benben also uses when using other drivers. This transmits four bytes per sample of audio.

i64

64-bit signed integer PCM. Overkill in nearly all cases. This transmits eight bytes per sample of audio.

i32

32-bit signed integer PCM. This transmits four bytes per sample of audio.

i24

24-bit signed integer PCM. This transmits four bytes per sample of audio (not three).

i16

16-bit signed integer PCM. This is what CD audio uses. This transmits two bytes per sample of audio.

i8

8-bit signed integer PCM. This transmits one byte per sample of audio.

u8

8-bit unsigned integer PCM. This transmits one byte per sample of audio.

8.2 Example Using aplay As a Client Over SSH

One possible use of the TCP driver is to transmit audio from one machine to another, then play the audio using the aplay command on the other machine. This is a command that comes with ALSA, so it may not be available on non-Linux platforms, so you may need to adjust this example if you are on something like BSD.

This example assumes you have basic knowledge of SSH and how SSH port forwarding works, and are comfortable with the command line.

Let’s assume we have two machines: computer1 and computer2. Benben is installed on computer1 and is configured to send audio over TCP to localhost:6969. We want to hear that audio on computer2. The first thing we want to do is connect to computer1 from computer2 using SSH and forwarding the proper port. So let’s start on computer2:

[user@computer2]$ ssh -L 6969:computer1:6969 computer1

Next, on computer1, we launch Benben with the TCP driver. This will cause it to open a socket on computer1 port 6969:

[user@computer1]$ benben --driver tcp cool-song.mp3

Audio is now ready to be transmitted over port 6969. Since we’ve forwarded it over SSH, this port is now available on computer2. So, back on computer2, we then use netcat and aplay to receive the audio and play it. Note that we have to tell aplay the format, the number of channels, and the sample rate because this is raw audio that we’re sending:

[user@computer2]$ nc localhost 6969 | aplay -f FLOAT_LE -c 2 -r 44100 -

At this point, the song will begin playing on computer1 and you’ll hear it on computer2. You can control Benben directly on computer1, or use remote-benben via your SSH connection to control it. Or, you could even forward the UNIX domain socket over SSH and tell remote-benben to use the forwarded socket. At this point, the sky is the limit.