Transport Controls


The Alexa transport controls responsive component (AlexaTransportControls) displays a set of video player controls. You can customize the appearance of the buttons and define the commands to run when the user select the buttons.

Compatibility

AlexaTransportControls is designed to work with the following viewport profiles:

  • The following widget viewport profiles in the alexa-viewport-profiles package:
    • Widget Medium (@hubWidgetMedium)
  • All standard viewport profiles in the alexa-viewport-profiles package:
    • All hub round profiles
    • All hub landscape profiles
    • All hub portrait profiles
    • All mobile profiles
    • All TV profiles

For details about viewport profiles, see Viewport Profiles.

If you use AlexaTransportControls on an unsupported viewport, you might have unexpected results.

Differences for widgets

Widgets don't support playing video. In a widget, use AlexaTransportControls to display a "play" button that opens your skill to a full-screen video experience.

Import the alexa-layouts package

To use AlexaTransportControls, import the alexa-layouts package.

The latest version of the alexa-layouts package is 1.7.0. AlexaTransportControls was introduced in version 1.0.0.

Use the Other Versions option at the top of this page to see documentation for different versions of AlexaTransportControls. The table of parameters notes the version of alexa-layouts in which each parameter was added.

AlexaTransportControls parameters

All parameters except type are optional.

Name Type Default Description Widget support Version added

accessibilityLabel

String

Play pause button

A string describing the Play/Pause button. Voice over reads this string when user selects the Play/Pause button.

Medium

1.2.0

autoplay

Boolean

false

Determines the starting state of the play/pause icon. This should match the autoplay state of the media playing component.

Not supported

1.0.0

entities

Array

Array of entity data to bind to this component.

Medium

1.2.0

mediaComponentId

String

The id of the media playing component. For example, the id for the Video component that displays the video to control.

Not supported

1.0.0

playPauseToggleButtonId

String

alexaPlayPauseToggleButton

Optional id for the Play/Pause toggle button. Use this property to identify the transport controls component in other commands, such as the onPlay / onPause handlers in the Video component. You must also set unique identifiers when you display multiple instances of AlexaTransportControls on the same screen.

Not supported

1.0.0

primaryControlPauseAction

Command

ControlMedia command

The command to run when the user selects the primary pause control.

When not set, selecting the control toggles the play/pause icon for the control and runs the ControlMedia command with the pause option and the media component specified with mediaComponentId. When used in a widget, the command should launch a full screen video experience.

Medium

1.2.0

primaryControlPlayAction

Command

ControlMedia command

The command to run when the user selects the primary play control.

When not set, selecting the control toggles the play/pause icon for the control and runs the ControlMedia command with the play option and the media component specified with mediaComponentId. When used in a widget, the command should launch a full screen video experience.

Medium

1.2.0

primaryControlSize

Dimension

@transportPrimaryButtonSize

The height and width for the primary button. When used in a widget, use the default size.

Medium

1.0.0

secondaryControlSize

Dimension

@transportSecondaryButtonSize

The height and width for the secondary buttons.

Not supported

1.0.0

secondaryControls

String

skip

The type of secondary controls to use. Valid options are skip | jump10 | jump30 | none. See Standard and custom secondary controls.

Not supported

1.2.0

secondaryControlsAVGLeft

String

The AVG path drawing data for a custom left secondary control. When defined, secondaryControlsLeftAction is required. Note that this value is same value you would include in the pathData property of an Alexa Vector Graphic. For details about defining the path data for a vector graphic, see pathData. See Standard and custom secondary controls.

Not supported

1.2.0

secondaryControlsAVGRight

String

The AVG path drawing data for a custom right secondary control. When defined, secondaryControlsRightAction is required. Note that this value is same value you would include in the pathData property of an Alexa Vector Graphic. For details about defining the path data for a vector graphic, see pathData. See Standard and custom secondary controls.

Not supported

1.2.0

secondaryControlsLeftAccessibilityLabel

String

A string describing the left secondary control. Voice over reads the string when user selects the left secondary control.

Not supported

1.2.0

secondaryControlsLeftAction

Command

The command to run when the user selects the custom left secondary control. Applies when secondaryControlsAVGLeft is set. See Standard and custom secondary controls.

Not supported

1.2.0

secondaryControlsRightAccessibilityLabel

String

A string describing the right secondary control. Voice over reads the string when user selects the right secondary control.

Not supported

1.2.0

secondaryControlsRightAction

Command

The command to run when the user selects the custom right secondary control. Applies when secondaryControlsAVGRight is set. See Standard and custom secondary controls.

Not supported

1.2.0

theme

String

dark

Set the dark or light color theme. The selected theme controls the colors used for the component.

Medium

1.2.0

Standard and custom secondary controls

AlexaTransportControls provides three options for the secondary controls. Alternatively, you can provide your own custom controls.

To use the standard secondary controls

