MediaPlayback Cluster

Cluster ID: 0x0506 | Endpoint: Media endpoint (TV, speaker, set-top box, etc.)

MediaPlayback is the core Cluster in Matter for controlling media playback. It provides standard media control operations such as play, pause, stop, fast-forward, rewind, and seek, applicable to TVs, smart speakers, set-top boxes, streaming players, and all devices that require media playback capabilities. All playback control commands return a unified PlaybackResponse containing an operation result status code.

Feature-Driven Capability Tiers

MediaPlayback uses 5 Feature bits to control different capability tiers. Basic devices (such as simple speakers) only need to support basic commands like Play/Pause/Stop; advanced devices (such as smart TVs) can enable AdvancedSeek (AS) for position seeking, VariableSpeed (VS) for variable-speed playback, TextTracks (TT) and AudioTracks (AT) for subtitle and multi-audio-track switching.

Commands

The MediaPlayback Cluster has 14 commands covering everything from basic playback control to advanced seeking, audio track, and text track switching. All commands return a PlaybackResponse containing a StatusEnum status code upon execution. Click a command ID in the table below to jump to its detailed description.

ID	Name	Description	Required Feature
`0x00`	Play	Start or resume playback	None
`0x01`	Pause	Pause playback	None
`0x02`	Stop	Stop playback	None
`0x03`	StartOver	Restart from beginning	None
`0x04`	Previous	Previous track/episode	None
`0x05`	Next	Next track/episode	None
`0x06`	Rewind	Rewind	None
`0x07`	FastForward	Fast-forward	None
`0x08`	SkipForward	Skip forward by a specified duration	None
`0x09`	SkipBackward	Skip backward by a specified duration	None
`0x0B`	Seek	Seek to a specified position	AS
`0x0C`	ActivateAudioTrack	Switch audio track	AT
`0x0D`	ActivateTextTrack	Enable/switch text track	TT
`0x0E`	DeactivateTextTrack	Disable text track	TT

Play — Start Playback (0x00)

Starts or resumes media playback. On success, the CurrentState attribute changes to Playing (0). If playback is already in progress, the command still succeeds with no additional effect. No parameters required.

Usage Scenarios

Invoked when the user presses the play button on a remote, a voice assistant executes a "play" command, or playback is resumed after a pause.

↑ Back to Commands

Pause — Pause Playback (0x01)

Pauses current playback. On success, the CurrentState attribute changes to Paused (1). The device retains the current playback position and can resume via the Play command. No parameters required.

Usage Scenarios

Invoked when the user presses the pause button, playback is auto-paused on an incoming call, or a voice assistant executes a "pause" command.

↑ Back to Commands

Stop — Stop Playback (0x02)

Stops media playback and releases playback resources. On success, the CurrentState attribute changes to NotPlaying (2). Unlike Pause, Stop indicates the user does not intend to continue watching the current content. No parameters required.

Usage Scenarios

Invoked when the user exits the current content, switches to another app, or closes the player.

↑ Back to Commands

StartOver — Restart from Beginning (0x03)

Resets the playback position of the current content to the beginning and starts playback. No parameters required.

Usage Scenarios

Invoked when the user wants to rewatch the current episode or a voice assistant executes a "start over" command.

↑ Back to Commands

Previous — Previous Item (0x04)

Switches to the previous media item in the playlist (previous track/episode). If already at the first item, the device behavior is implementation-defined (may restart or ignore). No parameters required.

Usage Scenarios

Invoked when the user presses the previous track button on the remote or a voice assistant executes a "previous" command.

↑ Back to Commands

Next — Next Item (0x05)

Switches to the next media item in the playlist (next track/episode). If already at the last item, the device behavior is implementation-defined (may stop playback or loop to the first item). No parameters required.

Usage Scenarios

Invoked when the user presses the next track button on the remote or a voice assistant executes a "next" command.

↑ Back to Commands

Rewind — Rewind (0x06)

Starts rewinding playback. The device plays media content in reverse at an accelerated speed. If the device supports the VariableSpeed (VS) feature, consecutive calls can progressively increase the rewind speed (e.g., -2x, -4x, -8x), and PlaybackSpeed updates to a negative value. No parameters required.

