APL Video (APL 1.6 to 1.7)


(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)

The Video component displays a video player that can display a single video or a series a videos. The embedded video player does not have any controls. Instead, the Video component 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.

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

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.

Devices that don't support video

Note that some devices with screens do not support video playback. On a device that does not support video, the Video component remains on the screen, but displays no content so users will see a blank area on the screen. Provide an alternative experience for devices that don't support video.

The disallowVideo property in the data-binding context returns true when the device does not support video. You can use this property in the conditional logic in your APL document.

Alternatively, you can check for video support in your skill code. Check the context.Viewport.video property in the request sent to your skill.

Properties

The Video component has the following properties in addition to the base component properties. See the meaning of the columns.

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 Default Styled Dynamic Description

audioTrack

One of: foreground, background, none

foreground

No

No

Audio track to play on.

autoplay

boolean

false

No

No

If true, automatically start playing the video.

onEnd

Array of commands

[ ]

No

No

Commands to run when the last video track is finished playing.

onPause

Array of commands

[ ]

No

No

Commands to run when the video switches from playing to paused.

onPlay

Array of commands

[ ]

No

No

Commands to run when the video switches from paused to playing.

onTimeUpdate

Array of command

[ ]

No

No

Commands to run when the playback position changes.

onTrackUpdate

Array of commands

[ ]

No

No

Commands to run when the current video track changes.

preserve

Array of string

[]

No

No

Properties to save when reinflating the document with the Reinflate command.

scale

One of: best-fill, best-fit

best-fit

No

No

How the video should scale to fill the space.

source, source

URL or source array

[ ]

No

Yes

Video source or sources.

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 causes the microphone to open while the video is playing. See Manage voice input after playing a video.

When the Video is the source or target of an event, the following values are reported in event.source or event.target:

{
  // Video-specific values
  "type": "Video",
  "currentTime": Integer, // Current playback position in the current track, expressed in milliseconds
  "duration": Integer,    // Duration of of the current track in milliseconds
  "ended": Boolean,       // True if the video is in the ended state
  "paused": Boolean,      // True if the video is in a paused state
  "trackCount": Integer,  // Total number of video tracks
  "trackIndex": Integer,  // Index of the current track (0-based)
  "url": URL,             // The URL of the current track

  // General component values
  "bind": Map,         // Access to component data-binding context
  "checked": Boolean,  // Checked state
  "disabled": Boolean, // Disabled state
  "focused": Boolean,  // Focused state
  "height": Number,    // Height of the component, in dp (includes the padding)
  "id": ID,            // ID of the component
  "opacity": Number,   // Opacity of the component [0-1]
  "pressed": Boolean,  // Pressed state
  "uid": UID,          // Runtime-generated unique ID of the component
  "width": Number      // Width of the component, in dp (includes the padding)
}

audioTrack

The audioTrack property assigns the media content to foreground or background audio, or mutes it entirely (none). Foreground audio interleaves with speech commands and sound effects. Background audio plays behind speech commands and sound effects. Only one audio source may be foreground or background at a time.

Value Description
foreground Audio plays on the foreground track. Speaking with the Alexa voice causes this media to pause.
background Audio plays on the background music track. It stops any existing background audio. Speaking with the Alexa voice may cause this media to duck or pause briefly.
none Audio content is ignored and only the video content is played.

With audioTrack set to foreground, the PlayMedia command does not "finish" until the all media tracks have finished. Thus, a simple command sequence can run that interleaves media content and speech, as shown in this example.

"onPress": [
  {
    "type": "PlayMedia",
    "componentId": "myVideoPlayer",
    "source": URL,
    "audioTrack": "foreground"
  },
  {
    "type": "SpeakItem",
    "description": "This will run after the media finishes playing",
    "componentId": "myAnswerBox"
  }
]

When a PlayMedia command has audioTrack set to background or none, the audio "finishes" immediately, and does not wait for the media content to end. Background media does not respond to touching the screen. For example, in the following sequence the SendEvent command fires immediately and does not wait for the media to finish playing.

"onPress": [
  {
    "type": "PlayMedia",
    "componentId": "myVideoPlayer",
    "source": URL,
    "audioTrack": "background"
  },
  {
    "type": "SendEvent",
    "description": "This will run immediately",
    "arguments": ["Media has started, but hasn't stopped yet"]
  }
]

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 false.

preserve

An array of dynamic component properties and bound properties to save when reinflating the document with the Reinflate command.

A Video component has the following component-specific property names you can assign to the preserve array:

  • source – The array of tracks
  • playingState – The state of the player (playing or paused).

The source option saves the current list of sources from the old video player and restores them in the new video player. This includes the currently selected track and position within that track.

The playingState option saves whether or not the video is currently playing. If playingState is not preserved, then the autoplay property in the video component is used to decide if the video player should automatically start playing video.

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 are 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 are applied to the sides or top/bottom of the video if it has different aspect ratio than the container.

source

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

If more than a single video is provided, the player plays 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 minimal definition is equivalent to the previous definition:

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

When source is a data array, it has the following structure:

Property Type Default Description
description String "" Optional description of this source material
duration Number none Duration of time to play, in milliseconds. If not set, defaults to the entire stream.
url URL REQUIRED Media source material
repeatCount Integer 0 Number of times to loop the video.
entity (entities) Array of Entities [] Entity data to set when reporting this media to Alexa
offset Number 0 Offset to start playing at in the stream.
duration
Duration of time to play, in milliseconds. Leave not set to play the full video. When set to a duration shorter than the actual media clip, this stops the playback after playing for the specified time. 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 not played.
url (urls)
The URL of the source of the media. Must be https URLs. Determine which formats are supported by checking the video property of the Viewport.
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": {
    "type": "Video",
    "handler": "End",
    ...                     // Component source properties
  },
  "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
}

Refer to Event source for a description of event.source properties.

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": {
    "type": "Video",
    "handler": "Pause",
    ...                     // Component source properties
  },
  "trackIndex": Integer,
  "trackCount": Integer,
  "currentTime": Integer,
  "duration": Integer,
  "paused": true,
  "ended": BOOLEAN
}

Refer to Event source for a description of event.source properties.

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": {
    "type": "Video",
    "handler": "Play",
    ...                     // Component source properties
  },
  "trackIndex": Integer,
  "trackCount": Integer,
  "currentTime": Integer,
  "duration": Integer,
  "paused": false,
  "ended": BOOLEAN
}

Refer to Event source for a description of event.source properties.

onTimeUpdate

The onTimeUpdate handler is invoked when the playback position of the current video changes. The handler is invoked on a "best effort" basis; there is no guaranteed frequency of invocation.

The event generated has the form:

"event": {
  "source": {
    "type": "Video",
    "handler": "TimeUpdate",
  ...                     // Component source properties
  },
  "trackIndex": Integer,
  "trackCount": Integer,
  "currentTime": Integer,
  "duration": Integer,
  "paused": BOOLEAN,
  "seekable": BOOLEAN,
  "ended": BOOLEAN
}

Refer to Event source for a description of event.source properties.

The onTimeUpdate handler always runs in fast mode.

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": {
    "type": "Video",
    "handler": "TrackUpdate",
    ...                     // Component source properties
  },
  "trackIndex": Integer,
  "trackCount": Integer,
  "currentTime": Integer,
  "duration": Integer,
  "paused": BOOLEAN,
  "ended": BOOLEAN
}

Refer to Event source for a description of event.source properties.


Was this page helpful?

Last updated: Nov 28, 2023