MPF config file reference: the FAST Pinball audio interface¶

MPF 0.57 Configuration Reference for FAST Pinball Hardware

This page is parrt of the reference material for users of the Mission Pinball Framework and FAST Pinball hardware. If you're new to MPF and FAST, read the MPF + FAST overview first. If you are a programmer writing your own software, see our Developer's Reference Guide.

Note that this guide only applies to MPF 0.57. If you're using MPF 0.56 or older, then the FAST Pinball configuration section of the Mission Pinball website has everything you need.

This guide explains how to configure MPF for the FAST Pinball Audio Interface. Everything on this page requires MPF 0.57.0.dev27 or newer.

Understanding how the FAST Audio Interface works with MPF¶

The FAST Audio Interface is essentially a software controlled amplifier. (Well, technically, it's three amplifiers, but we'll get to that in a minute.) The key thing to understand is that the FAST Audio Interface is not a DAC (digital to analog converter). It's not a sound card, rather, it takes the analog audio output from your computer's sound card (via a ⅛" audio cable) and amplifies if for your pinball machine's speakers.

You do not need to use MPF-MC to use the FAST Audio Interface

Since the FAST Audio Interface just controls the analog audio output from your computer, you do not need to use MPF-MC to use it. You can use it regardless of whether you're using Godot, Unity, or anything else for your game's sounds and media.

Like other types of FAST hardware, when you connect the FAST Audio Interface to your computer, a virtual serial port appears. You configure this in the fast: section of your MPF config file, using an aud: entry (similar to how you configure the FAST Pinball net: or exp: connections.) In additional to the port and debug settings, there are several other settings for the volume controls, amps, and other control pins on the audio interface.

Here's a complete listing off all the settings in the aud: section of your config file. Note that you do not need to include all of these, as these are all the defaults that MPF uses if you don't specify them. We'll explain them below.

FAST Pinball Audio Interface config in MPF 0.57

fast:
  net:
    [ settings not shown ]

  aud:
    port: auto
    debug: false

    main_amp_enabled: true
    sub_amp_enabled: true
    headphones_amp_enabled: true

    main_steps: 20
    sub_steps: 20
    headphones_steps: 20

    default_main_volume: 10
    default_sub_volume: 10
    default_headphones_volume: 10

    persist_volume_settings: true

    max_hw_volume_main: 63
    max_hw_volume_sub: 63
    max_hw_volume_headphones: 63

    main_levels_list: None
    sub_levels_list: None
    headphones_levels_list: None

    link_sub_to_main: true
    link_headphones_to_main: false

    headphones_level: headphones
    mute_speakers_with_headphones: true

    # settings for the PC and LCD control pins
    pin1_pulse_time: 100
    pin2_pulse_time: 100
    pin3_pulse_time: 100
    pin4_pulse_time: 100
    pin5_pulse_time: 100
    pin6_pulse_time: 100
    reset_pulse_time: 100
    power_pulse_time: 100

Most settings come in three: "main", "sub", "headphones"¶

The FAST Audio Interface has three amplifiers. More details are in the Audio Interface wiring guide. The "main" amp is typically connected to your machine's backbox speakers, the "sub" is typically used for a subwoofer, and the "headphones" amp is connected to a ⅛" jack and typically used for headphones, (though you can also configure it for line-level output for connection to streaming or recording equipment, or your home theater 😁).

Anyway, you'll notice that most of the settings in MPF come in groups of three, one for each amp.

port:¶

Like other FAST hardware, you can specify the serial port for the audio interface, or you can use auto to have MPF automatically find it. (This is the default.)

debug:¶

Add debug: true to print all the FAST Serial Protocol commands on the AUD interface to the log.

main_amp_enabled:, sub_amp_enabled:, headphones_amp_enabled:¶

These settings control whether each amp is enabled or not. The default is true for all three. If you don't have one of the amps hooked up to anything, set it to false to disable it.

main_steps:, sub_steps:, headphones_steps:¶

This is the number of volume steps for each amp. This does NOT affect how loud the "max" volume is. (That's controlled via the max_hw_volume settings below.`) Rather this is how many steps there are between 0 and the max volume.

The default is 20, but the FAST Audio Interface hardware supports 63 levels of granularity. (So 63 is the max value here). MPF will automatically add a "zero" volume level, so if you set this to 20, you'll technically have 21 volume levels, 0-20.

One of the nice features of having this set per-amp is you can have different numbers of steps for each amp. For example, you might want to have 20 steps for the main amp, but only 10 for the headphones.

All volume level references in MPF are on the scale that you specify here. So if you set the number of steps to 20, then a volume of 10 will be 50% volume, etc.

Also note that you can display the volume at any scale you want, using dynamic values in MPF display widgets and events. So if you set this to 20, you can still display the volume as a percentage 0-100% at 5% increments, etc.

default_main_volume:, default_sub_volume:, default_headphones_volume:¶

MPF stores the current volume of each amp in three machine variables: fast_audio_main_volume, fast_audio_sub_volume, and fast_audio_headphones_volume.

This is nice because machine variables can be persisted to disk when MPF is powered down, so this means the volume for each amp can be remembered between boots. (This is controlled by the persist_volume_settings setting below.)

If MPF boots and there are no values for these variables, it will use these default values. The default is 10 for all three. (And again, these are all on the scale of the "steps" setting above.)

persist_volume_settings:¶

If you set persist_volume_settings: true, then MPF will save the volume machine variables to disk when the machine shuts down, and restore them when the machine boots. If you set this to false, then the volume settings will be lost when the machine shuts down and the defaults from the sections above will be used. The default is true.

max_hw_volume_main:, max_hw_volume_sub:, max_hw_volume_headphones:¶

These are the maximum hardware volume levels for each amp, on the FAST Audio Interface hardware scale of 0-63. Note that these are NOT on the same scale as the "steps" settings above.

The maximum value you set here will be the maximum volume level that MPF will set the amp to when the volume is all the way up (based on the steps values above).

Using the default max of 63 is probably fine in many cases, though depending on your machine and speakers, sometimes setting the volume too loud will distort or sound bad, so you can use these settings to dial back the max volume if you want.

link_sub_to_main:, link_headphones_to_main:¶

These control whether the sub or headphones amp volume levels are linked to the main amp.

A value of true means they are linked, so when the main volume changes, the linked amp will change too. This provides a nicer interface for the user since they can have simple volume up / volume down controls which could control both the main and sub amps.

The default is true for sub the and false for the headphones. (Most likely you would not want to have the headphones linked to the speaker volumes, but if you re-purpose the headphone amp for an additional set or speakers, you might want to link its volume to the main as well.)

One of the cool things about linking the amps is that each amp can have its own custom levels for each volume step. (This is covered in the next section.) This means a volume of "6" for the main and sub amps might be different actual volume levels, but they will be the same relative volume level. (e.g. 6 might be 50% volume for the main amp, but 75% volume for the sub amp.)

In order to link an amp to the main, it has to have the same number of volume steps as the main. (So if you set the main to 20 steps, then the sub or headphone amps must also be set to 20 steps to link them.)

main_levels_list:, sub_levels_list:, and headphones_levels_list:¶

These settings let you map the friendly volume level to the actual hardware volume level for each amp. (e.g. volume 1 might be 02 for the hardware, volume 2 is 05, volume 3 is 09, etc.) By creating a custom list, you can tune the volume levels for each amp to sound perfect to your ear.

These settings are optional. If you do not specify a custom list, then MPF will automatically calculate the lists when it starts based on the number of steps and max_hw_volume settings mentioned above. (Technically this list has one more entry than the number of steps you specified above, because it includes the 0 value.)

All that said, sometimes when you have a linear list, the volume levels don't "feel" even, as some steps might sound the same or have too big of a jump. So these settings let you type in your own list of volume levels for each step of each amp.

To specify a list, you'll need to enter a comma-separated list of hardware volume (0-63)values. The number of entries in your list will be the number of steps for your volume. (You will need to start your list with zero, but will want it to be one entry longer than the number of steps you want. e.g. if you want your volume to have 20 steps, you'll need to specify a list of 21 values.) And the value of the highest number in your list will be the maximum hardware volume. When you manually enter a volume levels list for an amp, MPF will ignore the max_volume and steps settings for that amp since those are dictated by the length and content of your list.

You can create different length lists for each amp, but if you want to link the sub or headphones to the main, then they must have the same number of items in the list as the main.

Keep in mind that the actual values for each position do not need to be the same across amps. Actually, that's kind of the whole point. You can tune each amp for each step so it sounds perfect to your ear. Then as you increase the volume up or down, MPF will select the actual value for each amp in that position.

Here's an example of how this might look:

fast:
  aud:
    main_levels_list: 0, 3, 6, 9, 12, 14, 16, 18, 20, 24, 28, 32, 36, 40, 44, 48, 52, 56, 60, 62, 63
    sub_levels_list: 0, 2, 4, 6, 8, 10, 12, 14, 16, 18, 20, 22, 24, 26, 28, 30, 32, 34, 36, 38, 40
    link_sub_to_main: true
    headphones_steps: 10
    max_hw_volume_headphones: 63

So a volume of "0" will set the hardware level of the main amp to 0, and the sub to 0. A volume of 3 will be the 4^th item of each list which would set the hardware volume of the main amp to 9 and the sub to 6.

headphones_level:¶

This setting controls the audio level of the headphones jack. The default is headphones, which means the headphones jack is being used for headphones. You can also set this to line to make the headphones jack a line-level output. (Even if you have a headphone jack on the front of your machine, you might choose to expose this setting in the service menu so people could plug this into a streaming or video rig to capture perfect audio from your machine.)

mute_speakers_with_headphones:¶

This setting controls whether the speakers (main+sub) are muted when the headphones are plugged in. The default is true. If you set it to false, then when you plug in headphones, the main and sub speakers will continue to play. (The speakers will fade down and the headphones rise up over a few seconds of cross fading.)

Note that the FAST Audio Interface uses impedance sensing to detect when headphones are plugged in, so even though you'll need to use a headphone extension cable running to the front of your machine for the headphones, you can still use these settings to control what happens when they're plugged in.

If your headphones_level is set to line, then this setting is ignored.

Also MPF is able to detect when headphones are plugged in, so if you want to customize the exact behavior of what happens, you can.

pulse_time settings:¶

The FAST Audio Interface has control pins which you can use to control the power or reset lines of your computer running MPF, and to control the menu button settings on an LCD screen.)

