Google Cast 發送端應用程式可將 JSON 格式的訊息傳送至接收端應用程式，藉此控管接收器裝置的播放作業。同樣地，接收器也會將訊息傳回給寄件者 (同時採用 JSON)。這類訊息可能是來自變更玩家狀態的傳送者的指令、對接收器的指令做出回應，或是描述接收器應用程式媒體的資料結構。
根據《Google Cast SDK 額外開發人員服務條款》，Cast 媒體應用程式必須使用這些訊息 (如本文所定義)，以控制接收器的媒體播放。如此一來，媒體應用程式就能在各種平台上提供一致的使用者體驗，並確保 Cast 應用程式將支援新的和未來的用途。這些結構也在適用情況下，支援自訂資料，應用程式可定義 SDK 不支援的指令。
媒體播放訊息的命名空間定義為 urn:x-cast:com.google.cast.media。
注意：此規格中的郵件和結構的隱含大小上限取決於傳輸郵件的大小上限，個別欄位則沒有限制。傳輸訊息大小上限目前為 64 KB。
常見的命名空間資料結構
所有媒體命名空間成果所使用的資料結構，都是以通用命名空間來定義。
圖片
這是圖片說明，包括少量中繼資料，可讓寄件者應用程式根據圖片的顯示方式來選擇圖片。
在圖片陣列中，您只能針對單一項目指定高度和寬度。舉例來說，如果系統只傳回單一項目，那麼則為選用項目；如果系統傳回兩個項目，則其中一個項目必須指定高度和寬度，但是如果傳送者沒有使用特定參數傳送的項目，就可以選擇使用 [預設] 選項。
| 名稱 | 類型 | 說明 |
|---|---|---|
| 網址 | URI | 映像檔的 URI |
| 高度 | 整數 | 選填 圖片高度 |
| 寬度 | 整數 | 選填：圖片寬度 |
資料量
媒體串流音量。用於媒體串流的淡出/淡出效果。(附註：使用寄件者 API 會變更系統音量)。串流音量不得與音量滑桿或音量按鈕搭配使用，以控制裝置音量。您必須傳遞下列至少一個參數，才能變更串流磁碟區。
| 名稱 | 類型 | 說明 |
|---|---|---|
| 層級 | 雙精度值 | 選用 目前的串流音量等級，介於 0.0 和 1.0 之間 (1.0 代表最大音量)。 |
| 靜音 | 布林值 | 選填：投放裝置是否設為靜音，與音量無關 |
媒體命名空間資料結構
這些訊息會說明媒體播放器的狀態。命名空間為 urn:x-cast:com.google.cast.media。
媒體資訊
此資料結構說明瞭媒體串流。
| 名稱 | 類型 | 說明 |
|---|---|---|
| 內容 ID | string | 媒體播放器目前載入內容的服務專屬 ID。這是應用程式專用的任意形式字串，在多數情況下，這是指媒體的網址，但傳送者可以選擇傳送字串，讓接收器能夠正確解讀。長度上限：1,000 |
| streamType | 列舉 (字串) |
將媒體構件的描述描述為下列其中一種：
|
| string | 播放媒體的 MIME 內容類型 | |
| 中繼資料 | 物件 | 選用 媒體中繼資料物件，可能為下列其中一種： |
| 時間長度 | 雙精度值 | 選填：目前播放串流的秒數 (以秒為單位) |
| 自訂資料 | 物件 | 選填：由傳送者應用程式或接收端應用程式定義的應用程式特定 blob |
一般媒體中繼資料
描述一般媒體構件。
| 名稱 | 類型 | 說明 |
|---|---|---|
| metadataType | 整數 | 0 (唯一值) |
| title | string | 選填：內容的說明標題。玩家可以使用 content_id 獨立擷取標題，或由傳送者在 Load 訊息中提供 |
| 子標題 | string | 選填：影片內容的說明文字。玩家可以使用 content_id 獨立擷取標題，或由傳送者在 Load 訊息中提供 |
| 圖片 | 圖片[] | 選填：與內容相關的圖片網址的陣列。寄件者的初始值可以在 Load 訊息中提供。應提供建議的大小 |
| releaseDate | 字串 (ISO 8601) | (選用) 內容發布時的 ISO 8601 日期和時間。玩家可以使用 content_id 獨立擷取標題，或由傳送者在 Load 訊息中提供 |
電影媒體中繼資料
用於說明電影媒體成果。
| 名稱 | 類型 | 說明 |
|---|---|---|
| metadataType | 整數 | 1 (唯一值) |
| title | string | 選填：內容的說明標題。玩家可以使用 content_id 獨立擷取標題，或由傳送者在 Load 訊息中提供 |
| 子標題 | string | 選填：影片內容的說明文字。玩家可以使用 content_id 獨立擷取標題，或由傳送者在 Load 訊息中提供 |
| 工作室 | string | 選填，發布內容的工作室。播放器可以使用 content_id 獨立擷取工作室，或者由傳送者在 Load 訊息中 |
| 圖片 | 圖片[] | 選填：與內容相關的圖片網址的陣列。寄件者的初始值可以在 Load 訊息中提供。應提供建議的大小 |
| releaseDate | 字串 (ISO 8601) | (選用) 內容發布時的 ISO 8601 日期和時間。玩家可以使用 content_id 獨立擷取標題，或由傳送者在 Load 訊息中提供 |
電視表演媒體中繼資料
用於說明電視節目劇集的媒體構件。
| 名稱 | 類型 | 說明 |
|---|---|---|
| metadataType | 整數 | 2 (唯一值) |
| SeriesTitle | string | 選填 t.v. 系列的描述性標題。玩家可以使用 content_id 獨立擷取標題，或由傳送者在 Load 訊息中提供 |
| 子標題 | string | 選填 t.v. 劇集的描述性字幕。玩家可以使用 content_id 獨立擷取標題，或由傳送者在 Load 訊息中提供 |
| 季度 | 整數 | 選填 電視節目的季別編號 |
| 劇集 | 整數 | 選填 電視節目的季別編號 (當季) |
| 圖片 | 圖片[] | 選填：與內容相關的圖片網址的陣列。寄件者的初始值可以在 Load 訊息中提供。應提供建議的大小 |
| originalAirDate | 字串 (ISO 8601) | 選用 單集節目的 ISO 8601 日期和時間。玩家可以使用 content_id 獨立擷取原始 AirDate，也可以由寄件者在 Load 訊息中提供 |
音樂曲目媒體中繼資料
用於描述音樂曲目媒體構件。
| 名稱 | 類型 | 說明 |
|---|---|---|
| metadataType | 整數 | 3 (唯一值) |
| albumName | string | 選填：繪製此曲目的專輯或系列作品。播放器可以使用 content_id 獨立擷取相簿名稱，或由傳送者在 Load 訊息中提供 |
| title | string | 選填：曲目的名稱 (例如歌曲名稱)。玩家可以使用 content_id 獨立擷取標題，或由傳送者在 Load 訊息中提供 |
| albumArtist | string | 選填：與這個曲目相關聯的專輯相關聯的演出者名稱。播放器可以使用 content_id 獨立擷取專輯的演出者，或讓傳送者在 Load 訊息中提供 |
| 演出者 | string | 選填：與媒體曲目相關聯的演出者名稱。播放器可以使用 content_id 獨立擷取演出者，或是在 Load 訊息中由作者提供 |
| 作曲家 | string | 選填：與媒體曲目相關聯的 Composer 名稱。播放器可以使用 content_id 獨立擷取 Composer，也可以在 Load 訊息中由傳送者提供 |
| 追蹤號碼 | 整數 | 選填：專輯中的曲目編號 |
| 磁碟號碼 | 整數 | 選填 專輯的音量 (例如光碟) |
| 圖片 | 圖片[] | 選填：與內容相關的圖片網址的陣列。寄件者的初始值可以在 Load 訊息中提供。應提供建議的大小 |
| releaseDate | 字串 (ISO 8601) | (選用) 內容發布時的 ISO 8601 日期和時間。播放器可以使用 content_id 獨立擷取 releaseDate，也可以由 Load 訊息中的傳送者提供 |
PhotoMediaMetadata
用於描述攝影媒體構件。
| 名稱 | 類型 | 說明 |
|---|---|---|
| metadataType | 整數 | 4 (唯一值) |
| title | string | 選填：相片標題。玩家可以使用 content_id 獨立擷取標題，或由傳送者在 Load 訊息中提供 |
| 演出者 | string | 選填：攝影師名稱。播放器可以使用 content_id 獨立擷取演出者，或是在 Load 訊息中由作者提供 |
| 地點 | string | 選填：相片的口頭位置，例如「馬德里，西班牙」。玩家可以使用 content_id 獨立擷取位置，或由傳送者在 Load 訊息中提供 |
| latitude | 雙精度值 | 選用：相片拍攝地點的地理緯度值。玩家可以使用 content_id 獨立擷取緯度，或者由傳送者在 Load 訊息中提供 |
| longitude | 雙精度值 | 選用：拍攝地點的地理經度值。播放器可以使用 content_id 獨立擷取經度，或者由傳送者在 Load 訊息中提供 |
| 寬度 | 整數 | 選用：相片的寬度 (以像素為單位)。播放器可以使用 content_id 獨立擷取寬度，或者由傳送者在 Load 訊息中提供 |
| 高度 | 整數 | 選用：相片的高度 (以像素為單位)。播放器可透過 content_id 個別擷取高度，或者由傳送者在 Load 訊息中提供 |
| creationDateTime | 字串 (ISO 8601) | 選用 這張相片的 ISO 8601 日期和時間。玩家可以使用 content_id 獨立擷取 createDateTime，或由傳送者在 Load 訊息中提供 |
媒體狀態
說明媒體成果相對於工作階段的目前狀態。
| 名稱 | 類型 | 說明 |
|---|---|---|
| 媒體工作階段 ID | 整數 | 播放這個工作階段特定的專屬 ID。這個 ID 是由接收端的 LOAD 設定，可用來識別特定播放。舉例來說，如果同一個工作階段中有 2 個「Wish you are here」(這真的是你在這裡)，則每次播放都會有專屬的 mediaSessionId。 |
| media | 媒體資訊 | 選填 (如果是狀態訊息)：正在播放的內容完整說明。只有在 MediaInformation 已變更時，才會傳回狀態訊息。 |
| playbackRate | 浮動 | 表示媒體進度是否正常，以及速率。由於媒體時間可以在任何狀態中停止，因此這與播放器狀態無關。1.0 是常規時間，0.5 是慢動作 |
| playerState | 列舉 (字串) | 將播放器的狀態描述如下：
|
| idReason 原因 | 列舉 (字串) | 選用 如果 playerState 是 IDLE，且已知為 IDLE，已知提供此屬性。如果玩家只是處於已啟動狀態 (IDLE)，系統就不會提供這項屬性；如果玩家處於其他任何狀態，則不應提供這項屬性。適用以下值：
|
| 目前時間 | 雙精度值 | 媒體播放器自內容開始播放後的目前位置 (以秒為單位)。如果是即時串流內容，這個欄位代表活動開始時 (以秒為單位) 的時間。 |
| supportedMediaCommands | flag | 此標記說明媒體播放器支援的媒體指令：
組合則稱為總和；例如 Pause+Seek+StreamVolume+靜音 == 15。 |
| 音量 | 音量 | 串流音量 |
| 自訂資料 | 物件 | 選填 接收器應用程式定義的資料專用 blob |
從寄件者到接收器的指令
這些指令會控制媒體播放器。下方訊息中的所有 customData 物件皆為選用項目 (也就是說，如果資料未傳送，接收器應正確降級)。這樣一來，一般遙控器應用程式就可以正常運作。
載入
將新內容載入媒體播放器。
| 名稱 | 類型 | 說明 |
|---|---|---|
| 要求編號 | 整數 | 要求的 ID，將要求和回應建立關聯 |
| 類型 | string | LOAD (僅限值) |
| media | 媒體資訊 | 要載入的媒體中繼資料 (包括 contentId) |
| 自動播放 | 布林值 | 選用 (預設值為 true)。如果已指定自動播放參數，媒體播放器就會在載入後開始播放內容。即使未指定自動播放，媒體播放器實作仍可能選擇立即開始播放。如果開始播放，回應中的播放器狀態應設為 BUFFERING，否則應設為 PAUSED |
| 目前時間 | 雙精度值 | 選填：從內容開始算起的秒數。如果內容為即時內容，且未指定位置，則串流會在直播位置開始播放 |
| 自訂資料 | 物件 | 選填：寄件者應用程式定義的資料專屬 blob |
| 回應 | 觸發條件 | 廣播 | 錯誤 |
|---|---|---|---|
| 無 | 接收器狀態變更 | 媒體狀態變更訊息 | 玩家狀態無效 載入失敗 已取消載入 |
暫停
暫停播放目前的內容。向所有傳送者應用程式觸發 STATUS 事件通知。
| 名稱 | 類型 | 說明 |
|---|---|---|
| 媒體工作階段 ID | 整數 | 要暫停的媒體工作階段 ID |
| 要求編號 | 整數 | 要求的 ID，用於為要求/回應建立關聯 |
| 類型 | string | 暫停 (僅限值) |
| 自訂資料 | 物件 | 選填：寄件者應用程式定義的資料專屬 blob |
| 回應 | 觸發條件 | 廣播 | 錯誤 |
|---|---|---|---|
| 無 | 接收器狀態變更 | 媒體狀態變更訊息 | 玩家狀態無效 |
跳轉
設定串流中的目前位置。向所有傳送者應用程式觸發 STATUS 事件通知。如果提供的位置超出目前內容的有效位置範圍，播放器應選擇接近要求位置的有效位置。
| 名稱 | 類型 | 說明 |
|---|---|---|
| 媒體工作階段 ID | 整數 | 設定串流位置的媒體工作階段 ID |
| 要求編號 | 整數 | 要求的 ID，將要求和回應建立關聯 |
| 類型 | string | SEEK (僅限值) |
| ReumeState | 列舉 (字串) | 選用 如果未設定，播放狀態不會改變；以下的值將適用：
|
| 目前時間 | 雙精度值 | 選填：從內容開始算起的秒數。如果內容為即時內容，且未指定位置，則串流會在直播位置開始播放 |
| 自訂資料 | 物件 | 選填：寄件者應用程式定義的資料專屬 blob |
| 回應 | 觸發條件 | 廣播 | 錯誤 |
|---|---|---|---|
| 無 | 接收器狀態變更 | 媒體狀態變更訊息 | 玩家狀態無效 |
停止
停止播放目前的內容。向所有傳送者應用程式觸發 STATUS 事件通知。執行這個指令之後，系統就不會再載入內容，mediaSessionId 也會失效。
| 名稱 | 類型 | 說明 |
|---|---|---|
| 媒體工作階段 ID | 整數 | 停止內容的媒體工作階段 ID |
| 要求編號 | 整數 | 要求的 ID，將要求和回應建立關聯 |
| 類型 | string | STOP (僅限值) |
| 自訂資料 | 物件 | 選填：寄件者應用程式定義的資料專屬 blob |
| 回應 | 觸發條件 | 廣播 | 錯誤 |
|---|---|---|---|
| 無 | 接收器狀態變更 | 媒體狀態變更訊息 | 玩家狀態無效 |
播放
開始播放透過載入呼叫載入的內容，系統會從目前時間位置繼續播放內容。
| 名稱 | 類型 | 說明 |
|---|---|---|
| 媒體工作階段 ID | 整數 | 要播放內容的媒體工作階段 ID |
| 要求編號 | 整數 | 要求的 ID，將要求和回應建立關聯 |
| 類型 | string | PLAY (僅限值) |
| 自訂資料 | 物件 | 選填：寄件者應用程式定義的資料專屬 blob |
| 回應 | 觸發條件 | 廣播 | 錯誤 |
|---|---|---|---|
| 無 | 接收器狀態變更 | 媒體狀態變更訊息 | 玩家狀態無效 |
取得狀態
擷取媒體狀態。
| 名稱 | 類型 | 說明 |
|---|---|---|
| 媒體工作階段 ID | 整數 | 選填：要傳回媒體狀態的媒體工作階段 ID。如未提供，則系統會提供所有媒體工作階段 ID 的狀態。 |
| 要求編號 | 整數 | 要求的 ID，將要求和回應建立關聯 |
| 類型 | string | GET_STATUS (僅限值) |
| 自訂資料 | 物件 | 選填：寄件者應用程式定義的資料專屬 blob |
| 回應 | 觸發條件 | 廣播 | 錯誤 |
|---|---|---|---|
| MediaStatus 訊息給提出要求的寄件者 | 無 | 無 | 無 |
設定音量
設定媒體串流音量。用於媒體串流的淡出/淡出效果。(附註：使用網路傳送者 setVolume 可變更接收器音量。)串流音量不得與音量滑桿或音量按鈕搭配使用，以控制裝置音量。變更串流量時，接收器不會觸發任何使用者介面。
| 名稱 | 類型 | 說明 |
|---|---|---|
| 媒體工作階段 ID | 整數 | 變更串流磁碟區的媒體工作階段 ID |
| 要求編號 | 整數 | 要求的 ID，將要求和回應建立關聯 |
| 類型 | string | VOLUME (僅限值) |
| 音量 | 音量 | 串流音量 |
| 自訂資料 | 物件 | 選填：寄件者應用程式定義的資料專屬 blob |
| 回應 | 觸發條件 | 廣播 | 錯誤 |
|---|---|---|---|
| 無 | 接收器狀態變更 | 媒體狀態變更訊息 | 玩家狀態無效 |
給收件者的郵件
收件者會傳送兩種類型的訊息：
- 錯誤：當傳送者收到錯誤回應時傳送的單例訊息。
- 狀態：廣播訊息。
- 由寄件者發起的動作。將包含造成變更要求的 requestId。
- 隨機：例如，接收端應用程式觸發了變更。RequestId 為 0。
錯誤：玩家狀態無效
因未能滿足寄件者的要求，導致無法傳送寄件者的要求。例如，如果應用程式尚未建立媒體元素。
| 名稱 | 類型 | 說明 |
|---|---|---|
| 要求編號 | 整數 | 產生這個錯誤的要求 ID |
| 類型 | string | INVALID_player_STATE(僅限值) |
| 自訂資料 | 物件 | 選填 接收器應用程式定義的資料專用 blob |
錯誤：載入失敗
載入要求失敗時傳送。播放器的狀態必須是「IDLE」。
| 名稱 | 類型 | 說明 |
|---|---|---|
| 要求編號 | 整數 | 產生這個錯誤的要求 ID |
| 類型 | string | LOAD_FAILED(僅限值) |
| 自訂資料 | 物件 | 選填 接收器應用程式定義的資料專用 blob |
錯誤：已取消載入
在載入要求取消時傳送 (收到第二次載入要求)。
| 名稱 | 類型 | 說明 |
|---|---|---|
| 要求編號 | 整數 | 產生這個錯誤的要求 ID |
| 類型 | string | LOAD_CANCELLED (僅限值) |
| 自訂資料 | 物件 | 選填 接收器應用程式定義的資料專用 blob |
錯誤：無效的要求
在要求無效時傳送 (例如未知請求類型)。
| 名稱 | 類型 | 說明 |
|---|---|---|
| 要求編號 | 整數 | 產生這個錯誤的要求 ID |
| 類型 | string | INVALID_REQUEST (僅限值) |
| 原因 | 列舉 (字串) | 值：
|
| 自訂資料 | 物件 | 選填 接收器應用程式定義的資料專用 blob |
媒體狀態
在狀態變更或媒體狀態要求之後傳送。系統只會傳送已變更或已請求的 MediaStatus 物件。
| 名稱 | 類型 | 說明 |
|---|---|---|
| 要求編號 | 整數 | 這個狀態回應，用於將此狀態回應與發出該狀態的要求建立關聯；如果狀態訊息是自動發出 (並非由傳送者要求觸發)，則為 0。寄件者應用程式會隨機選取 ID 並不斷增加 (不會使用 0)，藉此產生不重複的要求 ID。 |
| 類型 | string | MEDIA_STATUS(僅限值) |
| 狀態 | MediaStatus[] | 媒體狀態物件的陣列。注意：只有在 MediaStatus 經過變更時，才會傳回這些元素。 |
| 自訂資料 | 物件 | 選填 接收器應用程式定義的資料專用 blob |