Configuration File Format

The configuration file lets you specify nearly all of the midi123 options, saving you from having to type them in on the command line each time. The file uses the YAML format for ease of use. The first time you run midi123, a default configuration file will be created. If you have a configuration file from midi123 v2.0.1 or previous, it will be converted to the new format automatically.

The location of the configuration file depends on your platform:

On Linux/Unix: $XDG_CONFIG_HOME/midi123/midi123.yaml (this usually means ~/.config/midi123/midi123.yaml).
On Windows: %APPDATA/midi123/midi123.yaml

Note that command line options can still override the configuration file. So you can have your favorite SoundFont in the configuration file, but still use the -s parameter to temporarily switch to another SoundFont.

Song-specific Config Files

In addition to the main config file, you can specify alternative configurations for individual song files. These reside in:

On Linux/Unix: $XDG_CONFIG_HOME/midi123/song-settings/ (this usually means ~/.config/midi123/song-settings/).
On Windows: %APPDATA/midi123/song-settings/

Song configuration files are matched against the song's filename. So if you play a song with the filename /midi-songs/doom/D_E1M1.mid, then the program will look for a song config in:

On Linux/Unix: $XDG_CONFIG_HOME/midi123/song-settings/D_E1M1.mid.yaml
On Windows: %APPDATA/midi123/song-settings/D_E1M1.mid.yaml

Note how the config filenames include the file extension (such as .mid) followed by .yaml. This is important.

If a song configuration file exists for a specific song file, then any keys within that song 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
soundfont-path
repeat-playlist
render-jobs
sample-rate
vu-meter

You can use midi123 --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`	String	The output driver used to produce sound during playback. Use `midi123 --driver list` to see a list of valid options. Default: `portaudio`.
`soundfont-path`	`null` or a path	The path to the SoundFont to use. The default is `null`, meaning that no SoundFont path is provided.
`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`.
`sample-rate`	Integer between 44100 and 352800	The output sample rate, in hertz. The default is `44100`.
`disable-remapping`	`true` or `false`	When `true`, this disables automatic remapping of unknown patches. 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.
`disable-soft-clipping`	`true` or `false`	When `true`, then soft clipping is not applied on the final output. Default: `false`. This is a very subtle limiting effect that prevents clipping. Unlike normal hard clipping, the peaks that go above 0db are rounded off to give a smoother, warmer sound.
`vu-meter`	VU Meter config block (see below)	Configuration section for the VU meter.
`enable-reverb`	`true` or `false`	When `true`, this enables the reverberation effect. Default: `true`.
`reverb-type`	String	Changes the type of reverb applied to the signal. This only has an effect when `enable-reverb` is also `true`. You can run `midi123 --reverb-type list` to get a listing of the possible settings. Default: `zita`.
`reverb-level`	Integer between 0 and 255	The default amount of reverb applied to the signal. This can go from 0 to 255, and MIDI files are free to override this setting. This is merely the default for MIDIs that do not set a reverb level. Default: 64. This requires `enable-reverb` to be `true`, or it has no effect.
`zita-reverb-preset`	String or Zita Preset Block (see below)	If this is a string, then that reverb preset is selected for use when the Zita reverb is used. Otherwise this is a config block definining a custom preset for Zita. Use `midi123 --reverb-type zita --reverb-preset list` to see a list of presets for Zita. Default: `gmdefault`.
`mverb-reverb-preset`	String or MVerb Preset Block (see below)	If this is a string, then that reverb preset is selected for use when the MVerb reverb is used. Otherwise this is a config block definining a custom preset for MVerb. Use `midi123 --reverb-type mverb --reverb-preset list` to see a list of presets for MVerb. Default: `gmdefault`.
`schroeder-reverb-preset`	String or Schroeder Preset Block (see below)	If this is a string, then that reverb preset is selected for use when the Schroeder reverb is used. Otherwise this is a config block definining a custom preset for Schroeder. Use `midi123 --reverb-type schroeder --reverb-preset list` to see a list of presets for Schroeder. Default: `gmdefault`.
`enable-chorus`	`true` or `false`	When `true`, the chorus effect is enabled.
`chorus-level`	Integer between 0 and 255	The default amount of chorus effect applied to the signal. This can go from 0 to 255, and MIDI files are free to override this setting. This is merely the default for MIDIs that do not set a reverb level. Default: 0. This requires `enable-chorus` to be `true`, or it has no effect.
`chorus-interpolation`	String	What kind of interpolation is used for the chorus. This does not impact audio quality much. You can run `midi123 --chorus-interp list` to get a listing of the possible settings. Default: `cubic`.
`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.
`voice-filter-type`	String	The type of filter to apply to the voices. You can use `midi123 --voice-filter-type list` to get a listing of the possible settings. Defualt: `standard`.
`chan-filter-type`	String	The type of filter to apply to the audio channels. In other words, this is the filter that gets applied when MIDI controllers 74 or 71 are used. You can use `midi123 --chan-filter-type list` to get a listing of the possible settings. Defualt: `standard`.
`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`	Equalizer config block (see below)	Configuration section for the equalizer.

** 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: `▸`.
`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
`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: pulseaudio
soundfont-path: /home/alexa/doc/my-sc-55.sf2
repeat-playlist: true
render-jobs: 20
sample-rate: 44100
main-volume: 0.5
disable-remapping: false

enable-reverb: true
reverb-type: mverb
reverb-level: 72

zita-reverb-preset: gmdefault
schroeder-reverb-preset: gmdefault
mverb-reverb-preset:
  dampingFreq: 0.59
  density: 0.469
  bandwidthFreq: 0.688
  decay: 0.5084
  predelay: 0.0
  size: 0.69
  gain: 0.5
  mix: 1.0
  earlyLateMix: 0.795

enable-chorus: true
chorus-level: 0
chorus-interpolation: hermite

enable-stereo-enhancer: false
stereo-enhancement-amount: 0.5
disable-soft-clipping: false

equalizer-enabled: true
equalizer:
  low-shelf:
    frequency: 80.0
    gain: 2.0
    bandwidth: 0.9
  bands:
    - frequency: 105.0
      gain: 2.78
      bandwidth: 0.4
    - 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:

enable-reverb: true
reverb-type: zita
reverb-level: 80
zita-reverb-preset: gmdefault