Usage Scenarios

The user holds down the rewind button on the remote to find an earlier scene; consecutive presses increase the rewind speed.

↑ Back to Commands

FastForward — Fast-Forward (0x07)

Starts fast-forwarding playback. The device plays media content at an accelerated forward speed. If the device supports the VariableSpeed (VS) feature, consecutive calls can progressively increase the fast-forward speed (e.g., 2x, 4x, 8x), and PlaybackSpeed updates to the corresponding multiplier. No parameters required.

Usage Scenarios

The user holds the fast-forward button on the remote to skip ads or uninteresting segments; consecutive presses increase the speed.

↑ Back to Commands

SkipForward — Skip Forward (0x08)

Skips forward by a specified number of milliseconds from the current position. Unlike FastForward which is continuous, SkipForward is a one-time jump.

Parameter	Type	Description
DeltaPositionMilliseconds	uint64	Number of milliseconds to skip forward. For example, `30000` = skip forward 30 seconds

Usage Scenarios

Invoked by a "Skip 30 seconds" button in an app or when a voice assistant executes a "fast-forward 1 minute" command.

↑ Back to Commands

SkipBackward — Skip Backward (0x09)

Skips backward by a specified number of milliseconds from the current position. If the skip amount exceeds the elapsed playback time, the position resets to the beginning.

Parameter	Type	Description
DeltaPositionMilliseconds	uint64	Number of milliseconds to skip backward. For example, `10000` = skip backward 10 seconds

Usage Scenarios

The user missed a piece of dialogue and presses the "Back 10 seconds" button to review it.

↑ Back to Commands

Seek — Seek (0x0B)

Seeks to an absolute position in the media. Requires the device to support the AdvancedSeek (AS) feature. The seek position must be between SeekRangeStart and SeekRangeEnd; positions outside this range return a SeekOutOfRange (5) error.

Parameter	Type	Description
Position	uint64	Target position in milliseconds. For example, `600000` = seek to the 10-minute mark

Seek Range Validation

Before invoking Seek, you should first read the SeekRangeStart and SeekRangeEnd attributes to determine the seekable range. For live streams, the seekable range may be a sliding window (e.g., the last 2 hours); positions outside this window will be rejected.

Usage Scenarios

Invoked when the user drags the progress bar to a specific position or a voice assistant executes a "jump to the 30-minute mark" command.

↑ Back to Commands

ActivateAudioTrack — Switch Audio Track (0x0C)

Switches to the specified audio track. Requires the device to support the AudioTracks (AT) feature. The list of available audio tracks can be obtained from the AvailableAudioTracks attribute.

Parameter	Type	Description
TrackID	string	Target audio track ID, from the AvailableAudioTracks list
AudioOutputIndex	uint8	Audio output index (specifies which audio output the track routes to)

Usage Scenarios

The user switches the audio language of a movie on the TV, for example from the original English audio to a dubbed track.

↑ Back to Commands

ActivateTextTrack — Enable Text Track (0x0D)

Enables or switches to the specified text (subtitle) track. Requires the device to support the TextTracks (TT) feature. The list of available text tracks can be obtained from the AvailableTextTracks attribute.

Parameter	Type	Description
TrackID	string	Target text track ID, from the AvailableTextTracks list

Usage Scenarios

Invoked when the user enables subtitles while watching a foreign-language film or switches subtitle languages for practice.

↑ Back to Commands

DeactivateTextTrack — Disable Text Track (0x0E)

Disables the currently displayed text track. On success, the ActiveTextTrack attribute becomes null. Requires the device to support the TextTracks (TT) feature. No parameters required.

Usage Scenarios

Invoked when the user wants to turn off subtitles or a voice assistant executes a "disable subtitles" command.

↑ Back to Commands

PlaybackResponse — Command Response

All 14 commands return this response upon execution, containing an operation result status code and optional data.

Field	Type	Description
Status	StatusEnum	Command execution result. `0 (Success)` indicates success
Data	string / null	Optional additional data; content is implementation-defined

Response example:

