ContentLauncher Cluster

Cluster ID: 0x050A  |  Endpoint: Media endpoint (TV, set-top box, streaming device, etc.)

ContentLauncher handles launching content playback on media devices — either by searching with criteria or by directly launching via URL. It is one of the core Clusters for smart TVs, set-top boxes, and streaming sticks, serving as the underlying implementation for voice assistant "play XXX" commands. Controllers can specify search keywords, playback preferences (subtitle language, start position), and branding information.

Commands

The ContentLauncher Cluster has 2 request commands and 1 response command. LaunchContent searches for and launches content via criteria (requires CS feature), LaunchURL launches directly via URL (requires UP feature), and both return LauncherResponse with the launch result. Click a command ID in the table below to jump to its detailed description.

LaunchContent — Search and Launch Content (0x00)

Searches for and launches content on the device using search criteria. The criteria are described by ContentSearchStruct, which can combine multiple parameters (e.g., type + actor + genre) to precisely locate content. After receiving the command, the device either auto-plays (AutoPlay = true) or displays a search results list for the user to choose from.

// LaunchContent command example
// Search for "Three-Body Problem" and auto-play, prefer Chinese subtitles
{
  "Search": {
    "ParameterList": [
      {
        "Type": 12,
        "Value": "Movie"
      },
      {
        "Type": 0,
        "Value": "Three-Body"
      }
    ]
  },
  "AutoPlay": true,
  "Data": "season=1&episode=1",
  "PlaybackPreferences": {
    "PlaybackPosition": 0,
    "TextTrack": {
      "LanguageCode": "zh-CN",
      "Characteristics": [8]
    }
  },
  "UseCurrentContext": false
}

↑ Back to Commands

LaunchURL — Direct URL Launch (0x01)

Directly launches content playback on the device via URL. Suitable for scenarios where the content address is known, such as casting a video link from a phone app to the TV. Can include display text and branding information.

// LaunchURL command example
// Directly launch video via URL with branding info
{
  "ContentURL": "https://example.com/stream/movie-12345.m3u8",
  "DisplayString": "Three-Body Problem Season 1 Episode 1",
  "BrandingInformation": {
    "ProviderName": "ExampleTV"
  }
}

↑ Back to Commands

LauncherResponse — Launch Result (0x02)

Unified response for LaunchContent and LaunchURL. Contains a status code and optional additional data. Controllers determine success based on Status; on failure, Data may contain error details.

// LauncherResponse example
// Launch successful
{
  "Status": 0,
  "Data": "playback-session-id=abc123"
}

// Launch failed — URL not available
{
  "Status": 1,
  "Data": "URL expired or geo-restricted"
}

↑ Back to Commands

Attributes

The ContentLauncher Cluster has 2 attributes. Click an attribute ID in the summary table below to jump to its detailed description.

Content Capabilities (0x0000, 0x0001)

Describes the content types and streaming protocols the device can accept and play. Controllers should check these attributes before sending LaunchURL to ensure the device supports the target content format.

↑ Back to Attributes

Struct Definitions

The ContentLauncher Cluster uses multiple structures to describe search criteria, playback preferences, and branding information.

ContentSearchStruct

Describes the complete criteria for a content search, containing a set of search parameters. Multiple parameters have an AND relationship — the device must satisfy all conditions simultaneously.

ParameterStruct

Describes a single search parameter — consisting of parameter type, search value, and optional external IDs.

AdditionalInfoStruct

Describes an external identifier key-value pair for cross-platform content matching.

BrandingInformationStruct

Describes content provider branding information for the LaunchURL command. The device can display the provider's brand elements while loading content. Except for ProviderName, all other fields are optional StyleInformationStruct (containing image URL, color, size, and other style information).

PlaybackPreferencesStruct

Describes playback preference settings, including start position, subtitle and audio track selection. This struct is only available when the AP (AdvancedSeek) feature is enabled.

Enums & Bitmaps

StatusEnum

Status codes in LauncherResponse, indicating the content launch result.

ParameterEnum

Defines search parameter types. Controllers specify search dimensions via different Type values, and the device matches against its content library accordingly. Contains 14 enum values.

SupportedProtocolsBitmap

Bitmap of streaming protocols supported by the device. Controllers use this to select the appropriate stream address format.

Feature Bitmap

The ContentLauncher Cluster declares device capabilities via FeatureMap (0xFFFC):

Example Data

Attribute read results of the ContentLauncher Cluster from a smart TV supporting DASH and HLS:

{
  // --- Supported Content Types ---
  "0x0000": [                        // AcceptHeader
    "video/mp4",
    "video/webm",
    "audio/aac",
    "application/dash+xml",
    "application/x-mpegURL"
  ],

  // --- Supported Streaming Protocols ---
  "0x0001": 3                         // SupportedStreamingProtocols
                                      // = 0b11 (DASH + HLS)
}

Common Scenarios