Cast SDK 包含內建 API,可支援直播內容。其中包括靈活且立即可用的使用者介面,搭配 API 可讓開發人員使用幾行程式碼打造豐富的即時體驗。Live API 支援顯示開始和結束時間、節目中繼資料、DVR 控制項和可供搜尋的視窗。
本指南說明如何為 Live API 設定串流,包括用於設定核心即時情境的程式碼和中繼資料範例,以及示範各種情境的螢幕截圖。
必要條件
熟悉實作網路接收器之前,您必須先熟悉其中的基本概念。此外,若要執行程式碼範例,您必須能存取符合其中一個支援 Cast 支援的媒體類型的即時串流。直播功能通常支援支援的媒體適用的一般即時串流設定。
本指南使用以下字詞:
- 尋找內容的回溯期 - 使用者可在其中搜尋的直播活動範圍。
- 「Live Edge」:玩家可觀看的最新現場直播。
- 播放頭 - 目前播放位置的使用者介面時間戳記。
投放直播活動
您可以透過下列兩種方式將 Web Receiver SDK 設定為使用 Live API 執行內容:
- 使用
LOAD
訊息攔截器。(建議) - 使用傳送端或接收器端產生的載入要求。
攔截器會提供 LoadRequestData
物件,其中包含載入要求的所有重要中繼資料。如要表示直播活動的載入要求,只需將 mediaInformation
物件的 streamType
設為 StreamType.LIVE
即可。MediaInformation.duration
應為 -1
,因為播放器執行個體負責在內容為 LIVE
時負責計算。
/*
* This interceptor is called before your content is loaded by a Cast device
*/
playerManager.setMessageInterceptor(
cast.framework.messages.MessageType.LOAD,
request => { /* cast.framework.messages.LoadRequestData */
request.media.streamType = cast.framework.messages.StreamType.LIVE;
return request;
});
新增計劃指南資料
即時串流 (尤其是電視頻道等長時間執行的串流) 可以根據即時串流中的播放位置顯示螢幕導覽/節目規劃中繼資料。我們強烈建議內容供應商在網頁接收器應用程式中加入程式設計中繼資料,以提供更優質的使用者體驗。
您可以在 LOAD 訊息攔截器中設定串流的初始輔助資料,與在上述範例中指示串流使用的即時串流一樣。直播中的個別版面或節目會表示為 MediaMetadata
物件,然後將其儲存在佇列中。不同類型的程式有不同的 MediaMetadata
類別,例如 TvShowMediaMetadata
、MovieMediaMetadata
、MusicTrackMediaMetadata
等等。
在以下程式碼片段中,我們使用 MediaMetadata
物件來指定包含 sectionStartAbsoluteTime
屬性的 UNIX 時間戳記的各節目開始時間。程式顯示時間以秒為單位。
// The metadata for a single TV show
const currentShow = new cast.framework.messages.TvShowMediaMetadata();
currentShow.episode = 15;
currentShow.seriesTitle = 'The Odyssey';
currentShow.title = 'Scylla and Charybdis';
currentShow.sectionStartAbsoluteTime = toUnixTimestamp('9:00 PM');
currentShow.sectionDuration = HOUR_IN_SECONDS;
const previousShow = new ...;
const nextShow = new ...;
const containerMetadata = new cast.framework.messages.ContainerMetadata();
containerMetadata.title = 'My TV Channel';
containerMetadata.sections = [previousShow, currentShow, nextShow];
playerManager.getQueueManager().setContainerMetadata(containerMetadata);
可搜尋的範圍
Cast SDK 包含 UI 元素和控制項,可讓使用者在已啟用觸控式裝置的裝置中,使用展開的控制器或觸控設定移動播放頭。
LiveSeekableRange
代表使用者可串流的串流時間長度。在 Web 接收器上,您可以透過傳回 LiveSeekableRange
物件的 PlayerManager.getLiveSeekableRange()
存取可搜尋範圍的相關資訊。需要注意的物件主要屬性如下:
- start:相對於串流開始的範圍範圍的開始時間 (以秒為單位)。
- end:根據串流片段的可能與串流開始相關,系統可提供的最長時間 (以秒為單位)。
- ismoveWindow - 表示可搜尋範圍是否能隨著串流一起移動 (亦即,從資訊清單中移除舊區段) 的布林值,對所有直播而言,這應為 true。
- isLiveDone:布林值,表示直播活動是否已完成,也就是未產生新區隔。
可搜尋範圍的大小 (以 start
和 end
之間的時間表示) 取決於串流的可用片段數量,且會隨著串流一起移動。例如,如果在串流開始時,可搜尋的範圍是 {start:0, end: 600, isMovingWindow: false, isLiveDone: false}
,則在串流開始後的十秒內,它可以變成 {start: 10, end: 610,
isMovingWindow: true, isLiveDone: false}
。請特別注意,可搜尋範圍中的開始和結束時間會根據產生新區隔所需的時間而更新。因此,如果串流的一個片段一般長度為 10 秒,那麼開始和結束時間將大約每 10 秒更新一次。
停用搜尋功能
如要停用串流搜尋功能,您必須從網路接收器支援的媒體指令中移除搜尋功能:
// disable seeking in the LOAD messageInterceptor
playerManager.removeSupportedMediaCommands(cast.framework.messages.Command.SEEK, true);
將 SEEK
信號的支援媒體指令移除給傳送者應用程式,然後輕觸觸控功能以停用搜尋,但不會停用語音指令,例如「Ok Google,向後搜尋 30 秒」。如要進一步瞭解如何停用語音指令的媒體指令,請參閱支援語音的媒體指令指南。
即時架構事件
Live API 包含兩個事件 (LIVE_ENDED
和 LIVE_IS_MOVING_WINDOW_CHANGED
)。兩個事件都會傳遞 LiveStatusEvent
物件,其中包含目前可搜尋的可搜尋範圍。
事件 | 說明 |
---|---|
LIVE_ENDED |
系統會在直播結束時觸發。此時,LiveSeekableRange 中的 end 值將停止更新;使用者仍可查看目前可搜尋範圍內的內容。 |
LIVE_IS_MOVING_WINDOW_CHANGED |
當直播的可搜尋範圍從固定視窗變更為移動視窗時,就會觸發這個事件。對即時串流而言,當玩家偵測到資訊清單移除舊片段時,就會發生這種情況。 |
直播情境
即時串流有八種可能的情況,每種情境都採用三種核心設定來進行設定:
- 串流有開始時間
- 串流的結束時間
- 使用者可於直播的尋找視窗中尋找影片
如要瞭解如何設定這些值,請參閱新增節目指南資料。
下列為 Live API 支援的情境的說明和螢幕截圖。變數 T1 和 T2 分別用於代表 UI 左側的左右時間戳記。
開始時間 | 結束時間 | 跳轉 | T1 | T2 | |
---|---|---|---|---|---|
情境 1 | 否 | 否 | 否 | 播放頭部 | 未顯示 |
情境 7 | 是 | 是 | 否 | 顯示開始時間 | 顯示結束時間 |
情境 8 | 是 | 是 | 是 | 顯示開始時間 | 顯示結束時間 |
情境 1
開始時間 | 結束時間 | 跳轉 | T1 | T2 |
---|---|---|---|---|
否 | 否 | 否 | 播放頭 | 未顯示 |
情境 1 沒有開始或結束時間,且使用者無法在串流中搜尋。使用者停止串流時,系統會從直播邊緣 (而非暫停的位置) 恢復播放。
情境 7
開始時間 | 結束時間 | 跳轉 | T1 | T2 |
---|---|---|---|---|
是 | 是 | 否 | 播放頭部 | 計劃時間長度 |
情境 7 設有開始和結束時間,但並不容易搜尋。UI 中的兩個時間戳記 (T1 和 T2) 分別代表目前的播放頭時間和程式的總時間長度。當使用者暫停/繼續播放時,串流會在串流的即時邊緣恢復。在上述範例中,搜尋列的紅色部分代表自使用者開始觀看後串流部分。
情境八
開始時間 | 結束時間 | 跳轉 | T1 | T2 |
---|---|---|---|---|
是 | 是 | 是 | 播放頭部 | 計劃時間長度 |
情境 7 有開始時間、結束時間,且可供搜尋。UI 中的兩個時間戳記 (T1 和 T2) 分別代表目前的播放頭時間和程式的總時間長度。當使用者暫停/繼續播放時,如果串流在可供搜尋的期間內,串流就會恢復播放。搜尋列上的紅色區域代表使用者可繼續播放的位置,白色區域代表使用者可往回觀看的地方。
設定情境
將串流設定為特定的直播情境時,需完成三個步驟:
- 設定串流類型:將串流標示為即時串流。
- 新增節目指南資料 - 在
MediaMetadata
物件中設定開始時間和持續時間。 - 設定 Seek 功能 - 啟用或停用尋找功能。
播放行為
暫停時,使用者介面會持續更新播放中繼資料,包括播放頭和即時邊緣時間。繼續串流時,需要注意的行為因串流設定而異。
跳轉訊息串
恢復可搜尋的串流後:
- 即時邊緣應更新為即時位置,可調整的範圍會隨之調整。
- 如果播放頭跳過目前節目,進度列就會以新節目的中繼資料 (包括開始時間和結束時間 (如有)) 更新。
- 如果可搜尋的視窗長度為「X」,可搜尋的範圍會延長至最多「X」或顯示至開頭的開頭 (以時間較長者為準)。
- 如果使用者暫停的時間夠長,使得目前時間不在可搜尋的視窗中,串流就會在可搜尋視窗的最早時間點 (最左端) 恢復。
跳轉到 LiveSeekableRange.end
後,請在取消暫停後,於即時邊緣繼續播放。
let playerManager = cast.framework.CastReceiverContext.getInstance().getPlayerManager();
// Intercept the message to PLAY
playerManager.setMessageInterceptor(cast.framework.messages.MessageType.PLAY, (requestData) => {
...
if (playerManager.getLiveSeekableRange()) {
// Resume playback at the live edge
playerManager.seek(playerManager.getLiveSeekableRange().end);
} else {
return requestData;
}
...
});
不可搜尋的串流
恢復無法搜尋的串流時:
- 在這種情況下,播放內容會在即時邊緣繼續播放。
- 如果即時邊緣跳過目前的節目,拖曳列會依照新節目的中繼資料 (包括開始時間和結束時間 (如有)) 更新。
API 介面異動及自訂即時 UI
Cast SDK 內建現成的功能,可讓您建立自訂使用者介面,不必使用立即可用的使用者介面。不過,自訂介面時,請務必遵循 Cast 使用者體驗設計檢查清單。
網路接收器
在 Web 接收器上,PlayerData
包含下列欄位,可讓開發人員擴充直播活動的自訂介面:
- isLive - 表示目前串流是否為即時串流的標記,而非 VOD。
- liveSeekableRange - 在螢幕上顯示 DVR 倒帶時間範圍的可搜尋範圍。
- mediaStartAbsoluteTime - 部分在絕對時間開始 (UNIX Epoch) 的時間。
- sectionStartTimeInMedia - 相對於媒體開始時間的區段開始時間 (以秒為單位)。
- sectionDuration:版面長度,以秒為單位。
此外,自訂 UI 時請務必考量兩個現場直播。
Android SDK
在 Live 功能中,UIMediaController
中的 Android Seekbar 小工具已淘汰,請改用 CastSeekBar
。