APL Media Commands
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 |
---|---|---|---|
Controls a media player to play, pause, change tracks, or perform some other common action. |
No |
Not supported | |
Plays media on a video player. |
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 |
---|---|---|---|
|
|
|
Audio track to play on. Defaults to |
|
|
The Video component. | |
|
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 thepreservedSequencers
array onReinflate
. - Both the
source
andplayingState
properties on theVideo
component are specified in thepreserve
property for theVideo
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"
}
next
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.
previous
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.
Related topics
Last updated: Feb 07, 2023