Skip to content

sound_player:

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 ✅

Note

This section can also be used in a show file in the sounds: section of a step.

The sound_player: section of your config is where you specify actions to perform on sounds when MPF events are received.

This is an example:

sound_player:
  mode_attract_started:
    song_01:
      action: play
      loops: -1
  mode_attract_stopped:
    song_01:
      action: stop
  slingshot_hit:
    zap:
      block: true  # "blocks" this event from being passed to sound player sections in lower-priority modes

Additional information may be found in the sound_player documentation.

Express configuration

When referencing sounds in the sound player, there is an alternative syntax to specify a sound when you don't wish to provide any additional settings. This shortcut notation is known as the "express configuration" and for the sound player it is simply the name of the sound asset. It can be used in both configuration files and show steps. In the config file example above, play_sound_slingshot: slingshot_01 is an example using the express configuration (sound name only).

Sound behavior upon mode (or show) stop

When the mode or show stops that contains a sound_player, all sounds started in that mode or show will continue to play and stop automatically when they reach their end. Sounds that are looping will have their looping stopped so the sound will no longer continue to loop and will stop when they reach their end. Sounds that are pending playback and are queued will be canceled (removed from the queue) and will not be played. If you need a sound to be stopped immediately when a mode or show ends, you will need to add an entry in the sound_player to trigger a stop action based on the mode or show stop event.

Optional settings

The following sections are optional in the sound_player: 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). Default: -1

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!


action:

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

The action: setting controls what action will be performed on the specified sound. Options for action: are:

  • play - The specified sound will be played. Any optional parameter values will override the sound's settings.
  • stop - All currently playing and queued instances of the specified sound will stopped/canceled. Any optional parameter values will be ignored as the stop action takes no parameters. There is currently no way to stop specific instances of a particular sound while leaving others playing, but that is on the list to be implemented in a future version.
  • stop_looping - Looping will be canceled for all currently playing instances of the specified sound (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.
  • load - Loads the specified sound or sound pool from its source file into memory to prepare it to be played. The request is ignored if the sound is already loaded.
  • unload - Unloads the specified sound or sound pool from memory. All instances of the sound or sound pool will be immediately stopped. The request is ignored if the sound is not currently loaded.

block:

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

When set to true, the triggering event is blocked from being passed to other sound_player sections in lower priority modes. This is useful if you have a switch in a base mode that plays a sound (like a jet bumper), but then in a special mode (like super jets) you want that switch to play a different sound but you don't also want the base mode to play the sound configured there (we don't want two simultaneous sounds for the jet bumper, just one).

##! mode: mode1
sound_player:
  sw_jet_bumper_active:
    super_jet_bumper_sound:
      block: true

There is also a shorthand way (express config format):

##! mode: mode1
sound_player:
  sw_jet_bumper_active: super_jet_bumper_sound|block

bus:

New in MPF 0.80

Single value, type: string. Defaults to empty.

Specifies an audio bus on which this sound should be played. Overrides the sound setting if one exists.

delay:

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

When the triggering event occurs, delay for a certain amount of time before playing the sound.

events_when_about_to_finish:

List of one (or more) events. Those will be posted by the device. Default: use_sound_setting

Please refer to the sounds: documentation for details about this setting as it just overwrites the setting in your sound.

events_when_looping:

List of one (or more) events. Those will be posted by the device. Default: use_sound_setting

Please refer to the sounds: documentation for details about this setting as it just overwrites the setting in your sound.

events_when_played:

List of one (or more) events. Those will be posted by the device. Default: use_sound_setting

Please refer to the sounds: documentation for details about this setting as it just overwrites the setting in your sound.

events_when_stopped:

List of one (or more) events. Those will be posted by the device. Default: use_sound_setting

Please refer to the sounds: documentation for details about this setting as it just overwrites the setting in your sound.

fade_in:

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

Please refer to the sounds: documentation for details about this setting as it just overwrites the setting in your sound.

fade_out:

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

Please refer to the sounds: documentation for details about this setting as it just overwrites the setting in your sound.

key:

Single value, type: string. Default: use_sound_setting

Used to reference this sound entry when stopping/pausing/resuming it.

loops:

Single value, type: int_or_token. Defaults to empty.

Please refer to the sounds: documentation for details about this setting as it just overwrites the setting in your sound.

max_queue_time:

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

Please refer to the sounds: documentation for details about this setting as it just overwrites the setting in your sound.

mode_end_action:

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

Please refer to the sounds: documentation for details about this setting as it just overwrites the setting in your sound.

pan:

Single value, type: float_or_token. Defaults to empty.

Please refer to the sounds: documentation for details about this setting as it just overwrites the setting in your sound.

priority:

Single value, type: int_or_token. Defaults to empty.

Please refer to the sounds: documentation for details about this setting as it just overwrites the setting in your sound.

start_at:

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

Please refer to the sounds: documentation for details about this setting as it just overwrites the setting in your sound.

track:

Deprecated in MPF 0.80. Use bus instead.

Single value, type: string. Defaults to empty.

Please refer to the sounds: documentation for details about this setting as it just overwrites the setting in your sound.

volume:

Single value, type: gain setting (-inf, db, or float between 0.0 and 1.0). Defaults to empty.

Please refer to the sounds: documentation for details about this setting as it just overwrites the setting in your sound.


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