Help

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.

Themes

Starting with Benben v0.5.0, theme-related settings have moved to their own file.

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
ui
repeat-playlist
resampler
seek-time
equalizer

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`, `tcp`, `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 48000	The output sample rate, in hertz. The default is `44100`.
`tcp-driver-host`	String	The hostname of the machine to send audio to when using the TCP driver. This only affects the TCP `audio-driver`. The default is `localhost`.
`tcp-driver-port`	An Integer between 1 and 65535	The port of the machine to send audio to when using the TCP driver. This only affects the TCP `audio-driver`. The default is `6969`.
`tcp-driver-format`	One of: `f64`, `f32`, `i64`, `i32`, `i24`, `i16`, `i8`, `u8`	The raw audio format to send when using the TCP driver. This only affects the TCP `audio-driver`. The default is `f32`, meaning 32-bit IEEE Floating Point.
`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
`no-soft-clipping`	`true` or `false`	When `true`, soft clipping is disabled by default. Default: `false`..
`soft-clipping-oversampling`	An Integer between 1 and 65535	How much oversampling to apply when using the soft clipping effect. Default is `1`, meaning "no oversampling".
`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.
`main-volume`	Float between 0.0 and 2.0	The main output volume. Default: 1.0
`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")
`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`.
`seek-time`	An integer between 1 and 65536	How far to seek when fast-forwarding/rewinding. The meaning of this value is format-dependent. Default: `10`.
`replay-gain`	One of: `Disabled`, `Mix`, `Album`	What kind of replay gain to apply. This is only applicable for formats that support ReplayGain. Default: `Disabled`.
`remote`	`true` or `false`	Whether or not to enable remote control via the `remote-benben` program at startup. Default: `false`.
`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.
`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.
`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.
`ui`	UI (User Interface) config block (see below)	The settings for the user interface.
`vgm`	VGM config block (see below)	The settings for VGM files.
`modules`	Module format config block (see below)	The settings for module/tracker files.
`midi`	MIDI format config block (see below)	The settings for MIDI/MUS files.
`c64`	C64 SID format config block (see below)	The settings for C64 SID files.

VGM Config Block:

`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.
`emulators`	Emulator config block (see below)	Sets emulator-specific settings.

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`

User Interface (UI) Config Block:

`animations-enabled`	`true` or `false`	Whether or not animations in the UI are enabled. Default: `true`.
`banner`	A String, or an Array of Strings	The banner to display at the top of the UI. Valid banner names are: `graffiti`, `cyber`, `rounded`, `chunky`, `soft`, `doomed`, `stronger`, `graffiti`. If this value is a string, then only that banner is used. If the value is an array, then a random banner will be chosen from the array values. Default: an array of all possible banners.

Modules Config Block:

`default-panning`	An Integer between 0 and 255	The default amount of panning for modules with no panning information. Default: `69`.
`interpolation`	One of: `Nearest`, `Linear`, `Spline`	What kind of interpolation to apply to the sound. Default: `Linear`.
`fade-out-songs`	`true` or `false`	When true, songs are looped and slowly faded out at the end. Otherwise songs just simply "end" when they're at the end. Default: `false`.

VGM Config Block:

