媒體播放訊息

Google Cast 傳送端應用程式會將 JSON 格式的訊息傳送至接收端應用程式，藉此控制接收端裝置的播放作業。同樣地，接收者也會以 JSON 格式將訊息傳回給傳送者。這些訊息可能是寄件者傳送的指令 (可變更播放器狀態)、收件者對這些指令的回應，或是描述收件者應用程式媒體的資料結構。

根據 Google Cast SDK 附加開發人員服務條款，Cast 媒體應用程式必須使用這裡定義的訊息，控制接收器上的媒體播放作業。這麼做可確保媒體應用程式在各平台提供一致的使用者體驗，並確保 Cast 應用程式支援新用途和未來用途。這些結構也支援自訂資料 (如適用)，且應用程式可為 SDK 不支援的指令定義自己的訊息。

媒體播放訊息的命名空間定義為 urn:x-cast:com.google.cast.media。

注意：本規格中的訊息和結構體具有隱含的大小上限，取決於傳輸訊息的大小上限，個別欄位則沒有限制。目前傳輸訊息的大小上限為 64 KB。

常見的命名空間資料結構

所有媒體命名空間構件使用的資料結構超集，都會定義在通用命名空間中。

圖片

這是圖片的說明，包括少量中繼資料，讓傳送端應用程式可根據圖片的顯示方式選擇圖片。

在 Images 陣列中，只有一個項目可選擇性提供高度和寬度。舉例來說，如果系統只傳回一個項目，則為選用；如果傳回兩個項目，其中一個項目必須指定高度和寬度，但如果傳送者不喜歡使用特定參數傳送的項目，也可以選擇「預設」選項。

名稱 類型 說明
url URI 圖片的 URI
height 整數 選用 ：圖片高度
width 整數 選用 ：圖片寬度

音量

媒體串流音量。用於媒體串流的淡入/淡出效果。(注意：系統音量是使用傳送者 API 變更。)請勿同時使用音量滑桿或音量按鈕控制裝置音量，如要變更串流音量，至少須傳遞下列其中一個參數。

名稱 類型 說明
level 雙精準數 選用 ：目前的串流音量，值介於 0.0 和 1.0 之間，1.0 代表最大音量。
muted 布林值 選用 ：無論音量大小，是否將 Google Cast 裝置設為靜音

媒體命名空間資料結構

這些訊息會說明媒體播放器的狀態。命名空間為 urn:x-cast:com.google.cast.media。

MediaInformation

這個資料結構會說明媒體串流。

名稱 類型 說明
contentId 字串 媒體播放器目前載入內容的服務專屬 ID。這是任意形式的字串，且專屬於應用程式。在大多數情況下，這會是媒體的網址，但傳送者可以選擇傳遞接收者可正確解讀的字串。長度上限：1,000 個字元
streamType enum
(string)

說明媒體構件的類型，可以是下列其中一種：

  • NONE
  • 已緩衝
  • 直播
contentType 字串 播放中媒體的 MIME 內容類型
中繼資料 物件

選用 ：媒體中繼資料物件，可以是下列其中一種：

duration 雙精準數 選用 ：目前播放串流的長度 (以秒為單位)
customData 物件 選用 ：由傳送端應用程式或接收端應用程式定義的應用程式專屬資料 Blob

GenericMediaMetadata

說明一般媒體構件。

名稱 類型 說明
metadataType 整數 0  (唯一值)
title 字串 選用 ：內容的描述性標題。播放器可使用 content_id 獨立擷取片名，也可以由傳送者在 Load 訊息中提供
subtitle 字串 選用 ：內容的描述性子標題。播放器可使用 content_id 獨立擷取片名，也可以由傳送者在 Load 訊息中提供
圖片 圖片[] 選填 ：與內容相關聯的圖片網址陣列。寄件者可以在「Load」訊息中提供欄位的初始值。應提供建議大小
releaseDate 字串 (ISO 8601) 選用 ：這項內容發布的 ISO 8601 日期和時間。播放器可使用 content_id 獨立擷取片名，也可以由傳送者在 Load 訊息中提供