{
  "Status": 0,     // Success
  "Data": null      // No additional data
}

↑ Back to Commands

Attributes

The MediaPlayback Cluster has 11 application attributes, divided into three groups: playback state, time information, and audio/text tracks. Click an attribute ID in the summary table below to jump to its detailed description.

ID	Name	Type	Group	Description
`0x0000`	CurrentState	PlaybackStateEnum	Playback State	Current playback state
`0x0001`	StartTime	epoch_us / null	Time Information	Media start time
`0x0002`	Duration	uint64 / null	Time Information	Total media duration (milliseconds)
`0x0003`	SampledPosition	PlaybackPositionStruct / null	Time Information	Sampled playback position
`0x0004`	PlaybackSpeed	single (float)	Time Information	Current playback speed
`0x0005`	SeekRangeEnd	uint64 / null	Time Information	Seekable range end (milliseconds)
`0x0006`	SeekRangeStart	uint64 / null	Time Information	Seekable range start (milliseconds)
`0x0007`	ActiveAudioTrack	TrackStruct / null	Audio & Text Tracks	Current audio track
`0x0008`	AvailableAudioTracks	list<TrackStruct> / null	Audio & Text Tracks	Available audio tracks list
`0x0009`	ActiveTextTrack	TrackStruct / null	Audio & Text Tracks	Current text track
`0x000A`	AvailableTextTracks	list<TrackStruct> / null	Audio & Text Tracks	Available text tracks list

Playback State (0x0000)

Describes the current playback state of the device. This is the only mandatory attribute of MediaPlayback.

ID	Name	Type	Description
`0x0000`	CurrentState	PlaybackStateEnum	The current playback state of the device. Apps should subscribe to this attribute to synchronize the play/pause button state on the UI. This is the only mandatory attribute of MediaPlayback

↑ Back to Attributes

Time Information (0x0001 ~ 0x0006)

Describes the time-related information of the current media: start time, total duration, current position, playback speed, and seekable range. Most of these attributes require the AdvancedSeek (AS) feature.

Time Units

Duration, SampledPosition.Position, SeekRangeStart, and SeekRangeEnd are in milliseconds. StartTime and SampledPosition.UpdatedAt are in microsecond-precision epoch (microseconds since 1970-01-01 UTC).

ID	Name	Type	Description
`0x0001`	StartTime	epoch_us / null	The start time of the current media content (microsecond-precision UTC epoch). For on-demand content, this is typically the publish time; for live streams, it is the stream start time. Nullable — `null` means not applicable. Requires AS feature
`0x0002`	Duration	uint64 / null	Total duration of the current media in milliseconds. For example, a 90-minute movie is `5400000`. Nullable — `null` means the duration is unknown (e.g., a live stream). Requires AS feature
`0x0003`	SampledPosition	PlaybackPositionStruct / null	The playback position as last sampled by the device, including the sample time and the corresponding playback position. Apps can combine `PlaybackSpeed` and the time difference from the sample to estimate the current actual position. Nullable — `null` means the device does not support position reporting. Requires AS feature
`0x0004`	PlaybackSpeed	single (float)	Current playback speed multiplier. `1.0` = normal speed, `2.0` = 2x fast-forward, `-1.0` = normal speed rewind, `0.0` = paused. Devices supporting the VS feature allow additional speed tiers. Requires AS feature
`0x0005`	SeekRangeEnd	uint64 / null	The furthest seekable position in milliseconds. For on-demand content, this is typically equal to Duration; for live streams, it is the latest rewindable position. The Seek command Position must not exceed this value. Nullable — `null` means no limit. Requires AS feature
`0x0006`	SeekRangeStart	uint64 / null	The earliest seekable position in milliseconds. For on-demand content, this is typically `0`; for live streams, it is the start boundary of the rewind window. The Seek command Position must not be less than this value. Nullable — `null` means no limit. Requires AS feature

Estimating Real-Time Position

The device does not push position updates in real time; instead, it provides a sampled snapshot via SampledPosition. Apps need to calculate the current position themselves: Current Position = SampledPosition.Position + (Current Time - SampledPosition.UpdatedAt) * PlaybackSpeed. Note that UpdatedAt is in microseconds and Position is in milliseconds, so unit alignment is required.