These settings specify the default pulse times, in milliseconds, for the various control pins on the audio interface. The default is 100ms for all of them.

Controlling the volume from MPF¶

Now that you have your audio interface configured, you need a way to actually control the hardware volume from MPF itself. In MPF, the FAST Audio Interface uses machine variables to store the volume levels of the three amps. To change the volume of an amp, you just change the machine variable value, and the FAST Audio Interface will pick up the event notification from that and change the volume. The three machine variables are fast_audio_main_volume, fast_audio_sub_volume, and fast_audio_headphones_volume.

The master_volume machine variable has nothing to do with hardware audio!

If you use the MPF-MC, you might be familiar with the master_volume machine variable which has a value of 0.0 - 1.0. This setting is connected to the software audio mixer in MPF-MC, and has nothing to do with the FAST Audio Interface.

In most cases, you will want to set the master_volume to a level that allows for the loudest, clean sound, and then use the FAST Audio machine variables to control the actual volume of the amps.

Remember that the volume values you set the machine variables to are on the scale of the steps setting you specified above (which in turn are translated to hardware volume settings via the volume levels list).

You can use the variable_player: section of your config file to set up MPF events which change the value of machine variables. (This is similar to how you set up scoring, etc.)

You can just copy and paste this complete section into your config file to set up these events:

