构建自定义 Web 接收器

1. 概览

Google Cast 徽标

此 Codelab 会教您如何构建自定义网络接收器应用,以便在支持 Cast 的设备上播放内容。

什么是 Google Cast?

Google Cast 可让用户将移动设备上的内容投射到电视上。然后,用户可以使用移动设备或桌面设备上的 Chrome 浏览器作为遥控器,在电视上播放媒体。

借助 Google Cast SDK,您的应用可以控制支持 Google Cast 的设备(例如电视或音响系统)。Cast SDK 根据 Google Cast 设计核对清单为您提供了必要的界面组件。

Google Cast 设计核对清单用于在所有受支持的平台上实现简单、可预测的 Cast 用户体验。请点击此处了解详情。

构建目标

完成此 Codelab 后,您将拥有一个 HTML5 应用,该应用可充当您自己的自定义接收器,能够在支持 Cast 的设备上显示视频内容。

学习内容

  • 如何为接收器开发进行设置?
  • 基于 Cast 应用框架且支持 Cast 的接收器的基础知识。
  • 如何接收投射的视频。
  • 如何集成调试记录器。
  • 如何针对智能显示屏优化接收器

所需条件

  • 最新的 Google Chrome 浏览器。
  • node.js、npm、http-serverngrok 模块。
  • 一部具有互联网访问权限的 Google Cast 设备,例如 ChromecastAndroid TV
  • 一台带 HDMI 输入端口的电视或显示器。

体验

  • 您需要具备之前的网络开发知识。
  • 您还需要有观看电视的经验 :)

您打算如何使用本教程?

仅阅读教程内容 阅读并完成练习

您如何评价自己在构建 Web 应用方面的经验水平?

新手水平 中等水平 熟练水平

您如何评价自己在观看电视方面的经验水平?

新手水平 中等水平 熟练水平

2. 获取示例代码

您可以将所有示例代码下载到您的计算机…

然后解压下载的 zip 文件。

3. 在本地部署接收器

为了能够将接收器与 Cast 设备搭配使用,该接收器需要托管在支持 Cast 设备连接的地方。如果您已经有可以使用 https 的服务器,请跳过以下说明并记下此网址,因为下一部分需要用到该网址。

如果您没有现成可用的服务器,也无需担心。您可以安装 node.jshttp-serverngrok 节点模块。

npm install -g http-server
npm install -g ngrok

运行服务器

如果您使用的是 http-server,请转到您的控制台并执行以下操作:

cd app-start
http-server

然后,您应该会看到如下所示的内容:

Starting up http-server, serving ./
Available on:
  http://127.0.0.1:8080
  http://172.19.17.192:8080
Hit CTRL-C to stop the server

请注意所使用的本地端口,并在新终端中执行以下操作,以使用 ngrok 通过 HTTPS 公开本地接收器:

ngrok http 8080

