媒体播放 Cluster（MediaPlayback）

Cluster ID: 0x0506  |  所在 Endpoint: 媒体端点（电视、音箱、机顶盒等）

MediaPlayback 是 Matter 中用于控制媒体播放的核心 Cluster。 它提供了播放、暂停、停止、快进、快退、跳转等标准媒体控制操作， 适用于电视、智能音箱、机顶盒、流媒体播放器等所有需要媒体播放能力的设备。 所有播放控制命令都会返回统一的 PlaybackResponse，包含操作结果状态码。

命令（Commands）

MediaPlayback Cluster 共有 14 个命令，覆盖从基础播控到高级跳转、音轨字幕切换等全部操作。 所有命令执行后都会返回 PlaybackResponse，包含 StatusEnum 状态码。 点击下方表格中的命令 ID 可跳转到对应的详细说明。

Play —— 播放（0x00）

开始或恢复媒体播放。执行成功后，CurrentState 属性变为 Playing (0)。如果当前已经在播放，命令仍然成功但不产生额外效果。 不需要参数。

↑ 返回命令列表

Pause —— 暂停（0x01）

暂停当前播放。执行成功后，CurrentState 属性变为 Paused (1)。设备保留当前播放进度，可通过 Play 命令恢复。 不需要参数。

↑ 返回命令列表

Stop —— 停止（0x02）

停止媒体播放并释放播放资源。执行成功后，CurrentState 属性变为 NotPlaying (2)。与 Pause 不同，Stop 表示用户不打算继续观看当前内容。 不需要参数。

↑ 返回命令列表

StartOver —— 从头播放（0x03）

将当前播放内容的进度重置到起始位置，并开始播放。 不需要参数。

↑ 返回命令列表

Previous —— 上一个（0x04）

切换到播放列表中的上一个媒体项目（上一曲/上一集）。 如果已经是第一个项目，设备行为由实现决定（可能从头播放或忽略）。 不需要参数。

↑ 返回命令列表

Next —— 下一个（0x05）

切换到播放列表中的下一个媒体项目（下一曲/下一集）。 如果已经是最后一个项目，设备行为由实现决定（可能停止播放或循环到第一项）。 不需要参数。

↑ 返回命令列表

Rewind —— 快退（0x06）

开始快退播放。设备将以反向加速播放媒体内容。 如果设备支持 VariableSpeed（VS） 特性，连续多次调用可逐级增加快退速度 （如 -2x、-4x、-8x），PlaybackSpeed 会更新为负值。 不需要参数。

↑ 返回命令列表

FastForward —— 快进（0x07）

开始快进播放。设备将以正向加速播放媒体内容。 如果设备支持 VariableSpeed（VS） 特性，连续多次调用可逐级增加快进速度 （如 2x、4x、8x），PlaybackSpeed 会更新为对应倍速。 不需要参数。

↑ 返回命令列表

SkipForward —— 向前跳过（0x08）

从当前位置向前跳过指定的毫秒数。与 FastForward 的持续性不同，SkipForward 是一次性跳转。

↑ 返回命令列表

SkipBackward —— 向后跳过（0x09）

从当前位置向后跳过指定的毫秒数。如果跳过量超过已播放时间，回到媒体起点。

↑ 返回命令列表

Seek —— 跳转（0x0B）

跳转到媒体的指定绝对位置。需要设备支持 AdvancedSeek（AS） 特性。 跳转位置必须在 SeekRangeStart 和 SeekRangeEnd 之间， 超出范围会返回 SeekOutOfRange (5) 错误。

↑ 返回命令列表

ActivateAudioTrack —— 切换音轨（0x0C）

切换到指定的音轨。需要设备支持 AudioTracks（AT） 特性。 可用音轨列表通过 AvailableAudioTracks 属性获取。

↑ 返回命令列表

ActivateTextTrack —— 开启字幕（0x0D）

开启或切换到指定的字幕轨道。需要设备支持 TextTracks（TT） 特性。 可用字幕列表通过 AvailableTextTracks 属性获取。

↑ 返回命令列表

DeactivateTextTrack —— 关闭字幕（0x0E）

