本页包含适用于自定义 Web 接收器应用的功能的代码段和说明。
cast-media-player
元素,表示随 Web 接收器提供的内置播放器界面。- 为
cast-media-player
元素设置类似于 CSS 的自定义样式,用于设置各种界面元素(例如background-image
、splash-image
和font-family
)的样式。 - 用于加载 Web 接收器框架的脚本元素。
- 用于拦截消息和处理事件的 JavaScript 代码。
- 加入自动播放队列。
- 用于配置播放的选项。
- 用于设置网络接收器上下文的选项。
- 用于设置 Web 接收器应用支持的命令的选项。
- 用于启动 Web 接收器应用的 JavaScript 调用。
应用配置和选项
配置应用
CastReceiverContext
是提供给开发者的最外层的类,用于管理底层库的加载并处理 Web 接收器 SDK 的初始化。SDK 提供的 API 可让应用开发者通过 CastReceiverOptions
配置 SDK。系统会在每次应用启动时对这些配置进行一次评估,并在对 start
的调用中设置可选参数时将其传递给 SDK。
以下示例展示了如何替换用于检测发送者连接是否仍处于活跃状态的默认行为。当 Web 接收器在 maxInactivity
秒内无法与发送者通信时,系统会分派 SENDER_DISCONNECTED
事件。以下配置可替换此超时设置。这在调试问题时非常有用,因为当没有任何已连接的发送者处于 IDLE
状态时,这会阻止 Web 接收器应用关闭 Chrome 远程调试程序会话。
const context = cast.framework.CastReceiverContext.getInstance();
const options = new cast.framework.CastReceiverOptions();
options.maxInactivity = 3600; // Development only
context.start(options);
配置播放器
加载内容时,Web Receiver SDK 提供了一种使用 cast.framework.PlaybackConfig
配置播放变量(例如 DRM 信息、重试配置和请求处理程序)的方法。此信息由 PlayerManager
处理,并在创建玩家时进行评估。每次有新负载传递到 Web 接收器 SDK 时,系统都会创建播放器。系统会在下次加载内容时评估创建播放器后对 PlaybackConfig
所做的修改。SDK 提供了以下用于修改 PlaybackConfig
的方法。
CastReceiverOptions.playbackConfig
,用于在初始化CastReceiverContext
时替换默认配置选项。PlayerManager.getPlaybackConfig()
,用于获取当前配置。PlayerManager.setPlaybackConfig()
,用于替换当前配置。此设置将应用于所有后续加载,或直到再次被替换为止。PlayerManager.setMediaPlaybackInfoHandler()
,以便仅为当前配置之上加载的媒体内容应用其他配置。系统会在创建玩家之前调用该处理程序。在此处所做的更改不是永久性的,并且不包含在对getPlaybackConfig()
的查询中。当下一个媒体内容加载时,系统会再次调用此处理程序。
以下示例展示了如何在初始化 CastReceiverContext
时设置 PlaybackConfig
。该配置会覆盖用于获取清单的传出请求。该处理程序指定应使用 Cookie 或授权标头等凭据发出 CORS 访问权限控制请求。
const playbackConfig = new cast.framework.PlaybackConfig();
playbackConfig.manifestRequestHandler = requestInfo => {
requestInfo.withCredentials = true;
};
context.start({playbackConfig: playbackConfig});
以下示例展示了如何使用 PlayerManager
中提供的 getter 和 setter 替换 PlaybackConfig
。该设置会将播放器配置为在加载 1 个片段后继续播放内容。
const playerManager =
cast.framework.CastReceiverContext.getInstance().getPlayerManager();
const playbackConfig = (Object.assign(
new cast.framework.PlaybackConfig(), playerManager.getPlaybackConfig()));
playbackConfig.autoResumeNumberOfSegments = 1;
playerManager.setPlaybackConfig(playbackConfig);
以下示例展示了如何使用媒体播放信息处理程序替换特定加载请求的 PlaybackConfig
。处理程序会调用应用实现的方法 getLicenseUrlForMedia
,以从当前项的 contentId
获取 licenseUrl
。
playerManager.setMediaPlaybackInfoHandler((loadRequestData, playbackConfig) => {
const mediaInformation = loadRequestData.media;
playbackConfig.licenseUrl = getLicenseUrlForMedia(mediaInformation.contentId);
return playbackConfig;
});
事件监听器
Web 接收器 SDK 让您的 Web 接收器应用能够处理播放器事件。事件监听器接受 cast.framework.events.EventType
参数(或这些参数的数组),用于指定应触发监听器的事件。您可以在 cast.framework.events.category
中找到适用于调试的预配置 cast.framework.events.EventType
数组。事件参数提供有关事件的更多信息。
例如,如果您想知道何时广播 mediaStatus
更改,可以使用以下逻辑来处理事件:
const playerManager =
cast.framework.CastReceiverContext.getInstance().getPlayerManager();
playerManager.addEventListener(
cast.framework.events.EventType.MEDIA_STATUS, (event) => {
// Write your own event handling code, for example
// using the event.mediaStatus value
});
消息拦截
Web 接收器 SDK 让您的 Web 接收器应用能够拦截消息,并针对这些消息执行自定义代码。消息拦截器接受一个 cast.framework.messages.MessageType
参数,用于指定应拦截的消息类型。
拦截器应返回修改后的请求,或使用修改后的请求值进行解析的 Promise。如果返回 null
,系统将阻止调用默认消息处理程序。如需了解详情,请参阅加载媒体。
例如,如果要更改加载请求数据,可以使用以下逻辑来拦截和修改它:
const context = cast.framework.CastReceiverContext.getInstance();
const playerManager = context.getPlayerManager();
playerManager.setMessageInterceptor(
cast.framework.messages.MessageType.LOAD, loadRequestData => {
const error = new cast.framework.messages.ErrorData(
cast.framework.messages.ErrorType.LOAD_FAILED);
if (!loadRequestData.media) {
error.reason = cast.framework.messages.ErrorReason.INVALID_PARAM;
return error;
}
if (!loadRequestData.media.entity) {
return loadRequestData;
}
return thirdparty.fetchAssetAndAuth(loadRequestData.media.entity,
loadRequestData.credentials)
.then(asset => {
if (!asset) {
throw cast.framework.messages.ErrorReason.INVALID_REQUEST;
}
loadRequestData.media.contentUrl = asset.url;
loadRequestData.media.metadata = asset.metadata;
loadRequestData.media.tracks = asset.tracks;
return loadRequestData;
}).catch(reason => {
error.reason = reason; // cast.framework.messages.ErrorReason
return error;
});
});
context.start();
错误处理
当消息拦截器中出现错误时,您的 Web 接收器应用应返回相应的 cast.framework.messages.ErrorType
和 cast.framework.messages.ErrorReason
。
playerManager.setMessageInterceptor(
cast.framework.messages.MessageType.LOAD, loadRequestData => {
const error = new cast.framework.messages.ErrorData(
cast.framework.messages.ErrorType.LOAD_CANCELLED);
if (!loadRequestData.media) {
error.reason = cast.framework.messages.ErrorReason.INVALID_PARAM;
return error;
}
...
return fetchAssetAndAuth(loadRequestData.media.entity,
loadRequestData.credentials)
.then(asset => {
...
return loadRequestData;
}).catch(reason => {
error.reason = reason; // cast.framework.messages.ErrorReason
return error;
});
});
消息拦截与事件监听器
消息拦截和事件监听器之间的一些主要区别如下:
- 事件监听器不允许您修改请求数据。
- 事件监听器最适合用于触发分析或自定义函数。
playerManager.addEventListener(cast.framework.events.category.CORE,
event => {
console.log(event);
});
- 借助消息拦截,您可以监听和拦截消息,并修改请求数据本身。
- 消息拦截最适合用于处理与请求数据相关的自定义逻辑。
加载媒体
MediaInformation
提供了多种属性,用于在 cast.framework.messages.MessageType.LOAD
消息中加载媒体,包括 entity
、contentUrl
和 contentId
。
- 建议您在实现中,为发送方应用和接收方应用使用
entity
属性。该属性是一个深层链接网址,它可以是播放列表或媒体内容。您的应用应解析此网址,并至少填充另外两个字段中的一个。 contentUrl
对应于播放器用于加载内容的可播放网址。例如,此网址可能指向 DASH 清单。contentId
可以是可播放内容网址(类似于contentUrl
属性的网址),也可以是正在加载的内容或播放列表的唯一标识符。如果将此属性用作标识符,您的应用应在contentUrl
中填充一个可播放网址。
建议使用 entity
存储实际 ID 或键参数,并使用 contentUrl
作为媒体网址。以下代码段展示了一个示例,其中 LOAD
请求中存在 entity
,并且系统检索了可播放的 contentUrl
:
playerManager.setMessageInterceptor(
cast.framework.messages.MessageType.LOAD, loadRequestData => {
...
if (!loadRequestData.media.entity) {
// Copy the value from contentId for legacy reasons if needed
loadRequestData.media.entity = loadRequestData.media.contentId;
}
return thirdparty.fetchAssetAndAuth(loadRequestData.media.entity,
loadRequestData.credentials)
.then(asset => {
loadRequestData.media.contentUrl = asset.url;
...
return loadRequestData;
});
});
设备功能
getDeviceCapabilities
方法可提供连接的 Cast 设备以及连接的视频或音频设备上的设备信息。getDeviceCapabilities
方法可为 Google 助理、蓝牙以及连接的显示和音频设备提供支持信息。
此方法会返回一个对象,您可以通过传入其中一个指定的枚举来查询该对象,以获取该枚举的设备功能。枚举在 cast.framework.system.DeviceCapabilities
中定义。
此示例会检查网络接收器设备是否能够分别使用 IS_HDR_SUPPORTED
和 IS_DV_SUPPORTED
键播放 HDR 和杜比视界 (DV)。
const context = cast.framework.CastReceiverContext.getInstance();
context.addEventListener(cast.framework.system.EventType.READY, () => {
const deviceCapabilities = context.getDeviceCapabilities();
if (deviceCapabilities &&
deviceCapabilities[cast.framework.system.DeviceCapabilities.IS_HDR_SUPPORTED]) {
// Write your own event handling code, for example
// using the deviceCapabilities[cast.framework.system.DeviceCapabilities.IS_HDR_SUPPORTED] value
}
if (deviceCapabilities &&
deviceCapabilities[cast.framework.system.DeviceCapabilities.IS_DV_SUPPORTED]) {
// Write your own event handling code, for example
// using the deviceCapabilities[cast.framework.system.DeviceCapabilities.IS_DV_SUPPORTED] value
}
});
context.start();
处理用户互动
用户可以通过发送器应用(Web、Android 和 iOS)、内置 Google 助理设备上的语音指令、智能显示屏上的触控功能以及 Android TV 设备上的遥控器与您的 Web 接收器应用互动。Cast SDK 提供了各种 API,让网络接收器应用能够处理这些互动、通过用户操作状态更新应用界面,以及选择性地发送更改以更新任何后端服务。
支持的媒体命令
界面控件状态由以下因素驱动:MediaStatus.supportedMediaCommands
(适用于 iOS 和 Android 发送器展开的控制器)、在触摸设备上运行的接收器和遥控器应用,以及 Android TV 设备上的接收器应用。在属性中启用特定的按位 Command
时,与该操作相关的按钮将启用。如果未设置该值,则按钮处于停用状态。若要在 Web 接收器中更改这些值,请执行以下操作:
- 使用
PlayerManager.setSupportedMediaCommands
设置特定的Commands
- 使用
addSupportedMediaCommands
添加新命令 - 使用
removeSupportedMediaCommands
移除现有命令。
playerManager.setSupportedMediaCommands(cast.framework.messages.Command.SEEK |
cast.framework.messages.Command.PAUSE);
当接收器准备好更新后的 MediaStatus
时,它会将更改包含在 supportedMediaCommands
属性中。当状态被广播时,已连接的发送器应用将相应地更新其界面中的按钮。
如需详细了解支持的媒体命令和触摸设备,请参阅 Accessing UI controls
指南。
管理用户操作状态
当用户与界面互动或发送语音指令时,他们可以控制与播放的项目相关的内容和属性的播放。控制播放的请求由 SDK 自动处理。修改当前播放项的属性的请求(例如 LIKE
命令)要求接收器应用处理这些属性。SDK 提供了一系列 API 来处理这些类型的请求。如需支持这些请求,必须执行以下操作:
- 使用用户在加载媒体项时的偏好设置
MediaInformation
userActionStates
。 - 拦截
USER_ACTION
消息并确定请求的操作。 - 更新
MediaInformation
UserActionState
以更新界面。
以下代码段会拦截 LOAD
请求并填充 LoadRequestData
的 MediaInformation
。在这种情况下,用户喜欢正在加载的内容。
playerManager.setMessageInterceptor(
cast.framework.messages.MessageType.LOAD, (loadRequestData) => {
const userActionLike = new cast.framework.messages.UserActionState(
cast.framework.messages.UserAction.LIKE);
loadRequestData.media.userActionStates = [userActionLike];
return loadRequestData;
});
以下代码段会拦截 USER_ACTION
消息,并通过所请求的更改处理对后端的调用。然后,它会调用以更新接收器上的 UserActionState
。
playerManager.setMessageInterceptor(cast.framework.messages.MessageType.USER_ACTION,
(userActionRequestData) => {
// Obtain the media information of the current content to associate the action to.
let mediaInfo = playerManager.getMediaInformation();
// If there is no media info return an error and ignore the request.
if (!mediaInfo) {
console.error('Not playing media, user action is not supported');
return new cast.framework.messages.ErrorData(messages.ErrorType.BAD_REQUEST);
}
// Reach out to backend services to store user action modifications. See sample below.
return sendUserAction(userActionRequestData, mediaInfo)
// Upon response from the backend, update the client's UserActionState.
.then(backendResponse => updateUserActionStates(backendResponse))
// If any errors occurred in the backend return them to the cast receiver.
.catch((error) => {
console.error(error);
return error;
});
});
以下代码段模拟了对后端服务的调用。该函数会检查 UserActionRequestData
以查看用户请求的更改类型,并且仅在后端支持该操作时进行网络调用。
function sendUserAction(userActionRequestData, mediaInfo) {
return new Promise((resolve, reject) => {
switch (userActionRequestData.userAction) {
// Handle user action changes supported by the backend.
case cast.framework.messages.UserAction.LIKE:
case cast.framework.messages.UserAction.DISLIKE:
case cast.framework.messages.UserAction.FOLLOW:
case cast.framework.messages.UserAction.UNFOLLOW:
case cast.framework.messages.UserAction.FLAG:
case cast.framework.messages.UserAction.SKIP_AD:
let backendResponse = {userActionRequestData: userActionRequestData, mediaInfo: mediaInfo};
setTimeout(() => {resolve(backendResponse)}, 1000);
break;
// Reject all other user action changes.
default:
reject(
new cast.framework.messages.ErrorData(cast.framework.messages.ErrorType.INVALID_REQUEST));
}
});
}
以下代码段接受 UserActionRequestData
,并从 MediaInformation
中添加或移除 UserActionState
。更新 MediaInformation
的 UserActionState
会更改与所请求操作相关联的按钮的状态。此变更反映在智能显示屏控制界面、遥控器应用和 Android TV 界面中。它还通过传出的 MediaStatus
消息进行广播,以更新针对 iOS 和 Android 发送者的展开控制器界面。
function updateUserActionStates(backendResponse) {
// Unwrap the backend response.
let mediaInfo = backendResponse.mediaInfo;
let userActionRequestData = backendResponse.userActionRequestData;
// If the current item playing has changed, don't update the UserActionState for the current item.
if (playerManager.getMediaInformation().entity !== mediaInfo.entity) {
return;
}
// Check for existing userActionStates in the MediaInformation.
// If none, initialize a new array to populate states with.
let userActionStates = mediaInfo.userActionStates || [];
// Locate the index of the UserActionState that will be updated in the userActionStates array.
let index = userActionStates.findIndex((currUserActionState) => {
return currUserActionState.userAction == userActionRequestData.userAction;
});
if (userActionRequestData.clear) {
// Remove the user action state from the array if cleared.
if (index >= 0) {
userActionStates.splice(index, 1);
}
else {
console.warn("Could not find UserActionState to remove in MediaInformation");
}
} else {
// Add the UserActionState to the array if enabled.
userActionStates.push(
new cast.framework.messages.UserActionState(userActionRequestData.userAction));
}
// Update the UserActionState array and set the new MediaInformation
mediaInfo.userActionStates = userActionStates;
playerManager.setMediaInformation(mediaInfo, true);
return;
}
语音指令
适用于内置 Google 助理的设备的 Web 接收器 SDK 目前支持以下媒体命令。这些命令的默认实现位于 cast.framework.PlayerManager
中。
命令 | 说明 |
---|---|
开始游戏 | 从暂停状态播放或继续播放。 |
暂停 | 暂停当前播放的内容。 |
上一步 | 跳至媒体队列中的上一项媒体内容。 |
继续 | 跳至媒体队列中的下一项媒体内容。 |
停止 | 停止当前播放的媒体。 |
不重复 | 禁止在队列中的最后一项播放完毕后重复播放队列中的媒体内容。 |
重复单曲 | 无限期重复播放当前播放的媒体。 |
全部重复 | 当队列中的最后一项播放完毕后,重复该队列中的所有项。 |
全部重复和随机播放 | 当队列中的最后一项播放完毕后,随机打乱队列并重复播放队列中的所有项。 |
随机播放 | 随机播放媒体队列中的媒体内容。 |
字幕开启 / 关闭 | 为媒体启用 / 停用字幕。此外,您还可以根据语言启用 / 停用。 |
将跳转到绝对时间 | 跳转到指定的绝对时间。 |
跳转到相对于当前时间的时间 | 相对于当前播放时间,向前或向后快进指定的时间段。 |
重玩 | 重新启动当前正在播放的媒体;如果当前未播放任何内容,则播放上次播放的媒体项。 |
设置播放速率 | 请采用不同的媒体播放速率。这应默认进行处理。您可以使用 SET_PLAYBACK_RATE 消息拦截器来替换传入的速率请求。 |
支持的语音媒体命令
如需阻止语音指令在内置 Google 助理的设备上触发媒体命令,您必须先设置您计划支持的受支持的媒体命令。然后,您必须通过启用 CastReceiverOptions.enforceSupportedCommands
属性来强制执行这些命令。Cast SDK 发送器和触控设备上的界面会发生变化,以反映这些配置。如果该标志未启用,系统将执行传入的语音指令。
例如,如果您允许来自发送器应用和触屏设备使用 PAUSE
,则还必须配置接收器以反映这些设置。配置后,如果未包含在受支持命令列表中,传入的任何语音指令都将被丢弃。
在以下示例中,我们会在启动 CastReceiverContext
时提供 CastReceiverOptions
。我们添加了对 PAUSE
命令的支持,并强制播放器仅支持该命令。现在,如果语音指令请求其他操作(例如 SEEK
),操作将被拒绝。系统会通知用户该命令还不受支持。
const context = cast.framework.CastReceiverContext.getInstance();
context.start({
enforceSupportedCommands: true,
supportedCommands: cast.framework.messages.Command.PAUSE
});
您可以为每个要限制的命令应用单独的逻辑。移除 enforceSupportedCommands
标志;对于您要限制的每个命令,您都可以拦截传入的消息。在这里,我们会拦截 SDK 提供的请求,这样,向内置 Google 助理的设备发出的 SEEK
命令就不会在网络接收器应用中触发跳转。
对于应用不支持的媒体命令,返回适当的错误原因,例如 NOT_SUPPORTED
。
playerManager.setMessageInterceptor(cast.framework.messages.MessageType.SEEK,
seekData => {
// Block seeking if the SEEK supported media command is disabled
if (!(playerManager.getSupportedMediaCommands() & cast.framework.messages.Command.SEEK)) {
let e = new cast.framework.messages.ErrorData(cast.framework.messages.ErrorType
.INVALID_REQUEST);
e.reason = cast.framework.messages.ErrorReason.NOT_SUPPORTED;
return e;
}
return seekData;
});
语音活动记录的后台运行
如果 Cast 平台因 Google 助理 activity(例如倾听用户语音或回复)而将您应用的声音置于后台,则当该 activity 启动时,系统会向 Web 接收器应用发送 NOT_IN_FOCUS
FocusState
消息。当该 activity 结束时,系统会发送另一条带有 IN_FOCUS
的消息。根据您的应用和正在播放的媒体,您可能需要在 FocusState
为 NOT_IN_FOCUS
时,通过拦截 FOCUS_STATE
消息来暂停媒体。
例如,如果 Google 助理回应了用户查询,暂停播放有声读物是一种很好的用户体验。
playerManager.setMessageInterceptor(cast.framework.messages.MessageType.FOCUS_STATE,
focusStateRequestData => {
// Pause content when the app is out of focus. Resume when focus is restored.
if (focusStateRequestData.state == cast.framework.messages.FocusState.NOT_IN_FOCUS) {
playerManager.pause();
} else {
playerManager.play();
}
return focusStateRequestData;
});
语音指定的字幕语言
如果用户没有明确说明字幕的语言,则字幕的语言就是用户说出命令时所使用的语言。
在这些情况下,传入消息的 isSuggestedLanguage
参数会指示关联的语言是用户建议还是明确请求。
例如,对于“Ok Google,打开字幕”命令,isSuggestedLanguage
设置为 true
,因为系统会根据用户说出命令的语言推断出语言。如果明确请求语言(例如在“Ok Google,开启英文字幕”),isSuggestedLanguage
会设置为 false
。
元数据和语音投放
虽然语音指令默认由 Web 接收器处理,但您应确保内容的元数据完整且准确。这样可确保 Google 助理正确处理语音指令,并确保元数据在新型界面(例如 Google Home 应用和 Google Home Hub 等智能显示屏)上正确显示。
流式传输
保留会话状态是数据流传输的基础,在这种情况下,用户可以使用语音指令、Google Home 应用或智能显示屏在设备之间移动现有的音频和视频串流。媒体在一台设备(来源)上停止播放,然后在另一台设备(目标)上继续播放。任何具有最新固件的 Cast 设备都可以作为流式传输传输中的来源或目的地。
数据流传输的事件流如下:
- 在源设备上:
- 媒体停止播放。
- Web 接收器应用收到用于保存当前媒体状态的命令。
- Web Receiver 应用已关闭。
- 在目标设备上:
- 系统会加载 Web Receiver 应用。
- Web 接收器应用收到用于恢复已保存的媒体状态的命令。
- 媒体继续播放。
媒体状态的元素包括:
- 歌曲、视频或媒体项的具体位置或时间戳。
- 视频出现在更宽泛的队列中(例如播放列表或音乐人电台)。
- 经过身份验证的用户。
- 播放状态(例如,正在播放或已暂停)。
启用数据流传输
如需为 Web 接收器实现数据流传输,请执行以下操作:
- 使用
STREAM_TRANSFER
命令更新supportedMediaCommands
:playerManager.addSupportedMediaCommands( cast.framework.messages.Command.STREAM_TRANSFER, true);
- 可以选择替换
SESSION_STATE
和RESUME_SESSION
消息拦截器,如保留会话状态中所述。只有在需要将自定义数据存储为会话快照的一部分时,才替换这些变量。否则,用于保留会话状态的默认实现将支持数据流传输。
保留会话状态
Web 接收器 SDK 为网络接收器应用提供默认实现,以便通过截取当前媒体状态的快照、将状态转换为加载请求以及通过加载请求恢复会话来保留会话状态。
如有必要,可以在 SESSION_STATE
消息拦截器中替换网络接收器生成的加载请求。如果要将自定义数据添加到加载请求中,我们建议将其放入 loadRequestData.customData
中。
playerManager.setMessageInterceptor(
cast.framework.messages.MessageType.SESSION_STATE,
function (sessionState) {
// Override sessionState.loadRequestData if needed.
const newCredentials = updateCredentials_(sessionState.loadRequestData.credentials);
sessionState.loadRequestData.credentials = newCredentials;
// Add custom data if needed.
sessionState.loadRequestData.customData = {
'membership': 'PREMIUM'
};
return sessionState;
});
您可以从 RESUME_SESSION
消息拦截器中的 loadRequestData.customData
检索自定义数据。
let cred_ = null;
let membership_ = null;
playerManager.setMessageInterceptor(
cast.framework.messages.MessageType.RESUME_SESSION,
function (resumeSessionRequest) {
let sessionState = resumeSessionRequest.sessionState;
// Modify sessionState.loadRequestData if needed.
cred_ = sessionState.loadRequestData.credentials;
// Retrieve custom data.
membership_ = sessionState.loadRequestData.customData.membership;
return resumeSessionRequest;
});
内容预加载
Web 接收器支持在队列中的当前播放项之后预加载媒体项。
预加载操作会预先下载未来项目的多个部分。规范是在 QueueItem 对象中的 preloadTime 值上完成的(如果未提供,则默认为 20 秒)。该时间以相对于当前播放项末尾的秒数表示。只有正值才有效。例如,如果值为 10 秒,则此项会在前一项内容完成播放前 10 秒预加载。如果预加载时间高于 currentItem 上剩余时间,预加载将尽快完成。因此,如果为 queueItem 指定了非常大的预加载值,则每当播放当前项时,我们已经在预加载下一个项时就可以实现这样的效果。不过,我们将此设置和选择留给开发者,因为该值可能会影响当前播放项的带宽和流式传输性能。
默认情况下,预加载适用于 HLS、DASH 和流畅流式传输内容。
系统不会预加载常规 MP4 视频和音频文件(如 MP3),因为 Cast 设备仅支持一个媒体元素,且无法在现有内容项仍在播放时用于预加载。
自定义消息
消息交换是 Web 接收器应用的关键互动方法。
发送者使用发送者所运行平台(Android、iOS、Web)的发送者 API 向 Web 接收器发送消息。传递给事件监听器的事件对象(即消息的表现形式)包含一个数据元素 (event.data
),其中数据采用特定事件类型的属性。
Web 接收器应用可以选择监听指定命名空间中的消息。鉴于此,Web 接收器应用可据此支持该命名空间协议。然后,任何连接的发送方希望在该命名空间上进行通信,以使用适当的协议。
所有命名空间都由字符串定义,并且必须以“urn:x-cast:
”开头,后跟任意字符串。例如,“urn:x-cast:com.example.cast.mynamespace
”。
以下代码段供 Web 接收器监听来自已连接的发送者的自定义消息:
const context = cast.framework.CastReceiverContext.getInstance();
const CUSTOM_CHANNEL = 'urn:x-cast:com.example.cast.mynamespace';
context.addCustomMessageListener(CUSTOM_CHANNEL, function(customEvent) {
// handle customEvent.
});
context.start();
同样,网络接收器应用可以通过向已连接的发送器发送消息,让发送器了解网络接收器的状态。Web 接收器应用可以使用 CastReceiverContext
上的 sendCustomMessage(namespace, senderId, message)
发送消息。网络接收器可以将消息发送给单个发送者,以响应收到的消息或由于应用状态更改。除了点对点消息传递(上限为 64kb)之外,网络接收器也可以向所有连接的发送器广播消息。
适用于音频设备的 Cast
如需了解对纯音频播放的支持,请参阅适用于音频设备的 Google Cast 指南。
Android TV
本部分介绍了 Google Web 接收器如何使用您的输入源进行播放,以及如何与 Android TV 兼容。
将您的应用与遥控器集成
如媒体播放消息中所述,在 Android TV 设备上运行的 Google Web 接收器会将设备的控制输入(即手持遥控器)的输入转换为为 urn:x-cast:com.google.cast.media
命名空间定义的媒体播放消息。您的应用必须支持这些消息才能控制应用媒体播放,以允许通过 Android TV 的控制输入实现基本的播放控制。
Android TV 兼容性指南
为了确保您的应用与 Android TV 兼容,您需要避免以下建议和常见误区:
- 请注意,用户代理字符串同时包含“Android”和“CrKey”;有些网站可能会重定向到仅限移动设备的网站,因为它们检测到“Android”标签。不要假设用户代理字符串中的“Android”始终表示移动设备用户。
- Android 的媒体堆栈可能会使用透明的 GZIP 提取数据。请确保您的媒体数据可以响应
Accept-Encoding: gzip
。 - Android TV HTML5 媒体事件的触发时间可能与 Chromecast 不同,这可能会导致 Chromecast 上隐藏的问题。
- 更新媒体时,请使用由
<audio>/<video>
元素(如timeupdate
、pause
和waiting
)触发的媒体相关事件。避免使用progress
、suspend
和stalled
等网络相关事件,因为这些事件往往依赖于平台。如需详细了解如何在接收器中处理媒体事件,请参阅媒体事件。 - 在配置接收方网站的 HTTPS 证书时,请务必包含中级 CA 证书。请参阅 Qualsys SSL 测试页面以验证:如果您网站的可信认证路径包含标记为“额外下载”的 CA 证书,则该证书可能无法在 Android 平台上加载。
- 虽然 Chromecast 会在 720p 图形平面上显示接收器页面,但包括 Android TV 在内的其他投射平台可以最高显示 1080p 的页面。确保接收器页面在不同分辨率下都能正常缩放。