`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.
`emulators`	Emulator config block (see below)	Sets emulator-specific settings.

MIDI Config Block:

`soundfont`	String	The path to the SoundFont file to use when playing MIDI/MUS files. Without a SoundFont, MIDI/MUS files cannot be played. Default: empty string.
`reverb-enabled`	`true` or `false`	When `true`, then a reverb effect will be enabled by default. This setting is specific to MIDI/MUS files since they handle reverb differently. Default: `true`.
`reverb-type`	One of: `mverb`, `zita`, `schroeder`	The type of reverb to apply when reverb is enabled. This setting is specific to MIDI/MUS files since they handle reverb differently. Default: `mverb`.
`reverb-amount`	An Integer between 0 and 255	The default amount of reverb to apply. MIDI/MUS files may still change this per-channel during playback. This setting is specific to MIDI/MUS files since they handle reverb differently. Default: `64`.
`disable-remapping`	`true` or `false`	Whether or not to attempt to map unknown instruments to a known instrument. Default: `false`.
`chorus-enabled`	`true` or `false`	When `true`, then a chorus effect will be enabled by default. This setting is specific to MIDI/MUS files since they handle chorus differently. Default: `true`.
`chorus-amount`	An Integer between 0 and 255	The default amount of chorus to apply. MIDI/MUS files may still change this per-channel during playback. This setting is specific to MIDI/MUS files since they handle chorus differently. Default: `0`.
`chorus-interpolation`	One of: `Linear`, `Cubic`, `Hermite`, `HermiteAlt`, `BSpline`, `Parabolic2X`, `Optimal2X4P2O`, `Optimal32X4P4O`	The type of interpolation to use within the chorus effect. This setting is specific to MIDI/MUS files since they handle chorus differently. Default: `Cubic`.
`voice-filter-type`	One of: `Standard`, `Cem`, `Ssm`, `Hornet`, `MS20`, `Disabled`	What type of filter to use for voices. `Standard` is the standard filter as described by the SoundFont specifications, and changing this value may cause your MIDI/MUS files to sound unintentionally different. Default: `Standard`.
`channel-filter-type`	One of: `Standard`, `Cem`, `Ssm`, `Hornet`, `MS20`, `Disabled`	What type of filter to use for channels that request a lowpass filter to be applied during playback. `Standard` is the standard filter as described by the SoundFont specifications, and changing this value may cause your MIDI/MUS files to sound unintentionally different. Default: `Standard`.
`fadeout`	`true` or `false`	When `true`, then each MIDI/MUS will be looped and slowly faded out at the end. When `false`, then the songs simply "end" at the end. Default: `false`.
`post-track-seconds`	An Integer between 0 and 255	How much extra time to add at the end of a track. This is useful to hear the reverbs/instruments slowly fade out at the end rather than abruptly stop, so it's recommended that you leave it at the default or higher. Default: `4`.
`mverb-reverb-preset`	String	The preset to use for the reverb when reverb is enabled and `reverb-type` is set to `mverb` in the `midi` block. This setting is specific to MIDI/MUS files since they handle reverb differently. Default: `GmDefault`.
`zita-reverb-preset`	String	The preset to use for the reverb when reverb is enabled and `reverb-type` is set to `zita` in the `midi` block. This setting is specific to MIDI/MUS files since they handle reverb differently. Default: `GmDefault`.
`schroeder-reverb-preset`	String	The preset to use for the reverb when reverb is enabled and `reverb-type` is set to `schroeder` in the `midi` block. This setting is specific to MIDI/MUS files since they handle reverb differently. Default: `GmDefault`.

C64 Config Block:

`song-length-db`	String	The path to the songlength's database file, as found on High Voltage Sid Collection. Default: empty string (no database).
`default-song-length`	An integer between 1 and 4294967295	The default amount of time in seconds to play a SID file when it is not found in the `song-length-db` database, or when no database is loaded. Default: `180`
`kernal-rom`	String	The path to a Commodore 64 KERNAL ROM file. Default: empty string. Note: the spelling is purposely "kernal".
`basic-rom`	String	The path to a Commodore 64 BASIC ROM file. Default: empty string.
`chargen-rom`	String	The path to a Commodore 64 Character (CHARGEN) ROM file. Default: empty string.
`default-c64-model`	One of: `Pal`, `Ntsc`, `OldNtsc`, `Drean`	The default model of Commodore 64 to emulate when a SID file does not specify a model. `Pal` for European PAL-B model, `Ntsc` for American/Japanese NTSC-M models, `OldNtsc` for NTSC-M models with old video chip, and `Drean` for Argentinian PAL-N model. Default: `Ntsc`.
`force-c64-model`	`true` or `false`	When true, then the `default-c64-model` value will always be applied regardless of what a SID file requests. Default: `false`.
`default-sid-model`	One of: `Mos6581`, `Mos8580`	The default model of SID chip to emulate when a SID file does not specify a model. Default: `Mos6581`.
`force-sid-model`	`true` or `false`	When true, then the `default-sid-model` value will always be applied regardless of what a SID file requests. Default: `false`.
`sampling-method`	One of: `Interpolate`, `ResampleInterpolate`	The resampling mode, where `Interpolate` is faster while `ResampleInterpolate` is slower but more accurate. Default: `Interpolate`.
`fast-sampling`	`true` or `false`	Whether or not a faster but slightly less accurate resampling method is used when `sampling-method` is `ResampleInterpolate`. Default: `false`.
`multi-sid-as-mono`	`true` or `false`	Whether or not to play multi-SID files (e.g. 2SID, 3SID) with one channel (monaural). Default: `false`.

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:

buffer-size: 1024
audio-driver: pulseaudio
sample-rate: 44100
fadeout-seconds: 5
repeat-playlist: false
render-jobs: 20
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/alexa/doc/soundfonts/my-sc-55.sf2"
  reverb-enabled: true
  reverb-type: mverb

c64:
  song-length-db: /home/alexa/doc/Songlengths.txt
  default-song-length: 180
  kernal-rom: /home/alexa/.local/share/sidplayfp/kernal
  basic-rom: /home/alexa/.local/share/sidplayfp/basic
  chargen-rom: /home/alexa/.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, blue-phosphor, plum, phosphor]
  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

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