MovieMediaMetadata

描述電影媒體構件。

名稱 類型 說明
metadataType 整數 1  (唯一值)
title 字串 選用 ：內容的描述性標題。播放器可使用 content_id 獨立擷取片名，也可以由傳送者在 Load 訊息中提供
subtitle 字串 選用 ：內容的描述性子標題。播放器可使用 content_id 獨立擷取片名，也可以由傳送者在 Load 訊息中提供
studio 字串 選用 ：發布內容的影視公司。播放器可使用 content_id 獨立擷取工作室，或由傳送者在 Load 訊息中提供
圖片 圖片[] 選填 ：與內容相關聯的圖片網址陣列。寄件者可以在「Load」訊息中提供欄位的初始值。應提供建議大小
releaseDate 字串 (ISO 8601) 選用 ：這項內容發布的 ISO 8601 日期和時間。播放器可使用 content_id 獨立擷取片名，也可以由傳送者在 Load 訊息中提供

TvShowMediaMetadata

說明電視節目集數媒體構件。

名稱 類型 說明
metadataType 整數 2  (唯一值)
seriesTitle 字串 選用 ：電視影集的說明標題。播放器可使用 content_id 獨立擷取片名，也可以由傳送者在 Load 訊息中提供
subtitle 字串 選用 電視節目集的描述性副標題。播放器可使用 content_id 獨立擷取片名，也可以由傳送者在 Load 訊息中提供
season 整數 選填 電視節目的季別
episode 整數 選填 ：電視節目在該季中的集數
圖片 圖片[] 選填 ：與內容相關聯的圖片網址陣列。寄件者可以在「Load」訊息中提供欄位的初始值。應提供建議大小
originalAirDate 字串 (ISO 8601) 選用 ：這集節目發布的 ISO 8601 日期和時間。播放器可使用 content_id 獨立擷取 originalAirDate，也可以由傳送者在 Load 訊息中提供

MusicTrackMediaMetadata

描述音樂曲目媒體構件。

名稱 類型 說明
metadataType 整數 3  (唯一值)
albumName 字串 選填 ：這首曲目所屬的專輯或合輯。播放器可使用 content_id 獨立擷取 albumName，也可以由傳送者在 Load 訊息中提供
title 字串 選填 曲目名稱 (例如歌曲名稱)。播放器可使用 content_id 獨立擷取片名，也可以由傳送者在 Load 訊息中提供
albumArtist 字串 選填 ：與收錄這首曲目的專輯相關聯的藝人名稱。播放器可使用 content_id 獨立擷取 albumArtist，也可以由傳送者在 Load 訊息中提供
藝人 字串 選用 ：與媒體曲目相關聯的藝人名稱。播放器可使用 content_id 獨立擷取藝人，也可以由傳送者在 Load 訊息中提供
composer 字串 選填 ：與媒體曲目相關聯的作曲家名稱。播放器可以獨立使用 content_id 擷取作曲家，也可以由傳送者在「Load」訊息中提供
trackNumber 整數 選用 ：專輯中曲目的編號
discNumber 整數 選填 ：專輯的卷號 (例如光碟)
圖片 圖片[] 選填 ：與內容相關聯的圖片網址陣列。寄件者可以在「Load」訊息中提供欄位的初始值。應提供建議大小
releaseDate 字串 (ISO 8601) 選用 ：這項內容發布的 ISO 8601 日期和時間。播放器可使用 content_id 獨立擷取 releaseDate，也可以由傳送者在 Load 訊息中提供

PhotoMediaMetadata

說明攝影媒體構件。

