本開發人員指南說明如何使用 Cast SDK,為 Web Sender 應用程式新增 Google Cast 支援。
術語
行動裝置或瀏覽器是控製播放的「傳送者」;Google Cast 裝置則是「接收端」,可在螢幕上顯示播放內容。
Web Sender SDK 分為兩個部分: Framework API (cast.framework) 和 Base API (chrome.cast)。一般來說,您會在較簡單、高階的 Framework API 進行呼叫,然後由較低階的 Base API 處理。
傳送者架構是指架構 API、模組和相關資源,可為低階功能提供包裝函式。傳送者應用程式或 Google Cast Chrome 應用程式是指在傳送端裝置的 Chrome 瀏覽器中執行的網頁 (HTML/JavaScript)。網路接收器應用程式是指在 Chromecast 或 Google Cast 裝置上執行的 HTML/JavaScript 應用程式。
傳送者架構使用非同步回呼設計,向傳送方應用程式告知事件,並在 Cast 應用程式生命週期的不同狀態之間進行轉換。
載入程式庫
為了讓應用程式實作 Google Cast 功能,必須知道 Google Cast Web Sender SDK 的位置 (如下所示)。一併新增 loadCastFramework 網址查詢參數,以便載入 Web Sender Framework API。應用程式所有頁面都必須參照下列程式庫:
<script src="https://www.gstatic.com/cv/js/sender/v1/cast_sender.js?loadCastFramework=1"></script>
架構
Web Sender SDK 使用 cast.framework.* 命名空間。命名空間代表下列內容:
- 會在 API 上叫用作業的方法或函式
- API 中事件監聽器函式的事件監聽器
這個架構包含以下主要元件:
CastContext
是一個單例模式物件,可提供目前投放狀態的相關資訊,並觸發投放狀態和投放工作階段狀態變更的事件。CastSession
物件會管理工作階段,它會提供狀態資訊及觸發事件,例如裝置音量變更、靜音狀態,以及應用程式中繼資料。- 「投放」按鈕元素,是可展開 HTML 按鈕的簡易 HTML 自訂元素。如果提供的「投放」按鈕不敷使用,您可以使用「投放」狀態導入「投放」按鈕。
RemotePlayerController
提供資料繫結,可簡化遠端玩家的實作。
如需命名空間的完整說明,請參閱 Google Cast Web Sender API 參考資料。
投放按鈕
應用程式中的「投放」按鈕元件完全由架構處理。包括瀏覽權限管理和點擊事件處理。
<google-cast-launcher></google-cast-launcher>
或者,您也可以透過程式輔助方式建立按鈕:
document.createElement("google-cast-launcher");
您可以視需要為元素套用任何其他樣式,例如大小或位置。使用 --connected-color
屬性選擇連線的網路接收端狀態的顏色,使用 --disconnected-color
則選擇中斷連線狀態。
初始化
載入架構 API 後,應用程式會呼叫處理常式 window.__onGCastApiAvailable
。您應確保應用程式先在 window
上設定這個處理常式,再載入傳送者程式庫。
在這個處理常式中,您可以呼叫 CastContext
的 setOptions(options)
方法,初始化 Cast 互動。
例如:
<script>
window['__onGCastApiAvailable'] = function(isAvailable) {
if (isAvailable) {
initializeCastApi();
}
};
</script>
接著,請初始化 API,如下所示:
initializeCastApi = function() {
cast.framework.CastContext.getInstance().setOptions({
receiverApplicationId: applicationId,
autoJoinPolicy: chrome.cast.AutoJoinPolicy.ORIGIN_SCOPED
});
};
首先,應用程式會擷取架構所提供 CastContext
物件的單例模式例項。然後透過 CastOptions
物件使用 setOptions(options)
來設定 applicationID
。
如果您使用不需要註冊的預設媒體接收器,則會使用 Web Sender SDK 預先定義的常數,而非 applicationID
:
cast.framework.CastContext.getInstance().setOptions({
receiverApplicationId: chrome.cast.media.DEFAULT_MEDIA_RECEIVER_APP_ID
});
媒體管理
初始化 CastContext
後,應用程式隨時可以使用 getCurrentSession()
擷取目前的 CastSession
。
var castSession = cast.framework.CastContext.getInstance().getCurrentSession();
CastSession
可用來透過 loadMedia(loadRequest)
將媒體載入已連結的投放裝置。首先,使用 contentId
和 contentType
,以及任何其他與內容相關的資訊建立 MediaInfo
。然後從其中建立 LoadRequest
,設定要求的所有相關資訊。最後,請在 CastSession
上呼叫 loadMedia(loadRequest)
。
var mediaInfo = new chrome.cast.media.MediaInfo(currentMediaURL, contentType);
var request = new chrome.cast.media.LoadRequest(mediaInfo);
castSession.loadMedia(request).then(
function() { console.log('Load succeed'); },
function(errorCode) { console.log('Error code: ' + errorCode); });
loadMedia
方法會傳回 Promise,可用於執行任何必要的作業,以便取得成功結果。如果 Promise 遭拒,函式引數就會是 chrome.cast.ErrorCode
。
您可以在 RemotePlayer
中存取玩家狀態變數。所有與 RemotePlayer
的互動 (包括媒體事件回呼和指令) 都會使用 RemotePlayerController
處理。
var player = new cast.framework.RemotePlayer();
var playerController = new cast.framework.RemotePlayerController(player);
RemotePlayerController
可讓應用程式對已載入的媒體控制 PLAY、暫停、停止和查看的媒體控制權。
- 播放/暫停:
playerController.playOrPause();
- 停止:
playerController.stop();
- 查看:
playerController.seek();
RemotePlayer
和 RemotePlayerController
可與資料繫結架構 (例如 Polymer 或 Angular) 搭配使用,以實作遠端玩家。
以下是 Angular 的程式碼片段:
<button id="playPauseButton" class="playerButton" ng-disabled="!player.canPause" ng-click="controller.playOrPause()"> {{player.isPaused ? 'Play' : 'Pause'}} </button> <script> var player = new cast.framework.RemotePlayer(); var controller = new cast.framework.RemotePlayerController(player); // Listen to any player update, and trigger angular data binding update.controller.addEventListener( cast.framework.RemotePlayerEventType.ANY_CHANGE, function(event) { if (!$scope.$$phase) $scope.$apply(); }); </script>
媒體狀態
在媒體播放期間,如要擷取各種事件,您可以在 RemotePlayerController
物件上設定各種 cast.framework.RemotePlayerEventType
事件的事件監聽器。
如要取得媒體狀態資訊,請使用 cast.framework.RemotePlayerEventType
.MEDIA_INFO_CHANGED
事件,此事件會在播放變更和 CastSession.getMediaSession().media
變更時觸發。
playerController.addEventListener(
cast.framework.RemotePlayerEventType.MEDIA_INFO_CHANGED, function() {
// Use the current session to get an up to date media status.
let session = cast.framework.CastContext.getInstance().getCurrentSession();
if (!session) {
return;
}
// Contains information about the playing media including currentTime.
let mediaStatus = session.getMediaSession();
if (!mediaStatus) {
return;
}
// mediaStatus also contains the mediaInfo containing metadata and other
// information about the in progress content.
let mediaInfo = mediaStatus.media;
});
發生暫停、播放、繼續或跳轉等事件時,應用程式需要對這些事件採取行動,並將其本身與投放裝置上的網路接收器應用程式同步處理。詳情請參閱狀態更新。
工作階段管理的運作方式
Cast SDK 介紹投放工作階段的概念,並結合了連接裝置、啟動 (或加入) Web 接收器應用程式、連線至該應用程式,以及初始化媒體控制管道的步驟。如要進一步瞭解投放工作階段和 Web Receiver 生命週期,請參閱 Web Receiver 應用程式生命週期指南。
工作階段由 CastContext
類別管理,應用程式可以透過 cast.framework.CastContext.getInstance()
擷取。個別工作階段會以 Session
類別的子類別表示。舉例來說,CastSession
代表使用投放裝置的工作階段。應用程式可透過 CastContext.getCurrentSession()
存取目前進行中的投放工作階段。
如要監控工作階段狀態,請為 CastContextEventType
.SESSION_STATE_CHANGED
事件類型新增事件監聽器至 CastContext
。
var context = cast.framework.CastContext.getInstance();
context.addEventListener(
cast.framework.CastContextEventType.SESSION_STATE_CHANGED,
function(event) {
switch (event.sessionState) {
case cast.framework.SessionState.SESSION_STARTED:
case cast.framework.SessionState.SESSION_RESUMED:
break;
case cast.framework.SessionState.SESSION_ENDED:
console.log('CastContext: CastSession disconnected');
// Update locally as necessary
break;
}
})
如果是中斷連線 (例如在使用者點選「投放」對話方塊中的「停止投放」按鈕時),您可以在事件監聽器中新增 RemotePlayerEventType
.IS_CONNECTED_CHANGED
事件類型的事件監聽器。在事件監聽器中,請檢查 RemotePlayer
是否已中斷連線。如果有,請視需要更新本機玩家狀態。例如:
playerController.addEventListener(
cast.framework.RemotePlayerEventType.IS_CONNECTED_CHANGED, function() {
if (!player.isConnected) {
console.log('RemotePlayerController: Player disconnected');
// Update local player to disconnected state
}
});
雖然使用者可以透過架構的「投放」按鈕直接控制投放功能終止,但傳送者本身可以使用目前的 CastSession
物件停止投放。
function stopCasting() {
var castSession = cast.framework.CastContext.getInstance().getCurrentSession();
// End the session and pass 'true' to indicate
// that Web Receiver app should be stopped.
castSession.endSession(true);
}
變更串流裝置
保留工作階段狀態是串流傳輸的基礎,可讓使用者透過語音指令、Google Home 應用程式或智慧螢幕,在不同裝置上移動現有的音訊和影片串流。媒體會在某部裝置 (來源) 上停止播放,然後在另一部 (目的地) 上繼續播放。任何安裝最新韌體的 Cast 裝置都可以做為串流傳輸的來源或目的地。
如要在串流轉移期間取得新的目的地裝置,請在呼叫 cast.framework.SessionState
.SESSION_RESUMED
事件時呼叫 CastSession#getCastDevice()
。
詳情請參閱「Web Receiver 上的串流傳輸」。