Matter Cluster 1286 — Media Playback Cluster

Cluster Identity

Revision history

Shadow Path Format

Cluster 1286 values in the device shadow use this format:

endpoint_id / 1286 / attribute_id

Example:

{
  "1/1286/0": 0
}

Cluster 1286 Features

The FeatureMap attribute (1/1286/65532) is a bitmap. Each bit set means the device implements that feature and the attributes and commands that depend on it.

Example: FeatureMap = 0 means no optional feature is enabled; 31 means every feature listed above is enabled.

Data Types

CharacteristicEnum

PlaybackStateEnum

StatusEnum

PlaybackPositionStruct (struct)

This structure defines a playback position within a media stream being played.

TrackAttributesStruct (struct)

This structure includes the attributes associated with a Text/Audio Track

TrackStruct (struct)

This structure defines a uniquely identifiable Text Track or Audio Track.

Cluster 1286 Attributes

Cluster 1286 defines 11 attributes plus the global attributes. Conformance: M mandatory, O optional, a feature code means "mandatory when that feature is present", square brackets mean "optional when …".

Global attributes

Attribute Details

Attribute 0 / 0x0000 — CurrentState

Path example:

1/1286/0

Indicates the current playback state of media. During fast-forward, rewind, and other seek operations; this attribute is set to PLAYING.

Values (PlaybackStateEnum):

Example:

{
  "1/1286/0": 0
}

Attribute 1 / 0x0001 — StartTime

Path example:

1/1286/1

Indicates the start time of the media, in case the media has a fixed start time (for example, live stream or television broadcast), or null when start time does not apply to the current media (for example, video-on-demand). This time is a UTC time. The client needs to handle conversion to local time, as required, taking in account time zone and possible local DST offset.

Example:

{
  "1/1286/1": 0
}

Attribute 2 / 0x0002 — Duration

Path example:

1/1286/2

Indicates the duration, in milliseconds, of the current media being played back or null when duration is not applicable (for example, in live streaming content with no known duration). This attribute must never be 0.

Example:

{
  "1/1286/2": 1
}

Attribute 3 / 0x0003 — SampledPosition

Path example:

1/1286/3

Indicates the position of playback (Position field) at the time (UpdateAt field) specified in the attribute. The client may use the SampledPosition attribute to compute the current position within the media stream based on the PlaybackSpeed, PlaybackPositionStruct.UpdatedAt and PlaybackPositionStruct.Position fields. To enable this, the SampledPosition attribute is updated whenever a change in either the playback speed or the playback position is triggered outside the normal playback of the media.

Value is a PlaybackPositionStruct struct (see Data Types).

Example:

{
  "1/1286/3": {
    "updatedAt": 1,
    "position": 1
  }
}

Attribute 4 / 0x0004 — PlaybackSpeed

Path example:

1/1286/4

Indicates the speed at which the current media is being played.

Example:

{
  "1/1286/4": 1
}

Attribute 5 / 0x0005 — SeekRangeEnd

Path example:

1/1286/5

Indicates the furthest forward valid position to which a client may seek forward, in milliseconds from the start of the media. When the media has an associated StartTime, a value of null indicates that a seek forward is valid only until the current time within the media, using a position computed from the difference between the current time offset and StartTime, in milliseconds from start of the media, truncating fractional milliseconds towards 0. A value of null when StartTime is not specified indicates that seeking forward is not allowed.

Example:

{
  "1/1286/5": 1
}

Attribute 6 / 0x0006 — SeekRangeStart

Path example:

1/1286/6

Indicates the earliest valid position to which a client may seek back, in milliseconds from start of the media. A value of null indicates that seeking backwards is not allowed.

Example:

{
  "1/1286/6": 1
}

Attribute 7 / 0x0007 — ActiveAudioTrack

Path example:

1/1286/7

Indicates the Audio track currently set and being used for the streaming media. A value of null indicates that no Audio Track corresponding to the current media is currently being played.

Value is a TrackStruct struct (see Data Types).

Example:

{
  "1/1286/7": {
    "id": "example",
    "trackAttributes": {
      "languageCode": "example",
      "characteristics": [],
      "displayName": "example"
    }
  }
}

Attribute 8 / 0x0008 — AvailableAudioTracks

Path example:

1/1286/8

Indicates the list of Audio tracks available for the current title being played. A value of null indicates that no Audio Tracks corresponding to the current media are selectable by the client.

Each entry is a TrackStruct (see Data Types).

Example:

{
  "1/1286/8": []
}

