将 Cast SDK 集成到您的 Web 发送器应用中

本开发者指南介绍了如何向 Web 应用添加 Google Cast 支持 使用 Cast SDK 的发送器应用。

术语

移动设备或浏览器是控制播放的发送方; Google Cast 设备是接收方,用于在 Google Cast 中显示内容 屏幕进行播放。

Web Sender SDK 由两部分组成:Framework API (cast.framework) 和 Google Base API (chrome.cast) 一般来说,您可以在更简单、更高层级的 Framework API 上进行调用, 然后由较低级别的 Base API 处理。

“发送者框架”是指框架 API、模块以及关联的 为较低级别功能提供封装容器的资源。通过 发送者应用Google Cast Chrome 应用:一种网络 (HTML/JavaScript) 应用 。Web 接收器应用是指 Chromecast 或 Google Cast 设备上运行的 HTML/JavaScript 应用。

发送者框架使用异步回调设计来告知发送者 事件应用,以及在 Cast 应用生命周期的各种状态之间转换 循环。

加载库

为了让应用实现 Google Cast 的功能,应用需要知道 Google Cast Web Sender SDK 的位置,如下所示。将 用于加载 Web Sender Framework API 的 loadCastFramework 网址查询参数 。应用的所有页面都必须按如下方式引用该库:

<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 属性执行以下操作: 选择已连接的 Web Receiver 状态的颜色,以及 --disconnected-color(表示断开连接状态)。

初始化

加载框架 API 后,应用将调用处理程序 window.__onGCastApiAvailable。您应确保应用设置了此处理程序 对 window 执行上述操作,然后再加载 sender 库

在此处理程序中,您可以通过调用 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 对象 架构功能。然后,它会使用 setOptions(options) 使用 CastOptions 对象 以设置 applicationID

如果您使用的是不需要注册的默认媒体接收器, 您需要使用 Web Sender SDK 预定义的常量(如下所示),而不是 applicationID

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

媒体控件

CastContext 启动后, 已经初始化后,应用就可以检索当前的 CastSession(在任意时间) CANNOT TRANSLATE getCurrentSession()

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

CastSession 可用于通过以下方法将媒体加载到连接的 Cast 设备: 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 使应用能够完全控制 对已加载的媒体执行 PLAY、暂停、STOP 和 SEEK 操作。

  • 播放/暂停:playerController.playOrPause();
  • 停止:playerController.stop();
  • 查找: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 对象。

要获取媒体状态信息,请使用 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 会话的概念,即 它的创建过程中,涉及到连接设备、启动(或加入)Web 的步骤 接收方应用、连接到该应用并初始化媒体控制渠道。查看网络接收器 应用生命周期指南 详细了解 Cast 会话和网络接收器生命周期。

会话由 类管理 CastContext、 您的应用可以通过 cast.framework.CastContext.getInstance()。 各个会话由类的子类表示。 Session。例如: CastSession 表示与投放设备的会话。您的应用可以访问当前活跃的 投放会话的方式 CastContext.getCurrentSession()

要监控会话状态,请在 CastContextCastContextEventType.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;
    }
  })

对于断开连接,例如当用户点击“停止投放”时按钮 您可以添加一个监听器来监听 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 跨设备移动现有音频和视频流 应用或智能显示屏媒体在一台设备(源设备)上停止播放,然后在另一台设备(源设备)上继续播放 目标)。任何具有最新固件的投放设备都可以在 流式传输。

要在流式传输期间获取新的目标设备,请调用 CastSession#getCastDevice()cast.framework.SessionState.SESSION_RESUMED 事件。

请参阅 通过网络接收器进行流式传输