↑ Back to Attributes

Audio & Text Tracks (0x0007 ~ 0x000A)

Describes the available audio tracks and text tracks for the current media, as well as the currently active audio/text track. Requires the AudioTracks (AT) or TextTracks (TT) feature.

ID	Name	Type	Description
`0x0007`	ActiveAudioTrack	TrackStruct / null	The currently active audio track. Nullable — `null` means no audio track is active. Requires AT feature
`0x0008`	AvailableAudioTracks	list<TrackStruct> / null	All audio tracks provided by the current media. Used by apps to display the audio track selection list. Nullable — `null` means no audio track information is available. Requires AT feature
`0x0009`	ActiveTextTrack	TrackStruct / null	The currently displayed text track. Nullable — `null` means subtitles are disabled. Requires TT feature
`0x000A`	AvailableTextTracks	list<TrackStruct> / null	All text tracks provided by the current media. Used by apps to display the subtitle selection list. Nullable — `null` means no subtitle information is available. Requires TT feature

↑ Back to Attributes

Enum Definitions

PlaybackStateEnum — Playback State

Playback state enumeration for the device. Defines the value range for the CurrentState attribute.

Playing Playing — Media is currently playing normally

Paused Paused — Playback is paused and can be resumed

NotPlaying Not Playing — No content is playing (idle or stopped)

Buffering Buffering — Loading media data; playback is temporarily interrupted

StatusEnum — Command Response Status

Status code in PlaybackResponse, indicating the command execution result.

Success Success — Command executed successfully

InvalidStateForCommand Invalid State — Command cannot be executed in the current playback state

NotAllowed Not Allowed — Command was rejected (e.g., insufficient permissions)

NotActive Not Active — No active playback session

SpeedOutOfRange Speed Out of Range — Requested playback speed is outside the device's supported range

SeekOutOfRange Seek Out of Range — Requested position is outside the SeekRange bounds

Data Structures

PlaybackPositionStruct — Playback Position

Describes the playback position sampled by the device at a specific moment. Used for the SampledPosition attribute. After reading this structure, apps can combine it with PlaybackSpeed and the current time to estimate the real-time position.

Field	Type	Description
UpdatedAt	epoch_us	Sample timestamp (microsecond-precision UTC epoch). Indicates when this position information was captured
Position	uint64 / null	Playback position at the sample timestamp, in milliseconds. Nullable — `null` means position is unknown

TrackStruct — Track Information

Describes information about an audio or text track. Used in audio and text track related attributes.

Field	Type	Description
ID	string	Unique track identifier. Used as a parameter for the ActivateAudioTrack and ActivateTextTrack commands
TrackAttributes	TrackAttributesStruct	Detailed track attribute information (see below)

TrackAttributesStruct — Track Attributes

Field	Type	Required	Description
LanguageCode	string	Yes	Language code following the ISO 639-1 standard (e.g., `"zh"`, `"en"`, `"ja"`)
DisplayName	string / null	No	Optional display name for the app to show directly to the user (e.g., `"Chinese"`, `"English"`). Nullable

Feature Bitmap

The MediaPlayback Cluster declares which advanced capabilities the device supports via FeatureMap (0xFFFC):

Bit 0

AS (AdvancedSeek) Advanced Seek — Enables the Seek command, StartTime, Duration, SampledPosition, PlaybackSpeed, SeekRange, and related attributes

Bit 1

VS (VariableSpeed) Variable Speed — Allows Rewind/FastForward at multiple speed tiers (2x, 4x, etc.)

Bit 2

TT (TextTracks) Text Tracks — Enables text track related attributes and the ActivateTextTrack / DeactivateTextTrack commands

Bit 3

AT (AudioTracks) Audio Tracks — Enables audio track related attributes and the ActivateAudioTrack command

Bit 4

AA (AudioAdvance) Audio Advance — Supports advanced audio management capabilities such as audio output routing

Feature Combination Examples

