APL Video

A video player shows an embedded video or series of videos to play. With APL, the embedded video player does not have any controls. Instead, the video player provides the events and commands necessary to build the controls for controlling the video player. Refer to the PlayMedia and ControlMedia commands for how to drive the video player.

The video player has the following known issue:

  • If outputSpeech and video are played together, by setting the video's autoplay property to true, they play in parallel.

Sample video

{
  "type": "Video",
  "source": URL,
  "autoplay": true
}

Playback intents

You must implement built-in intents to support voice-based playback control.

Manage voice input after playing a video

If you want your skill to play a video and then accept voice input, use the onEnd event handler to invoke a SendEvent command. Your skill should handle the subsequent UserEvent request. Send a response with shouldEndSession set to false to accept voice input. Your response should include appropriate outputSpeech and reprompt objects to ask your Alexa customer for input.

Properties

The video player has the following properties in addition to the Component properties. The default height and width properties are each set at 100dp.

The media that is played is a single file. Live content is not supported.

Property Type Required Styled Dynamic Description
audioTrack foreground No No Audio track to play on. Defaults to foreground.  
autoplay boolean No No No If true, automatically start playing the video. Defaults to false.
scale One of: best-fill, best-fit No No No How the video should scale to fill the space. Defaults to best-fit.
source(s) URL or Source array No No Yes Video source or sources.
onEnd Array of commands No No No Commands to execute when the last video track is finished playing.
onPause Array of commands No No No Commands to execute when the video switches from playing to paused.
onPlay Array of commands No No No Commands to execute when the video switches from paused to playing.
onTrackUpdate Array of commands No No No Commands to execute when the current video track changes.

The height and width of the Video component default to 100dp if not specified.

Do not set autoplay to true and also set shouldEndSession to false in an effort to keep the session open for voice input. This will cause the microphone to open while the video is playing. See Manage voice input after playing a video.

source(s)

The sources property is an array of one or more videos to be played. If more than a single video is provided, the player will play each video in turn. The source property of the Video component and the url property of each source follow the rules of "array-ification". For the url property, a plain string can be accepted as a single URL, as well as an object with a url property. Thus, all of the following are valid ways to set the source property:

"source": URL
"source": [ URL ]
"source": { "url": URL }
"source": [ { "url": URL } ]
"source": [ URL1, { "url": URL2 } ] } ]

The most general way of specifying the media sources is to fully expand the definition:

"source": [
  {
    "description": "The first video clip to play",
    "offset": 150,   // Skip the first 150 milliseconds
    "url": URL1,
  },
  {
    "description": "The second video clip to play",
    "url": URL2,
    "repeatCount": -1    // Repeat forever
  },
  {
    "description": "This video clip will only be reached by a command",
    "url": URL3
  }
]

The following definition is minimalized and equivalent to the previous definition:

"source": [
  {
    "offset": 150,   // Skip the first 150 milliseconds
    "url": URL1,
  },
  {
    "url": URL2,
    "repeatCount": -1    // Repeat forever
  },
  URL3
]

audioTrack

The audio track to play audio content on.

Value Description
foreground The audio plays on the foreground track. Speaking with the Alexa voice causes this media to pause. This is the default and only option.

With audioTrack set to foreground, the PlayMedia command does not "finish" until the all media tracks have finished.

Skills that use the video component must provide a way to pause the video content by voice and using an on-screen button.

autoPlay

If set to true, the video automatically starts playing as soon as it is loaded. If false, the video must be explicitly told to start. Defaults to true.

scale

Scales the video within the container.

Name Description
best-fill Scale the video so that it fills the container with no letterboxing. The top/bottom or left/right sides of the video will be hidden if the video has a different aspect ratio than the container.
best-fit Scale the video so that it fits within the container. Letterbox blocks will be applied to the sides or top/bottom of the video if it has different aspect ratio than the container.

source

Holds the video clip or sequence of video clips to play. The source property may be either a plain URL or an array of source data.

If it is a data array, it has the following structure:

Property Type Required Description
description String No Optional description of this source material
duration Number No Duration of time to play. If not set, defaults to the entire stream. Expressed in milliseconds.
url (urls) One or more URLs/source objects. Each URL must be an https URL. Yes Media source material
repeatCount Integer No Number of times to loop the video. Defaults to 0.
offset Number No Offset to start playing at in the stream. Defaults to 0.

duration

The duration is the length of the media clip, in milliseconds. No extra playing time is added if the specified duration is longer than the actual media clip. If duration is zero or smaller, the media clip is skipped and will not be played.

url (urls)

The URL of the source of the media. Must be https URLs. The MPEG4 or H.264 codec formats are supported.

repeatCount

The number of times to repeat playing this media. Defaults to 0, which means to play once through and stop. If set to -1, the video will repeat forever.

offset

The offset from the start of the media where it should start playing, expressed in milliseconds. Defaults to 0, which means that play begins at the start of the media. A video with a positive repeatCount value will restart playing the media at the same offset each time.

Handlers

The following handlers are invoked as described.

onEnd

The onEnd handler is invoked when the last video in the video sequence finishes repeating and finishes playing. The onEnd handler can be invoked multiple times. For example, a video might play through to the end and stop, then receive a seek command to rewind to an earlier point, then receive a play command, and then play through to the end and stop.

The event generated has this form:

"event": {
  "source": {
    "source": "Video",
    "handler": "End",
    "id": ID,          // ID of the video component
    "value": null      // No value reported
  },
  "trackIndex": Integer,    // Will be equal to trackCount - 1.
  "trackCount": Integer,
  "currentTime": Integer,   // Will be equal to or greater than duration
  "duration": Integer,
  "paused": true,
  "ended": true
}

onPause

The onPause handler is invoked when the video playback intentionally switches from playing to paused. This may occur as a result of the video player reaching the end of the last video, a command being issued to the video player that stops playback, or by an interruption in synchronous video playback. The onPause handler is not invoked if the video player has to pause playback to download video content.

The event generated has this form:

"event": {
  "source": {
    "source": "Video",
    "handler": "Pause",
    "id": ID,          // ID of the video component
    "value": null      // No value reported
  },
  "trackIndex": Integer,
  "trackCount": Integer,
  "currentTime": Integer,
  "duration": Integer,
  "paused": true,
  "ended": BOOLEAN
}

onPlay

The onPlay handler is invoked each time when the video playback switches from paused to playing. This may occur in a video with autoplay set to true, from a PlayMedia command, or from a play command.

The event generated has this form:

"event": {
  "source": {
    "source": "Video",
    "handler": "Play",
    "id": ID,          // ID of the video component
    "value": null      // No value reported
  },
  "trackIndex": Integer,
  "trackCount": Integer,
  "currentTime": Integer,
  "duration": Integer,
  "paused": false,
  "ended": BOOLEAN
}

onTrackUpdate

The onTrackHandler handler is invoked when the active video track changes. This can happen during normal video sequence playback as the player advances to the next video track or as a result of a command issued against the player.

The event generated has this form:

"event": {
  "source": {
    "source": "Video",
    "handler": "Play",
    "id": ID,              // ID of the video component
    "value": trackIndex    // Equal to the trackIndex field below
  },
  "trackIndex": Integer,
  "trackCount": Integer,
  "currentTime": Integer,
  "duration": Integer,
  "paused": BOOLEAN,
  "ended": BOOLEAN
}