APL Media Commands (APL 2022.2)

(This is not the most recent version of APL. Use the Other Versions option to see the documentation for the most recent version of APL)

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

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

String

SELF

Name of the media playing 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

The ID of the media component. If omitted, use the current component.

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 String SELF Name of the media-playing 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

The ID of the media component. If omitted, use the current component.

value

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

Was this page helpful?

Last updated: Nov 28, 2023