Simple Bluetooth speaker: FeatureMap = 0x00 (basic playback control only). Smart TV: FeatureMap = 0x0F (AS + VS + TT + AT = 0b01111), supports progress bar, variable speed, subtitles, and multi-audio tracks. Streaming box: FeatureMap = 0x1F (all features), complete media playback experience.

Example Data

Read results of the MediaPlayback Cluster from a smart TV currently playing a movie (with AS + VS + AT + TT features enabled):

{
  // --- Playback State ---
  "0x0000": 0,                // CurrentState = Playing

  // --- Time Information (requires AS feature) ---
  "0x0001": 1695400000000000,  // StartTime (media start time, microsecond-precision epoch)
  "0x0002": 5400000,           // Duration = 5,400,000 ms (90 minutes)
  "0x0003": {                  // SampledPosition
    "UpdatedAt": 1695401200000000,
    "Position": 1230000
  },
  "0x0004": 1.0,               // PlaybackSpeed = 1.0 (normal speed)
  "0x0005": 5400000,           // SeekRangeEnd = 5,400,000 ms
  "0x0006": 0,                 // SeekRangeStart = 0 ms

  // --- Audio Track Information (requires AT feature) ---
  "0x0007": {                  // ActiveAudioTrack
    "ID": "audio-zh",
    "TrackAttributes": {
      "LanguageCode": "zh",
      "DisplayName": "Chinese"
    }
  },
  "0x0008": [                  // AvailableAudioTracks
    { "ID": "audio-zh", "TrackAttributes": { "LanguageCode": "zh", "DisplayName": "Chinese" } },
    { "ID": "audio-en", "TrackAttributes": { "LanguageCode": "en", "DisplayName": "English" } }
  ],

  // --- Text Track Information (requires TT feature) ---
  "0x0009": {                  // ActiveTextTrack
    "ID": "sub-zh",
    "TrackAttributes": {
      "LanguageCode": "zh",
      "DisplayName": "Chinese Subtitles"
    }
  },
  "0x000A": [                  // AvailableTextTracks
    { "ID": "sub-zh", "TrackAttributes": { "LanguageCode": "zh", "DisplayName": "Chinese Subtitles" } },
    { "ID": "sub-en", "TrackAttributes": { "LanguageCode": "en", "DisplayName": "English Subtitles" } }
  ]
}

Developer Tip

Most attributes are Nullable; simple devices may only report CurrentState (0x0000). Before reading, check FeatureMap (0xFFFC) to determine which features the device supports, then read the corresponding attributes as needed to avoid errors from reading non-existent attributes.

Common Scenarios

Scenario 1: Smart TV Playback Control and Progress Bar

Read FeatureMap (0xFFFC) to confirm the device supports the AdvancedSeek (AS) feature
Send Play (0x00) to start playback; subscribe to CurrentState (0x0000) to sync the play button state
Read Duration (0x0002) to get the total duration and render the progress bar
Periodically read SampledPosition (0x0003) and combine it with PlaybackSpeed (0x0004) to estimate the current position and update the progress bar
When the user drags the progress bar, read SeekRangeStart (0x0006) and SeekRangeEnd (0x0005) to confirm the range, then send Seek (0x0B) to jump
When the user taps the pause button, send Pause (0x01); tapping play again sends Play (0x00)

Scenario 2: Multi-Language Movie Audio and Subtitle Switching

Read FeatureMap to confirm the device supports AudioTracks (AT) and TextTracks (TT)
Read AvailableAudioTracks (0x0008) and display an audio track selection list in the app (e.g., "Chinese Dub," "English Original," "Japanese")
Read AvailableTextTracks (0x000A) and display a subtitle selection list in the app (e.g., "Chinese Subtitles," "English Subtitles," "Off")
User selects English original audio + Chinese subtitles:
- Send ActivateAudioTrack (0x0C) with TrackID set to the English audio track ID
- Send ActivateTextTrack (0x0D) with TrackID set to the Chinese subtitle track ID
User wants to turn off subtitles: send DeactivateTextTrack (0x0E)
Subscribe to ActiveAudioTrack (0x0007) and ActiveTextTrack (0x0009) to keep the app's current selections in sync