媒体输入 Cluster（MediaInput）

Cluster ID: 0x0507  |  所在 Endpoint: 媒体端点（电视、AV 接收器等）

MediaInput 负责管理设备的外部输入源 —— HDMI、USB、分量、光纤等各种音视频输入接口。 用户可以通过它查询设备有哪些输入源、当前选中哪个、切换到指定输入源，以及为输入源自定义名称。 它是智能电视和 AV 接收器等媒体设备的核心 Cluster 之一。

NameUpdates（NU）特性

MediaInput Cluster 定义了一个 NameUpdates（NU） Feature。 启用后，控制端可以通过 RenameInput 命令为输入源自定义名称 （例如把"HDMI 2"改成"PS5"）。未启用时，输入源名称由设备固定，不可修改。

命令（Commands）

MediaInput Cluster 共有 4 个命令。SelectInput 用于切换输入源，ShowInputStatus / HideInputStatus 控制输入源信息的 OSD 显示， RenameInput 允许用户为输入源自定义名称（需要 NU 特性）。 点击下方表格中的命令 ID 可跳转到对应的详细说明。

ID 名称 说明 所需特性
0x00 SelectInput 切换到指定输入源 无
0x01 ShowInputStatus 在屏幕上显示输入源信息 无
0x02 HideInputStatus 隐藏输入源信息的屏幕显示 无
0x03 RenameInput 重命名指定输入源 NU

SelectInput —— 切换输入源（0x00）

将设备切换到指定的输入源。Index 必须是 InputList 中某个 InputInfoStruct 的 Index 值，否则设备会返回错误。 执行成功后，CurrentInput 属性会更新为指定的 Index 值。

参数类型说明
Index uint8 目标输入源的索引值，必须存在于 InputList 中
使用场景

用户在手机 App 上选择"HDMI 1"，App 读取 InputList 获取该输入源的 Index 值， 然后发送 SelectInput 命令。电视切换到对应的 HDMI 输入，CurrentInput 随之更新。

↑ 返回命令列表

ShowInputStatus —— 显示输入源信息（0x01）

请求设备在屏幕上显示当前输入源的信息（OSD 叠加层），类似按遥控器上的"信息"按钮。 不需要参数。显示的内容和持续时间由设备自行决定。

使用场景

用户想确认当前电视在哪个输入源上，通过 App 发送此命令，电视屏幕上会弹出输入源信息（如"HDMI 1 - 客厅机顶盒"）。

↑ 返回命令列表

HideInputStatus —— 隐藏输入源信息（0x02）

请求设备隐藏屏幕上的输入源信息显示。不需要参数。 如果当前没有显示输入源信息，此命令不产生任何效果。

使用场景

在 ShowInputStatus 弹出信息后，用户觉得碍眼，通过 App 发送此命令关闭 OSD 叠加层。

↑ 返回命令列表

RenameInput —— 重命名输入源（0x03）

为指定的输入源设置一个自定义名称。修改后，InputList 中对应条目的 Name 字段会更新。 此命令需要设备启用 NU（NameUpdates） 特性。

参数类型说明
Index uint8 要重命名的输入源索引，必须存在于 InputList 中
Name string 新的输入源名称 
// RenameInput 命令示例
// 将 Index=2 的输入源重命名为 "PS5"
{
  "Index": 2,
  "Name": "PS5"
}
// 执行后 InputList 中 Index=2 的 Name 变为 "PS5"
使用场景

用户把游戏主机接到了 HDMI 2，但设备默认显示"HDMI 2"不够直观。 通过 App 发送 RenameInput，将 Index=2 的输入源重命名为"PS5"。 之后 InputList 中该条目的 Name 会变为"PS5"，UI 上也会显示新名称。

↑ 返回命令列表

属性详解

MediaInput Cluster 共有 2 个属性。点击下方汇总表中的属性 ID 可跳转到对应的详细说明。

ID 名称 类型 说明
0x0000 InputList list<InputInfoStruct> 设备所有输入源的列表
0x0001 CurrentInput uint8 当前选中的输入源索引

输入源状态（0x0000, 0x0001）

描述设备当前可用的输入源列表和当前选中的输入源。

ID 名称 类型 说明
0x0000 InputList（输入源列表） list<InputInfoStruct> 设备声明的全部可用输入源，每个元素是一个 InputInfoStruct。列表内容反映设备实际的物理和虚拟输入接口，每个 Index 值唯一。当用户通过 RenameInput 修改名称后，对应条目的 Name 会更新
0x0001 CurrentInput（当前输入源） uint8 当前选中的输入源索引。该值始终指向 InputList 中某个 InputInfoStruct.Index。通过 SelectInput 命令改变，也可能由用户通过遥控器切换
订阅变化

