媒體播放訊息

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

根據《Google Cast SDK 附加開發人員服務條款》後，投放媒體應用程式必須使用這裡定義的訊息，控制接收器上的媒體播放。如此一來，媒體應用程式就能在各種平台上提供一致的使用者體驗，並確保投放應用程式支援各種新用途。在適用情況下，這些結構也支援自訂資料，且應用程式可以針對 SDK 不支援的指令定義自己的訊息。

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

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

常見的命名空間資料結構

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

映像檔

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

在圖片陣列中的單一項目中，你不一定要設定高度和寬度。舉例來說，如果傳回單一項目，則為選用項目。如果傳回兩個項目，一個項目就必須指定高度和寬度，但傳送者可能會選擇使用「預設」選項，而非使用特定參數傳送的項目。

名稱 類型 說明
網址 URI 圖片的 URI
高 整數 選填 ：圖片的高度
寬度 整數 選填  圖片的寬度

音量

媒體串流音量。用於媒體串流的淡入/淡出效果。(注意：系統磁碟區是透過傳送者 API 變更)。串流音量不得搭配音量滑桿或音量按鈕用於控制裝置音量。您必須傳送至少一項參數才能變更串流磁碟區。

名稱 類型 說明
等級 double 選填 ：目前串流音量是以 0.0 到 1.0 之間的值，其中 1.0 為最大音量。
靜音 boolean 選用 ：是否要將投放裝置設為靜音 (無論音量大小為何)

媒體命名空間資料結構

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

MediaInformation

這個資料結構可描述媒體串流。

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

將媒體構件類型描述為下列其中一種類型：

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

選用 ：媒體中繼資料物件，值為下列其中一項：
duration double 選填 ：目前播放串流的時間長度 (以秒為單位)
customData 物件 選用 ：傳送者應用程式或接收者應用程式定義的應用程式專屬 blob

GenericMediaMetadata

說明一般媒體構件。

名稱 類型 說明
metadataType 整數 0  (唯一值)
title 字串 選填  內容的描述性標題。玩家可以使用 content_id 單獨擷取標題，也可以在「載入」訊息中由傳送者提供標題
副標題 字串 選用  (選用) 內容的描述性副標題。玩家可以使用 content_id 單獨擷取標題，也可以在「載入」訊息中由傳送者提供標題
圖片 圖片[] 選用 ：與內容相關的圖片的陣列網址陣列。寄件者可在 Load 訊息中提供欄位初始值。必須提供建議的大小
releaseDate 字串 (ISO 8601) 選填 。這個內容的發行日期和時間 (採用 ISO 8601 標準)。玩家可以使用 content_id 單獨擷取標題，也可以在「載入」訊息中由傳送者提供標題

MovieMediaMetadata

說明電影媒體構件。

名稱 類型 說明
metadataType 整數 1  (唯一值)
title 字串 選填  內容的描述性標題。玩家可以使用 content_id 單獨擷取標題，也可以在「載入」訊息中由傳送者提供標題
副標題 字串 選用  (選用) 內容的描述性副標題。玩家可以使用 content_id 單獨擷取標題，也可以在「載入」訊息中由傳送者提供標題
工作室 字串 選用 ：用於發布內容的工作室。播放器可以使用 content_id 單獨擷取工作室，也可以在「Load」訊息中由傳送者提供
圖片 圖片[] 選用 ：與內容相關的圖片的陣列網址陣列。寄件者可在 Load 訊息中提供欄位初始值。必須提供建議的大小
releaseDate 字串 (ISO 8601) 選填 。這個內容的發行日期和時間 (採用 ISO 8601 標準)。玩家可以使用 content_id 單獨擷取標題，也可以在「載入」訊息中由傳送者提供標題

TvShowMediaMetadata

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

名稱 類型 說明
metadataType 整數 2  (唯一值)
seriesTitle 字串 選填  t.v. 系列的描述性標題。玩家可以使用 content_id 單獨擷取標題，也可以在「載入」訊息中由傳送者提供標題
副標題 字串 選填 。T.v. 劇集的描述性副標題。玩家可以使用 content_id 單獨擷取標題，也可以在「載入」訊息中由傳送者提供標題
季節 整數 選填 。電視節目的季別編號
劇集 整數 選填 。電視節目劇集的季別編號 (季別)
圖片 圖片[] 選用 ：與內容相關的圖片的陣列網址陣列。寄件者可在 Load 訊息中提供欄位初始值。必須提供建議的大小
originalAirDate 字串 (ISO 8601) 選用 ，採用 ISO 8601 格式，這集節目的發行日期和時間。播放器可以使用 content_id 單獨擷取 originalAirDate，也可以在 Load 訊息中由傳送者提供

