This is the documentation the latest work-in-progress version of MPF!
This is the documentation for MPF 0.56, which is the “dev” (next) release of MPF that is a work-in-progress. This is probably ok, and means you’ll be on the latest, cutting-edge version of MPF.
However, if you want a more stable version, select the
v:stableversion from the lower-left corner of this page, which is the most recent version that is not getting new updates.
If you are new to MPF, we have recently rewritten the installation process which only applies to this “latest” 0.56, so you probably want to stay here because the prior installation process doesn’t work on the latest OS and Python versions.
Sounds, Music & Audio¶
Everything in this “Displays & Graphics” section is about default the MPF Media Controller
Since the release of MPF 0.30, audio and sound support has been provided by a custom audio library built on SDL2, SDL_Mixer, and GStreamer libraries. This custom library allows the MPF development team to create audio features optimized for pinball machines. The first release provides basic sound loading and playback capabilities along with some great new features like ducking and sound pools. (Sound support is part of the MPF media controller and only available if you’re using MPF-MC for your media controller).
The basic concept with audio in MPF is that you collect all your audio files (16-bit .wav, .ogg,
and .flac files are currently supported) and put them in the
/sounds folder in your machine
folder (you can organize them into sub-folders if you would like). Then in your config file you
create entries for each sound which map a friendly name to the actual file on disk. You can also
set a bunch of defaults for each sound, such as volume, start time, etc. Then when you want to
play a sound in a game, you can refer to it by the friendly name from your configuration file.
You can also add entries into your configuration file to set up sounds so they play based on
certain MPF events. (For example, play the sound “laser” every time the event from a pop bumper
being hit is posted.) You can also add sounds to your show files so they play in-sync with
lighting and display effects.
You can think of the audio system in MPF as a sound mixing board that you control via configuration settings and events. It is divided into tracks (similar to channels on a mixer), each of which has its own properties such as name, volume and the number of sounds that may be played simultaneously. New in MPF 0.50 are specialized track types optimized for specific audio tasks (such as music playback and creation). You can create up to 8 tracks in your sound system, although typically most machines will typically use 3 standard tracks (“voice”, “sfx”, and “music”). Sounds are played on specific tracks and then the tracks are mixed together to form the final mix. The sounds themselves are objects that include many properties that control how they will be played such as what track they play on, volume, looping, priority, how long to wait in the playback queue before being discarded, ducking, etc.
Sounds can be grouped together into a logical grouping called a sound pool. Sounds pools allow 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.
You configure your sound system (including tracks) in the sound_system: section of your machine configuration file. You add settings for individual sound files in the sounds: section. You can configure sounds to automatically play on standard tracks when selected MPF events are posted in the sound_player: section. Sound pools are specified in the sound_pools: section. Sound loop tracks use sound_loop_sets and the sound_loop_player to play and loop sounds. Playlist tracks use playlists and the playlist_player for playing music. Tracks can be controlled when selected MPF events are posted in the track_player: section.