这将设置连接到本地 HTTP 服务器的 ngrok 隧道,并分配一个全局可用的 HTTPS 安全端点,供您在下一步中使用 (https://116ec943.eu.ngrok.io):

ngrok by @inconshreveable                                                                                                                                                                                                                                     (Ctrl+C to quit)

Session Status         online
Version                2.2.4
Web Interface          http://127.0.0.1:8080
Forwarding             http://116ec943.eu.ngrok.io -> localhost:8080
Forwarding             https://116ec943.eu.ngrok.io -> localhost:8080

在此 Codelab 的学习期间,您应让 ngrokhttp-server 保持运行状态。您在本地所做的任何更改都会立即生效。

4. 在 Cast 开发者控制台中注册应用

您必须注册应用才能在 Chromecast 设备上运行自定义接收器(如本 Codelab 中所构建)。注册您的应用后,您将收到一个应用 ID,发送者应用必须使用该 ID 来执行 API 调用,例如启动接收器应用。

Google Cast SDK 开发者控制台的图片,其中突出显示了“添加新应用”按钮

点击“添加新应用”

“新建接收器应用”屏幕的图片,其中突出显示了“自定义接收器”选项

选择“自定义接收者”,这就是我们要构建的内容。

“新的自定义接收器”屏幕的图片,其中显示有人在“接收器应用网址”字段中输入的网址

输入新接收器的详细信息,请务必使用您最后使用的网址

记下分配给全新接收器的应用 ID

此外,您必须注册 Google Cast 设备,才能让该设备访问您的接收器应用,然后再发布。接收器应用发布后,便可供所有 Google Cast 设备使用。在此 Codelab 中,建议使用未发布的接收器应用。

Google Cast SDK 开发者控制台的图片,其中突出显示了“添加新设备”按钮

点击“添加新设备”

“添加 Cast 接收器设备”对话框的图片

输入 Cast 设备背面印刷的序列号,并为其指定一个描述性名称。访问 Google Cast SDK 开发者控制台时,您也可以通过在 Chrome 上投射屏幕来查找该序列号

接收器和设备可能需要 5-15 分钟才能进行测试。等待 5-15 分钟后,您必须重新启动 Cast 设备。

5. 运行示例应用

Google Chrome 徽标

在等待新的接收器应用准备好进行测试期间,让我们看看已完成的接收器应用是什么样的。我们要构建的接收器能够播放采用自适应比特率流式传输的媒体内容(我们将使用针对基于 HTTP 的动态自适应流式传输 (DASH) 编码的示例内容)。

在浏览器中,打开命令与控制 (CaC) 工具

命令与控制 (CaC) 工具的 Cast Connect & Logger Controls 标签页的图片

  1. 您应该会看到我们的 CaC 工具。
  2. 使用默认的“CC1AD845”示例接收器 ID,然后点击“设置应用 ID”按钮。
  3. 点击左上角的“投射”按钮,然后选择您的 Google Cast 设备。

命令和控制 (CaC) 工具的 Cast Connect 日志记录器控件标签页的图片,指示其已连接到接收方应用

  1. 转到顶部的“加载媒体”标签页。

命令与控制 (CaC) 工具的 'Load Media' 标签页的图片

  1. 点击“按内容加载”按钮可播放示例视频。
  2. 视频将开始在 Google Cast 设备上播放,显示使用默认接收器时接收器的基本功能。

6. 准备启动项目

我们需要在您下载的入门级应用中添加 Google Cast 支持。以下是我们将在此 Codelab 中使用的一些 Google Cast 术语:

  • 发送设备应用是指在移动设备或笔记本电脑上运行的应用;
  • 接收设备应用是指在 Google Cast 设备上运行的应用。

现在,您可以使用自己喜爱的文本编辑器,在入门级项目的基础上进行构建了:

  1. 从下载的示例代码中选择 文件夹图标app-start 目录。
  2. 打开 js/receiver.jsindex.html

请注意,在完成此 Codelab 的过程中,http-server 应该会获取您所做的更改。如果您发现它并未完成,请尝试终止并重启 http-server

应用设计

接收设备应用会初始化 Cast 会话,并一直保持运行,直到收到发送器的 LOAD 请求(即播放媒体内容的命令)。

该应用由一个在 index.html 中定义的主视图和一个名为 js/receiver.js 的 JavaScript 文件组成,该文件包含接收器正常运行的所有逻辑。

index.html

此 HTML 文件将包含接收方应用的界面。目前,该文件是空的,我们将在整个 Codelab 中向该文件添加内容。

接收器.js

此脚本将管理接收器应用的所有逻辑。它现在只是一个空文件,但我们在下一部分中只需几行代码即可将其转换为功能完善的 Cast 接收器。

7. 基本的 Cast 接收器

基本 Cast 接收器将在启动时初始化 Cast 会话。必须告诉所有已连接的发送器应用已成功启动接收器。此外,新的 SDK 已预先配置为可在开箱即用型处理自适应比特率流媒体(使用 DASH、HLS 和 Smooth Streaming)和普通 MP4 文件。我们来试试看。

初始化

将以下代码添加到标头中的 index.html

<head>
  ...

  <script src="//www.gstatic.com/cast/sdk/libs/caf_receiver/v3/cast_receiver_framework.js"></script>
</head>

footer> 加载 receiver.js, 之前,将以下代码添加到 index.html <body> 中,以便为接收器 SDK 留出空间,以便调出您刚刚添加的脚本附带的默认接收器界面。

<cast-media-player></cast-media-player>

现在,我们需要在 js/receiver.js 中初始化 SDK,其中包括:

  • 获取对 CastReceiverContext(整个接收器 SDK 的主要入口点)的引用
  • 存储对 PlayerManager 的引用、处理播放的对象以及为您提供插入自己的自定义逻辑所需的所有钩子
  • 通过对 CastReceiverContext 调用 start() 来初始化 SDK

将以下代码添加到 js/receiver.js 中。

const context = cast.framework.CastReceiverContext.getInstance();
const playerManager = context.getPlayerManager();

context.start();

8. 投射“基本”视频内容

在此 Codelab 中,请使用 CaC 工具试用全新的接收器。

将网络浏览器指向命令与控制 (CaC) 工具

命令与控制 (CaC) 工具的 Cast Connect & Logger Controls 标签页的图片

请务必替换您之前在此字段注册的应用 ID,然后点击“设置应用 ID”。这会指示该工具在启动 Cast 会话时使用接收器。

投射媒体

大体上讲,如需在 Cast 设备上播放媒体,需要满足以下条件:

  1. 发送者从 Cast SDK 创建一个为媒体项建模的 MediaInfo JSON 对象。
  2. 发送者连接到 Cast 设备,以启动接收者应用。
  3. 接收器通过 LOAD 请求加载 MediaInfo 对象以播放内容。
  4. 接收器会监控和跟踪媒体状态。
  5. 发送者向接收者发送播放命令,以便根据用户与发送者应用的互动来控制播放。

在第一次基本尝试中,我们将使用可播放的资源网址(存储在 MediaInfo.contentUrl 中)填充 MediaInfo

真实的发送者使用 MediaInfo.contentId 中的应用专用的媒体标识符。接收器使用 contentId 作为标识符,以执行适当的后端 API 调用来解析实际的素材资源网址并将其设置为 MediaInfo.contentUrl.。此外,接收器还将处理一些任务,例如获取 DRM 许可或注入广告插播时间点信息。

我们将在下一部分对接收器进行扩展,使其执行类似的操作。目前,请点击“投射”图标,然后选择您的设备以打开接收器。

命令和控制 (CaC) 工具的 Cast Connect 日志记录器控件标签页的图片,指示其已连接到接收方应用

转到“加载媒体”标签页,然后点击“按内容加载”按钮。您的接收器应开始播放示例内容。

命令与控制 (CaC) 工具的 &#39;Load Media&#39; 标签页的图片

因此,接收器 SDK 开箱即可处理:

  • 初始化 Cast 会话
  • 处理来自包含可播放素材资源的发送者的 LOAD 请求
  • 提供可在大屏幕上显示的基本播放器界面。

在进入下一部分之前,您可以随意探索 CaC 工具及其代码。在下一部分,我们将扩展接收器,与简单的示例 API 通信,以满足来自发送者的传入 LOAD 请求。

9. 与外部 API 集成

与大多数开发者在真实应用中与其 Cast 接收器交互的方式一致,我们将修改接收器,以便通过 API 密钥(而不是通过可播放的素材资源网址)引用预期媒体内容的 LOAD 请求。

应用通常会执行此操作,原因如下:

  • 发件人可能不知道内容网址。
  • Cast 应用旨在直接在接收器上处理身份验证、其他业务逻辑或 API 调用。

此功能主要在 PlayerManager setMessageInterceptor() 方法中实现。这样,您就可以按类型拦截传入的消息,并在到达 SDK 的内部消息处理程序之前对其进行修改。在本部分中,我们将处理 LOAD 请求,在此过程中,我们将执行以下操作:

  • 读取传入的 LOAD 请求及其自定义 contentId
  • 对我们的 API 发出 GET 调用,以通过其 contentId 查找可流式传输的资源。
  • 使用数据流的网址修改 LOAD 请求。
  • 修改 MediaInformation 对象以设置流类型参数。
  • 将请求传递给 SDK 进行播放,或者在我们无法查找请求的媒体时拒绝该命令。

提供的示例 API 展示了用于自定义常见接收器任务的 SDK 钩子,同时仍然主要依赖于开箱即用的体验。

API 示例

让浏览器指向 https://storage.googleapis.com/cpe-sample-media/content.json,并查看我们的示例视频目录。内容包括 png 格式的海报图片的网址,以及 DASH 和 HLS 视频流的网址。DASH 和 HLS 流指向分块 mp4 容器中存储的多路分配视频和音频源。

{
  "bbb": {
    "author": "The Blender Project",
    "description": "Grumpy Bunny is grumpy",
    "poster": "https://[...]/[...]/BigBuckBunny/images/screenshot1.png",
    "stream": {
      "dash": "https://[...]/[...]/BigBuckBunny/BigBuckBunny_master.mpd",
      "hls": "https://[...]/[...]/BigBuckBunny/BigBuckBunny_master.m3u8",
    "title": "Big Buck Bunny"
  },
  "fbb_ad": {
    "author": "Google Inc.",
    "description": "Introducing Chromecast. The easiest way to enjoy [...]",
    "poster": "https://[...]/[...]/ForBiggerBlazes/images/screenshot8.png",
    "stream": {
      "dash": "https://[...]/[...]/ForBiggerBlazes/ForBiggerBlazes.mpd",
      "hls": "https://[...]/[...]/ForBiggerBlazes/ForBiggerBlazes.m3u8",
    "title": "For Bigger Blazes"
  },

  [...]

}

在下一步中,我们将在使用 LOAD 请求调用接收器后将每个条目的键(例如,bbb, fbb_ad)映射到数据流的网址。

拦截 LOAD 请求

在此步骤中,我们将创建一个加载拦截器,其中包含一个向托管 JSON 文件发出 XHR 请求的函数。获取 JSON 文件后,我们将解析内容并设置元数据。在以下部分中,我们将自定义 MediaInformation 参数以指定内容类型。

将以下代码添加到 js/receiver.js 文件中,紧接着在调用 context.start() 时添加。

function makeRequest (method, url) {
  return new Promise(function (resolve, reject) {
    let xhr = new XMLHttpRequest();
    xhr.open(method, url);
    xhr.onload = function () {
      if (this.status >= 200 && this.status < 300) {
        resolve(JSON.parse(xhr.response));
      } else {
        reject({
          status: this.status,
          statusText: xhr.statusText
        });
      }
    };
    xhr.onerror = function () {
      reject({
        status: this.status,
        statusText: xhr.statusText
      });
    };
    xhr.send();
  });
}

playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.LOAD,
    request => {
      return new Promise((resolve, reject) => {
        // Fetch content repository by requested contentId
        makeRequest('GET', 'https://storage.googleapis.com/cpe-sample-media/content.json').then(function (data) {
          let item = data[request.media.contentId];
          if(!item) {
            // Content could not be found in repository
            reject();
          } else {
            // Add metadata
            let metadata = new
               cast.framework.messages.GenericMediaMetadata();
            metadata.title = item.title;
            metadata.subtitle = item.author;

            request.media.metadata = metadata;

            // Resolve request
            resolve(request);
          }
        });
      });
    });

下一部分将介绍如何为 DASH 内容配置加载请求的 media 属性。

使用示例 API DASH 内容

现在,我们已准备好负载拦截器,并向接收器指定内容类型。此信息将为接收者提供主播放列表网址和视频流 MIME 类型。将以下代码添加到 LOAD 拦截器的 Promise() 中的 js/receiver.js 文件:

...
playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.LOAD,
    request => {
      return new Promise((resolve, reject) => {
          ...
          } else {
            // Adjusting request to make requested content playable
            request.media.contentUrl = item.stream.dash;
            request.media.contentType = 'application/dash+xml';
            ...
          }
        });
      });
    });

