PlayMedia Command

Plays media on a video player.


The PlayMedia command has the properties shown in the following table, in addition to the common command properties. Set the type property to PlayMedia.

In the following table, the "Default" column shows "Required" for properties that must have a value for the command to run. Otherwise it displays the default value, which might be none.

Property Type Required Description


background, foreground, none


Audio track to play on. Defaults to foreground.




The Video component.


URL or Source array


Media source

Running a PlayMedia command on a player that is actively playing content will cause the player to stop the current playback, clear all existing source data, and replace it with the newly provided source data. The media content will automatically load and start playing.

The duration of the PlayMedia command is a function of the audioTrack. When the audioTrack is set to "foreground", the PlayMedia command remains active for as long as the media is playing. When the audioTrack is set to "background" or "none", the PlayMedia command returns immediately. For example, to sequence a media track with speech, write:

  "type": "Sequential",
  "items": [
      "type": "PlayMedia",
      "componentId": "myAudioPlayer",
      "source": "",
      "audioTrack": "foreground"
      "type": "SpeakItem",
      "componentId": "mySpokenItem"

In the above case, the SpeakItem command runs after the media track finishes playing. If the audioTrack had been set to "background", the SpeakItem command starts just after the media track starts playing. An action that stops the PlayMedia command early (for example, by the user touching on the screen or by a new command being received from Alexa) stops the video playing only when the audioTrack is set to foreground. If the audioTrack is "background", the PlayMedia command has already finished and there is nothing to stop.

The PlayMedia command is ignored in fast mode.


Refer to the audioTrack property in the Video component.


A selector that identifies the Video component. When not provided, defaults to :source. The :source selector targets the component that issued the PlayMedia command.


Refer to Video for the definition of the source property.

Reinflation strategy

When the Reinflate command runs, the PlayMedia command can resume after Alexa reinflates the document. The PlayMedia command resumes when all of the following conditions are met:

  • The command runs on a sequencer that is specified in the preservedSequencers array on Reinflate.
  • Both the source and playingState properties on the Video component are specified in the preserve property for the Video component.

Was this page helpful?

Last updated: frontmatter-missing