Transport Controls

Note: Learn how to improve your skills with APL with Build visually rich experiences using APL at the Alexa Learning Lab.

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

This example illustrates the default jump10 secondary controls.

{
  "type": "AlexaTransportControls",
  "mediaComponentId": "VideoPlayer1",
  "playPauseToggleButtonId": "PlayButton1",
  "secondaryControls": "jump10"
}

Transport controls with the default 'jump10' option

To define custom secondary controls

Set secondaryControlsAVGLeft and secondaryControlsAVGRight to the vector graphic pathData of a custom image to use for the left and right controls.
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": "SetState",
    "componentId": "PlayButton1",
    "state": "checked",
    "value": true
  },
  "secondaryControlsLeftAction": {
    "type": "SetState",
    "componentId": "PlayButton1",
    "state": "checked",
    "value": false
  }
}

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.

Last updated: Mar 02, 2023