Attribute 9 / 0x0009 — ActiveTextTrack

Path example:

1/1286/9

Indicates the Text track currently set and being used for the streaming media. This can be nil. A value of null indicates that no Text Track corresponding to the current media is currently being displayed.

Value is a TrackStruct struct (see Data Types).

Example:

{
  "1/1286/9": {
    "id": "example",
    "trackAttributes": {
      "languageCode": "example",
      "characteristics": [],
      "displayName": "example"
    }
  }
}

Attribute 10 / 0x000A — AvailableTextTracks

Path example:

1/1286/10

Indicates the list of Text tracks available for the current title being played. This can be an empty list. A value of null indicates that no Text Tracks corresponding to the current media are selectable by the client.

Each entry is a TrackStruct (see Data Types).

Example:

{
  "1/1286/10": []
}

Cluster 1286 Commands

Cluster 1286 has 14 client-to-server commands and 1 response.

AcceptedCommandList

The AcceptedCommandList attribute lists the command IDs the endpoint actually implements:

endpoint_id / 1286 / 65529

{
  "1/1286/65529": [
    0,
    1,
    2,
    3,
    4,
    5,
    6,
    7,
    8,
    9,
    11,
    12,
    13,
    14
  ]
}

Bridge Command Payload Format

The bridge accepts Matter commands in this structure:

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 1,
    "cluster_id": 1286,
    "command_name": "Play",
    "payload": {},
    "timed_request_timeout_ms": 1000
  }
}

For Cluster 1286, always use "cluster_id": 1286. Payload keys are the command field names in lowerCamelCase. Octet-string fields are base64-encoded. timed_request_timeout_ms is required for timed commands and ignored otherwise.

Command: Play

Purpose

This command is used to start playback of the media. Upon receipt, this must play media. If content is currently in a FastForward or Rewind state. Play returns media to normal playback speed.

Command Identity

Payload Fields

This command has no payload fields.

Bridge Command Example

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 1,
    "cluster_id": 1286,
    "command_name": "Play",
    "payload": {}
  }
}

The device answers with PlaybackResponse (see below).

Command: Pause

Purpose

This command is used to pause playback of the media. Upon receipt, this must pause playback of the media.

Command Identity

Payload Fields

This command has no payload fields.

Bridge Command Example

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 1,
    "cluster_id": 1286,
    "command_name": "Pause",
    "payload": {}
  }
}

The device answers with PlaybackResponse (see below).

Command: Stop

Purpose

This command is used to stop playback of the media. Upon receipt, this must stop playback of the media. User-visible outcome is context-specific. This may navigate the user back to the location from where the media was originally launched.

Command Identity

Payload Fields

This command has no payload fields.

Bridge Command Example

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 1,
    "cluster_id": 1286,
    "command_name": "Stop",
    "payload": {}
  }
}

The device answers with PlaybackResponse (see below).

Command: StartOver

Purpose

This command is used to start playback of the media from the beginning. Upon receipt, this must Start Over with the current media playback item.

Command Identity

Payload Fields

This command has no payload fields.

Bridge Command Example

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 1,
    "cluster_id": 1286,
    "command_name": "StartOver",
    "payload": {}
  }
}

The device answers with PlaybackResponse (see below).

Command: Previous

Purpose

This command is used to go back to the previous media playback item. Upon receipt, this must cause the handler to be invoked for "Previous". User experience is context-specific. This will often Go back to the previous media playback item.

Command Identity

Payload Fields

This command has no payload fields.

Bridge Command Example

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 1,
    "cluster_id": 1286,
    "command_name": "Previous",
    "payload": {}
  }
}

The device answers with PlaybackResponse (see below).

Command: Next

Purpose

This command is used to go to the next media playback item. Upon receipt, this must cause the handler to be invoked for "Next". User experience is context-specific. This will often Go forward to the next media playback item.

Command Identity

Payload Fields

This command has no payload fields.

Bridge Command Example

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 1,
    "cluster_id": 1286,
    "command_name": "Next",
    "payload": {}
  }
}

The device answers with PlaybackResponse (see below).

Command: Rewind

Purpose

This command is used to rewind the media. Upon receipt, this must start playback of the media backward in case the media is currently playing in the forward direction or is not playing. If the playback is already happening in the backwards direction receipt of this command must increase the speed of the media playback backwards. Different "rewind" speeds may be reflected on the media playback device based upon the number of sequential calls to this function and the capability of the device.

Command Identity

Payload Fields