完成此步骤后,您可以继续测试并尝试加载 DASH 内容。如果您想使用 HLS 内容测试加载,请查看下一步。

使用示例 API HLS 内容

示例 API 包括 HLS 内容和 DASH。除了像上一步那样设置 contentType 之外,加载请求还需要一些额外的属性,才能使用示例 API 的 HLS 网址。当接收器配置为播放 HLS 视频流时,默认的默认容器类型为传输流 (TS)。因此,如果只有 contentUrl 属性被修改,接收器将尝试以 TS 格式打开示例 MP4 流。在加载请求中,应使用其他属性修改 MediaInformation 对象,以便接收方知道内容的类型为 MP4,而非 TS。将以下代码添加到加载拦截器中的 js/receiver.js 文件以修改 contentUrlcontentType 属性。此外,请添加 HlsSegmentFormatHlsVideoSegmentFormat 属性。

...
playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.LOAD,
    request => {
      return new Promise((resolve, reject) => {
          ...
          } else {
            // Adjusting request to make requested content playable
            request.media.contentUrl = item.stream.hls;
            request.media.contentType = 'application/x-mpegurl';
            request.media.hlsSegmentFormat = cast.framework.messages.HlsSegmentFormat.FMP4;
            request.media.hlsVideoSegmentFormat = cast.framework.messages.HlsVideoSegmentFormat.FMP4;
            ...
          }
        });
      });
    });

