本开发者指南介绍了如何向 Web 应用添加 Google Cast 支持 使用 Cast SDK 的发送器应用。
术语
移动设备或浏览器是控制播放的发送方; Google Cast 设备是接收方,用于在 Google Cast 中显示内容 屏幕进行播放。
Web Sender SDK 由两部分组成:Framework API (cast.framework) 和 Google Base API (chrome.castchrome.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
、
使用 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 被拒绝,则函数参数将是
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();
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 会话的概念,即 它的创建过程中,涉及到连接设备、启动(或加入)Web 的步骤 接收方应用、连接到该应用并初始化媒体控制渠道。查看网络接收器 应用生命周期指南 详细了解 Cast 会话和网络接收器生命周期。
会话由 类管理
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;
}
})
对于断开连接,例如当用户点击“停止投放”时按钮
您可以添加一个监听器来监听
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
事件。
请参阅 通过网络接收器进行流式传输 。