MPF-MC is being deprecated

This instruction page is for the legacy MPF-MC for MPF versions 0.57 and prior. For users of MPF 0.80 and later, please refer to the Godot Media Controller (GMC) Documentation

How to setup sound for your machine

This guide explains the basic steps to setup sound for your machine. Sound support is part of the MPF media controller and only available if you're using MPF-MC for your media controller. Please ensure your system is properly setup to play sound (drivers are installed and configured) before proceeding with this guide.

1. Configuring the sound_system

The first step in the process of setting up sound for your machine is to setup the sound_system: section of your machine configuration file (see sound_system: for more detailed information). Generally you can just use the default values for the settings in the section. However, you do need to define the tracks the sound system will use. Tracks can be thought of as channels on an audio mixer with their own volume and other settings. The example below shows a typical pinball machine sound setup with three tracks: music, voice, and sfx. The simultaneous_sounds: setting controls how may sounds may be played at the same time on each track. It is recommended that you only allow one music and one voice clip to be played at a time and that many sound effects (sfx) can be played simultaneously so that is what we have configured in the example below.

Example:

sound_system:
  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

2. Configuring your sound asset folders

The next step is to configure your sound asset folders. First you will need to create a folder named sounds directly under your machine folder. The recommended way to organize your sound files is to create sub-folders for each track in the sounds folder (music, sfx, and voice). If you are going to be using a lot of sounds you can create as many sub-folders beneath each track folder as you like. It can help you stay organized and be able to locate your sounds.

File system directory structure example:

machine_folder
    sounds
        music
        sfx
        voice

Now that our sound asset folders have been created, it's time to let MPF know where to look for sound files when it starts and what basic settings to apply to each sound it finds. This is done by adding a sounds: section to the assets: section in our machine configuration file. The example below illustrates what this should look like in your machine configuration file. The default: setting contains the default settings that should be applied to all sound assets. In this example below, load: should be assigned a value of on_demand for all sound assets. Next we enter a setting for each sub-folder located in our sounds directory and specify the settings we want applied to each sound asset found in those sub-folders. In our case we have created sub-directories for each track and want the sounds contained in them to play on their respective tracks (music, sfx, and voice) so we set the track: setting accordingly.

assets: section in machine configuration file:

assets:
  sounds:
    default:
      load: on_demand
    music:
      track: music
    sfx:
      track: sfx
    voice:
      track: voice

When your machine launches, the asset manager will now search for supported audio files in the specified directories and assign the proper settings to each file it finds. We're well on our way to actually hearing some sound!

3. Put some sounds in your sound folders

You probably don't need much assistance with this obvious step, but let's go through the process anyway just in case. As of version 0.33, MPF supports 16-bit .wav (Wave), .ogg (Ogg Vorbis), and .flac (FLAC) audio files (we hope to add other formats in future releases such as .mp3). Locate some supported audio files and place them in the appropriate track folders that you created in the previous step (a good site to find free public domain sounds is www.freesound.org). Put all music files in the music folder, voice callouts in the voice folder, and all other sound effects in the sfx folder. You are welcome to create any sub-folders you desire and put sounds in them to help keep things organized.

4. Setting the default master volume level

The master volume (applied to all tracks in the sound system) can be adjusted from the service switches or custom events. MPF stores the master volume level as a machine variable, so the selected volume will persist each time the game boots up.

The master volume ranges from 0.0 (silent) to 1.0 (full), and defaults to 0.5 (50%). You can set your own default volume by overriding the machine variable settings in your machine config file.

machine_vars:
  master_volume:
    initial_value: 0.25   # Set this to any value you want
    value_type: float
    persist: true         # If false, the volume will reset to default
                          # each time the machine boots up

5. Additional configuration for selected sounds

Now when you start your machine you will have some sounds available (assuming you placed some supported sound files in your sounds folder during the last step) and they will all have some very basic default settings. It is very likely that you won't be happy with the default settings for all of your sounds so let's create some more tailored settings for a few of them.

Renaming some sounds

Your sounds now all have names based on their file names (without the extensions), and by default that is how they must be referenced in your config files. Perhaps some of your file names are either a bit cryptic or contain additional text that you'd like to shorten. One option is to simply rename any files you'd like in the operating system. Another option is to setup some configuration options in your config files to reference the sound file by a different name which is what we will do next.

