直播

Cast SDK 包含用于支持实时内容的内置 API。其中包括 灵活的开箱即用界面 - 提供了丰富的 API 支持， 实时体验。Live API 支持显示 开始和结束时间、节目元数据、DVR 控件以及可查找的窗口。

本指南将演示如何配置直播 API 的直播，包括 用于配置核心直播场景的代码和元数据示例，以及 屏幕截图，演示每种场景。

警告 ：目前不允许使用 Live API Ad Breaks API 支持此功能。

前提条件

熟悉实现 在审核此内容之前，必须指定网络接收器 指南。此外，要运行代码示例，您还需要访问 符合某个 支持 Cast 的媒体类型。一般来说，“直播”功能 支持适用于 支持的媒体。

本指南中使用了以下术语：

• 可跳转窗口 - 用户可以在其中跳转的直播范围。
• 直播边缘 - 可供玩家观看的最新直播内容。
• 播放头 - 当前播放位置的界面时间戳。

投放直播

您可以通过以下两种方式配置 Web Receiver SDK 以使用 Live API 内容：

1. 在 Web Receiver 应用中使用 LOAD 消息拦截器。 （推荐）
2. 发送数据

拦截器提供 LoadRequestData 对象，其中包含有关加载请求的所有重要元数据。接收者 指示加载请求是针对直播视频流的，只需设置 streamType 在 mediaInformation 对象 StreamType.LIVE。 MediaInformation.duration 应为 -1，因为播放器实例为 当内容为 LIVE 时，负责计算该值。

/*
* This interceptor is called before your content is loaded by a Cast device
*/
playerManager.setMessageInterceptor(
   cast.framework.messages.MessageType.LOAD,
   request => { /* cast.framework.messages.LoadRequestData */
       request.media.streamType = cast.framework.messages.StreamType.LIVE;
   return request;
});

添加收视指南数据

直播，特别是电视频道等长时间播放的直播，能够 根据当前播放内容在屏幕上显示指南/节目元数据 位置。强烈建议内容提供方 在 Web Receiver 应用中对元数据进行编程，从而更好地帮助最终用户 体验

您可以在 LOAD 消息中为数据流配置初始指南数据 就像我们指示流是 上一个示例。直播中的单个版块或节目 表示为 MediaMetadata 这些对象随后会存储在 队列。 不同类型的节目有不同的 MediaMetadata 类，例如 TvShowMediaMetadata, MovieMediaMetadata, MusicTrackMediaMetadata, 等等

在以下代码段中，我们使用 MediaMetadata 对象来指定 每个节目的开始时间 UNIX 时间戳 sectionStartAbsoluteTime 属性。节目的时长以秒表示。

// The metadata for a single TV show
const currentShow = new cast.framework.messages.TvShowMediaMetadata();
currentShow.episode = 15;
currentShow.seriesTitle = 'The Odyssey';
currentShow.title = 'Scylla and Charybdis';
currentShow.sectionStartAbsoluteTime = toUnixTimestamp('9:00 PM');
currentShow.sectionDuration = HOUR_IN_SECONDS;

const previousShow = new ...;
const nextShow = new ...;

const containerMetadata = new cast.framework.messages.ContainerMetadata();
containerMetadata.title = 'My TV Channel';
containerMetadata.sections = [previousShow, currentShow, nextShow];

playerManager.getQueueManager().setContainerMetadata(containerMetadata);

实时可寻址范围

Cast SDK 包含界面元素和控件，用户可通过这些元素和控件 使用 展开的控制器 或触控设备上的触控操作。

通过 LiveSeekableRange 表示用户可在流中跳转的时间范围。在 Web 接收器，您可通过 PlayerManager.getLiveSeekableRange()、 该函数会返回 LiveSeekableRange 对象。对象需要注意的主要属性包括：

• start - 该范围相对于 （以秒为单位）。
• end - 玩家可以跳转到的最长时间（以秒为单位）， 基于可用片段（相对于视频流开头）进行投放。
• isMovingWindow - 布尔值，指示可查找范围 随音频流移动（即从清单中移除较旧的片段）， 对于所有直播活动，此属性应为 true。
• isLiveDone - 指示直播活动是否已 即表示不再生成新的细分。

可查找范围的大小，表示为 start 和 end取决于视频流中可用的片段数量， 随音频流而变化例如，如果在流开始时，可查找项 范围是 {start:0, end: 600, isMovingWindow: false, isLiveDone: false}，十 在音频流开始几秒钟后，其状态可能会变为 {start: 10, end: 610, isMovingWindow: true, isLiveDone: false}。请务必注意 可查找范围内的结束时间会根据 生成新的细分。因此，如果您的直播片段的典型长度 为 10 秒，则开始时间和结束时间大约每 10 秒更新一次，即 。

注意： 如果用户暂停直播的时间过长，导致播放头位于外面 或者如果完全停用跳转功能，则视频流 在直播的直播边缘重新开始播放。

停用跳转功能

若要在流内停用跳转功能，您需要移除跳转功能 ：

// disable seeking in the LOAD messageInterceptor
playerManager.removeSupportedMediaCommands(cast.framework.messages.Command.SEEK, true);

正在为 SEEK 向发送应用信号移除受支持的媒体命令 和触控显示来停用跳转功能，但不会停用此类语音指令 “Ok Google，快退 30 秒” 支持的语音媒体命令 指南。

直播框架活动

包含 LIVE_ENDED 和 LIVE_IS_MOVING_WINDOW_CHANGED 这两个事件 Live API系统会向这两个事件传递 LiveStatusEvent 对象，其中包含当前的可查找范围。

