sounds:

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.

Valid in
machine config files	YES
mode config files	YES

The sounds: section of your config is where you configure non-default parameter values for any sound assets you want to use in your game. Note: You do not have to have an entry for every single sound you want to use, rather, you only need to add individual assets to your config file that have settings which different from other assets in that asset's folder. (This section is part of the MPF media controller and only available if you're using MPF-MC for your media controller.)

MPF-MC currently supports 16-bit Wave (.wav), Ogg Vorbis (.ogg), and FLAC (.flac) files.

Here's an example:

##! asset: sounds/extra_ball_12753.wav=../mc/sound/sounds/sound.ogg
##! asset: sounds/slingshot_01.ogg=../mc/sound/sounds/sound.ogg
#! sound_system:
#!   buffer: 1024
#!   channels: 1
#!   enabled: true
#!   frequency: 44100
#!   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
sounds:
  extra_ball:
    file: extra_ball_12753.wav
    events_when_stopped: extra_ball_callout_finished
    streaming: false
    track: voice
    volume: 0.5
    priority: 50
    max_queue_time: None
    ducking:
      target: music
      delay: 0
      attack: 0.3 sec
      attenuation: -18db
      release_point: 2.0 sec
      release: 1.0 sec
  slingshot_01:
    volume: 0.5
    max_queue_time: 0

Optional settings

The following sections are optional in the sounds: section of your config. (If you don't include them, the default will be used).

about_to_finish_time:

Single value, type: time string (secs) (Instructions for entering time strings). Defaults to empty.

The point relative to the end of the sound at which to post the events_when_about_to_finish event(s). A value of 0.5 seconds means to post the event(s) prior to the end of the sound. When set to None, no events will be posted. If the value of this setting is greater than the duration of the sound, the event(s) will be posted as soon as the sound begins playback. This value is specified as a time string.

ducking:

Single value, type: sound_ducking:. Defaults to empty.

The ducking: section controls ducking for the sound.

events_when_about_to_finish:

List of one (or more) events. Those will be posted by the device. Defaults to empty.

A list of one or more names of events that MPF will post when this sound is about to finish playing. The exact timing of this event is determined by the about_to_finish_time setting for this sound. Enter the list in the MPF config list format. These events are posted exactly as they're entered.

events_when_looping:

List of one (or more) events. Those will be posted by the device. Defaults to empty.

A list of one or more names of events that MPF will post when this sound loops back to the beginning while playing. Enter the list in the MPF config list format. These events are posted exactly as they're entered.

events_when_played:

List of one (or more) events. Those will be posted by the device. Defaults to empty.

A list of one or more names of events that MPF will post when this sound is played. 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) events. Those will be posted by the device. Defaults to empty.

A list of one or more names of events that MPF will post when this sound stops playing. Enter the list in the MPF config list format. These events are posted exactly as they're entered. These events can be useful to trigger some action when a callout has finished playing.

fade_in:

Single value, type: time string (secs) (Instructions for entering time strings). Default: 0

The number of seconds over which to fade in the sound when it is played.

fade_out:

Single value, type: time string (secs) (Instructions for entering time strings). Default: 0

The number of seconds over which to fade out the sound when it is stopped. This value is not applied when the sound stops on its own by reaching the end of the sound (will likely be added in a future version). At the moment it only comes into play when the sound is actively stopped by an event.

file:

Single value, type: string. Defaults to empty.

Sometimes you might want to name a file one thing on disk but refer to it as another thing in your game and config files. In this case, you can create an file: setting in an asset entry. (Note the file: extra_ball_12753.wav setting in the example above, and note that it includes the file extension.) In this example, you would refer to that image asset as extra_ball even though the file is extra_ball_12753. You might be wondering why this exists? Why not just change the file name to be whatever you want and/or who cares what the name is? The reason this function exists is because it allows for the separation of the actual file on disk from the way it's called in the game. For example, you could use this to create two sets of assets---one for a traditional DMD and one for a color DMD---and then you could refer to the asset by its generic name throughout your configs. (In other words, you could swap out assets for different physical machine types without having to update your display code.) That said, we expect that 99% of people won't use this file: setting, which is fine.

key:

Single value, type: string. Defaults to empty.

Help us write it!

This section is unwritten or needs an update or edit. Can you help write it? Get your name in lights and geeky pinball bragging rights! Hit the magic sparkly wand to the right of the title to see this page source on GitHub. Then add/edit and submit your change. It's easy!

CLICK TO LEARN HOW TO EDIT THIS PAGE

loop_end_at:

Single value, type: time string (secs) (Instructions for entering time strings). Defaults to empty.

The position in the sound file (in seconds) at which to start looping and return to the start of the loop as determined by the loop_start_at: setting. By default (None) the sound will loop when it reaches the end of the sound. This setting only applies to sounds loaded in memory and played on a standard audio track (not to any streaming sound or sound played on any other track type).

loop_start_at:

Single value, type: time string (secs) (Instructions for entering time strings). Default: 0