Set secondaryControls to one of the following:

  • skip – Display the secondary controls as left and right "skip" buttons. Selecting these buttons runs the ControlMedia command with the previous / next option and the media component specified with mediaComponentId.
  • jump10 – Display the secondary controls as buttons to seek forward/backward 10 seconds. Selecting these buttons runs the ControlMedia command with the seek option set to 10 seconds and the media component specified with mediaComponentId.
  • jump30 – Display the secondary controls as buttons to seek forward/backward 30 seconds. Selecting these buttons runs the ControlMedia command with the seek option set to 30 seconds and the media component specified with mediaComponentId.

This example illustrates the default skip controls.

{
  "type": "AlexaTransportControls",
  "mediaComponentId": "VideoPlayer1",
  "playPauseToggleButtonId": "PlayButton1"
}
Transport controls with the default 'skip' option
Transport controls with the default 'skip' option

This example illustrates the default jump10 secondary controls.

{
  "type": "AlexaTransportControls",
  "mediaComponentId": "VideoPlayer1",
  "playPauseToggleButtonId": "PlayButton1",
  "secondaryControls": "jump10"
}
Transport controls with the default 'jump10' option
Transport controls with the default 'jump10' option

To define custom secondary controls

  1. Set secondaryControlsAVGLeft and secondaryControlsAVGRight to the vector graphic pathData of a custom image to use for the left and right controls.
  2. Set secondaryControlsLeftAction and secondaryControlsRightAction to the commands to run when the user selects the buttons. These properties are required when you set secondaryControlsAVGLeft and secondaryControlsAVGRight.
{
  "type": "AlexaTransportControls",
  "playPauseToggleButtonId": "PlayButton1",
  "secondaryControlsAVGLeft": "M21,8H3C2.448,8,2,7.552,2,7s0.448-1,1-1h18c0.553,0,1,0.448,1,1S21.553,8,21,8z M22,12c0-0.552-0.447-1-1-1H3 c-0.552,0-1,0.448-1,1s0.448,1,1,1h18C21.553,13,22,12.552,22,12z M22,17c0-0.553-0.447-1-1-1H3c-0.552,0-1,0.447-1,1s0.448,1,1,1 h18C21.553,18,22,17.553,22,17z",
  "secondaryControlsAVGRight": "M1,7c0-0.552,0.448-1,1-1c3.161,0,5.354,1.74,7.314,3.78c-0.272,0.295-0.539,0.591-0.801,0.883 c-0.186,0.206-0.367,0.406-0.549,0.606C6.238,9.458,4.444,8,2,8C1.448,8,1,7.552,1,7z M22.789,16.59l-5.002-3.5 c-0.153-0.106-0.354-0.12-0.518-0.033C17.104,13.143,17,13.313,17,13.5v2.407c-1.949-0.335-3.483-1.622-4.966-3.174 c-0.181,0.2-0.362,0.399-0.547,0.604c-0.261,0.29-0.528,0.585-0.799,0.88c1.747,1.814,3.678,3.391,6.312,3.715V20.5 c0,0.187,0.104,0.357,0.27,0.443C17.342,20.981,17.421,21,17.5,21c0.101,0,0.201-0.03,0.287-0.09l5.002-3.5 c0.133-0.094,0.213-0.247,0.213-0.41S22.922,16.684,22.789,16.59z M22.789,6.59l-5.002-3.5c-0.153-0.107-0.354-0.121-0.518-0.034 C17.104,3.143,17,3.313,17,3.5v2.568c-3.368,0.414-5.591,2.872-7.743,5.264C7.096,13.732,5.055,16,2,16c-0.552,0-1,0.447-1,1 s0.448,1,1,1c3.945,0,6.384-2.71,8.743-5.331c1.916-2.128,3.74-4.144,6.257-4.576V10.5c0,0.187,0.104,0.357,0.27,0.443 C17.342,10.981,17.421,11,17.5,11c0.101,0,0.201-0.03,0.287-0.09l5.002-3.5c0.133-0.094,0.213-0.247,0.213-0.41 S22.922,6.684,22.789,6.59z",
  "secondaryControlsRightAction": {
    "type": "SetValue",
    "componentId": "PlayButton1",
    "property": "checked",
    "value": true
  },
  "secondaryControlsLeftAction": {
    "type": "SetValue",
    "componentId": "PlayButton1",
    "property": "checked",
    "value": false
  }
}
Transport controls with custom secondary controls
Transport controls with custom secondary controls

AlexaTransportControls example

The following example illustrates an APL document that displays Video component with the AlexaTransportControls. Note that the onPlay and onPause handlers for the Video component set the checked state of AlexaTransportControls. This keeps the play/pause icon in sync with whether the video is playing or paused.


The following example shows the AlexaTransportControls component used in a widget. When the user taps the "Play" button, the widget runs the SendEvent command to send a request to the skill. The skill can then open a full-screen video experience. To test the SendEvent command, copy the example into a skill.



Was this page helpful?

Last updated: Dec 06, 2023