测试

再次打开 Command and Control (CaC) 工具,并将您的应用 ID 设置为接收器的应用 ID。使用“投射”按钮选择您的设备。

转到“加载媒体”标签页。这次删除“内容网址”字段中“按内容加载”按钮旁边的文字,这会强制应用发送仅包含对媒体的 contentId 引用的 LOAD 请求。

命令与控制 (CaC) 工具的 &#39;Load Media&#39; 标签页的图片

假定对接收器的修改一切正常,拦截器应负责将 MediaInfo 对象调整为 SDK 可在屏幕上播放的内容。

点击“按内容加载”按钮可查看您的媒体能否正常播放。您可以随意在 content.json 文件中将 Content ID 更改为其他 ID。

10. 针对智能显示屏进行优化

智能显示屏是具有触摸功能的设备,可让接收者应用支持触摸式控件。

本部分将介绍在智能显示屏上启动时如何接收接收器应用,以及如何自定义播放器控件。

访问界面控件

可以使用 cast.framework.ui.Controls.GetInstance() 访问智能显示屏的界面控件对象。将以下代码添加到 js/receiver.js 文件中的 context.start() 上方:

...

// Optimizing for smart displays
const touchControls = cast.framework.ui.Controls.getInstance();

context.start();

如果您不使用 <cast-media-player> 元素,则需要在 CastReceiverOptions 中设置 touchScreenOptimizedApp。在此 Codelab 中,我们使用的是 <cast-media-player> 元素。

