sound_system:¶
Config file section
| Valid in machine config files | YES |
| Valid in mode config files | NO |
The sound_system: section of your machine config controls the general settings for the
machine’s sound system. (This section is part of the MPF media controller and only available
if you’re using MPF-MC for your media controller.)
Here’s an example of a typical sound configuration.
sound_system:
buffer: 1024
channels: 1
enabled: True
frequency: 44100
master_volume: 0.75
tracks:
music:
type: standard
simultaneous_sounds: 1
volume: 0.5
voice:
type: standard
simultaneous_sounds: 1
volume: 0.7
sfx:
type: standard
simultaneous_sounds: 8
volume: 0.4
sound_system:
buffer: 1024
channels: 1
enabled: True
frequency: 44100
master_volume: 0.75
tracks:
music:
type: standard
simultaneous_sounds: 1
volume: 0.5
voice:
type: standard
simultaneous_sounds: 1
volume: 0.7
sfx:
type: standard
simultaneous_sounds: 8
volume: 0.4
Optional settings¶
The following sections are optional in the sound_system: section of your config. (If you don’t
include them, the default will be used). If you omit the sound_system: section completely,
the sound configuration will contain nothing but the default values, which includes a single audio
track named default. It is recommended that you at least specify the tracks: section in
your machine.
buffer:¶
Single value, type: integer. Default: 2048
This is the size of your sound buffer. It must be a power of 2. The exact value you should use may take some trial-and-error. A bigger buffer means that there’s less chance of skipping and dropout (lower CPU usage), but it also means that sounds can take longer to play since the buffer has to fill first. Some limited power platform have to run with a buffer of 4096 or 8192 or 16384, others at 512 or 256. So just play with it and see what works for you.
channels:¶
Single value, type: integer. Default: 1
The number of channels the sound system will support. 1 for mono, 2 for stereo. You’re probably thinking, “aww man, I need stereo sound!” But almost no pinball machines do this since the speakers in the backbox are 2 feet apart and they’re 4 feet away from the player’s ears. (Maybe if you’re going to use headphones or put tweeters in the front of the machine?) Again, if you have a resource-constrained system, then go for mono and make sure all your sound files are mono. If not, meh, go ahead and use stereo.
enabled:¶
Single value, type: boolean (Yes/No or True/False). Default: True
Indicates whether or not the sound system will be enabled in your machine.
frequency:¶
Single value, type: integer. Default: 44100
How many sound samples per second you want. 44100 is so-called “CD quality” audio, though with the sound systems in most pinball machines, if you cut it in half (to 22050) it still sounds virtually the same. If you’re running on a resource-constrained host computer, you should make sure all your sound files are encoded at the same rate so MPF doesn’t waste time re-encoding them on the fly. Smaller values mean smaller sound files, less memory consumption, and less CPU processing. So if you’re on a resource constrained host computer, think about 22050 instead of 44100. (But be sure to resample all your sound files to match.)
master_volume:¶
Single value, type: gain setting (Instructions for entering gain values)
-inf, db, or float between 0.0 and 1.0. Default: 0.5
The overall volume of the MPF sound system. As with all volume parameters in MPF, this item can be represented
as a number between 0.0 and 1.0 (1.0 is max volume, 0.0 is off, 0.9 is 90%, etc.) It also can be represented as
a decibel string from -inf to 0.0 db (ex: -3.0 db). Note that this only controls the volume of the MPF app,
not the host OS’es system volume. So you still need to make sure that the host OS is not on mute and that the
volume is turned up.
tracks:¶
Every sound that’s played in MPF is played on a track. If you are familiar with an audio mixer a track can be thought of as a mixer channel. Each track can have it’s own settings, and you can set volume on a per-track basis. You can have up to 8 audio tracks in your MPF machine. The example above shows three tracks, called music, voice, and sfx. The idea (in case it isn’t obvious) is that you play all your music clips on the music track, voice callouts on the voice track, and the sound effects on the sfx track. To create a track, add a sub entry to the tracks: section which will be the name of that track. (So again, music:, voice: and sfx: in the example. Then create one or more of the following settings for each track:
Optional settings¶
The following sections are optional in the tracks: section of your config. (If you don’t include them,
the default will be used).
type:¶
Single value, type: one of the following options: standard, sound_loop. Default: standard
The track type: setting determines what type of audio track will be used. For more detailed
information about the various audio track types see Tracks. Options for
type: are:
standard- The track will be a standard audio track. Standard audio tracks provide a comprehensive set of features to support most pinball audio needs. This will be the audio track type you will use most of the time (prior to MPF version 0.50 only standard audio tracks were available). settings.sound_loop- The track will be a sound loop audio track. Sound loop audio tracks are optimized for live looping music control driven by events. This specialized track type can synchronize playback of multiple looping sounds simultaneously in layers and supports gapless switching to a new set of loops. Sound loops are designed to build music that dynamically changes based on events in your game. Sound used in sound_loop tracks must be loaded in memory (streaming sounds are not supported).
Common settings¶
The following settings are common to all track types:
volume:¶
Single value, type: gain setting (Instructions for entering gain values)
-inf, db, or float between 0.0 and 1.0. Default: 0.5
This is the volume setting for this track (how loud will it be), as either a value between 0.0 and 1.0 or a decibel value between -inf and 0.0 db. Note that each track’s volume will be combined with the overall system volume. So if your MPF master volume is set to 0.8 (80%) and you have a track set to 0.5 (50%), sounds on that track will play at 40% overall volume (50% of 80%).
events_when_played:¶
List of one (or more) values, each is a type: string. Default: None
A list of one or more names of events that MPF will post when the track is played or resumed after being stopped/paused. Enter the list in the MPF config list format. These events are posted exactly as they’re entered.
events_when_stopped:¶
List of one (or more) values, each is a type: string. Default: None
A list of one or more names of events that MPF will post when the track is stopped. Enter the list in the MPF config list format. These events are posted exactly as they’re entered.
events_when_paused:¶
List of one (or more) values, each is a type: string. Default: None
A list of one or more names of events that MPF will post when the track is paused. Enter the list in the MPF config list format. These events are posted exactly as they’re entered.
Standard track settings¶
The following settings are specific to standard audio tracks:
simultaneous_sounds:¶
Single value, type: integer (between 1 and 32). Default: 8
This sets the maximum number of simultaneous sounds that can be played on this track. The example config file above shows the music and voice tracks with a max of 1 simultaneous sound playing, since if you have two music clips or voice callouts playing at the same time, it will sound like gibberish. A sound effects track, on the other hand, can probably have a few sounds playing at once. Note that MPF gives you detailed control over what happens if a new sound wants to play when the max simultaneous sounds are already playing on that track. Should the new sound break in and stop an existing sound? Should it wait until the existing sound is done? How long should it wait? You can control all this on a per sound basis (see the sounds: documentation for more information).