variable_player:
  increase_main_volume:
    fast_audio_main_volume:
      action: add_machine
      int: 1
  decrease_main_volume:
    fast_audio_main_volume:
      action: add_machine
      int: -1
  increase_sub_volume:
    fast_audio_sub_volume:
      action: add_machine
      int: 1
  decrease_sub_volume:
    fast_audio_sub_volume:
      action: add_machine
      int: -1
  increase_headphones_volume:
    fast_audio_headphones_volume:
      action: add_machine
      int: 1
  decrease_headphones_volume:
    fast_audio_headphones_volume:
      action: add_machine
      int: -1

Then, you simply need to post these events to increase or decrease the volume. For example, to increase the main volume, you would post the increase_main_volume event. To decrease the sub volume, you would post the decrease_sub_volume event, etc.

If you have your sub or headphones amps linked to the main, then you can just post the main volume events and the sub and headphones will automatically change too.

Temporarily changing the volume without saving it to disk¶

The MPF FAST Audio Interface allows you to temporarily change the volume without saving it to disk. For example, you might want to lower the volume temporarily when the coin door is opened, and restore it when it's closed, and you wouldn't want that temporary low value to be saved if the machine is powered down while the door is open.

To temporarily change the volume, post an event fast_audio_temp_volume. You will need to attach 2 keyword/value pairs, one specifying which amp you want to change, and the other is how many steps (positive or negative) you want it to change. For example, amp=main, change=5. (If you have the sub or headphones linked to the main, then they will change too.)

To restore the amp to the previous value (from the machine variable), post the event fast_audio_restore with the k/v pair amp=main.

Using events to pulse the control pins¶

You can use the following events to pulse the control pins:

fast_audio_pulse_lcd_pin, pin=1 (Valid pin values are 1-6)
fast_audio_pulse_power_pin
fast_audio_pulse_reset_pin

You can add a ms keyword to any of these events to override the default pulse time you set in your config file.

Next Up: Segment Displays

N or > jump the next page, P or < for previous, search with S or ?