名稱 類型 說明
metadataType 整數 4  (唯一值)
title 字串 選填 ：相片的標題。播放器可使用 content_id 獨立擷取片名，也可以由傳送者在 Load 訊息中提供
藝人 字串 選用 攝影師姓名。播放器可使用 content_id 獨立擷取藝人，也可以由傳送者在 Load 訊息中提供
位置 字串 選填 ：相片的拍攝地點，例如「西班牙馬德里」。播放器可以使用 content_id 獨立擷取位置，也可以由傳送者在 Load 訊息中提供
latitude 雙精準數 選填 ：相片拍攝地點的地理緯度值。播放器可使用 content_id 獨立擷取緯度，也可以由傳送者在 Load 訊息中提供
longitude 雙精準數 選填 ：相片拍攝地點的地理經度值。播放器可使用 content_id 獨立擷取經度，或由傳送者在 Load 訊息中提供
width 整數 選用 ：相片的寬度 (以像素為單位)。播放器可使用 content_id 獨立擷取寬度，或由傳送者在 Load 訊息中提供
height 整數 選用 ：相片的高度 (以像素為單位)。播放器可使用 content_id 獨立擷取高度，或由傳送者在 Load 訊息中提供
creationDateTime 字串 (ISO 8601) 選用 ：這張相片的拍攝日期和時間，採用 ISO 8601 格式。播放器可使用 content_id 獨立擷取 creationDateTime，或由傳送者在 Load 訊息中提供

MediaStatus

說明媒體構件在工作階段中的目前狀態。

名稱 類型 說明
mediaSessionId 整數 這個特定工作階段的播放專屬 ID。這個 ID 是由接收端在 LOAD 時設定，可用於識別特定播放執行個體。舉例來說，如果同一工作階段中播放兩次「Wish you were here」，這兩次播放都會有專屬的 mediaSessionId。
media MediaInformation 選填 (適用於狀態訊息) ：播放內容的完整說明。只有在 MediaInformation 變更時，才會在狀態訊息中傳回。
playbackRate 浮點數 指出媒體時間是否正在推進，以及推進速度。這與播放器狀態無關，因為媒體時間可以在任何狀態下停止。1.0 為正常時間，0.5 為慢動作
playerState 列舉 (字串)

說明播放器的狀態，如下所示：

  • IDLE  尚未載入播放器
  • 播放  ：播放器正在播放內容
  • 緩衝  ：播放器處於「播放」模式，但未主動播放內容 (currentTime 不會變更)
  • 已暫停  ：播放器已暫停
idleReason 列舉 (字串)

選用 ：如果 playerState 為 IDLE，且系統知道進入 IDLE 狀態的原因，就會提供這項屬性。如果播放器剛啟動而處於 IDLE 狀態，系統不會提供這項屬性；如果播放器處於任何其他狀態，系統也不應提供這項屬性。可能出現的值如下：

  • 已取消  ：傳送者使用 STOP 指令要求停止播放
  • 已中斷  ：傳送者使用 LOAD 指令要求播放其他媒體
  • 已完成  ：媒體播放完畢
  • 錯誤  ：媒體因發生錯誤而中斷，例如播放器因網路問題而無法下載媒體
currentTime 雙精準數 媒體播放器從內容開頭算起的目前位置 (以秒為單位)。如果是直播內容，這個欄位代表播放器應知的活動時間 (以秒為單位)。
supportedMediaCommands flags

說明媒體播放器支援哪些媒體指令的旗標：

  • 1 << 0  暫停
  • 1 << 1  搜尋
  • 1 << 2  串流音量
  • 1 << 3  串流靜音
  • 1 << 4  快轉 (已淘汰)
  • 1 << 5  倒轉 (已淘汰)
  • 1 << 6  Queue next
  • 1 << 7  將上一首歌曲加入佇列
  • 1 << 8  佇列隨機播放
  • 1 << 9  略過廣告
  • 1 << 10  佇列重複播放所有歌曲
  • 1 << 11  將單一項目加入佇列並重複播放
  • 1 << 12  編輯字幕軌
  • 1 << 13  播放速率
  • 1 << 14  喜歡
  • 1 << 15  不喜歡
  • 1 << 16  追蹤
  • 1 << 17  取消追蹤

組合以加總表示，例如 Pause+Seek+StreamVolume+Mute == 15。
音量 音量 串流音量
customData 物件 選用 ：接收端應用程式定義的應用程式專屬資料 Blob

