ControlMedia Command (APL 2023.1)

Controls a media player to play, pause, change tracks, or perform some other common action.

Properties

The ControlMedia command has the properties shown in the following table, in addition to the common command properties. Set the type property to ControlMedia.

In the following table, the "Default" column shows "Required" for properties that must have a value for the command to run. Otherwise it displays the default value, which might be none.

Property Type Default Description

command

Enumeration from command

Required

Command to issue on the media player, for example, play.

componentId

Selector

:source

The Video component.

value

Integer

0

Optional data value required for the seek, seekTo and setTrack commands.

For example:

{
  "type": "ControlMedia",
  "componentId": "myAudioPlayer",
  "command": "next"
}

The ControlMedia command supports all operations in fast mode except for the play sub-command.

command

The command enumerated value specifies the operation to perform on the media player. The following table lists the available commands.

Property Play/pause state Value Fast mode Description

play

Playing

—

No

Start playing media.

pause

Paused

—

Yes

Stop playing media.

next

Paused

—

Yes

Go forward to the next media track in the source array.

previous

Paused

—

Yes

Go backward to the previous media track in the source array.

rewind

Paused

—

Yes

Rewind the current media track to its start.

seek

Preserved

Relative offset in milliseconds

Yes

Offset the media playback position to a specified value.

setTrack

Paused

Track index

Yes

Change the current track in the source array to the track at the specified value.

play

Starts playing from the current media track and position. This command doesn't affect the current repeat counter on a video track. If the video isn't playing, the play operation generates an onPlay event.

{
  "type": "ControlMedia",
  "componentId": "myAudioPlayer",
  "command": "play"
}

pause

Pauses video playback. If the video is already playing, the pause operation generates an onPause event

{
  "type": "ControlMedia",
  "componentId": "myAudioPlayer",
  "command": "pause"
}

next

Pause video playback and move to the start of the next video track. The repeat counter for the new video track is honored. For example, if that video track is set to repeat twice, running the play command plays through the new video track three times in total. If the video player is already on the last video track, the video seek position moves to the end of the last video track and the repeat counter resets to zero.

For example:

{
  "type": "ControlMedia",
  "componentId": "myAudioPlayer",
  "command": "next"
}

Video playback doesn't start automatically after you invoke this command. The play command must be explicitly started to start video playback.

previous

Pause video playback and move to the start of the previous video track. The repeat counter for the new video track is honored. For example, if that video track is set to repeat twice, running the play command plays through the new video track three times in total. If the video player is already on the first video track, the video seek position moves to the start of the first video track and the repeat counter reloads.

For example:

{
  "type": "ControlMedia",
  "componentId": "myAudioPlayer",
  "command": "previous"
}

rewind

Pauses video playback and reloads the current video track. The repeat counter for the new video track reloads.

For example:

{
  "type": "ControlMedia",
  "componentId": "myAudioPlayer",
  "command": "rewind"
}

Video playback doesn't start automatically after you invoke this command. The play command must be explicitly started to start video playback.

seek

Apply a relative change to the position of the player. This value is relative to the current position of the player and is clipped to the valid range for the current track. The seek operation preserves the state of video playback. If the video is playing when you issue the seek command, the video jumps to the new position and continues to play. If the video is paused when you issue the seek command, the video remains paused and jumps to the new position.

For example, assume the following Video component with a clipped video track.

{
  "type": "Video",
  "id": "MyVideoPlayer",
  "source": {
    "url": "http://example.com/example.mp4",
    "offset": 500,
    "duration": 1000
  }
}

Assume the player is at 700 milliseconds when you run the following command:

{
  "type": "ControlMedia",
  "componentId": "MyVideoPlayer",
  "command": "seek",
  "value": 500
}

The command moves the player to 1200 milliseconds (700 + 500). If you run the same command a second time, the player moves to 1500 milliseconds instead of 1700 because the source definition limits the playback position to between 500 and 1500 milliseconds.

The seek command doesn't change the repeat counter for the current video track.

setTrack

Pause video playback and change the current track. Pass the track zero-based index to the value property for the command. This index must be a valid index in the source array or the command is ignored. The repeat counter for the track reloads, even if the track doesn't change.

For example:

{
  "type": "ControlMedia",
  "componentId": "myAudioPlayer",
  "command": "setTrack",
  "value": 2
}

Video playback doesn't start automatically after invoking this command. The play command must be explicitly started to start video playback.

componentId

A selector that identifies the Video component. When not provided, defaults to :source. The :source selector targets the component that issued the ControlMedia command.

value

The value to set for the command. Set the value for the seek, seekTo and setTrack commands.

Was this page helpful?

Last updated: frontmatter-missing