context.start({ touchScreenOptimizedApp: true });

默认控件按钮基于 MetadataTypeMediaStatus.supportedMediaCommands 分配给每个槽。

视频控件

对于 MetadataType.MOVIEMetadataType.TV_SHOWMetadataType.GENERIC,智能显示屏的界面控件对象将如以下示例所示。

播放视频的界面控件叠加在顶部

  1. --playback-logo-image
  2. MediaMetadata.subtitle
  3. MediaMetadata.title
  4. MediaStatus.currentTime
  5. MediaInformation.duration
  6. ControlsSlot.SLOT_SECONDARY_1ControlsButton.QUEUE_PREV
  7. ControlsSlot.SLOT_PRIMARY_1ControlsButton.SEEK_BACKWARD_30
  8. PLAY/PAUSE
  9. ControlsSlot.SLOT_PRIMARY_2ControlsButton.SEEK_FORWARD_30
  10. ControlsSlot.SLOT_SECONDARY_2ControlsButton.QUEUE_NEXT

音频控制

对于 MetadataType.MUSIC_TRACK,智能显示屏的界面控件对象将如下所示:

图片音乐播放,界面控件叠加在顶部

  1. --playback-logo-image
  2. MusicTrackMediaMetadata.albumName
  3. MusicTrackMediaMetadata.title
  4. MusicTrackMediaMetadata.albumArtist
  5. MusicTrackMediaMetadata.images[0]
  6. MediaStatus.currentTime
  7. MediaInformation.duration
  8. ControlsSlot.SLOT_SECONDARY_1ControlsButton.NO_BUTTON
  9. ControlsSlot.SLOT_PRIMARY_1ControlsButton.QUEUE_PREV
  10. PLAY/PAUSE
  11. ControlsSlot.SLOT_PRIMARY_2ControlsButton.QUEUE_NEXT
  12. ControlsSlot.SLOT_SECONDARY_2ControlsButton.NO_BUTTON