注意 ：您无法更新事件中的值。如需了解详情，请参阅 关于在 CAF 中处理事件的指南。

事件	说明
LIVE_ENDED	在直播结束时触发。此时，LiveSeekableRange 中的 end 值将停止更新；用户仍然可以查看直播可查找范围内的内容。
LIVE_IS_MOVING_WINDOW_CHANGED	当直播视频流的可寻址范围从固定窗口更改为移动窗口或移动窗口时，即会触发该事件。对于直播，如果播放器检测到清单正在移除较早的片段，就会出现这种情况。

直播场景

注意： 场景 1、7 和其中 8 种类型已获得官方支持。

实时流式传输有八种可能的场景，每种 通过设置三项核心设置进行配置：

• 直播有开始时间
• 直播有结束时间
• 用户可以在直播的可寻址窗口中跳转

如需了解如何配置，请参阅添加节目指南数据 这些值

以下是直播功能支持的场景的说明和屏幕截图 API。变量 T1 和 T2 用于表示 分别位于界面左侧和右侧

	开始时间	结束时间	可跳转	T1	T2
场景 1	否	否	否	游戏头	未显示
场景 2	否	否	是	播放头	未显示
场景 3	否	是	否	播放头	未显示
场景 4	否	是	是	播放头	未显示
场景 5	是	否	否	显示开始计时	播放头
场景 6	是	否	是	显示开始计时	播放头
场景 7	是	是	否	显示开始时间	显示结束时间
场景 8	是	是	是	显示开始时间	显示结束时间

注意 ：场景 3 和 4 不在官方支持范围内，但播放 。

场景一

开始时间	结束时间	可跳转	T1	T2
否	否	否	播放头部	未显示

场景一没有开始时间或结束时间，用户无法在 。当用户停止直播时，系统会改为从直播边缘继续播放 视频流暂停位置

场景 7

开始时间	结束时间	可跳转	T1	T2
是	是	否	游戏头	计划时长

场景 7 有开始时间和结束时间，但不可查找。两者 界面中的时间戳 T1 和 T2 表示当前进度条指针的时间和总时间 时长。如果用户暂停/恢复播放，视频流将 在视频流的直播边缘继续播放在上述示例中， 进度条表示自用户开始播放以来 观看。

场景八

开始时间	结束时间	可跳转	T1	T2
是	是	是	游戏头	计划时长

场景 7 包含开始时间和结束时间，并且是可寻址的。两个时间戳 T1 和 T2 代表当前的进度条指针时间和总节目 时长。如果用户暂停/恢复播放，流式传输将恢复 （如果广告位于可查找窗口内），则广告停止展示时， 进度条表示用户可以后退的位置，白色的区域 代表他们可以跳转到哪个位置

配置场景

将直播配置为特定现场场景的过程分为三个部分：

1. 设置直播类型 - 将直播标记为 实时流式传输。
2. 添加收视指南数据 - 设置开始时间 在 MediaMetadata 对象中设置和时长。
3. 配置跳转功能 - 启用或 停用跳转功能。

播放行为

暂停时，界面会继续更新其播放元数据 包括播放头部时间和实时边缘时间。恢复数据流后， 有一些需要注意的行为，这些行为因数据流配置而异。

可跳转的视频流

恢复可查找流时：

• 活动边缘应更新为活动位置和可寻址范围 进行相应的调整
• 如果进度条指针跳到当前节目之外，进度条会进行更新 包含新节目的元数据（包括开始时间和结束时间， ）。
• 如果可查找窗口的长度为“X”，可查找范围将扩展回 最多“X”或到节目开头（以较小者为准）。
• 如果用户暂停的时间足够长，导致当前时间不再处于 可查找窗口，则流会在最早的时间点（最左侧）继续播放 可查找窗口大小

跳转至 LiveSeekableRange.end 以便在取消暂停后在直播边缘继续播放。

let playerManager = cast.framework.CastReceiverContext.getInstance().getPlayerManager();
// Intercept the message to PLAY
playerManager.setMessageInterceptor(cast.framework.messages.MessageType.PLAY, (requestData) => {
  ...
  if (playerManager.getLiveSeekableRange()) {
    // Resume playback at the live edge
    playerManager.seek(playerManager.getLiveSeekableRange().end);
  } else {
    return requestData;
  }
  ...
});

不可跳转的数据流

恢复不可搜索的流时：

• 在这种情况下，播放将在实时边缘继续播放。
• 如果直播边缘超出当前节目，拖动条应 使用新节目的元数据（包括开始时间和结束时间）进行更新 时间（如果有）。

API Surface 变更和自定义 Live 界面

Cast SDK 本身就支持创建自定义界面，而不是 使用开箱即用的界面。但请务必遵循 在自定义 界面。

网络接收器

在网络接收器上， PlayerData 包含以下字段，以便开发者扩展其自定义 实时流式传输：

• isLive - 指示当前直播是否为直播的标记。 （而不是视频点播）。
• liveSeekableRange - 要在屏幕分界线上显示的可查找范围 DVR 窗口。
• mediaStartAbsoluteTime - 该版块以绝对时间开始播放的时间 （UNIX 纪元）。
• sectionStartTimeInMedia - 相对于 媒体开始时间。
• sectionDuration - 部分时长（以秒为单位）。

此外，请务必考虑 两个直播活动。

Android SDK

作为实时功能的一部分，在 UIMediaController 已被弃用，请改用 CastSeekBar。