寄件者傳送給接收者的指令

這些指令可控制媒體播放器。以下訊息中的所有 customData 物件都必須是選用物件 (也就是說，如果未傳遞資料，接收器應適當降級)。這樣一來，一般遙控器應用程式就能正常運作。

載入

將新內容載入媒體播放器。

名稱 類型 說明
requestId 整數 要求 ID，用於建立要求和回應的關聯
type 字串 LOAD (僅限值)
media MediaInformation 要載入媒體的中繼資料 (包括 contentId)
autoplay 布林值

選用 (預設為 true)：如果指定自動播放參數，媒體播放器會在載入內容時開始播放。即使未指定自動播放，媒體播放器實作項目仍可選擇立即開始播放。如果已開始播放，回應中的播放器狀態應設為 BUFFERING，否則應設為 PAUSED
currentTime 雙精準數 選用 ：內容開始後經過的秒數。如果是直播內容，且未指定位置，系統會從直播位置開始播放
customData 物件 選用 ：傳送端應用程式定義的應用程式專屬資料 Blob
回應 觸發條件 廣播 錯誤
無 接收器狀態變更 媒體狀態變更訊息 無效的播放器狀態
載入失敗
載入已取消

暫停

暫停播放目前的內容。觸發 STATUS 事件通知，傳送給所有傳送端應用程式。

名稱 類型 說明
mediaSessionId 整數 要暫停的媒體工作階段 ID
requestId 整數 要求 ID，用於建立要求/回應關聯
type 字串 PAUSE (僅限值)
customData 物件 選用 ：傳送端應用程式定義的應用程式專屬資料 Blob
回應 觸發條件 廣播 錯誤
無 接收器狀態變更 媒體狀態變更訊息 播放器狀態無效

搜尋

設定串流中的目前位置。觸發 STATUS 事件通知，傳送給所有傳送端應用程式。如果提供的位置超出目前內容的有效位置範圍，播放器應盡可能選取最接近要求位置的有效位置。

名稱 類型 說明
mediaSessionId 整數 設定串流位置的媒體工作階段 ID
requestId 整數 要求 ID，用於建立要求和回應的關聯
type 字串 SEEK (僅限值)
resumeState 列舉 (字串)

選用 ：如未設定，播放狀態不會變更；適用下列值：

  • PLAYBACK_START  強制媒體開始播放
  • PLAYBACK_PAUSE  ：強制暫停媒體
currentTime 雙精準數 選用 ：內容開始後經過的秒數。如果是直播內容，且未指定位置，系統會從直播位置開始播放
customData 物件 選用 ：傳送端應用程式定義的應用程式專屬資料 Blob
回應 觸發條件 廣播 錯誤
無 接收器狀態變更 媒體狀態變更訊息 播放器狀態無效

停止

停止播放目前的內容。觸發 STATUS 事件通知，傳送給所有傳送端應用程式。執行這項指令後，系統就不會再載入內容，且 mediaSessionId 會失效。

名稱 類型 說明
mediaSessionId 整數 要停止的內容媒體工作階段 ID
requestId 整數 要求 ID，用於建立要求和回應的關聯
type 字串 STOP (僅限值)
customData 物件 選用 ：傳送端應用程式定義的應用程式專屬資料 Blob
回應 觸發條件 廣播 錯誤
無 接收器狀態變更 媒體狀態變更訊息 播放器狀態無效

播放

開始播放透過載入呼叫載入的內容，並從目前的播放時間位置繼續播放。

名稱 類型 說明
mediaSessionId 整數 要播放內容的媒體工作階段 ID
requestId 整數 要求 ID，用於建立要求和回應的關聯
type 字串 PLAY (僅限值)
customData 物件 選用 ：傳送端應用程式定義的應用程式專屬資料 Blob
回應 觸發條件 廣播 錯誤
無 接收器狀態變更 媒體狀態變更訊息 播放器狀態無效

取得狀態

擷取媒體狀態。