I downloaded a triangle sound from www.freesound.org that has an undesirable filename: 22783__franciscopadilla__80-mute-triangle.wav. I would rather just refer to it in my config files as triangle and not 22783__franciscopadilla__80-mute-triangle (which is what it will be by default). In my sounds: section of my machine configuration file (see sounds: in the documentation for more details) I can put the following text:

sounds:
  triangle:
    file: 22783__franciscopadilla__80-mute-triangle.wav

That simple configuration change will allow the sound as to be referred to as triangle wherever you refer to that sound in other configuration locations. Note: be sure to include the complete file name, including the extension when using the file: setting.

Setting the volume of a specific sound

A very common adjustment to make is to set the volume for each and every sound you load in your machine. This allows you to balance out sounds from various sources rather than trying to adjust the levels in each sound file using audio editing software. Building on the example above, let's set the volume of the triangle sound in our config file:

sounds:
  triangle:
    file: 22783__franciscopadilla__80-mute-triangle.wav
    volume: 0.85

volume: controls the volume of the sound and works in conjunction with the track volume and the master volume. Volume can either be entered as a number between 0.0 and 1.0 or as a decibel level (see Instructions for entering gain values) for more information). You will probably have to spend some time adjusting the volumes of many sounds in your machine to get everything to sound just the way you want it.

Note: If you hear distortion in your sounds when they are played back in a mix, be sure to try lowering the volume as you may be experiencing clipping.

Other sound settings

There are many other settings you may wish to change for some sounds in your machine.

• How do you cause your sound to loop 3 times every time it is played? Add loops: 3 to the config section for your sound. How do you loop a sound indefinitely? Add loops: -1.
• How do you adjust the which sounds can preempt other sounds and how long a sound may wait to be played before it is discarded? Use the priority: and max_queue_time: settings.
• How do you send events to MPF when a sound begins or finished playing? Use the events_when_played: and events_when_stopped: settings.
• What about ducking? Just what is it anyway? Learn about ducking in the documentation.

The documentation for the sounds: configuration section contains further information about all these settings.

Example sounds: configuration demonstrating most common settings:

sounds:
  triangle:
    file: 22783__franciscopadilla__80-mute-triangle.wav
    volume: 0.85
    max_queue_time: 0
  laser:
    volume: 0.5
    loops: 3
    max_queue_time: 0
  extra_ball:
    file: extra_ball_12753.wav
    events_when_started: extra_ball_callout_started
    events_when_stopped: extra_ball_callout_finished
    volume: 0.8
    priority: 50
    max_queue_time: None
    ducking:
      target: music
      delay: 0
      attack: 0.3 sec
      attenuation: 0.45
      release_point: 2.0 sec
      release: 1.0 sec
  slingshot_01:
    volume: 0.5
    max_queue_time: 0
  song_01:
    volume: 1.0
    priority: 100
    about_to_finish_time: 2s
    events_when_about_to_finish: song_01_about_to_finish

6. Hooking up an MPF event to play a sound

Now that your sounds have been setup and are available in your machine, the next step is to configure them to be played. The sound player was designed to do just this (associate a sound action, such as play or stop, with an MPF event). The sound player can be configured in either the machine configuration file, a mode configuration file, or even in a show step (or in all of them). To keep things simple here, let's configure the sound player in the machine configuration file.

The scenario in this example is we want our song from the previous example (song_01) to play infinitely when the attract mode starts and stop when the attract mode stops. Create the following entries in the sound_player: section of the machine config file:

sound_player:
  mode_attract_started:
    song_01:
      action: play
      loops: -1
  mode_attract_stopped:
    song_01:
      action: stop

That's it. The song_01 sound will be played on the music track whenever attract mode is started and will stop whenever attract mode is stopped. The mode_attract_started section refers to a standard MPF event that is sent whenever a mode named attract is started and mode_attract_stopped is a standard MPF event that is sent whenever a mode named attract is stopped. For more information, see the sound_player: documentation.

Finished

Congratulations! You have completed your the basic sound system setup and should have some simple audio playing in your machine.

References

• Sound & Audio
• Ducking
• Tips & tricks
• sound_system:
• tracks
• sounds:
• sound_player:
• sound_loop_sets:
• sound_loop_player:
• playlists:
• playlist_player:
• Instructions for entering gain values

---

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