YouTube Live Streaming API 概览

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

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

本文档适用于希望编写应用程序以在 YouTube 上进行现场直播的开发者。介绍了 YouTube 的基本概念和 API 本身。此外，它还概述了 API 支持的不同函数。

核心概念

广播
广播表示活动正在进行时，可在 YouTube 上观看。系统还可以录制直播并将其保存为 YouTube 视频，以便用户在直播后观看。
溪流
数据流用于标识向 YouTube 传送的音频/视频内容。每次广播都与一个视频流相关联。
广告插入点
广告插入点表示可插入到直播中的广告插播时间点。

API 用例

以下列表推荐了在应用中使用该 API 的几种方法：

  • 安排广播并定义广播设置。您的应用可以让用户预定义广播设置，然后选择要应用到特定广播的设置。

  • 关联视频流和广播。

  • 让直播方可以同时定义直播及其视频的相关信息（使用 YouTube Data API）。

  • 简化广播状态（例如 testing 或 live）之间的转换，并让用户能够插入广告插入点。

前期准备

  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. 熟悉 JavaScript 对象表示法 (JSON) 数据格式的核心概念。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 请求必须获得 Google 账号的授权，该 Google 账号必须与拥有播出的 YouTube 频道的内容所有者相关联。

资源和资源类型

资源是指具有唯一标识符的单个数据实体。下表介绍了 您可以使用 Live Streaming API.从技术层面来讲 实际上定义为 YouTube Data API 或 YouTube Content ID API。不过， liveBroadcast, liveStream和 cuepoint 项资源 仅用于创建和管理直播活动。

资源
liveBroadcast 包含你正在 YouTube 上播出的活动的相关信息。答 liveBroadcast 资源是对 YouTube 视频资源的扩展，用于设置视频 这些元数据与直播相关，但与其他 YouTube 视频无关。

因此，一个 liveBroadcast 资源恰好对应于一个 YouTube 视频资源。 事实上，liveBroadcast 资源和 video 资源共享 相同的 ID。使用 Live Streaming API 创建直播后，您可以使用 YouTube 数据 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 阶段。监控视频流不显示广告插播时间点。

  • 广播视频流是向观众显示的视频流。你可以将直播的隐私状态设置为 public、private 或 unlisted。（不公开的直播只有明确受邀观看的用户才能看到，而不公开的直播则会显示给知道观看链接的任何人）。

    您可以选择延迟直播视频流，使其不会与监控视频流同时运行。通过延迟直播视频流，您可以更精细地控制在直播中插入广告插入点的时间。

    但是，延迟直播会致使直播演示者难以与观看观众互动。此外，推迟直播可提高观看者从直播以外的其他来源中发现有关活动的关键详细信息的可能性。例如，如果您直播的体育赛事延迟 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 秒的缓冲时间。例如：

  • 广播的测试阶段为 5 分钟。
  • 直播视频流会在监控视频流之后出现 60 秒的延迟。
  • 广播方在广播过渡到 4 分钟后插入广告插入点 live 状态。（直播视频流显示后 3 分钟）。

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

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

  • elapsed_time=540000 - 监控流已运行九次 分钟（540 秒，540000 毫秒）。liveBroadcasts.cuepoint
  • broadcast_delay=60000 - 广播流延迟 60 秒（即 60000 毫秒）。
  • Δ=5000 - 无法可靠地插入广告插入点时的 5 秒缓冲区。

问题排查和错误处理

以下指南介绍了如何解决可能出现的具体问题。对于列表 有关每种 API 方法可能返回的错误的详细信息，请参阅 YouTube Live Streaming API - 错误。

  • 当某个直播从一种状态过渡到另一种状态时，当 YouTube 完成与此过渡相关的操作时，系统可能会暂时为其分配其他状态。例如，如果您发送 liveBroadcasts.transition 请求以将广播的状态从 ready 更改为 testing，则 YouTube 会将广播的状态设置为 testStarting，然后完成与状态更改相关的操作。完成所有上述操作后，YouTube 会将广播的状态更新为testing，从而表明转换已完成。

    如果广播因 testStarting 或 liveStarting 状态卡住，您需要调用 liveBroadcasts.delete 方法并删除该广播。然后创建新广播，将其绑定到您的直播视频流，并继续执行测试过程。

    如 liveBroadcasts.transition 方法的文档所述，您应在调用该方法之前，确认绑定到广播的数据流的 status.streamStatus 属性的值为 active。