The position in the sound file (in seconds) to start playback of the sound after it is looped. By default when the sound is looped it will loop back to the beginning of the sound file. Setting this value to something other than zero is particularly useful when you have a music sound that has an introduction section and want it to loop back to a verse and not the intro. This setting works in correlation with loop_end_at: and only applies to sounds loaded in memory and played on a standard audio track (not to any streaming sound or sound played on any other track type). Be sure to use many decimal places in your times as precision is important when it comes to loop points. If you hear pops and clicks at the loop points, you may need to slightly adjust your start and end loop times to alleviate them.

loops:

Single value, type: integer. Default: 0

An integer value that controls the looping behavior of this sound. A value of 0 indicates the sound will not loop when reaching the end (also known as a "one-shot"). A value of -1 indicates the sound should loop infinitely until it is stopped. A value greater than 0 specifies the number of times the sound should loop back to the beginning while playing. Note that this value is not the total number of times the sound is played, but the number of times it should play again after the first time through.

markers:

List of one (or more) values, each is a type: sound_marker:. Defaults to empty.

The markers: section establishes a list of markers and their associated events at specific times in the sound. When a marker is reached during playback, the associated events will be posted. Markers are useful for synchronizing various actions with specific points in a sound. A typical use might be to send an 'almost_finished_playing' event a short time before a sound finishes playback or establish various checkpoints in a sound that could be used to restart a sound at that point on the user's next turn (using mode code).

Here's a simple example utilizing markers:

sounds:
  long_sound_1:
    volume: 0.8
    markers:
      - time: 2.534 sec
        events: send_this_event, also_this_event
      - time: 6.712 sec
        events: almost_finished_playing

max_queue_time:

Single value, type: time string (secs) (Instructions for entering time strings). Defaults to empty.

Specifies the maximum time this sound can be queued before it's played. If the time between when this sound is requested and when MPF can actually play it is longer than this queue time, then the request is discarded and the sound doesn't play. This only comes into play if this sound is requested but the track it's playing on is at its simultaneous_sounds limit. Then if this sound doesn't have a high enough priority to kill any of the existing sounds, it will be queued to play later. Some sounds (like voice callouts) might be ok to queue, but other sounds (like sound effects for when you hit a pop bumper or slingshot) might only make sense if they're played right away, so in those cases you might want to use a short (or no) queue time. The default setting is "None" which means this sound will have no queue limit and will always play eventually.

mode_end_action:

Single value, type: one of the following options: stop, stop_looping. Default: stop_looping

The mode_end_action: setting determines what action to take when the mode that initiates the playback of the sound ends. Options for mode_end_action: are:

stop - All currently playing and queued instances of the specified sound started by the mode will be stopped/canceled. If the fade_out parameter has a non-zero value, the sound will fade out over the specified number of seconds.
stop_looping - Looping will be canceled for all currently playing instances of the specified sound started by the mode (the sound will continue to play to the end of the current loop). In addition, any queued instances of the sound awaiting playback will be removed/canceled.

pan:

Single value, type: number (will be converted to floating point). Default: 0

Pan the audio to the left or right channel. Currently, broken due to a bug. Let us know if you need this.

priority:

Single value, type: integer. Default: 0

The numeric value indicating the priority or importance of this sound. Sounds with higher priority values will preempt other sounds with lower priorities that are playing when a track has reached the maximum number of simultaneous sounds it is configured to play. If the track is busy and the priorities of all sounds currently playing greater than or equal to this sound, the sound will be queued for playback and will have to wait to be played.

simultaneous_limit:

Single value, type: integer. Defaults to empty.

The numeric value indicating the maximum number of instances of this sound 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 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 that may be played at once up to the limit of the track. The value of this setting is ignored when the streaming setting has a value of False.

start_at:

Single value, type: time string (secs) (Instructions for entering time strings). Default: 0

The position in the sound file (in seconds) to start playback of the sound when it is played. When the sound is looped it will loop back to the beginning of the sound file.

stealing_method:

Single value, type: one of the following options: skip, oldest, newest. Default: oldest

The stealing_method: of a sound determines the behavior of additional requests to play the sound 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.

streaming:

Single value, type: boolean (true/false). Default: false

Indicates whether or not the sound sound will be streamed (rather than stored in memory). Streaming sounds are limited to a single instance of the sound playing at a time. Multiple different streaming sounds may be played simultaneously, just not more than a single instance of a particular sound. When streaming is set to True, the simultaneous_limit setting is ignored and a value of 1 is used.

track:

Single value, type: string. Defaults to empty.

This is the name of the track this sound will play on. (You configure tracks and track names in the sound_system: section of your machine config files.)

volume:

Single value, type: gain setting (-inf, db, or float between 0.0 and 1.0). Default: 0.5

The volume of this sound. This value is factored into the track and overall MPF volumes. It's used to "balance" your sounds if you have one particular sound that's too loud or too quiet. 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).

Sounds, Music & Audio

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

sounds:

Optional settings

about_to_finish_time:

ducking:

events_when_about_to_finish:

events_when_looping:

events_when_played:

events_when_stopped:

fade_in:

fade_out:

file:

key:

loop_end_at:

loop_start_at:

loops:

markers:

max_queue_time:

mode_end_action:

pan:

priority:

simultaneous_limit:

start_at:

stealing_method:

streaming:

track:

volume:

Related How To guides