sound_pools:¶
Config file section
Valid in machine config files | YES |
Valid in mode config files | YES |
The 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.
sound_pools:
drain_callout:
type: random_force_all
track: voice
sounds:
- drain_01
- drain_02
- drain_03
- drain_04
slingshot:
load: preload
type: random
track: sfx
sounds:
- slingshot_01|5
- slingshot_02|3
- slingshot_03|2
target_completion:
load: on_demand
type: sequence
track: sfx
sounds:
- target_completion_01
- target_completion_02
- target_completion_03
sound_pools:
drain_callout:
type: random_force_all
track: voice
sounds:
- drain_01
- drain_02
- drain_03
- drain_04
slingshot:
load: preload
type: random
track: sfx
sounds:
- slingshot_01|5
- slingshot_02|3
- slingshot_03|2
target_completion:
load: on_demand
type: sequence
track: sfx
sounds:
- target_completion_01
- target_completion_02
- target_completion_03
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:
Required settings¶
The following sections are required for each named sound pool in your config:
sounds:¶
The 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 value of 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%).
Note
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
track:¶
Single value, type: string
. Default: None
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.)
Optional settings¶
The following sections are optional for each named sound pool in your config. (If you don’t include them, the default will be used).
load:¶
Single value, type: one of the following options: preload, on_demand. Default: 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 load:
are:
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.
type:¶
Single value, type: one of the following options: sequence, random, random_force_next,
random_force_all. Default: sequence
The 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 type:
are:
sequence
- Sounds are selected in the order in which they appear in thesounds:
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 thesounds:
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 thesounds:
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 thesounds:
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.
simultaneous_limit:¶
Single value, type: integer
. Default: None
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 of
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 track.
Note
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 pool.
stealing_method:¶
Single value, type: one of the following options: oldest, newest, skip. Default: oldest
The 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
simultaneous_limit
limit. This setting is ignored when simultaneous_limit
is set to None
.
Options for stealing_method:
are:
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.