控制端应订阅 CurrentInput 属性的变化，以便在用户通过遥控器或设备面板切换输入源时同步 App 界面。 同样，如果设备支持 NU 特性，也应订阅 InputList 的变化以获取最新的输入源名称。

↑ 返回属性列表

结构体定义

MediaInput Cluster 使用一个结构体来描述输入源信息。

InputInfoStruct

描述一个输入源的完整信息，包括索引、类型、名称和描述。

字段 类型 说明
Index uint8 输入源的唯一索引，用于 SelectInput 和 RenameInput 命令的定位
InputType InputTypeEnum 输入源的接口类型（见下方枚举）
Name string 输入源的显示名称，如 "HDMI 1"、"PS5"。启用 NU 特性后可通过 RenameInput 修改
Description string 输入源的补充描述，如 "客厅机顶盒"。由设备提供，供 UI 展示

InputTypeEnum

定义输入源的物理接口类型。共 12 个枚举值，涵盖常见的音视频输入接口。 控制端可据此在 UI 上展示对应的图标或分类。

0
Internal 内置源 —— 内置调谐器或流媒体应用
1
Aux 辅助输入 —— AUX 接口
2
Coax 同轴 —— 同轴电缆输入
3
Composite 复合 —— 复合视频（RCA 黄色接口）
4
HDMI HDMI —— 最常用的高清数字接口
5
Input 通用输入 —— 未分类的通用输入接口
6
Line 线路输入 —— Line In 音频输入
7
Optical 光纤 —— 光纤数字音频（TOSLINK/SPDIF）
8
Video 视频 —— 通用视频输入
9
SCART SCART —— 欧洲标准音视频接口
10
USB USB —— USB 媒体播放接口
11
Other 其他 —— 以上类型未涵盖的接口

Feature 位图

MediaInput Cluster 通过 FeatureMap（0xFFFC）声明设备支持的可选能力：

Bit 0
NU（NameUpdates） 名称更新 —— 启用后支持 RenameInput 命令，允许用户为输入源自定义名称
何时启用 NU

大多数智能电视和 AV 接收器都应启用此特性 —— 用户通常希望把"HDMI 1"改成更有意义的名称（如"机顶盒""PS5"）。 如果设备的输入源名称是出厂固定的且不支持修改，则不启用 NU。

示例数据

一台智能电视的 MediaInput Cluster 读取结果 —— 当前选中 HDMI 1，共有 4 个输入源：

{
  // --- 当前输入源 ---
  "0x0001": 1,                   // CurrentInput = 1（当前选中 HDMI 1）

  // --- 输入源列表 ---
  "0x0000": [                    // InputList
    {
      "Index": 0,
      "InputType": 0,            // Internal（内置调谐器）
      "Name": "TV Tuner",
      "Description": "内置数字电视调谐器"
    },
    {
      "Index": 1,
      "InputType": 4,            // HDMI
      "Name": "HDMI 1",
      "Description": "客厅机顶盒"
    },
    {
      "Index": 2,
      "InputType": 4,            // HDMI
      "Name": "HDMI 2",
      "Description": "游戏主机"
    },
    {
      "Index": 3,
      "InputType": 10,           // USB
      "Name": "USB",
      "Description": "USB 媒体播放"
    }
  ]
}
开发提示

控制端显示输入源切换 UI 时，应先读取 InputList (0x0000) 获取完整列表， 再读取 CurrentInput (0x0001) 高亮当前选中项。 可以根据 InputType 为不同接口类型显示不同图标（如 HDMI 图标、USB 图标等）， 提升用户识别效率。

常见场景

场景 1：App 切换电视输入源
  1. 读取 InputList (0x0000)，获取所有输入源（Index、Name、InputType、Description）
  2. 读取 CurrentInput (0x0001)，高亮当前选中的输入源
  3. 在 UI 上展示输入源列表，根据 InputType 显示对应图标
  4. 用户点击目标输入源，发送 SelectInput (0x00)，Index 设为该输入源的索引值
  5. 订阅 CurrentInput 属性变化，确认切换成功后更新 UI
场景 2：用户自定义输入源名称
  1. 检查设备的 FeatureMap (0xFFFC)，确认支持 NU（Bit 0 = 1）
  2. 读取 InputList (0x0000)，展示输入源列表
  3. 用户长按某个输入源（如 Index=2，当前名称"HDMI 2"），弹出重命名输入框
  4. 用户输入新名称"PS5"，发送 RenameInput (0x03)，Index=2，Name="PS5"
  5. 订阅 InputList 变化，确认名称更新后刷新 UI

注意：如果 FeatureMap 不包含 NU 特性，UI 上不应显示重命名入口， 发送 RenameInput 命令会被设备拒绝。