Login
Benben
Login

Benben

Benben playing 'Assimilate' by Skinny Puppy Benben is a fast and efficient command line audio player, and audio->WAV converter, for Linux/Unix. It supports multiple formats (see below), and is especially suited to people who organize their music in folders, and for those who prefer to use terminals instead of GUIs.

It is written almost entirely in the Crystal programming language. See "Notable Features" below for more information.

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.

Got another question? Check out the FAQ page!

Wanna support this project? Buy Remilia a coffee on Ko-Fi, or support her through Liberapay. Support is greatly appreciated for this volunteer effort!

Buy Me a Coffee at ko-fi.com Donate using Liberapay

Example Videos (VGM Files)

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

Supported Formats

Basic Usage

Benben is a command line program. To play an audio file, run Benben with the file 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.

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.

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:

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

# Play various files and stop after it finishes
$ benben "Cool Song.vgz" spacedeb.mod "02 - E1M1.flac"

# 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

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. Finally, Ruby is a build-time requirement.

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

Next, run the configure.rb program using Ruby: ruby configure.rb. You can also run ruby configure.rb --help to see the settings that you can customize.

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

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

Links and Licenses

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