MusicTrackMediaMetadata

說明音樂曲目媒體構件。

名稱 類型 說明
metadataType 整數 3  (唯一值)
albumName 字串 選用 ：用來繪製這個曲目的專輯或集錦。播放器可以使用 content_id 單獨擷取 AlbumName，也可以在 Load 訊息中由傳送者提供
title 字串 選填  曲目名稱 (例如歌名)。玩家可以使用 content_id 單獨擷取標題，也可以在「載入」訊息中由傳送者提供標題
albumArtist 字串 選填 ：與包含這首曲目的專輯相關聯的演出者名稱。播放器可以使用 content_id 單獨擷取專輯 Artist，也可以在 Load 訊息中由傳送者提供
藝人 字串 選填 ：與媒體曲目相關聯的藝人名稱。播放器可以使用 content_id 單獨擷取演出者，也可以在「Load」訊息中由傳送者提供
作曲家 字串 選填 ：與媒體音軌相關聯的作曲家名稱。播放器可以使用 content_id 單獨擷取作曲家，也可以在 Load 訊息中由傳送者提供
trackNumber 整數 選填 ：專輯中的曲目編號
discNumber 整數 選填 ：專輯的音量 (例如光碟)
圖片 圖片[] 選用 ：與內容相關的圖片的陣列網址陣列。寄件者可在 Load 訊息中提供欄位初始值。必須提供建議的大小
releaseDate 字串 (ISO 8601) 選填 。這個內容的發行日期和時間 (採用 ISO 8601 標準)。玩家可以使用 content_id 單獨擷取 releaseDate，也可以在「Load」訊息中由傳送者提供

PhotoMediaMetadata

說明攝影媒體構件。

名稱 類型 說明
metadataType 整數 4  (唯一值)
title 字串 選用 ：相片的標題。玩家可以使用 content_id 單獨擷取標題，也可以在「載入」訊息中由傳送者提供標題
藝人 字串 選填 ：攝影師的名稱。播放器可以使用 content_id 單獨擷取演出者，也可以在「Load」訊息中由傳送者提供
位置 字串 選擇性 ：相片拍攝地點的口頭地點，例如「西班牙馬德里」。玩家可以使用 content_id 單獨擷取位置，也可以在「Load」訊息中由傳送者提供
latitude double 選填 ：相片拍攝地點的地理緯度值。玩家可以使用 content_id 單獨擷取緯度，也可以在傳送 Load 訊息中給傳送者提供
longitude double 選填 ：相片拍攝地點的地理經度值。玩家可以使用 content_id 自行擷取經度，也可以在「Load」訊息中由傳送者提供
寬度 整數 選用 ：相片的寬度 (以像素為單位)。玩家可以使用 content_id 單獨擷取寬度，也可以在「Load」訊息中由傳送者提供
高 整數 選填 ：相片的高度 (以像素為單位)。玩家可以使用 content_id 單獨擷取高度，也可以在「Load」訊息中由傳送者提供
creationDateTime 字串 (ISO 8601) 選用  ISO 8601 相片拍攝日期和時間。播放器可以使用 content_id 單獨擷取 CreateDateTime，也可以在 Load 訊息中由傳送者提供

MediaStatus

說明與工作階段相關的媒體構件目前狀態。

名稱 類型 說明
mediaSessionId 整數 此特定工作階段播放的專屬 ID。這個 ID 是由 LOAD 的接收器設定，可以用來辨識播放的特定執行個體。舉例來說，在同一個工作階段內兩次播放「Wish You are here」(享受你這首歌) 時，就不會有專屬的 mediaSessionId。
media MediaInformation 選填 (針對狀態訊息) 正在播放的內容的完整說明。只有在 MediaInformation 有所變更時，才會在狀態訊息中傳回。
playbackRate float 指出媒體時間是否正在運作以及進度。這種狀態與播放器狀態無關，因為媒體時間可以在任何狀態下停止。1.0 是規律的時間，0.5 為慢動作
playerState 列舉 (字串)

說明下列其中一種玩家的狀態：

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