更新支持的媒体命令

界面控件对象还会根据 MediaStatus.supportedMediaCommands 确定是否显示 ControlsButton

supportedMediaCommands 的值等于 ALL_BASIC_MEDIA 时,默认控件布局将显示如下:

媒体播放器控件的图片:进度条、“播放”按钮、“快进”和“跳过”按钮

supportedMediaCommands 的值等于 ALL_BASIC_MEDIA | QUEUE_PREV | QUEUE_NEXT 时,默认控件布局将显示如下:

媒体播放器控件的图片:进度条、“播放”按钮、“快进”和“跳过”按钮,以及“将上一个播放曲目加入播放队列”和“将下一个播放队列排入队列”按钮

当 supportedMediaCommands 的值等于 PAUSE | QUEUE_PREV | QUEUE_NEXT 时,默认控件布局将显示如下:

媒体播放器控件的图片:进度条、“播放”按钮、“将上一个播放队列”和“将播放队列排入队列”按钮已启用

如有可用的字幕轨道,字幕按钮将始终显示在 SLOT_1 处。

媒体播放器控件的图片:进度条、“播放”按钮、“快进”和“跳过”按钮、“将上一个播放队列加入队列”,以及“接下来播放的字幕”按钮和启用的“静音”按钮

如需在启动接收器上下文后动态更改 supportedMediaCommands 的值,您可以调用 PlayerManager.setSupportedMediaCommands 以替换该值。此外,您也可以使用 addSupportedMediaCommands 添加新命令,或使用 removeSupportedMediaCommands 移除现有命令。

自定义控制按钮

您可以使用 PlayerDataBinder 来自定义控件。将以下代码添加到 js/receiver.js 文件中的 TouchControls 下方,以设置控件的第一个插槽:

...

// Optimizing for smart displays
const touchControls = cast.framework.ui.Controls.getInstance();
const playerData = new cast.framework.ui.PlayerData();
const playerDataBinder = new cast.framework.ui.PlayerDataBinder(playerData);

playerDataBinder.addEventListener(
  cast.framework.ui.PlayerDataEventType.MEDIA_CHANGED,
  (e) => {
    if (!e.value) return;

    // Clear default buttons and re-assign
    touchControls.clearDefaultSlotAssignments();
    touchControls.assignButton(
      cast.framework.ui.ControlsSlot.SLOT_PRIMARY_1,
      cast.framework.ui.ControlsButton.SEEK_BACKWARD_30
    );
  });

context.start();

11. 在智能显示屏上实现媒体浏览

媒体浏览是一项 CAF 接收器功能,可让用户在触摸设备上浏览更多内容。为了实现此目标,您将使用 PlayerDataBinder 设置 BrowseContent 界面。然后,您可以根据要显示的内容,使用 BrowseItems 进行填充。

浏览内容

以下是 BrowseContent 界面及其属性的示例:

显示两个视频缩略图和三分之一部分的浏览内容界面的图片

  1. BrowseContent.title
  2. BrowseContent.items

宽高比

使用 targetAspectRatio property 为图片素材资源选择最佳宽高比。CAF 接收器 SDK 支持三种宽高比:SQUARE_1_TO_1PORTRAIT_2_TO_3LANDSCAPE_16_TO_9

浏览项

使用 BrowseItem 显示每项内容的标题、副标题、持续时间和图片:

显示两个视频缩略图和三分之一部分的浏览内容界面的图片

  1. BrowseItem.image
  2. BrowseItem.duration
  3. BrowseItem.title
  4. BrowseItem.subtitle

设置媒体浏览数据

您可以通过调用 setBrowseContent 提供要浏览的媒体内容列表。将以下代码添加到 js/receiver.js 文件中的 playerDataBinder 下和 MEDIA_CHANGED 事件监听器中,以使用“接下来播放”标题设置浏览项。

// Optimizing for smart displays
const touchControls = cast.framework.ui.Controls.getInstance();
const playerData = new cast.framework.ui.PlayerData();
const playerDataBinder = new cast.framework.ui.PlayerDataBinder(playerData);

