Benben

Benben is a fast and efficient command line VGM player and VGM->WAV converter for Linux/Unix that uses Remilia's YunoSynth library for its VGM playback engine. It is written entirely in the Crystal programming language.

Releases and AppImages for x86-64 Linux systems can be found on the Releases wiki page. To build the program from source, or for other operating systems such as Dragonfly BSD, please consult the "Building from Source" section below.

Want to listen to MIDI files instead? Try Remilia's midi123 program.

Wanna support this project? Buy Remilia a coffee on Ko-Fi, or support her through Liberapay.

Example videos

• Sega Genesis/Mega Drive - Elemental Master - "Like The Wind"
• MSX - Impact MuSiX Disk #2 - "Ending 0.01"
• Sega Genesis/Mega Drive - Sonic the Hedgehog - "Green Hill Zone"
• Arcade - Toki - Stage 1 music
• Arcade - After Burner II - "After Burner (Melody Version)"
• Neo Geo - Metal Slug X - "Judgement -X-"
• X68000 - Granada - "Advance 'GRANADA' (Opening Theme)"
• PC-98 - Rusty - "Queen in The Night"
• PC Engine/TurboGrafx-16 - Soldier Blade - "Operation 1"
• Benben rendering 61 files in parallel to WAV

This example includes added reverb to show off the reverb effect:

• Arcade - Soul Edge - "Epic Calling!"

Basic Usage

Benben is a command line program. To play a VGM, run Benben with the VGM/VGZ files you want to play as parameters. Multiple files can be specified, and they will be played in the order that they appear on the command line. VGZST and VGB files are also supported.

Hardware requirements are pretty low: A 4-core CPU from around 2009 and 128MB RAM are the recommended minimum. Essentially it should run on most recent CPUs, as well as a PineBook Pro or Raspberry Pi 4 (or similar). Releases are tested on an emulated Nehalem-v2 CPU and a PineBook Pro. RAM usage depends on a few things: the song you're playing, if you enable the reverb, if you're playing songs over HTTP/Gemini, etc. Rendering multiple songs in parallel will also consume more RAM. But in many cases, Benben's RAM usage will be under 40MB.

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 play queue.
• p: Go to the previous file in the play queue.
• t: Toggle the displayed GD3 tag language.
• 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.
• [: Increase the number of times the song loops.
• q: Quit the program.
• space: Pause/unpause playback.

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.
• +: Song-specific config was found for the current song and loaded.
• -: Song-specific config was not found for the current song.

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 if the song does not have any loop information in it, then this will always read as 1 of 1.

Configuration

There is also a configuration file where you can set various options so that you don't need to always type in the command line parameters. The location for this file is $XDG_CONFIG_HOME/benben/benben.yaml (this usually means ~/.config/benben/benben.yaml).

Command Line Examples

Below are various examples of how to call Benben on the command line.

# Play a VGM file and stop after it finishes
$ benben "Cool Song.vgz"

# Play a VGM and loop twice
$ benben --loop 2 "Another Cool Song.vgz"

# Render multiple VGM files to WAVs in parallel
$ benben --render *.vgz

# Show the help information
$ benben --help

# Show version information
$ benben --version

# List reverb presets for "MVerb"
$ benben --reverb-type mverb --reverb-preset list

Notable Features

• PulseAudio, PortAudio, and libao backends
• High-performance playback.
• Multiple files can be specified and they will play one after the other.
• Song and playlist looping.
• Support for all the chips that supported by YunoSynth.
• Support for uncompressed VGMs, gzip compressed VGMs (.vgz), and additional non-standard formats.
• Support for XSPF and JSPF playlists
• Configuration file support, including support for per-song configurations.
• Rendering multiple files in parallel to either WAV or Au format.
• Support for multiple bit depths and sample rates, and both integer and floating point WAV/AU files.
• Optional effects:
  • Soft clipping.
  • Parametric EQ with an arbitrary number of bands.
  • Stereo enhancement effect.
  • Reverb with selectable type and preset.
• Customizable VU meter
• Keyboard control support

Building from Source

Note: only Linux is officially supported at the moment. Other platforms may build successfully, but you may need to change some of the source files in either Benben, or its dependencies.

You will need Fossil installed to clone this repo and the dependency. You will also need Shards v0.17.1 or later. If you have an earlier version of Shards, you will need to to build the latest version manually.

To build the program, start out by cloning this Fossil repository somewhere and changing into the directory.

fossil clone https://chiselapp.com/user/MistressRemilia/repository/benben
cd benben

You can then use rake to build things in the following ways:

• rake: Builds an optimized binary.
• rake help: See the various options for building the binary.
• rake benben[debug]: Builds a non-optimized debug build.
• rake benben[normal]: Builds an optimized binary.
• rake benben[fast]: Builds an optimized, striped binary.

There are more detailed instructions in the wiki.

Development

Development Milestones are listed in the wiki.

How do I contribute?

1. Go to https://chiselapp.com/user/MistressRemilia/repository/benben and clone the Fossil repository.
2. Create a new branch for your feature.
3. Push locally to the new branch.
4. Create a bundle with Fossil that contains your changes.
5. Get in contact with me.

Contributors

• Remilia Scarlet - creator and maintainer
  • Homepage: https://remilia.sdf.org/
  • Fediverse: @remilia@nanako-さめ.mooo.com
  • Email: zremiliaz@postzeoz.jpz My real address does not contain Z's

Links and Licenses

Benben is under the GNU Affero General Public License version 3.