YouTube Live Streaming API 概览

利用 YouTube Live Streaming API,您可以在 YouTube 上创建、更新和管理直播活动。使用此 API,您可以安排活动(直播)时间,并将其与代表实际直播内容的视频流关联在一起。

Live Streaming API 实际上由 YouTube Data API 和 YouTube Content ID API 的组件组成。Google Data API 可让 YouTube 用户管理自己的 YouTube 帐号,而 YouTube Content ID API 则可让 YouTube 的权利管理系统进行互动。但是,Live Streaming API 的所有资源都仅用于创建和管理直播活动。

本文档的适用对象是想要编写应用程序以方便在 YouTube 上进行直播的开发者。介绍了 YouTube 的基本概念和 API 本身。还简要介绍了该 API 支持的各种功能。

核心概念

广播
广播表示可在 YouTube 上观看的事件。系统还可以将直播内容录制并保存为 YouTube 视频,以便用户可以在直播结束后观看。
溪流
视频流用于标识传送给 YouTube 的音频和视频内容。每个直播都与一个视频流相关联。
广告插入点
广告插入点表示可以插入到直播中的广告插播时间点。

API 用例

下面列出了在应用中使用 API 的几种方法:

  • 安排直播时间并定义直播设置。您的应用可以让用户预定义直播设置,然后选择要应用于特定直播的设置。

  • 关联视频流和广播。

  • 让广播方同时定义广播及其视频的相关信息(使用 YouTube Data API)。

  • 简化广播状态(testinglive 等)之间的转换,并允许用户插入广告插入点。

前期准备

  1. 您需要有 Google 帐号才能访问Google API Console、请求 API 密钥以及注册应用。

  2. 通过 Google 注册您的应用以提交 API 请求。

  3. 注册应用后,选择 YouTube Data API 作为应用使用的一项服务:

    1. 转到 API Console,然后选择您刚刚注册的项目。
    2. 访问“已启用的 API”页面。 在 API 列表中,确保 YouTube Data API v3 和 YouTube Content ID API(如果您是 YouTube 内容合作伙伴)的状态为开启

  4. 熟悉 JSON(JavaScript 对象表示法)数据格式的核心概念。JSON 是一种与语言无关的常见数据格式,可提供任意数据结构的简单文本表示形式。如需了解详情,请参阅 json.org

为 API 请求授权

如上所述,Live Streaming API 使用的功能在技术上是 YouTube Data API 或 YouTube Content ID API 的一部分。您可以使用 Content ID API 向 YouTube 提供您的资产的元数据、所有权信息和政策信息。(直播视频直播就是一项资产。)您还可以通过该 API 声明视频版权并为视频设置广告政策。

本部分介绍了对 Content ID API 的请求的授权要求,这些授权要求不同于授权其他 Live Streaming API 请求的要求。

正在调用 Data API
该 API 请求必须获得要播放的 YouTube 频道的 Google 帐号的授权。
正在调用 Content ID API
API 请求必须由与拥有广播 YouTube 频道的内容所有者相关联的 Google 帐号授权。

资源和资源类型

资源是具有唯一标识符的单个数据实体。下表介绍了您将使用 Live Streaming API 进行交互的不同类型的资源。从技术上讲,所有这些资源实际上都被定义为 YouTube Data APIYouTube Content ID API 的一部分。但是,liveBroadcastliveStreamcuepoint 资源仅用于创建和管理直播活动。

资源
liveBroadcast 包含你正在 YouTube 上播放的活动的相关信息。liveBroadcast 资源是 YouTube 视频资源的扩展,可设置与直播但与其他 YouTube 视频无关的视频元数据。

