VideoApp Interface Reference

Note: Sign in to the developer console to build or publish your skill.

The VideoApp interface provides the VideoApp.Launch directive for streaming native video files on Alexa-enabled devices with a screen. Your skill can send the VideoApp.Launch directive to launch a video. Your skill can send a launch directive in response to a voice request, or in response when a user taps a programmed item on the screen.

Note: Not all devices support the VideoApp interface. Always check for VideoApp support in the context.System.device.SupportedInterfaces property in the incoming request before you attempt to send video content.

Supported Video Formats and Resolutions
VideoApp Features
VideoApp as Seen on Alexa-enabled devices with a screen
Configure Your Skill for the VideoApp Directives
Implement VideoApp Directives
Parameters of Response
Service Interface Reference (JSON)

Supported Video Formats and Resolutions

Supported video formats for VideoApp are shown in the following table.

Streaming format	Accompanying audio format
HLS, MPEG-TS	AAC
SmoothStreaming (SS), MP4, M4A	AAC, Dolby, Dolby Digital Plus

In addition, follow these guidelines for any video referenced by the VideoApp directive:

Provide an HTTPS URL to video content.
Supported file extensions: .mp4, .m3u8, .ts
MPEG4 or H.264 codec
Recommended resolution (frame size): 640x480 or 1280x720
Maximum resolution: 1280x720

Note: Echo Spot does not support 4K videos.

VideoApp Features

The VideoApp as seen on Alexa-enabled devices with a screen has the following features:

GUI features:

Playback controls
Title
Subtitle

Voice Controls:

Alexa, pause/resume
Alexa, stop/close

VideoApp as Seen on Alexa-enabled devices with a screen

On Echo Show and Fire TV Cube, the VideoApp screens will look similar to the following.

Native Video

Error

This table compares the default view of VideoPlayer on each device. Only Echo Show and Echo Spot are shown here.

Echo Show	Echo Spot
VideoPlayer with visible touch controls	VideoPlayer with visible touch controls

The following images show Echo Spot video with various levels of zoom. The default display is "letterbox". The customer can change to the other levels of zoom.

With "letterbox" zoom, note that the video is scaled so that its width and height are fully within the screen.

This image shows full-screen video.

This image shows "pillowbox" video. Note that the height is scaled so as to fit completely within the screen vertically, but the horizontal dimension does not fit within the screen.

Configure Your Skill for the VideoApp Directives

To use VideoApp directives for video playback, you must indicate that your skill implements this interface

In the developer console, navigate to Custom > Interfaces.
Enable the Video App option and then click Save Interfaces. Be sure to click Build Model to re-build your interaction model.

The standard built-in intents are implemented automatically, except that AMAZON.CancelIntent is not supported. They are described in Standard Intents. These standard built-in intents work with VideoApp:

AMAZON.PauseIntent and AMAZON.StopIntent, which send the same message to the skill
AMAZON.ResumeIntent

Implement VideoApp Directives

The VideoApp interface provides the VideoApp.Launch directive, which sends Alexa a command to stream the video file identified by the specified videoItem field.

The source for videoItem must be a native video file. Only one video item at a time may be supplied.

When including a directive in your skill service response, set the type property to the directive you want to send. Here is an example of a full response object sent from a LaunchRequest or IntentRequest.

In this example, one native-format video will be played.

{
  "version": "1.0",
  "sessionAttributes": null,
  "response": {
    "outputSpeech": null,
    "card": null,
    "directives": [
      {
        "type": "VideoApp.Launch",
        "videoItem": {
          "source": "https://www.example.com/video/sample-video-1.mp4",
          "metadata": {
            "title": "Title for Sample Video",
            "subtitle": "Secondary Title for Sample Video"
          }
        }
      }
    ],
    "reprompt": null
  }
}

For the full response format, see Response Body Syntax in the JSON Interface Reference for Custom Skills.

The back button is displayed on every VideoApp screen, and cannot be hidden, unlike for the Display interface. If clicked, the back button takes the customer to the previous display template in the current session. See Back Button in Display Templates.

Parameters of Response

See Response Body Syntax for more details. This section refers to the VideoApp-specific parameters of the response.

Important notes are as follows:

Do not include a Display.RenderTemplate directive in the same response.
Do not include the shouldEndSession parameter in the response, even if you set the value to null.

Parameter	Description	Type	Required?
`videoItem`	Contains an object providing information about the video stream to play.	object	yes

The following are sub-parameters of videoItem.

Parameter	Description	Type	Required?
`source`	Identifies the location of video content at a remote HTTPS location. The video file must be hosted at an Internet-accessible HTTPS endpoint. HTTPS is required, and the domain hosting the files must present a valid, trusted SSL certificate. Self-signed certificates cannot be used. Many content hosting services provide this. For example, you could host your files at a service such as Amazon Simple Storage Service (Amazon S3) (an Amazon Web Services offering).	string	yes
`metadata`	Contains an object that provides the information that can be displayed on VideoApp.	object	no

The following are sub-parameters of videoItem.metadata.

Parameter	Description	Type	Required?
`title`	Title for the video, intended to be displayed in the VideoApp.	string	no
`subtitle`	Secondary title for the video, intended to be displayed in the VideoApp.	string	no

Service Interface Reference (JSON)

Request Format and Standard Request Types:

Interfaces:

Was this page helpful?

Provide feedback

Last updated: Nov 28, 2023