選用 ：如果玩家 State 是 IDLE，而系統發現 IDLE 的原因不明，則會提供這個屬性。如果玩家一開始是 IDLE，就不會提供這個屬性；如果玩家處於任何其他狀態，則不應提供這個屬性。適用的值如下：

  • 已取消  ：傳送者使用「STOP」指令要求停止播放
  • INTERRUPTED  ：傳送方使用 LOAD 指令要求播放其他媒體
  • FINISHED   媒體播放完畢
  • 錯誤  ：媒體因錯誤而中斷。舉例來說，如果播放器因網路問題而無法下載媒體
currentTime double 媒體播放器從內容開頭算起的目前位置 (以秒為單位)。如果是直播活動內容，這個欄位代表從活動開始後，播放器應該知道的時間點 (以秒為單位)。
supportedMediaCommands flag

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

  • 1  暫停
  • 2  跳轉
  • 4  串流音量
  • 8   串流靜音
  • 16  快轉
  • 32  倒轉

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

寄件者與接收者的指令

這些指令可控制媒體播放器。下列訊息中的所有 customData 物件都必須是選擇性的 (也就是說，如未傳送資料，接收方應正確降級)。如此一來，通用的遙控器應用程式即可正常運作。

載入

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

名稱 類型 說明
requestId 整數 用來建立要求和回應關聯的要求 ID
類型 字串 LOAD (僅限值)
media MediaInformation 要載入的媒體中繼資料 (包括 contentId)
自動播放 boolean

選用 (預設為 true) 如果指定了自動播放參數，媒體播放器就會在載入時開始播放內容。即使未指定自動播放，媒體播放器導入時仍可能選擇立即開始播放。如果開始播放，回應中的播放器狀態應設為 BUFFERING，否則應設為 PAUSED
currentTime double 選填 ：內容開始後經過的秒數。如果內容為直播內容，且未設定位置，直播功能會從直播開始出現
customData 物件 選用 ：傳送者應用程式定義的應用程式專屬 blob
回應 觸發條件 廣播 錯誤
無 接收端狀態變更 媒體狀態變更訊息 播放器狀態無效
載入失敗
載入已取消

暫停

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

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

跳轉

設定在訊息串中的目前位置。向所有傳送者應用程式觸發 STATUS 事件通知。如果提供的位置超出目前內容的有效位置範圍，則播放器應盡量挑選接近要求位置的有效位置。

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

選用 。如未設定這個值，播放狀態將不會變更；適用的值如下：

  • PLAYBACK_START  強制啟動媒體
  • PLAYBACK_PAUSE   強制暫停媒體
currentTime double 選填 ：內容開始後經過的秒數。如果內容為直播內容，且未設定位置，直播功能會從直播開始出現
customData 物件 選用 ：傳送者應用程式定義的應用程式專屬 blob
回應 觸發條件 廣播 錯誤
無 接收端狀態變更 媒體狀態變更訊息 玩家狀態無效

停止

停止播放目前內容。向所有傳送者應用程式觸發 STATUS 事件通知。使用這個指令之後，系統就不會再載入內容，且 mediaSessionId 失效。

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

播放

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

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

取得狀態

擷取媒體狀態。

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

SetVolume

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

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

接收者傳送給寄件者的郵件

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

  • 錯誤：寄件者要求出現錯誤回應時，系統會傳送 Unicast 訊息。
  • 狀態：廣播訊息。
    • 寄件者執行動作的結果。包含造成變更的要求的 requestId。
    • 自發：例如，由於接收器應用程式觸發的變更。RequestId 會是 0。

錯誤：播放器狀態無效

當傳送者因未處於有效狀態而無法完成要求時，就會傳送這個事件。例如，如果應用程式尚未建立媒體元素，

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

錯誤：載入失敗

當載入要求失敗時傳送。玩家狀態會是 IDLE。

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

錯誤：已取消載入

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

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

錯誤：無效的要求

當要求無效 (例如未知的要求類型) 時傳送。

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

值：

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

媒體狀態

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

名稱 類型 說明
requestId 整數 這個 ID 可用於為此狀態回應與產生此回應的要求建立關聯；如果狀態訊息是自發 (而非由傳送方要求觸發)，則設為 0。傳送者應用程式要產生一個不重複的要求 ID，方法是選取一個隨機號碼，然後不斷增加 (不會使用 0)。
類型 字串 MEDIA_STATUS (僅限值)
狀態 MediaStatus[] Media Status 物件陣列。注意：MediaStatus 中的媒體元素只有在變更時才會傳回。
customData 物件 選用 ：接收端應用程式定義的應用程式專屬 blob