Cast SDK をウェブ センダー アプリに統合する

このデベロッパー ガイドでは、Cast SDK を使用してウェブ送信元アプリに Google Cast のサポートを追加する方法について説明します。

用語

モバイル デバイスまたはブラウザは送信元で、再生を制御します。 Google Cast デバイスは受信側で、再生のために画面にコンテンツを表示します。

ウェブ送信元 SDK は、Framework API （cast.framework） と Base API （chrome.cast） の 2 つの部分で構成されています。通常は、よりシンプルなハイレベルの Framework API を呼び出し、その呼び出しはローレベルの Base API によって処理されます。

送信元フレームワーク は、ローレベルの機能のラッパーを提供する Framework API、モジュール、関連リソースを指します。送信元アプリ または Google Cast Chrome アプリ は、送信元デバイスの Chrome ブラウザ内で実行されるウェブ（HTML/JavaScript）アプリを指します。ウェブ レシーバー アプリ は、Chromecast またはキャスト デバイスで実行される HTML/JavaScript アプリを指します。

送信元フレームワークは、非同期コールバック設計を使用して、送信元アプリにイベントを通知し、Cast アプリのライフサイクルのさまざまな状態を移行します。

ライブラリを読み込む

アプリで Google Cast の機能を実装するには、以下に示すように、Google Cast ウェブ送信元 SDK の場所を把握する必要があります。loadCastFramework URL クエリ パラメータを追加して、ウェブ送信元 Framework API も読み込みます。アプリのすべてのページで、ライブラリを次のように参照する必要があります。

<script src="https://www.gstatic.com/cv/js/sender/v1/cast_sender.js?loadCastFramework=1"></script>

フレームワーク

ウェブ送信元 SDK は、cast.framework.* 名前空間を使用します。この名前空間は次のものを表します。

• API でオペレーションを呼び出すメソッドまたは関数
• API のリスナー関数のイベント リスナー

フレームワークは、次の主要なコンポーネントで構成されています。

• CastContext は、現在の Cast の状態に関する情報を提供し、Cast の状態と Cast セッションの状態の変化に関するイベントをトリガーするシングルトン オブジェクトです。
• CastSession オブジェクトはセッションを管理します。状態 情報を提供し、デバイスの音量、 ミュート状態、アプリのメタデータの変更などのイベントをトリガーします。
• キャスト アイコン要素。HTML ボタンを拡張するシンプルな HTML カスタム要素です。提供されているキャスト アイコンで十分でない場合は、Cast の状態を使用してキャスト アイコンを実装できます。
• RemotePlayerController は、リモートプレーヤーの実装を簡素化するためのデータ バインディングを提供します。

名前空間の詳細については、 Google Cast ウェブ送信元 API リファレンスをご覧ください。

キャスト アイコン

アプリのキャスト アイコン コンポーネントは、フレームワークによって完全に処理されます。これには、可視性の管理とクリック イベントの処理が含まれます。

<google-cast-launcher></google-cast-launcher>

または、ボタンをプログラムで作成することもできます。

document.createElement("google-cast-launcher");

必要に応じて、サイズや配置などの追加のスタイルを要素に適用できます。--connected-color 属性を使用して、接続されたウェブ レシーバーの状態の色を選択し、--disconnected-color を使用して切断された状態の色を選択します。

初期化

フレームワーク API を読み込むと、アプリはハンドラ window.__onGCastApiAvailable を呼び出します。送信元ライブラリを読み込む前に、アプリがこのハンドラ を window に設定していることを確認してください。

このハンドラ内で、 setOptions(options) メソッドを呼び出して、Cast のインタラクションを初期化します。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 オブジェクト のシングルトン インスタンスを取得します。次に、 setOptions(options) を使用して CastOptionsオブジェクト を使用してapplicationIDを設定します。

登録を必要としないデフォルトのメディア レシーバーを使用している場合は、applicationID の代わりに、以下に示すように、ウェブ送信元 SDK で事前定義された定数を使用します。

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) を使用して接続された Cast デバイスにメディアを読み込むことができます。まず、 MediaInfoを使用して、contentIdとcontentType、およびコンテンツに関連するその他の情報 を作成します。次に、それから 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. RemotePlayer とのすべてのインタラクション（メディア イベントのコールバックや コマンドなど）は、 RemotePlayerController で処理されます。

var player = new cast.framework.RemotePlayer();
var playerController = new cast.framework.RemotePlayerController(player);

RemotePlayerController を使用すると、読み込まれたメディアの再生、一時停止、停止、シークを完全に制御できます。

• 再生/一時停止: 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>

メディア ステータス

メディアの再生中には、さまざまなイベントが発生します。これらのイベントは、 さまざまな cast.framework.RemotePlayerEventType イベントのリスナーを RemotePlayerControllerオブジェクトで設定することでキャプチャできます。

メディアのステータス情報を取得するには、 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 デバイス上のウェブ レシーバー アプリとの間で同期する必要があります。詳細については、ステータスの更新 をご覧ください。

セッション管理の仕組み

Cast SDK では、Cast セッションという概念が導入されています。このセッションの確立には、デバイスへの接続、ウェブ レシーバー アプリの起動（または参加）、そのアプリへの接続、メディア コントロール チャネルの初期化というプロセスが含まれます。Cast セッションとウェブ レシーバーのライフサイクルについて詳しくは、ウェブ レシーバー アプリケーションのライフサイクル ガイド をご覧ください。

セッションは CastContextクラスによって管理されます。 アプリは cast.framework.CastContext.getInstance()を介してこのクラスを取得できます。 個々のセッションは、クラス Sessionのサブクラスで表されます。たとえば、 CastSession は Cast デバイスとのセッションを表します。アプリは現在アクティブな Cast セッションに 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;
    }
  })

切断の場合（ユーザーが Cast ダイアログで [キャストを停止] ボタンをクリックした場合など）、リスナーで 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
    }
  });

ユーザーはフレームワークの Cast ボタンを使用して 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 アプリ、スマートディスプレイを使用して、既存の音声ストリームと動画ストリームをデバイス間で移動できます。メディアは 1 つのデバイス（送信元）での再生を停止し、別のデバイス（宛先）で再生を続行します。最新のファームウェアを搭載したキャスト デバイスは、ストリーミング転送の送信元または宛先として機能します。

ストリーミング転送中に新しい宛先デバイスを取得するには、 CastSession#getCastDevice() が呼び出されたときに cast.framework.SessionState.SESSION_RESUMED イベントを呼び出します。

詳細については、 ウェブ レシーバーでのストリーミング転送 をご覧ください。