This is a config file reference. Click for instructions.
This page is reference material which explains every setting and option for this section of an MPF yaml config file. See the instructions for config files for formatting and other details. See our guide to config file examples for more examples of real configs in action.
|machine config files
|mode config files
sound_pools: section of your config is where you specify pools (or
groupings) of sound assets in your machine.
Creating a sounds pool allows you to reference a group of sound variations as if it were a single sound. A sound pool name may be used anywhere a sound asset name may appear. Pools can be used for random differences in a sound (such as slight variations of a slingshot sound) or for an ordered sequence of sounds that will repeat. Another common use for sound pools is to play a random callout from a defined list when triggered. (Sound pools are 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_pool configuration.
To create a sound pool, add a sub entry to the
sound_pools: section of
your config which will be the name of that sound pool. The name must be
unique among all sound pools and sound assets. In the above example
drain_callout:, slingshot: and
target_completion: are each a sound pool name. Then create
one or more of the following settings for each sound pool:
The following sections are required for each named sound pool in your config:
sounds: section contains an indented list of existing sound assets
(one per line) that will be contained in the sound pool. It is suggested
you use block sequence notation for this list (begin each line with a
dash followed by a space
-). Optionally, a number may be appended to
the sound asset name delimited by a pipe (
|) character. This optional
number controls the relative weighting for random item selection, or the
number of times to play the sound before moving to the next sound in the
pool with a sequence pool. If no weight value is provided, a default
1 will be applied. In the example above, the
slingshot: random sound pool contains relative weighting
values. The weights sum to 10 for the three sounds so the
slingshot_01 sound has a probability of being randomly
selected of 5 out of 10 (50%), slingshot_02 3/10 (30%),
and slingshot_03 2/10 (20%).
If you want to use a sound that has spaces in its name, the name of the sound must be in quotes: :
sound_pools: drain_callout: type: random_force_all track: voice sounds: - drain_01 - drain_02 - "drain 03" # example of a sound with a space in its name using quotes - drain_04
Single value, type:
This is the name of the track this sound pool will play on. (You configure tracks and track names in the sound_system: section of your machine config files.)
The following sections are optional for each named sound pool in your config. (If you don't include them, the default will be used).
Single value, type: one of the following options: preload, on_demand.
This controls the timing of when the sound assets in the sound pool will
be loaded into memory (see the documentation on
(Managing Assets for an
explanation of what loading is). Options for
preload- The asset is loaded when MPF boots and stays in memory as long as MPF is running.
on_demand- The asset is loaded "on demand" when it's first called for. At this point, assets loaded on demand stay in memory forever, but at some point we'll change that so they can be unloaded on demand too.
Single value, type: one of the following options: sequence, random,
random_force_next, random_force_all. Default:
type: of sound pool dictates how the next sound in the pool will
be selected when the sound pool is referenced for playback. Options for
sequence- Sounds are selected in the order in which they appear in the
sounds:section. An optional number/weight appended after each sound controls how many times the sound will be played before the next one in the list is selected. The sequence of sounds will repeat once all sounds have been played.
random- Sounds are randomly selected from the list of sounds in the
sounds:section of the sound pool. The probability of selecting each sound in the list can be controlled by an optional numeric weight value appended after each sound. This weight value is relative to all other sounds in the list.
random_force_next- Sounds are randomly selected from the list of sounds in the
sounds:section of the sound pool. This sound pool type ensures that the next sound selected will not be the same as the previously selected sound (no back-to-back repeats of a single sound). The probability of selecting each sound in the list can be controlled by an optional numeric weight value appended after each sound. This weight value is relative to all other sounds in the list.
random_force_all- Sounds are randomly selected from the list of sounds in the
sounds:section of the sound pool. This sound pool type ensures that all sounds in the list will be played once before any sound will be repeated. The probability of selecting each sound in the list can be controlled by an optional numeric weight value appended after each sound. This weight value is relative to all other sounds in the list.
Single value, type:
The numeric value indicating the maximum number of instances of this
sound pool that may be played at the same time (up to the limit of the
track). Once the maximum number of instances has been reached, the
stealing_method setting determines the how additional requests to play
the sound pool will be managed. This setting is useful for sounds that
can be triggered in rapid succession (such as spinners and pop bumpers).
Setting a limit will ensure a reasonable number of instances will be
played simultaneously and not overwhelm the audio mix. The default value
None indicates no limits will be placed on the number of instances
of the sound pool that may be played at once up to the limit of the
The sounds contained in a sound pool can also have their own
simultaneous_limit setting which can lead to some unexpected behavior
when interacting with the
simultaneous_limit setting in the sound
Single value, type: one of the following options: oldest, newest, skip.
stealing_method: of a sound pool determines the behavior of
additional requests to play the sound pool once the number of
simultaneous instances of the sound has reached its
limit. This setting is ignored when
simultaneous_limit is set to
None. Options for
oldest- Steal/stop the oldest playing instance of the sound and replace it with a new instance (essentially restarts the oldest playing instance).
newest- Steal/stop the newest playing instance of the sound and replace it with a new instance (essentially restarts the newest playing instance).
skip- Do not steal/stop any currently running instances of the sound. Simply skip playback of the newly requested instance.
Something missing or wrong? You can fix it!
This website is edited by people like you! Is something wrong or missing? Is something out of date, or can you explain it better?
Please help us! You can fix it yourself and be an official "open source" contributor!
It's easy! See our Beginner's guide to editing the docs.
Page navigation via the keyboard: < >
You can navigate this site via the keyboard. There are two modes:
General navigation, when search is not focused:
- F , S , / : open search dialog
- P , , : go to previous page
- N , . : go to next page
While using the search function:
- Down , Up : select next / previous result
- Esc , Tab : close search
- Enter : go to highlighted page in the results