Skip to content

show_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 shows: section of a step.

The show_player: section of your config is where you start, stop, pause, (etc.) shows.

Here is an example:

show_player:
  some_event: your_show_name
  some_other_event: another_show

In the example above, when the event some_event is posted, the show called your_show_name will be played (started). When the event some_other_event is posted, the show called another_show will be played.

See Show player for details.

Optional settings

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

action:

Single value, type: one of the following options: play, stop, pause, resume, advance, step_back, update, queue. Default: play

play

: Starts playing the show. This is the default action which will happen if you don't include an action: setting.

stop

: Stops the show. Removes and "undoes" anything the show did, and posts the show stop events.

pause

: Pauses the show by holding it at the current step. Posts the show pause events.

resume

: Resumes a previously paused show.

advance

: Manually advances a show to the next step. Posts the show advance events.

step_back

: Manually moves the show back to the previous step. Posts the show step_back events.

update

: Not yet implemented. In the future it will be used to change a setting of a running show, like changing the playback speed.

block_queue:

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

You can use block_queue: yes if you want the show to block a queue event until the show is done. Note that you can only use this if the event that starts the show is a queue event.

For example, the mode stopping events are queue events. So take a look at the following config:

show_player:
  mode_my_mode_stopping:
    show_1:
      block_queue: true

In the example above, when the mode called my_mode posts its stopping event, show_1 will start playing. However because this show is set to block the queue event, the mode stopping event will not finish until the show finishes. In other words, the mode will not fully stop, and the mode_my_mode_stopped event will not be posted until the show ends.

If you didn't use the block_queue setting, then the show would start and then stop right away since the mode would end and be over (and shows started in modes are stopped when those modes end).

If you used this setting, make sure that you don't have loops: -1, or a duration: -1 as the final step of the show, since those will mean the show will never end, and then the queue event will never be unblocked, and your machine will hang.

events_when_advanced:

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

Event(s) that will be posted when this show has been manually advanced to the next step.

events_when_completed:

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

Event(s) that will be posted when this show has completed, meaning it ran through to the last step and ended naturally.

Note that if a show loops, these events are not posted when the loop happens. (You can use the events_when_looped for that.) However if a show is set to loop a specific number of times and then ends, these events will be posted at the end.

Note that if you want an event to post whenever the show stops, even if it didn't make it all the way to the end, you can use events_when_stopped.

events_when_looped:

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

Event(s) that will be posted when this show has looped (meaning it reached the end and is jumping back to the first step).

events_when_paused:

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

Event(s) that will be posted when this show has been paused.

events_when_played:

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

Event(s) that will be posted when this show is played (started).

events_when_resumed:

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

Event(s) that will be posted when this show is resumed from a pause.

events_when_stepped_back:

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

Event(s) that will be posted when this show has been manually stepped back to the previous step.

events_when_stopped:

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

Event(s) that will be posted when this show has been stopped. Note that these events are posted anytime the show has been stopped, regardless of whether it made it to the end and stopped on its own, or whether it was stopped randomly where it was.

events_when_updated:

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

Event(s) that will be posted when this show has been updated. Note that the show "update" function has not been implemented yet, so this setting is more of a placeholder at the moment.

key:

Single value, type: string. Defaults to empty.

Used to set a unique identifier you can set when playing a show which can then be used later to identify a show you want to perform an action on.

loops:

Single value, type: int_or_token. Default: -1

Controls the looping / repeating of the show. The default if you don't include this setting is loops: -1 means that the show will repeat indefinitely until it's stopped.

If you just want a show to play once and then stop, use loops: 0.

Since this setting is the number of times it loops, the value will be one less than the number of times the show will play. (e.g. loops: 1 means the show will loop once which means it will play through twice.)

Note that if a show only has one step, loops will be set to 0, regardless of the actual loops setting.

manual_advance:

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

If you set this to yes/true, then the show will not auto-advance based on time. Instead you will have to manually advance the show step-by-step with additional show_player entries with action: advance entries.

This can be useful if you want to have some kind of slow progress based on a series of events instead of a show that auto plays.

For example:

show_player:
  some_event:
    show_1:
      manual_advance: true
  some_advance_event:
    show_1:
      action: advance

In the example above, the event some_event will start show_1, but that show will stay on its first step since it's set to manually advance. Then each time the event some_advance_event is posted, show_1 will advance to its next step.

priority:

Single value, type: int_or_token. Default: 0

Adjusts the priority of the show that's played.

By default, shows play at the priority of the mode where the show_player entry is. So this setting merely adjusts the show's priority up or down. For example, if you have a mode running at priority 300, and a show in a show_player with the setting priority: 10, then that show will run at priority 310. Priorities can also be negative.

The show's priority affects the priority of everything it does. Sounds, slides, LEDs, etc.

show:

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!


show_queue:

Is this still a thing? Need to confirm, June 2023

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!


show_tokens:

One or more sub-entries. Each in the format of string : template_str

Allows you to specify show token values that will be used to replace the show tokens in the show when it's played.

Read what show tokens are here.

For example:

show_player:
  some_event:
    show1:
      show_tokens:
        led: right_inlane

In the example above, the show called "show1" will be played, but the show token called "led" in the show will be replaced at runtime with the value "right_inlane".

To learn more about show tokens and how to use dynamic values take a look at the Tokens reference page.

speed:

Single value, type: template_float_or_token. Default: 1

Controls the playback speed of the show. The default value of 1 means the show plays back at 1x speed. (In other words, it plays at the actual speed each step is configured for. In this case you don't actually need to include the setting.)

If you want to play the show at 2x the speed, use speed: 2. If you want to play it at half speed, use speed: .5. Etc.

You can use dynamic placeholders here also, as of MPF 0.56.1. This allows a show to be played using a variable speed.

start_running:

Single value, type: boolean or template (true/false; Instructions for entering templates). Default: True

Whether the show starts running immediately when it is played.

By default, calling play on a show begins at the starting step and advances through the steps according to the show config. If start_running is false, the show will play the starting step and immediately pause. You can begin playing the show by calling show_player with action: resume.

start_step:

Single value, type: integer or template (Instructions for entering templates). Default: 1

Which step the show starts on when it's played.

Note that you can use a dynamic value for this setting.

sync_ms:

Single value, type: int_or_token. Defaults to empty.

Sets the sync_ms value of this show which will delay the start to a certain millisecond multiple to ensure that multiple shows started at different times all play in sync with each other.

See the Synchronizing multiple shows documentation for details.

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!



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