...

let browseItems = getBrowseItems();

function getBrowseItems() {
  let browseItems = [];
  makeRequest('GET', 'https://storage.googleapis.com/cpe-sample-media/content.json')
  .then(function (data) {
    for (let key in data) {
      let item = new cast.framework.ui.BrowseItem();
      item.entity = key;
      item.title = data[key].title;
      item.subtitle = data[key].description;
      item.image = new cast.framework.messages.Image(data[key].poster);
      item.imageType = cast.framework.ui.BrowseImageType.MOVIE;
      browseItems.push(item);
    }
  });
  return browseItems;
}

let browseContent = new cast.framework.ui.BrowseContent();
browseContent.title = 'Up Next';
browseContent.items = browseItems;
browseContent.targetAspectRatio = cast.framework.ui.BrowseImageAspectRatio.LANDSCAPE_16_TO_9;

playerDataBinder.addEventListener(
  cast.framework.ui.PlayerDataEventType.MEDIA_CHANGED,
  (e) => {
    if (!e.value) return;

    ....

    // Media browse
    touchControls.setBrowseContent(browseContent);
  });

点击媒体浏览项会触发 LOAD 拦截器。将以下代码添加到 LOAD 拦截器,以将 request.media.contentId 映射到媒体浏览项中的 request.media.entity

playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.LOAD,
    request => {
      ...

      // Map contentId to entity
      if (request.media && request.media.entity) {
        request.media.contentId = request.media.entity;
      }

      return new Promise((resolve, reject) => {
            ...
        });
    });

您还可以将 BrowseContent 对象设置为 null,以移除媒体浏览界面。

12. 调试接收器应用

Cast 接收器 SDK 为开发者提供了另一种选择,即使用 CastDebugLogger API 和配套的命令与控制 (CaC) 工具来捕获日志,从而轻松调试接收器应用。

初始化

如需添加 API,请在 index.html 文件中添加 CastDebugLogger 源脚本。应在 Cast 接收器 SDK 声明后的 <head> 标记中声明来源。

<head>
  ...
  <script src="//www.gstatic.com/cast/sdk/libs/caf_receiver/v3/cast_receiver_framework.js"></script>
  <!-- Cast Debug Logger -->
  <script src="//www.gstatic.com/cast/sdk/libs/devtools/debug_layer/caf_receiver_logger.js"></script>
</head>

js/receiver.js 中文件顶部的 playerManager 下方,添加以下代码以检索 CastDebugLogger 实例并启用日志记录器:

const context = cast.framework.CastReceiverContext.getInstance();
const playerManager = context.getPlayerManager();

// Debug Logger
const castDebugLogger = cast.debug.CastDebugLogger.getInstance();
const LOG_TAG = 'MyAPP.LOG';

// Enable debug logger and show a 'DEBUG MODE' overlay at top left corner.
context.addEventListener(cast.framework.system.EventType.READY, () => {
  if (!castDebugLogger.debugOverlayElement_) {
      castDebugLogger.setEnabled(true);
  }
});

启用调试日志记录器后,接收器上会显示显示 DEBUG MODE 的叠加层。

以“调试模式”播放视频的视频的图片,在框架左上角以红色背景显示

记录播放器事件

使用 CastDebugLogger,您可以轻松记录由 CAF 接收器 SDK 触发的播放器事件,并使用不同的日志记录器级别来记录事件数据。loggerLevelByEvents 配置使用 cast.framework.events.EventTypecast.framework.events.category 来指定将记录哪些事件。

castDebugLogger 声明下方添加以下代码,以记录何时触发播放器 CORE 事件或广播 mediaStatus 更改:

// Debug Logger
const castDebugLogger = cast.debug.CastDebugLogger.getInstance();

// Enable debug logger and show a 'DEBUG MODE' overlay at top left corner.
context.addEventListener(cast.framework.system.EventType.READY, () => {
  if (!castDebugLogger.debugOverlayElement_) {
      castDebugLogger.setEnabled(true);
  }
});

// Set verbosity level for Core events.
castDebugLogger.loggerLevelByEvents = {
  'cast.framework.events.category.CORE': cast.framework.LoggerLevel.INFO,
  'cast.framework.events.EventType.MEDIA_STATUS': cast.framework.LoggerLevel.DEBUG
}