因此,一个 liveBroadcast 资源恰好对应一个 YouTube 视频资源。 实际上,liveBroadcast 资源和 video 资源具有相同的 ID。在使用 Live Streaming API 创建直播后,您可以使用 YouTube Data API 提供有关视频的其他元数据。
liveStream 包含您要传输到 YouTube 的视频流的相关信息。视频流提供了向 YouTube 用户播放的内容。创建后,一个 liveStream 资源只能绑定到一个 liveBroadcast 资源。(同样,liveBroadcast 资源只能绑定到一个 liveStream 资源。
cuepoint 在直播视频流中插入可能会触发广告插播时间点的广告插入点。使用 liveBroadcasts.cuepoint 方法在广播期间插入广告插入点。
video 表示单个 YouTube 视频。如上所述,liveBroadcast 资源是 video 资源的扩展。您可以使用 YouTube Data API 更新视频的相关元数据,例如录制位置或可观看直播的地区。
videoAdvertisingOptions 定义视频(或广播)的广告设置。您可以使用 YouTube Content ID API 设置广告选项。
asset 表示知识产权,例如电影或节目的某一集。在本例中,广播视频就是资产。您将使用 YouTube Content ID API 创建和管理 asset 资源。
claim 将视频与视频匹配的资产关联起来。您需要使用 YouTube Content ID API 创建版权主张,以表明自己为直播视频的所有者。
policy 定义规则,指定在哪些情况下您的内容可在 YouTube 上观看,或在哪些情况下禁止在 YouTube 上显示。你需要对广播视频应用政策,还可以指定 YouTube 对匹配你的广播视频的用户上传视频应用的政策。

支持的操作

下表显示了该 API 支持的不同方法:

运维
list 检索 (GET) 包含零个或多个资源的列表。
insert 创建 (POST) 新资源。
update 修改现有资源 (PUT) 以反映您的请求中的数据。
bind liveBroadcast 资源与 liveStream 资源相关联或移除此类链接。
transition 更改 liveBroadcast 资源的状态,并启动与新状态关联的所有进程。例如,当你将某个广播的状态转换为 testing 时,YouTube 会开始向该广播的监控流传输视频。
delete 移除 (DELETE) 特定资源。

下表列出了不同类型的资源支持的操作。插入、更新或删除资源的操作始终需要用户授权。在某些情况下,list 方法同时支持已获授权的请求和未经授权的请求,其中未经授权的请求只会检索公开数据,而已获授权的请求也可以检索仅限当前经过身份验证的用户查看的信息。

支持的操作
list insert update bind transition cuepoint delete
liveBroadcast
liveStream

部分资源

该 API 允许(实际上需要)检索部分资源,以便应用程序避免传输、解析和存储不需要的数据。此方法还可确保 API 更高效地使用网络、CPU 和内存资源。

对于检索或返回 YouTube Data API 资源的任何 API 请求,part 参数都是必需参数。该参数标识了 API 响应中应包含的一个或多个顶级(非嵌套)资源属性。例如,liveStream 资源包含以下部分:

  • snippet
  • cdn
  • status

所有这些部分都是包含嵌套属性的对象,您可以将这些对象视为 API 服务器可能会(或不可能)检索的元数据字段组。因此,part 参数要求您选择应用实际使用的资源组件。此要求有以下两个重要用途:

  • 它可以阻止 API 服务器花时间检索您的应用不使用的元数据字段,从而缩短延迟时间。
  • 它能减少(或消除)应用可能检索的不必要数据量,从而降低带宽使用量。

随着时间的推移,随着资源添加更多部分,这些优势只会增加,因为您的应用不会请求它不支持的新引入的属性。

技巧和最佳做法

声明你的内容的版权

如果您希望在直播期间展示广告,则需要在活动开始前声明直播视频的所有权。要声明内容版权,您必须是参与 Content ID 计划的 YouTube 内容合作伙伴

声明实时广播视频所有权的流程与声明视频所有权的流程不同。对实时视频提出版权主张时,您需要在视频实际存在之前创建版权主张。该 API 确实支持此功能,广播的生命周期文档介绍了可让您创建声明的 YouTube Content ID API 调用。

预览和测试您的内容

收到您的入站视频流后,YouTube 会在两个不同的出站视频流上播放该视频:

  • 通过监控视频流,您可以预览(和测试)视频广播。这是只有你本人可以访问的私享直播。只有启用了广播的监控流,才能将广播过渡到 testing 阶段。监控视频流不会显示广告插播时间点。

  • 广播流是面向观众的直播。您可以将广播的隐私状态设置为 publicprivateunlisted。(不公开的直播只有明确受邀观看的用户才能看到,而不公开的直播则只有知道观看链接的人才能看到)。

    您可以选择延迟流式传输视频流,以免与监控视频流同时运行。通过延迟广播流,您可以更精细地控制将广告插入点插入广播的时间。

    但是,延迟直播直播会导致直播演示者很难与观众互动。此外,延迟直播会增加观看者通过直播以外的来源发现活动关键详细信息的可能性。例如,如果您播出的体育赛事存在 60 秒的延迟,那么观看者可能会先通过其他实时新闻媒体了解该赛事的重要时刻,然后再真正在直播中看到这些时刻。

YouTube 建议你为直播启用监视流,以便测试你的内容。如果您想控制广告插入点的时间,而不是想要与观众互动或提供事件的实时报道,那么您应该根据自己的需要选择是否延迟直播。

在直播期间投放中贴片广告

在直播期间,您可以插入一个广告插入点,以指明广告插播时间点应尽快或在指定时间开始。广告插播时间点可让 YouTube 在直播期间投放中贴片广告。

广告插播时间点具有以下特征:

  1. 它具有预定义的时间长度,您可以使用 cuepoint 资源的 durationSecs 属性进行设置。广告插播结束后,观看者会返回到直播。

  2. 当广告插播时间点出现时,插入广告插入点后,只有当观看者正在观看广播时,广告才会在视频播放器中播放。当观看者刷新正在播放广播的页面时,或者访问者在插入广告插入点后开始观看广播时,广告不会投放。

以下步骤序列反映了在直播期间插入广告插播时间点的最佳实践:

设置时间偏移

插入广告插入点时,您可以指定应立即插入或在广播的特定点插入广告插入点。具体选项取决于视频的广播流是否出现延迟。

  • 如果您的广播流未延迟,您可以立即插入广告插入点,或使用 walltimeMs 属性让广告插播时间点在特定时间开始。

    • 若要立即开始广告插播,请调用 liveBroadcasts.cuepoint 方法。在请求正文的资源中,将 insertionOffsetTimeMs 属性的值设置为 0,或者不为该属性的值指定值,也不为 walltimeMs 属性指定值。

      重要提示:请注意,观看者不会立即看到生成的广告内容。用户可能需要等待大约 30 秒的时间,才能看到广告内容。在此期间,观看者仍然可以看到直播视频流,并且您需要观看直播视频流来确定广告内容实际显示的时间,而不是监控视频流的时间。

    • 若要在特定时间开始插播广告,请调用 liveBroadcasts.cuepoint 方法,并使用 walltimeMs 属性指定所需时间。属性值是一个整数,表示纪元时间戳。

  • 如果您的广播流出现延迟,那么您可以立即插入广告插入点(如上所述)、指定时钟时间(如上所述),还可以指定时间偏移值来确定广告插播何时开始。时间偏移量用于指定直播中观看者应看到广告的时间点。

    偏移量值是从广播的监控流的开头起算的,以毫秒为单位。请注意,如果您的广播包含一个测试阶段,监控流会在广播转换为 testing 状态时启动。否则,您的监控流会在广播转换为 live 状态时开始。

    插入广告插入点时,请将 cuepoint 资源的 insertionOffsetTimeMs 属性设置为所需的偏移量。

计算时间偏移值

如需检索偏移值,请针对正在播放监控流的播放器调用 YouTube Player API 的 getCurrentTime 函数。届时,使用检索到的值在广播流中插入广告插入点。

偏移量时间的可能值可按以下范围计算:

[(elapsed_time - broadcast_delay + Δ), (elapsed_time - Δ)]

当 YouTube 无法精确插入广告插入点时,Δ 是一个 5 秒的缓冲区,位于可能的时间偏移的开始和结束处。例如:

  • 直播有五分钟的测试阶段。
  • 直播视频流比监控视频流延迟 60 秒。
  • 广播方在广播转换为 live 状态四分钟后插入广告插入点。(系统显示直播视频流三分钟后)。

在这种情况下,偏移时间的可能范围为 [(485,000), (535,000)]

这些时间以毫秒为单位指定,并使用以下值计算得出:

  • elapsed_time=540000 - 调用 liveBroadcasts.cuepoint 方法时,监控流会运行 9 分钟(540 秒,540000 毫秒)。
  • broadcast_delay=60000 - 广播流延迟 60 秒(即 60000 毫秒)。
  • Δ=5000 - 无法可靠地插入广告插入点时的 5 秒缓冲区。

问题排查和错误处理

以下指南介绍了如何解决可能出现的具体问题。另请参阅错误文档,查看每种 API 方法可能返回的错误列表。

  • 当某个广播从一个状态转换为另一个状态时,在 YouTube 完成与该转换相关的操作期间,可能会暂时为其指定另一个状态。例如,如果您发送 liveBroadcasts.transition 请求以将广播状态从 ready 更改为 testing,YouTube 会将广播的状态设置为 testStarting,然后完成与状态更改相关联的操作。当所有这些操作都完成后,YouTube 会将直播的状态更新为 testing,从而表明转换已完成。

    如果广播卡在 testStartingliveStarting 状态,您需要调用 liveBroadcasts.delete 方法并删除广播。然后,创建新广播,将其绑定到您的直播,然后继续测试过程。

    liveBroadcasts.transition 方法的文档中所述,您应先确认绑定到广播的数据流的 status.streamStatus 属性的值为 active,然后再调用该方法。