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.

For design guidance, see Transport Controls.

Import the alexa-layouts package

To use AlexaTransportControls, import the alexa-layouts package.

The latest version of the alexa-layouts package is 1.4.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 Version added/updated

accessibilityLabel

String

Play pause button

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

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.

1.0.0

entities

Array

[]

Array of entity data to bind to this component.

1.2.0

mediaComponentId

String

none

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

1.0.0

playPauseToggleButtonId

String

alexaPlayPauseToggleButton

Optional id for the 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.

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.

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.

1.2.0

primaryControlSize

Dimension

@transportPrimaryButtonSize

The height and width for the primary button.

1.0.0

secondaryControlSize

Dimension

@transportSecondaryButtonSize

The height and width for the secondary buttons.

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.

1.2.0

secondaryControlsAVGLeft

String

none

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.

1.2.0

secondaryControlsAVGRight

String

none

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.

1.2.0

secondaryControlsLeftAccessibilityLabel

String

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

1.2.0

secondaryControlsLeftAction

Command

none

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

1.2.0

secondaryControlsRightAccessibilityLabel

String

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

1.2.0

secondaryControlsRightAction

Command

none

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

1.2.0

theme

String

dark

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

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": "SetState",
    "componentId": "PlayButton1",
    "state": "checked",
    "value": true
  },
  "secondaryControlsLeftAction": {
    "type": "SetState",
    "componentId": "PlayButton1",
    "state": "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.

AlexaTransportControls with a Video component
AlexaTransportControls with a Video component