將 Cast SDK 整合至 Web Sender 應用程式

本開發人員指南說明如何為您的網路新增 Google Cast 支援功能 使用 Cast SDK 的傳送端應用程式。

術語

行動裝置或瀏覽器是控製播放的傳送者。 Google Cast 裝置就是「接收端」,用於顯示內容 螢幕上的播放進度

Web Sender SDK 包含兩個部分:Framework API (cast.framework) 和基本 API (chrome.cast) 一般來說,您會在更簡單、高階的 Framework API 上發出呼叫。 然後由較低層級的 Base API 處理

寄件者架構是指 Framework API、模組和相關 為低階功能提供包裝函式的資源。 寄件者應用程式Google Cast Chrome 應用程式是指網頁 (HTML/JavaScript) 應用程式 所執行的程式碼網路接收器應用程式是指 投放到在 Chromecast 或 Google Cast 裝置上執行的 HTML/JavaScript 應用程式。

傳送方架構採用非同步回呼設計來通知傳送者 事件的應用程式中,以及轉換應用程式在不同狀態的切換

載入程式庫

如要在應用程式中實作 Google Cast 功能,必須知道 如下所示。將 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 上。

在此處理常式中,您可以呼叫 setOptions(options)敬上 方法是 CastContext

例如:

<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 物件 使用 Kubernetes 建立架構然後採用 setOptions(options)敬上 請使用 CastOptions 物件 設定 applicationID

如果您使用的是不須註冊的預設媒體接收器, 您會使用 Web Sender SDK 預先定義的常數 (如下所示),而非 applicationID

cast.framework.CastContext.getInstance().setOptions({
  receiverApplicationId: chrome.cast.media.DEFAULT_MEDIA_RECEIVER_APP_ID
});

媒體管理

CastContext 初始化後,應用程式即可擷取目前 任何 CastSession 使用 getCurrentSession()

var castSession = cast.framework.CastContext.getInstance().getCurrentSession();

CastSession 可用來將媒體載入已連線的投放裝置,例如: loadMedia(loadRequest)。 首先,請建立 MediaInfo、 使用 contentIdcontentType,以及任何其他資訊 與內容有關接著建立 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 可讓應用程式完整控制媒體 播放、暫停、停止及查看已載入的媒體。

  • 播放/暫停:playerController.playOrPause();
  • 停止:playerController.stop();
  • SEEK:playerController.seek();

RemotePlayerRemotePlayerController 可以是 與 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>

媒體狀態

在媒體播放期間,您可以設定能夠擷取各種事件 各種程式的接聽程式 cast.framework.RemotePlayerEventType敬上 在 RemotePlayerController 物件。

如要取得媒體狀態資訊,請使用 .MEDIA_INFO_CHANGED cast.framework.RemotePlayerEventType 這個事件會觸發系統通知 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 引進投放工作階段的概念 結合了連線至裝置、啟動 (或加入) 網路的步驟 接收端應用程式,連結至該應用程式,以及初始化媒體控制管道。查看網路接收端 應用程式生命週期指南 ,進一步瞭解投放工作階段和網路接收端的生命週期。

課程由課程管理 CastContext、 應用程式可透過 cast.framework.CastContext.getInstance()。 個別工作階段是以類別的子類別表示 Session。例如: CastSession敬上 則代表有投放裝置的工作階段。您的應用程式可以存取目前有效的 透過以下方式投放工作階段: CastContext.getCurrentSession()

如要監控工作階段狀態,請在 CastContext: 這個 CastContextEventType.SESSION_STATE_CHANGED 事件類型。

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;
    }
  })

針對連線中斷,例如當使用者點選「停止投放」時按鈕 您可以為「投放」對話方塊新增 .IS_CONNECTED_CHANGED RemotePlayerEventType 事件類型。透過事件監聽器檢查 RemotePlayer 是 已中斷連線。如果是,請視需要更新本機播放器狀態。例如:

playerController.addEventListener(
  cast.framework.RemotePlayerEventType.IS_CONNECTED_CHANGED, function() {
    if (!player.isConnected) {
      console.log('RemotePlayerController: Player disconnected');
      // Update local player to disconnected state
    }
  });

使用者可以透過投放架構直接控制 Cast 終止作業 按鈕,傳送者本身可使用目前的 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 語音指令,切換不同裝置中的現有音訊和影片串流 應用程式或智慧螢幕。在一部裝置 (來源) 上停止播放媒體,然後於另一部裝置 ( 目的地)。凡是裝有最新韌體的投放裝置,都可以做為來源或目的地 變更串流裝置。

如要在串流傳輸期間取得新的目標裝置,請撥打 CastSession#getCastDevice()敬上 當 cast.framework.SessionState.SESSION_RESUMED 新增事件

詳情請見 透過網路接收器轉移串流裝置 瞭解詳情