内容启动 Cluster（ContentLauncher）

Cluster ID: 0x050A  |  所在 Endpoint: 媒体端点（电视、机顶盒、流媒体设备等）

ContentLauncher 负责在媒体设备上启动内容播放 —— 既可以通过搜索条件查找内容，也可以直接通过 URL 启动。 它是智能电视、机顶盒、流媒体棒等设备的核心 Cluster 之一，是语音助手「播放 XXX」指令的底层实现。 控制端可以指定搜索关键词、播放偏好（字幕语言、起始位置）和品牌展示信息。

命令（Commands）

ContentLauncher Cluster 有 2 个请求命令和 1 个响应命令。 LaunchContent 通过搜索条件查找并启动内容（需要 CS 特性），LaunchURL 通过 URL 直接启动（需要 UP 特性）， 两者都返回 LauncherResponse 告知启动结果。 点击下方表格中的命令 ID 可跳转到对应的详细说明。

LaunchContent —— 搜索启动内容（0x00）

通过搜索条件在设备上查找并启动内容。搜索条件由 ContentSearchStruct 描述， 可以组合多个参数（如类型 + 演员 + 流派）来精确定位内容。设备收到命令后， 根据搜索结果自动播放（AutoPlay = true）或展示搜索结果列表让用户选择。

// LaunchContent 命令示例
// 搜索"三体"并自动播放，偏好中文字幕
{
  "Search": {
    "ParameterList": [
      {
        "Type": 12,
        "Value": "Movie"
      },
      {
        "Type": 0,
        "Value": "三体"
      }
    ]
  },
  "AutoPlay": true,
  "Data": "season=1&episode=1",
  "PlaybackPreferences": {
    "PlaybackPosition": 0,
    "TextTrack": {
      "LanguageCode": "zh-CN",
      "Characteristics": [8]
    }
  },
  "UseCurrentContext": false
}

↑ 返回命令列表

LaunchURL —— URL 直接启动（0x01）

通过 URL 直接在设备上启动内容播放。适用于已知内容地址的场景， 比如从手机 App 分享一个视频链接到电视播放。可以附带显示文本和品牌信息。

// LaunchURL 命令示例
// 直接通过 URL 启动视频，附带品牌信息
{
  "ContentURL": "https://example.com/stream/movie-12345.m3u8",
  "DisplayString": "三体 第一季 第1集",
  "BrandingInformation": {
    "ProviderName": "ExampleTV"
  }
}

↑ 返回命令列表

LauncherResponse —— 启动结果（0x02）

LaunchContent 和 LaunchURL 的统一响应。包含一个状态码和可选的附加数据。 控制端根据 Status 判断启动是否成功，失败时 Data 中可能包含错误详情。

// LauncherResponse 响应示例
// 启动成功
{
  "Status": 0,
  "Data": "playback-session-id=abc123"
}

// 启动失败 —— URL 不可用
{
  "Status": 1,
  "Data": "URL expired or geo-restricted"
}

↑ 返回命令列表

属性详解

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

内容能力（0x0000, 0x0001）

描述设备能够接受和播放的内容类型与流媒体协议。控制端在发送 LaunchURL 前应检查这些属性，确保设备支持目标内容格式。

↑ 返回属性列表

结构体定义

ContentLauncher Cluster 使用多个结构体来描述搜索条件、播放偏好和品牌信息。

ContentSearchStruct

描述一次内容搜索的完整条件，包含一组搜索参数。多个参数之间是 AND 关系 —— 设备需要同时满足所有条件。

ParameterStruct

描述单个搜索参数 —— 由参数类型、搜索值和可选的外部 ID 组成。

AdditionalInfoStruct

描述一个外部标识符的键值对，用于跨平台内容匹配。

BrandingInformationStruct

描述内容提供商的品牌展示信息，用于 LaunchURL 命令。设备在加载内容时可以显示提供商的品牌元素。 除 ProviderName 外，其他字段都是可选的 StyleInformationStruct（包含图片 URL、颜色、尺寸等样式信息）。

PlaybackPreferencesStruct

描述播放偏好设置，包括起始播放位置、字幕和音轨选择。此结构体仅在启用 AP（AdvancedSeek） 特性时可用。

枚举与位图

StatusEnum

LauncherResponse 中的状态码，表示内容启动的结果。

ParameterEnum

定义搜索参数的类型。控制端通过不同的 Type 值指定搜索维度， 设备据此在内容库中匹配。共 14 个枚举值。

SupportedProtocolsBitmap

设备支持的流媒体协议位图。控制端据此选择合适的流地址格式。

Feature 位图

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

示例数据

一台支持 DASH 和 HLS 的智能电视的 ContentLauncher Cluster 属性读取结果：

{
  // --- 支持的内容类型 ---
  "0x0000": [                        // AcceptHeader
    "video/mp4",
    "video/webm",
    "audio/aac",
    "application/dash+xml",
    "application/x-mpegURL"
  ],

  // --- 支持的流媒体协议 ---
  "0x0001": 3                         // SupportedStreamingProtocols
                                      // = 0b11 (DASH + HLS)
}

常见场景