Bridge Command Example

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 1,
    "cluster_id": 1286,
    "command_name": "Rewind",
    "payload": {
      "audioAdvanceUnmuted": true
    }
  }
}

The device answers with PlaybackResponse (see below).

Command: FastForward

Purpose

This command is used to fast forward the media. Upon receipt, this must start playback of the media in the forward direction in case the media is currently playing in the backward direction or is not playing. If the playback is already happening in the forward direction receipt of this command must increase the speed of the media playback. Different "fast-forward" speeds may be reflected on the media playback device based upon the number of sequential calls to this function and the capability of the device.

Command Identity

Payload Fields

Bridge Command Example

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 1,
    "cluster_id": 1286,
    "command_name": "FastForward",
    "payload": {
      "audioAdvanceUnmuted": true
    }
  }
}

The device answers with PlaybackResponse (see below).

Command: SkipForward

Purpose

This command is used to skip forward in the media. Upon receipt, this must Skip forward in the media by the given number of milliseconds.

Command Identity

Payload Fields

Bridge Command Example

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 1,
    "cluster_id": 1286,
    "command_name": "SkipForward",
    "payload": {
      "deltaPositionMilliseconds": 1
    }
  }
}

The device answers with PlaybackResponse (see below).

Command: SkipBackward

Purpose

This command is used to skip backward in the media. Upon receipt, this must Skip backward in the media by the given number of milliseconds.

Command Identity

Payload Fields

Bridge Command Example

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 1,
    "cluster_id": 1286,
    "command_name": "SkipBackward",
    "payload": {
      "deltaPositionMilliseconds": 1
    }
  }
}

The device answers with PlaybackResponse (see below).

Command: PlaybackResponse

Purpose

This command is used to indicate the status of the command that was issued by the client. This command is generated in response to various Playback Commands.

Command Identity

Response Fields

Status values (StatusEnum): 0 = Success, 1 = InvalidStateForCommand, 2 = NotAllowed, 3 = NotActive, 4 = SpeedOutOfRange, 5 = SeekOutOfRange

Command: Seek

Purpose

This command is used to seek to a specific position in the media. Upon receipt, this must change the playback position in the media to the given position.

Command Identity

Payload Fields

Bridge Command Example

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 1,
    "cluster_id": 1286,
    "command_name": "Seek",
    "payload": {
      "position": 1
    }
  }
}

The device answers with PlaybackResponse (see below).

Command: ActivateAudioTrack

Purpose

This command is used to activate a specific Audio Track for the media being played. Upon receipt, the server must set the active Audio Track to the one identified by the TrackID in the Track catalog for the streaming media. If the TrackID does not exist in the Track catalog, OR does not correspond to the streaming media OR no media is being streamed at the time of receipt of this command, the server will return an error status of INVALID_ARGUMENT.

Command Identity

Payload Fields

Bridge Command Example

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 1,
    "cluster_id": 1286,
    "command_name": "ActivateAudioTrack",
    "payload": {
      "trackID": "example"
    }
  }
}

Command: ActivateTextTrack

Purpose

This command is used to activate a specific Text Track for the media being played. Upon receipt, the server must set the active Text Track to the one identified by the TrackID in the Track catalog for the streaming media. If the TrackID does not exist in the Track catalog, OR does not correspond to the streaming media OR no media is being streamed at the time of receipt of this command, the server returns an error status of INVALID_ARGUMENT.

Command Identity

Payload Fields

Bridge Command Example

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 1,
    "cluster_id": 1286,
    "command_name": "ActivateTextTrack",
    "payload": {
      "trackID": "example"
    }
  }
}

Command: DeactivateTextTrack

Purpose

This command is used to deactivate a specific Text Track for the media being played. If a Text Track is active (i.e. being displayed), upon receipt of this command, the server must stop displaying it.

Command Identity

Payload Fields

This command has no payload fields.

Bridge Command Example

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 1,
    "cluster_id": 1286,
    "command_name": "DeactivateTextTrack",
    "payload": {}
  }
}

Cluster 1286 Events

Event 0 — StateChanged

If supported, this event is generated when there is a change in any of the supported attributes of the Media Playback cluster.

SmartphoneKey Notes

• Cluster 1286 is not currently exposed by SmartphoneKey devices. This page documents the Matter 1.6.1 specification so that future devices can be interpreted without changes to the backend.
• Shadow paths follow endpoint/1286/attribute; attribute values that the device reports as unreadable are written as n/a.
• Attribute IDs, command IDs and enum values on this page come from the CSA Matter 1.6.1 data model; descriptions are condensed from the specification text.