APL Media Commands

Note: Learn how to improve your skills with APL with Build visually rich experiences using APL at the Alexa Learning Lab.

Use these commands to play media on a screen device with Alexa.

For an overview of how commands work, see APL Commands. For other commands, see APL Standard Commands.

Available media commands

The following table lists the standard commands. The "Reinflation support" column indicates whether the command takes time to run and therefore has a reinflation strategy. The "Widget support" column indicates whether you can use the command in a widget.

Command	Description	Reinflation strategy	Widget support
`ControlMedia`	Controls a media player to play, pause, change tracks, or perform some other common action.	No	Not supported
`PlayMedia`	Plays media on a video player.	Yes	Not supported

PlayMedia

Plays media on a video player.

The PlayMedia command has the following properties in addition to the standard command properties.

Property	Type	Required	Description
`audioTrack`	`background`, `foreground`, `none`	`foreground`	Audio track to play on. Defaults to `foreground`.
`componentId`	Selector	`:source`	The Video component.
`source`	URL or Source array	REQUIRED	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": "http://music.amazon.com/s3/MAGIC_TRACK_HERE",
      "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.

audioTrack

Refer to the audioTrack property in the Video component.

componentId

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

source

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.

ControlMedia

Controls a media player to play, pause, change tracks, or perform some other common action.

The ControlMedia command has the following properties in addition to the standard command properties:

Property	Type	Default	Description
`command`	`play`, `pause`, `rewind`, …	REQUIRED	Command to issue on the media player
`componentId`	Selector	`:source`	The Video component
`value`	Integer	0	Optional data value

For example:

{
  "type": "ControlMedia",
  "componentId": "myAudioPlayer",
  "command": "next"
}

The ControlMedia command supports most operations in fast mode. The exception is the play subcommand.

command

The command enumerated value is the operation that should be performed on the media player. The following commands are available:

Property	Play / Pause State	Value	Fast mode	Description
`play`	Playing	n/a	no	Start playing media.
`pause`	Paused	n/a	yes	Stop playing media
`next`	Paused	n/a	yes	Go to the next media track in the source array.
`previous`	Paused	n/a	yes	Go to the previous media track in the source array.
`rewind`	Paused	n/a	yes	Rewind the current media track to its start.
`seek`	Paused	relative offset in milliseconds	yes	Offset the media playback position
`setTrack`	Paused	track index	yes	Change the current track in the source array

play

Starts playing from the current media track and position. This command does not affect the current repeat counter on a video track. If the video is not playing, an onPlay event will be generated. For example:

{
  "type": "ControlMedia",
  "componentId": "myAudioPlayer",
  "command": "play"
}

pause

Pauses video playback. If the video is currently playing, an onPause event will be generated. For example:

{
  "type": "ControlMedia",
  "componentId": "myAudioPlayer",
  "command": "pause"
}

Pause video playback and move to the start of the next video track. The repeat counter for the new video track is honored (i.e., if that video track is set to repeat twice, then running the play command will play through the new video track three times in total). If the video player is already on the last video track, the video seek position will be moved to the end of the last video track and the repeat counter will be zeroed.

For example:

{
  "type": "ControlMedia",
  "componentId": "myAudioPlayer",
  "command": "next"
}

Video playback doesn't auto-start after invoking this command. The play command must be explicitly started to start video playback.

Pause video playback and move to the start of the previous video track. The repeat counter for the new video track is honored (i.e., if that video track is set to repeat twice, then running the play command will play through the new video track three times in total). If the video player is already on the first video track, the video seek position will be moved to the start of the first video track and the repeat counter will be reloaded.

For example:

{
  "type": "ControlMedia",
  "componentId": "myAudioPlayer",
  "command": "previous"
}

rewind

Pauses video playback and reloads the current video track. The repeat counter for the new video track is reloaded.

For example:

{
  "type": "ControlMedia",
  "componentId": "myAudioPlayer",
  "command": "rewind"
}

Video playback doesn't auto-start after invoking this command. The play command must be explicitly started to start video playback.

seek

Pause video playback and apply a relative change to the position of the player. This change is relative to the current position of the player and clips to the valid range for the current track.

For example, consider a clipped video track:

{
  "type": "Video",
  "id": "MyVideoPlayer",
  "source": {
    "url": "http://example.com/example.mp4",
    "offset": 500,
    "duration": 1000
  }
}

Assume the player is currently at 700 milliseconds. You run the following command:

{
  "type": "ControlMedia",
  "componentId": "MyVideoPlayer",
  "command": "seek",
  "value": 500
}

The command pauses playback and moves the player to 1200 milliseconds (700 + 500). If the same command is executed a second time the player moves to 1500 milliseconds because the source definition limits the playback position to between 500 and 1500 milliseconds.

The seek command doesn't change the repeat counter for the current video track. Video playback doesn't auto-start after the seek command runs. You must explicitly run the play command to start video playback.

setTrack

Pause video playback and change the current track. The desired track index (0-based) must be passed in the command data object. This index must be a valid index in the source array or the command will be ignored. The repeat counter for the track is reloaded (even if the track doesn't change).

For example:

{
  "type": "ControlMedia",
  "componentId": "myAudioPlayer",
  "command": "setTrack",
  "value": 2
}

Video playback doesn't auto-start after invoking this command. The play command must be explicitly started to start video playback.

componentId

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

value

The value to set for the command. This is used in the seek and setTrack commands.

Last updated: Feb 07, 2023

APL Media Commands

Available media commands

PlayMedia

audioTrack

componentId

source

Reinflation strategy

ControlMedia

command

play

pause

next

previous

rewind

seek

setTrack

componentId

value

Related topics