直播

Cast SDK 包含用于支持直播内容的内置 API。其中包括灵活的开箱即用界面，以及可让开发者通过几行代码打造丰富实时体验的 API。Live API 支持显示开始时间和结束时间、节目元数据、DVR 控件和可查找的窗口。

本指南介绍了如何为 Live API 配置数据流（包括用于配置核心 Live 场景的代码和元数据示例），以及展示每个场景的屏幕截图。

警告：Ad Breaks API 目前不支持使用 Live API。

前提条件

在查看本指南之前，您必须熟悉实现 Web 接收器的基础知识。此外，若要运行代码示例，您需要访问符合受支持的 Cast 媒体类型之一的直播。一般而言，直播功能支持支持的媒体的典型直播配置。

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

• 可搜索窗口 - 用户可以在其中查找的直播视频的范围。
• 直播边缘 - 向玩家直播的最新内容。
• 播放头 - 当前播放位置的界面时间戳。

投射直播

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

1. 使用 LOAD 消息拦截器。（推荐）
2. 使用发送方或接收方生成的加载请求。

拦截器会提供 LoadRequestData 对象，其中包含有关加载请求的所有重要元数据。如需指明加载请求是针对直播的，只需将 mediaInformation 对象上的 streamType 设置为 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;
});

添加收视指南数据

直播（尤其是电视频道等长时间运行的流）能够根据直播中当前的播放位置显示屏幕导视/节目元数据。强烈建议 Content Provider 在其 Web 接收器应用中添加编程元数据，以便提升最终用户的体验。

您可以在 LOAD 消息拦截器中配置数据流的初始指南数据，就像我们在上一示例中指示该数据流是直播一样。直播中的各个版块或节目表示为 MediaMetadata 对象，然后这些对象存储在队列中。不同类型的程序（例如 TvShowMediaMetadata、MovieMediaMetadata、MusicTrackMediaMetadata 等）有不同的 MediaMetadata 类。

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

// 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 表示视频流中用户可以跳转到的时间范围。在网络接收器上，您可以通过 PlayerManager.getLiveSeekableRange() 访问有关可查找范围的信息，该方法会返回 LiveSeekableRange 对象。对象需要注意的主要属性包括：

• start - 相对于视频流开始时间的范围的开始时间（以秒为单位）。
• end - 相对于流开头，播放器可以根据可用片段跳转到的最大可能时间（以秒为单位）。
• isMovingWindow - 一个布尔值，用于指示可查找范围是否随信息流一起移动（即从清单中移除更早的片段），对于所有直播，此值应为 true。
• isLiveDone - 一个布尔值，指示直播是否已结束，即不生成任何新片段。

可搜索范围的大小（表示为 start 到 end 之间的时间）取决于流中可用的细分数量，并将随流一起移动。例如，如果在数据流的开头，可搜索范围是 {start:0, end: 600, isMovingWindow: false, isLiveDone: false}，数据流开始 10 秒后，它可以变为 {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 API 中包含两个事件：LIVE_ENDED 和 LIVE_IS_MOVING_WINDOW_CHANGED。系统会向这两个事件传递 LiveStatusEvent 对象，该对象包含当前的可查找范围。

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

活动	说明
LIVE_ENDED	在直播结束时触发。此时，LiveSeekableRange 中的 end 值将停止更新，但用户仍可以查看实际可查找范围内的内容。
LIVE_IS_MOVING_WINDOW_CHANGED	当直播的可搜索范围从固定窗口更改为移动窗口（或相反）时触发。对于直播，当播放器检测到清单正在移除较早的片段时，就会发生这种情况。

直播场景

注意：场景 1、7 和 8 已正式获得支持。

直播有 8 种可能的场景，每种场景都通过设置 3 项核心设置进行配置：

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

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

以下是 Live API 支持的场景的说明和屏幕截图。变量 T1 和 T2 分别用于表示界面左侧和右侧的时间戳。

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

注意：场景 3 和场景 4 不是正式支持，但可以播放。

场景 1

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

场景 1 没有开始或结束时间，并且用户无法在流中寻找。当用户停止在线播放时，播放将从现场边缘（而不是信息流暂停的位置）继续播放。

场景 7

开始时间	结束时间	可查找	T1	T2
是	是	否	播放头	计划时长

场景 7 具有开始时间和结束时间，但无法查找。界面中的两个时间戳（T1 和 T2）分别表示当前的进度条指针时间和总节目时长。如果用户暂停/继续播放，流会在该流的直播边缘继续播放。在上面的示例中，进度条的红色部分表示自用户开始观看以来视频流的部分。

场景 8

开始时间	结束时间	可查找	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 UI

Cast SDK 支持创建自定义界面，而无需使用开箱即用的界面。不过，在自定义接口时，请务必遵循 Cast 用户体验设计核对清单。

网络接收器

在 Web 接收器上，PlayerData 包含以下字段，供开发者扩展其用于直播的自定义接口：

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

此外，在自定义界面时，请务必考虑两个直播活动。

Android SDK

作为 Live 功能的一部分，在 UIMediaController 中使用 Android Seekbar 微件的功能已被弃用，请改用 CastSeekBar。