日志消息和自定义标记

借助 CastDebugLogger API,您可以创建不同颜色的日志消息显示在接收器的调试叠加层上。您可以使用以下日志方法(按优先级从高到低排序):

  • castDebugLogger.error(custom_tag, message);
  • castDebugLogger.warn(custom_tag, message);
  • castDebugLogger.info(custom_tag, message);
  • castDebugLogger.debug(custom_tag, message);

对于每种日志方法,第一个参数都是一个自定义标记。可以是任何您认为有意义的标识字符串。CastDebugLogger 使用标记来过滤日志。下面更详细地介绍了标记的用途。第二个参数是日志消息

要实际显示日志,请将日志添加到 LOAD 拦截器。

playerManager.setMessageInterceptor(
  cast.framework.messages.MessageType.LOAD,
  request => {
    castDebugLogger.info(LOG_TAG, 'Intercepting LOAD request');

    // Map contentId to entity
    if (request.media && request.media.entity) {
      request.media.contentId = request.media.entity;
    }

    return new Promise((resolve, reject) => {
      // Fetch content repository by requested contentId
      makeRequest('GET', 'https://storage.googleapis.com/cpe-sample-media/content.json')
        .then(function (data) {
          let item = data[request.media.contentId];
          if(!item) {
            // Content could not be found in repository
            castDebugLogger.error(LOG_TAG, 'Content not found');
            reject();
          } else {
            // Adjusting request to make requested content playable
            request.media.contentUrl = item.stream.dash;
            request.media.contentType = 'application/dash+xml';
            castDebugLogger.warn(LOG_TAG, 'Playable URL:', request.media.contentUrl);

            // Add metadata
            let metadata = new cast.framework.messages.MovieMediaMetadata();
            metadata.metadataType = cast.framework.messages.MetadataType.MOVIE;
            metadata.title = item.title;
            metadata.subtitle = item.author;

            request.media.metadata = metadata;

            // Resolve request
            resolve(request);
          }
      });
    });
  });

通过在 loggerLevelByTags 中为每个自定义标记设置日志级别,您可以控制在调试叠加层上显示哪些消息。例如,启用日志级别为 cast.framework.LoggerLevel.DEBUG 的自定义标记会显示所有已添加错误、警告、信息和调试日志消息的消息。启用 WARNING 级别的自定义标记只会显示错误并警告日志消息。

loggerLevelByTags 配置是可选的。如果未针对其日志记录器级别配置自定义标记,则所有日志消息都将显示在调试叠加层上。

CORE 事件日志记录器下方添加以下代码:

// Set verbosity level for Core events.
castDebugLogger.loggerLevelByEvents = {
  'cast.framework.events.category.CORE': cast.framework.LoggerLevel.INFO,
  'cast.framework.events.EventType.MEDIA_STATUS': cast.framework.LoggerLevel.DEBUG
}

// Set verbosity level for custom tags.
castDebugLogger.loggerLevelByTags = {
    [LOG_TAG]: cast.framework.LoggerLevel.DEBUG,
};

调试叠加层

Cast 调试日志记录器在接收器上提供调试叠加层,用于在投射设备上显示您的自定义日志消息。使用 showDebugLogs 可切换调试叠加层,使用 clearDebugLogs 可清除叠加层上的日志消息。

添加以下代码,以预览接收器上的调试叠加层。

context.addEventListener(cast.framework.system.EventType.READY, () => {
  if (!castDebugLogger.debugOverlayElement_) {
      // Enable debug logger and show a 'DEBUG MODE' overlay at top left corner.
      castDebugLogger.setEnabled(true);

      // Show debug overlay
      castDebugLogger.showDebugLogs(true);

      // Clear log messages on debug overlay
      castDebugLogger.clearDebugLogs();
  }
});

显示调试叠加层的图片,视频帧顶部的半透明背景上的调试日志消息列表

13. 恭喜

您现在已经知道如何使用 Cast Web Receiver SDK 创建自定义网络接收器应用了。

如需了解详情,请参阅网络接收器开发者指南。