名稱 類型 說明
mediaSessionId 整數 選用 ：要傳回媒體狀態的媒體工作階段 ID。如未提供，系統會提供所有媒體工作階段 ID 的狀態。
requestId 整數 要求 ID，用於建立要求和回應的關聯
type 字串 GET_STATUS (僅限值)
customData 物件 選用 ：傳送端應用程式定義的應用程式專屬資料 Blob
回應 觸發條件 廣播 錯誤
MediaStatus 訊息給要求者 無 無 無

SetVolume

設定媒體串流音量。用於媒體串流的淡入/淡出效果。(注意：接收器音量是使用 Web 傳送端 setVolume 變更)。串流音量不得與音量滑桿或音量按鈕搭配使用，以控制裝置音量。串流音量變更不會在接收器上觸發任何 UI。

名稱 類型 說明
mediaSessionId 整數 要變更串流音量的媒體媒體工作階段 ID
requestId 整數 要求 ID，用於建立要求和回應的關聯
type 字串 VOLUME (僅限值)
音量 音量 串流音量
customData 物件 選用 ：傳送端應用程式定義的應用程式專屬資料 Blob
回應 觸發條件 廣播 錯誤
無 接收器狀態變更 媒體狀態變更訊息 播放器狀態無效

收件者傳送給寄件者的訊息

接收器會傳送兩種類型的訊息：

  • 錯誤：當傳送者要求收到錯誤回應時，系統會傳送單點傳播訊息。
  • 狀態：廣播訊息。
    • 寄件者發起動作的後果。包含導致變更的要求的 requestId。
    • 自發性：例如，因接收端應用程式觸發的變更而發生。RequestId 會是 0。

錯誤：播放器狀態無效

當播放器狀態異常，無法滿足傳送者的要求時，系統會傳送這個事件。舉例來說，如果應用程式尚未建立媒體元素。

名稱 類型 說明
requestId 整數 產生這項錯誤的要求 ID
type 字串 INVALID_PLAYER_STATE (僅限值)
customData 物件 選用 ：接收端應用程式定義的應用程式專屬資料 Blob

錯誤：載入失敗

載入要求失敗時傳送。播放器狀態會是 IDLE。

名稱 類型 說明
requestId 整數 產生這項錯誤的要求 ID
type 字串 LOAD_FAILED (僅限值)
customData 物件 選用 ：接收端應用程式定義的應用程式專屬資料 Blob

錯誤：載入已取消

在取消載入要求時傳送 (已收到第二個載入要求)。

名稱 類型 說明
requestId 整數 產生這項錯誤的要求 ID
type 字串 LOAD_CANCELLED (唯一值)
customData 物件 選用 ：接收端應用程式定義的應用程式專屬資料 Blob

錯誤：要求無效

要求無效時傳送 (例如要求類型不明)。

名稱 類型 說明
requestId 整數 產生這項錯誤的要求 ID
type 字串 INVALID_REQUEST (僅限值)
原因 列舉 (字串)

值：

  • INVALID_COMMAND  不支援這個指令
  • DUPLICATE_REQUESTID  ：要求 ID 不重複 (接收者正在處理具有相同 ID 的要求)
customData 物件 選用 ：接收端應用程式定義的應用程式專屬資料 Blob

媒體狀態

在狀態變更或媒體狀態要求後傳送。系統只會傳送已變更或要求的 MediaStatus 物件。

名稱 類型 說明
requestId 整數 用於將這個狀態回應與原始要求建立關聯的 ID，如果狀態訊息是自發性 (並非由傳送者要求觸發)，則為 0。傳送端應用程式會選取隨機數字並持續遞增 (不會使用 0)，藉此產生專屬要求 ID。
type 字串 MEDIA_STATUS (僅限值)
狀態 MediaStatus[] 媒體狀態物件的陣列。注意：只有在媒體元素有所變更時，系統才會傳回 MediaStatus 中的媒體元素。
customData 物件 選用 ：接收端應用程式定義的應用程式專屬資料 Blob