ControlMedia Command
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 |
---|---|---|---|
|
Enumeration from command |
Required |
Command to issue on the media player, for example, |
|
|
The Video component. | |
|
Integer |
0 |
Optional data value required for the |
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 |
---|---|---|---|---|
|
Playing |
— |
No |
Start playing media. |
|
Paused |
— |
Yes |
Stop playing media. |
|
Paused |
— |
Yes |
Go forward to the next media track in the source array. |
|
Paused |
— |
Yes |
Go backward to the previous media track in the source array. |
|
Paused |
— |
Yes |
Rewind the current media track to its start. |
|
Preserved |
Relative offset in milliseconds |
Yes |
Offset the media playback position to a specified |
|
Preserved |
Absolute time in milliseconds |
Yes |
Set the media playback position to a specified |
|
Paused |
Track index |
Yes |
Change the current track in the source array to the track at the specified |
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.
seekTo
Set the position of the player to an absolute value. This position is clipped to the valid range for the current track. The seekTo
operation preserves the state of video playback. If the video is playing when you issue the seekTo
command, the video jumps to the new position and continues to play. If the video is paused when you issue the seekTo
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
}
}
When you run the following command, the video jumps to 900 milliseconds.
{
"type": "ControlMedia",
"componentId": "MyVideoPlayer",
"command": "seekTo",
"value": 900
}
If you run a command that attempts to move outside of the valid track range, the video is clipped to the track range. For example, the following command moves the player to 500 milliseconds.
{
"type": "ControlMedia",
"componentId": "MyVideoPlayer",
"command": "seekTo",
"value": 10
}
The seekTo
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.
Related topics
Last updated: frontmatter-missing