关闭当前显示的字幕。执行成功后，ActiveTextTrack 属性变为 null。 需要设备支持 TextTracks（TT） 特性。不需要参数。

↑ 返回命令列表

PlaybackResponse —— 命令响应

所有 14 个命令执行后都会返回此响应，包含操作结果状态码和可选数据。

响应示例：

{
  "Status": 0,     // Success
  "Data": null      // 无附加数据
}

↑ 返回命令列表

属性详解

MediaPlayback Cluster 共有 11 个应用属性，分为播放状态、时间信息、音轨与字幕三组。点击下方汇总表中的属性 ID 可跳转到对应的详细说明。

播放状态（0x0000）

描述设备当前的播放状态。这是 MediaPlayback 唯一的必选属性。

↑ 返回属性列表

时间信息（0x0001 ~ 0x0006）

描述当前播放内容的时间维度信息：起始时间、总时长、当前进度、播放速度和可跳转范围。这些属性大部分需要 AdvancedSeek（AS） 特性。

↑ 返回属性列表

音轨与字幕（0x0007 ~ 0x000A）

描述当前媒体可用的音轨和字幕信息，以及当前激活的音轨/字幕。需要 AudioTracks（AT） 或 TextTracks（TT） 特性。

↑ 返回属性列表

枚举定义

PlaybackStateEnum —— 播放状态

设备的播放状态枚举。CurrentState 属性的取值范围。

StatusEnum —— 命令响应状态

PlaybackResponse 中的状态码，指示命令执行结果。

数据结构

PlaybackPositionStruct —— 播放位置

描述设备在某一时刻采样的播放进度。用于 SampledPosition 属性。 App 读取此结构后，结合 PlaybackSpeed 和当前时间可推算实时进度。

TrackStruct —— 轨道信息

描述一个音轨或字幕轨道的信息。用于音轨和字幕相关的属性。

TrackAttributesStruct —— 轨道属性

Feature 位图

MediaPlayback Cluster 通过 FeatureMap（0xFFFC）声明设备支持哪些高级能力：

示例数据

一台正在播放电影的智能电视（启用 AS + VS + AT + TT 特性）的 MediaPlayback Cluster 读取结果：

{
  // --- 播放状态 ---
  "0x0000": 0,                // CurrentState = Playing（正在播放）

  // --- 时间信息（需要 AS 特性）---
  "0x0001": 1695400000000000,  // StartTime（媒体起始时间，微秒级 epoch）
  "0x0002": 5400000,           // Duration = 5,400,000 毫秒（90 分钟）
  "0x0003": {                  // SampledPosition（采样位置）
    "UpdatedAt": 1695401200000000,
    "Position": 1230000
  },
  "0x0004": 1.0,               // PlaybackSpeed = 1.0（正常速度）
  "0x0005": 5400000,           // SeekRangeEnd = 5,400,000 毫秒
  "0x0006": 0,                 // SeekRangeStart = 0 毫秒

  // --- 音轨信息（需要 AT 特性）---
  "0x0007": {                  // ActiveAudioTrack
    "ID": "audio-zh",
    "TrackAttributes": {
      "LanguageCode": "zh",
      "DisplayName": "中文"
    }
  },
  "0x0008": [                  // AvailableAudioTracks
    { "ID": "audio-zh", "TrackAttributes": { "LanguageCode": "zh", "DisplayName": "中文" } },
    { "ID": "audio-en", "TrackAttributes": { "LanguageCode": "en", "DisplayName": "English" } }
  ],

  // --- 字幕信息（需要 TT 特性）---
  "0x0009": {                  // ActiveTextTrack
    "ID": "sub-zh",
    "TrackAttributes": {
      "LanguageCode": "zh",
      "DisplayName": "中文字幕"
    }
  },
  "0x000A": [                  // AvailableTextTracks
    { "ID": "sub-zh", "TrackAttributes": { "LanguageCode": "zh", "DisplayName": "中文字幕" } },
    { "ID": "sub-en", "TrackAttributes": { "LanguageCode": "en", "DisplayName": "English Subtitles" } }
  ]
}

常见场景