Configuration File Format

The configuration file lets you specify many of Benben's options, saving you from having to type them in on the command line each time, as well as a few that aren't available via the command line. The file uses the YAML format for ease of use. The first time you run Benben, a default configuration file will be created.

The location of the configuration file depends on your platform:

On Linux/Unix: $XDG_CONFIG_HOME/benben/benben.yaml (this usually means ~/.config/benben/benben.yaml).

Note that command line options can still override the configuration file. So you can have your configuration file set to loop each song 3 times, you still use the --loop parameter to temporarily change to another value.

Important Note

The configuration format is not considered stable, and won't be until Benben v1.0. Until then, you may have to make small adjustments when upgrading between versions. These changes will be noted in the release notes for each version of Benben.

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.

These 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.

Each song specific config has a new 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 my 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
preferred-tag-lang
vu-meter
ui

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

Options

The main configuration options:

Key	Type	Description
`audio-driver`	One of: `pulse_audio`, `port_audio`, `ao`, `any`	The output driver used to produce sound during playback. Use `benben --driver list` to see a list of valid options. Default: `pulse_audio`.
`buffer-size`	An integer that is at least 256, and evenly divisible by 256	The size of the audio buffer. Note that this also affects the smoothness of the VU meter. In most cases, this doesn't need changing. Default: `1024`.
`sample-rate`	Integer between 8000 and 352800	The output sample rate, in hertz. The default is `44100`.
`resampler`	One of: `Linear`, `ZeroOrderHold`, `SincFastest`, `SincMedium`, `SincBest`	The resampler mode to use when playing a file that does not match the `sample-rate` setting. The default is `SincFastest`.
`stderr-logging`	One of: `full`, `crystal_only`, `none`	When this is `full`, then all messages that would normally be printed to standard error will instead appear in `~/.local/share/benben/stderr.log` (or wherever $XDG_DATA_DIRS is pointing). This includes messages from the audio drivers. When this is set to `crystal_only`, then only messages that originate from the Crystal side of the code will be logged to the file (i.e., audio driver messages won't be logged to that file). If set to `none`, then no stderr messages will be logged, and all of them will instead appear in the terminal like normal. This setting should only be changed by a user who understands what they're doing, and the default (`full`) is fine for nearly all cases.
`max-loops`	An integer between 0 and 4294967295	The maximum number of times to loop if the song has loop information. If the song has no loop information, this is ignored. A value of 0 means "loop forever". Default: 1 (meaning "play once, then loop once")
`repeat-playlist`	`true` or `false`	When `true`, then the player will loop back to the first song once the final song is finished playing. This only has an effect during playback, not during rendering. Default: `false`.
`render-jobs`	Integer >= 1	The number of workers to use when rendering in parallel. This must be at least 1, and defaults to the number of logical CPU cores you have.
`fadeout-seconds`	An integer between 0 and 255	The number of seconds a looping song will fade out when finished. Default: 5
`main-volume`	Float between 0.0 and 2.0	The main output volume. Default: 1.0
`no-soft-clipping`	`true` or `false`	When `true`, soft clipping is disabled by default. Default: `false`..
`enable-stereo-enhancer`	`true` or `false`	When `true`, this enables a stereo enhancement effect. Default: `false`..
`stereo-enhancement-amount`	Float between 0.0 and 1.5	The amount of stereo enhancement to apply to the output signal. This requires `enable-stereo-enhancer` to be `true`. This can go from 0.0 (nearly monaural) to 1.5 (very wide). The default is 0.5, which is the same as not enabling this effect.
`reverb-enabled`	`true` or `false`	When `true`, then a reverb effect will be enabled by default. Default: `false`..
`reverb-type`	`mverb` or `zita`	The type of reverb to apply when reverb is enabled. Default: `mverb`.
`reverb-amount`	Float between 0.0 and 1.0	The amount of reverb to apply when reverb is enabled. Default: 0.5.
`mverb-reverb-preset`	String	The preset to use for the reverb when reverb is enabled and `reverb-type` is set to `mverb`. Default: `GmDefault`. Use the command line option `--reverb-preset list` together with `--reverb-type` to see a list of presets for that type.
`zita-reverb-preset`	String	The preset to use for the reverb when reverb is enabled and `reverb-type` is set to `zita`. Default: `GmDefault`. Use the command line option `--reverb-preset list` together with `--reverb-type` to see a list of presets for that type.
`preferred-gd3-lang`	One of: `english`, `japanese`, `toggle_prefer_english`, or `toggle_prefer_japanese`	The default language in which to display GD3 tag info. Default: `japanese`. This can be toggled during playback with the `t` key.
`ui`	User interface config block (see below)	The settings for the user interface, minus the VU meter..
`emulators`	Emulator config block (see below)	Sets emulator-specific settings.
`vu-meter`	VU Meter config block (see below)	Configuration section for the VU meter.
`equalizer-enabled`	`true` or `false`	When `true`, an equalizer effect will be applied to the output. You can still turn on and off the equalizer by pressing the `e` key during playback.
`equalizer-disabled-during-rendering`	`true` or `false`	When `true`, no equalizer effect will be applied to the output when rendering a VGM to WAV/Au. This only takes effect when rendering to files.
`equalizer`	Equalizer config block (see below)	Configuration section for the equalizer.

** Emulator Config Block:**

`dmg-boost-wave-chan`	`true` or `false`	Doubles the volume of the wave channel when playing GameBoy music. Default: `true`
`huc6280-core`	`mame` or `ootake`	Determines the emulation core used for music that uses the HuC6280 chip (e.g. PC Engine/TurboGrafx-16). Default: `ootake`
`ym2151-core`	`mame` or `nuked`	Determines the emulation core used for music that uses the YM2151 chip. Default: `mame`

** VU Meter Config Block:**

Key	Type	Description
`bar-character`	Any Unicode character	This is the character that is used to draw the VU meter bar. Default: `■`.
`tip-character`	Any Unicode character	This is the character that is used to draw the tip of the VU meter bar. Default: `▶`.
`clipped-channel-time`	An integer between 1 and 255, inclusive.	The amount of time in seconds that the VU meter will show the channel name in red if clipping occurs. Default: 2.
`colors`	An array of integers between 0 and 255, inclusive	The ANSI terminal colors to use for the VU meter segments. The VU meter will be divided up into as many segments as there are colors, with the first color being the left-most (most quiet) segment. There must be at least one color, and there can not be more than 70. You can use any ANSI 8-bit color index. Default: `[1, 3, 2]` (red, yellow, green)

** User Interface Config Block:**

Key	Type	Description
`animations-enabled`	`true` or `false`	When true, then various animations will be displayed by the user interface. This does not affect the VU meters. Default: `true`.
`tip-character`	Any Unicode character	This is the character that is used to draw the tip of the VU meter bar. Default: `▶`.
`clipped-channel-time`	An integer between 1 and 255, inclusive.	The amount of time in seconds that the VU meter will show the channel name in red if clipping occurs. Default: 2.
`colors`	An array of integers between 0 and 255, inclusive	The ANSI terminal colors to use for the VU meter segments. The VU meter will be divided up into as many segments as there are colors, with the first color being the left-most (most quiet) segment. There must be at least one color, and there can not be more than 70. You can use any ANSI 8-bit color index. Default: `[1, 3, 2]` (red, yellow, green)

Equalizer Config Block:

Key	Type	Description
`post-gain`	Float	The amount of gain to apply to the signal after the EQ has processed it, in decibels. Default: 0.0 (no change to the signal).
`low-shelf`	Low-Shelf config block (see below)	The settings for the low shelf filter.
`bands`	An array of Band config blocks (see below)	An array of peaking EQ bands for the equalizer. There can be as many or as few as you wish.
`high-shelf`	High-Shelf config block (see behigh)	The settings for the high shelf filter.

Low-Shelf Config Block:

Key	Type	Description
`frequency`	Float between 20.0 and 22050.0	The cutoff frequency for the low shelf in hertz. Default: 80.0.
`gain`	Float	How much the volume of the signal under the low shelf is adjusted, in decibels. Default: 0.0
`bandwidth`	Float	How wide the transition band of the filter is, in octaves. Default: 0.707.

Band Config Block:

Key	Type	Description
`frequency`	Float between 20.0 and 22050.0	The center frequency of the band, in hertz.
`gain`	Float	How much the volume of the signal around the center frequency is adjusted, in decibels.
`bandwidth`	Float	The width of the band, in octaves.

High-Shelf Config Block:

Key	Type	Description
`frequency`	Float between 20.0 and 22050.0	The cutoff frequency for the high shelf in hertz. Default: 80.0.
`gain`	Float	How much the volume of the signal under the high shelf is adjusted, in decibels. Default: 0.0
`bandwidth`	Float	How wide the transition band of the filter is, in octaves. Default: 0.707.

Example Configuration Files

Example of a main configuration file:

audio-driver: any
buffer-size: 1024
sample-rate: 44100
max-loops: 1
repeat-playlist: false
render-jobs: 20
fadeout-seconds: 5
no-soft-clipping: false
enable-stereo-enhancer: false
stereo-enhancement-amount: 1.0
main-volume: 1.0
preferred-gd3-lang: japanese
ui:
  animations-enabled: true
emulators:
  dmg-boost-wave-chan: true
  huc6280-core: ootake
  ym2151-core: mame
vu-meter:
  bar-character: ■
  tip-character: ▶
  colors:
  - 2
  - 3
  - 1
  clipped-channel-time: 2
equalizer-enabled: false
equalizer-disabled-during-rendering: false
equalizer:
  low-shelf:
    frequency: 80.0
    gain: 0.0
    bandwidth: 0.707
  bands:
  - frequency: 105.0
    gain: 0.0
    bandwidth: 1.0
  - frequency: 800.0
    gain: 0.0
    bandwidth: 1.0
  - frequency: 4600.0
    gain: 0.0
    bandwidth: 1.0
  high-shelf:
    frequency: 12000.0
    gain: 0.0
    bandwidth: 0.707
reverb-enabled: false
reverb-type: mverb
reverb-amount: 0.5
mverb-reverb-preset: GmDefault
zita-reverb-preset: GmDefault

Example song-specific config file that overrides a few settings:

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