广播的生命周期

简介

本文档将为您介绍在 YouTube 上利用 YouTube Live Streaming API 和 YouTube Content ID API 创建和管理直播的整个生命周期。

资源和资源类型

如入门指南中所述，资源是具有唯一标识符的单个数据实体。要在 YouTube 上创建和管理直播活动，您需要使用多种不同类型的资源，这些资源是 YouTube Data API 或 YouTube Content ID API 的一部分。YouTube Live Streaming API 标题下列出的资源在技术上是这些其他 API 中定义的，但单独列出，因为它们仅用于直播。

YouTube Live Streaming API 资源

YouTube Data API 资源

YouTube Content ID API 资源

创建和管理直播

以下步骤介绍了如何在 YouTube 上创建和管理直播活动。 相关步骤分为以下几个阶段：

  1. 设置直播
  2. 声明您的内容
  3. 测试
  4. 广播
  5. 结束广播
  6. 创建引用

第 1 阶段：设置您的广播

第 1.1 步：创建广播

调用 liveBroadcasts.insert 方法，以将您的直播添加到 YouTube 的直播活动中。您要插入的 liveBroadcast 资源必须定义下列属性的值。

设置广播时，请考虑以下准则：

  • 如果您希望在直播时有一个测试阶段，那么，当您观看直播时，即使其他观看者也看不到广播，您必须将 contentDetails.monitorStream.enableMonitorStream 属性设置为 true，并将 contentDetails.enableAutoStart 属性设置为 false。这些是两个属性的默认值。

  • 如果要基于录制的广播创建引用，您必须将广播的 contentDetails.recordFromStart 属性设置为 true。如果要在录制结束后立即将录制的视频用于播放，您还必须将 contentDetails.enableDvr 属性设置为 true。（这两个媒体资源的默认值均为 true）。

  • 只要广播的状态为 created 或 ready，您就可以更新任何 contentDetails 属性。

  • 只要广播的状态为 created、ready 或 testing，您就可以更新广播的预定开始时间和预定结束时间。

  • 您可以随时更新广播的标题、说明、隐私状态，以及属于广播 video 资源的其他元数据字段。

    注意：如果您只想让特定 YouTube 用户观看您的视频，请根据需要将 status.privacyStatus 属性值设置为 unlisted 或 private。

处理 API 响应

当您调用 liveBroadcasts.insert 方法时，API 响应会包含您创建的 liveBroadcast 资源。您的代码应从该资源中提取和存储 id。您在日后的 API 请求中将需要使用该值来标识广播。（您还可以标识与使用同一 ID 的 liveBroadcast 资源对应的 video 资源。）

第 1.2 步：创建直播

liveStream 资源可让您将视频传输到 YouTube，同时也说明了您要传输的内容。每个广播必须正好与一个数据流相关联。

调用 liveStreams.insert 方法为活动创建视频流。创建数据流时，您必须为下面列出的属性设置值：

除了流标题之外，这些值在创建流之后无法更新。如果您需要更改流，则实际上需要通过重复此步骤创建不同的流。本文档后面第 3.5 步会更详细地介绍此过程。

您还可以选择为以下属性设置值：

  • snippet.description - 与流标题一样，流说明可以在创建流后更新。YouTube 用户无法看到标题和说明。

  • contentDetails.isReusable - 指示流是否可以重复使用，这意味着它可以绑定到多个广播。此属性的值可以有效地确定通道在 liveBroadcast 和 liveStream 资源之间是多对一还是一对一关系：

    • 如果您使用属性的默认值 true，则可以对频道的所有广播使用相同的 liveStream 资源。这意味着您无需为每个广播重复此步骤 (1.2)。您可以改为重复使用流 ID 以用于后续广播。
    • 如果您将属性值设置为 false，则需要为每个广播创建一个新的数据流。

发出数据流请求后，API 响应会包含您创建的 liveStream 资源。您的代码应从该资源中提取和存储 id。在今后的 API 请求中，您需要使用该值来标识数据流。

第 1.3 步：将广播绑定到相应视频流

创建 liveBroadcast 和 liveStream 资源后，您现在需要使用 liveBroadcasts.bind 方法将这两者关联起来。此操作会将您要向 YouTube 传输的视频位与相应视频的事件广播相关联。

在调用 liveBroadcasts.bind 方法时，将 id 参数设置为在第 1.1 步中获得的广播 ID，并将 streamId 参数设置为在第 1.2 步中获得的数据流 ID。

第 2 阶段：声明您的内容

如果您希望在直播期间展示广告，则需要在活动开始前对广播视频主张版权。以下步骤说明了此过程。请注意，在此阶段讨论的所有 API 调用均在 YouTube Content ID API 中定义。

第 2.1 步：创建素材资源

asset 资源代表一项知识产权。在本例中，资产是广播。调用 assets.insert 方法来创建资源。

API 响应将包含您创建的 asset 资源。您的代码应从该资源中提取和存储 id，因为您需要在未来的 API 请求中使用该值来标识资产。

第 2.2 步：定义您对资产的所有权

资产的所有权数据可标识资产的所有者及其拥有资产的地区。YouTube 使用这些数据来确定所有者可以在什么位置为已主张版权的视频设置政策。

例如，如果您有权在美国播放活动，而另一个广播方对加拿大拥有相同的权利，那么您就可以分别针对广播视频和与广播视频匹配的用户上传视频定义不同的政策。您的匹配政策将应用于美国匹配的用户上传视频，而另一所有者的政策则适用于加拿大的匹配视频。

如需定义资产的所有权地区，请调用 ownership.update 方法。在该请求中，将 assetId 参数设置为您在第 2 步中存储的 id。

第 2.3 步：设置资产的匹配政策

资产的匹配政策说明了当用户上传与资产相关联的参考文件时，YouTube 应采取的措施。在这种情况下，匹配政策将指示 YouTube 应如何处理与您的直播匹配的已上传的视频。

注意：如果您计划根据广播视频创建参考文件，并使用该参考文件来识别与广播匹配的用户上传视频，则应设置匹配政策。否则，您可以跳过此步骤。

如需设置匹配政策，您首先需要确定想要应用的政策。您可以通过调用 policies.list 方法检索现有政策的列表，也可以通过调用 policies.insert 方法定义新政策。无论是哪种情况，您都需要捕获要应用的政策的 id。

确定政策后，请调用 assetMatchPolicy.update 方法。在该请求中，将 assetId 参数设置为您在第 2 步中存储的 id。

第 2.4 步：声明视频版权

在这一步中，您将创建一个版权主张，以便将您要广播的视频关联到您在第 2 步中创建的资产。该版权主张会设置一项仅适用于您的广播视频的政策。（与您上传的视频相匹配的用户上传视频均在上一步设置的匹配政策覆盖范围内。）

如需创建版权主张，请调用 claims.insert 方法。在插入的 claim 资源中，您需要为以下属性设置值：

  • assetId - 您在第 2.1 步中获得此值。
  • videoId – 这是您在第 1 步获得的广播 ID。
  • policy - 这是一个 policy 资源。如需应用现有政策，请将该资源的 id 属性设置为现有政策的 ID。上一步介绍了如何检索现有政策的 ID。
  • contentType - 将此值设为 audiovisual。

处理 API 响应

插入声明时，API 响应将包含您创建的 claim 资源。您的代码应从该资源中提取和存储 id。稍后您将使用该值根据已处理的视频创建参考文件。

第 2.5 步：更新广播的广告设置

如果您希望在观看者开始观看您的直播时播放前贴片广告，或者在直播的间歇期投放广告，则需要为视频设置广告选项。

  • 如果您为广播启用了前贴片广告，则所有观看者都会在开始观看您的直播时看到一则广告，即使他们开始在直播期间开始观看也是如此。
  • 如果您为广播启用了中贴片广告，那么您将能够在广播期间插入广告插入点。

如需启用广告，请调用 videoAdvertisingOptions.update 方法。在请求中，将 videoId 参数设置为您在第 1.1 步中获取的广播 id。使用 videoAdvertisingOption 资源的 adFormats[] 属性来标识您要启用的广告格式（preroll、midroll 或 postroll）。

第 3 阶段：测试

在此阶段，您将嵌入一个用于显示广播的监控流的播放器，以便测试观看体验。监控视频流是一种私享视频流，可让您在 YouTube 观看者预览直播视频时进行预览。

请注意，只有在视频监控流已启用的情况下，您才能测试其。默认情况下，广播的监控流处于启用状态。在创建或更新该广播时，您可以通过将 contentDetails.monitorStream.enableMonitorStream 属性设置为 false 来停用广播的监控流。

第 3.1 步：嵌入显示器流播放器

使用 liveBroadcasts.list 方法检索广播，并提取 contentDetails.streamDetails.monitorStreamEmbedHtml 属性的值。该值包含嵌入 YouTube 播放器所需的 HTML，此播放器会显示您的监控流。

第 3.2 步：开始录制视频

开始在您的视频流中传输视频。

第 3.3 步：确认您的视频流已启用

调用 liveStreams.list 方法来检索与广播关联的 liveStream 资源。确认 status.streamStatus 属性的值为 active，这表示 YouTube 服务器从编码器正确接收数据。

第 3.4 步：将广播状态转换为测试

调用 liveBroadcasts.transition 方法以更新广播的状态。将 id 参数值设为第 1.1 步中获取的广播 ID，并将 broadcastStatus 参数值设为 testing。

调用 liveBroadcasts.transition 方法后，该转换可能需要几秒钟，甚至一分钟的时间才能完成。在此期间，您应轮询该 API 以检查广播状态。在转换完成之前，广播的状态为 testStarting。转换完成后，状态将为 testing。

第 3.5 步：完成测试

如果您的测试顺利进行，则可继续执行第 4 阶段。 不过，在某些情况下，您可能需要做进一步的测试。例如，如果您的测试显示视频流配置不正确，则您需要先纠正此问题，然后再继续广播。

如果视频流配置不正确，则您需要解除绑定（并删除）现有视频流，然后创建一个新的视频流。例如，如果视频流指定了错误的视频格式，则可能无法正确配置。

  1. 如需解除绑定视频流，请调用第 1.3 步中的 liveBroadcasts.bind 方法。在 API 请求中，将 id 参数设置为在第 1.1 步中获取的 id。请勿在请求中包含 streamId 参数。

  2. 如需删除视频流，请调用 liveStreams.delete 方法。在请求中，将 id 参数设置为在第 1.2 步中获取的 id。

  3. 重复第 1.2 步，创建配置正确的新 liveStream 资源。然后重复步骤 1.3，将新流绑定到您的广播，并重复第 3.1 至 3.3 步以测试新流。

第 3.6 步：启用 autoStart 和 autoStop 属性

成功完成测试阶段后，您可以选择在实际广播开始之前将广播的 contentDetails.enableAutoStart 和 contentDetails.enableAutoStop 属性设置为 true。不能在测试阶段之前将这些属性设置为 true，因为测试实际上会导致广播开始。

第 4 阶段：广播

在此阶段，您的观众可以看到您的广播视频。

第 4.1 步：开始录制视频

开始在您的视频流中传输视频。

第 4.2 步：确认您的视频流已启用

调用 liveStreams.list 方法来检索与广播关联的 liveStream 资源。确认 status.streamStatus 属性的值为 active，这表示 YouTube 服务器从编码器正确接收数据。

第 4.3 步：将直播状态转换为直播

重要提示：此步骤会向观众展示您的视频。

调用 liveBroadcasts.transition 方法以更新广播的状态。将 id 参数值设为第 1.1 步中获取的广播 ID，并将 broadcastStatus 参数值设为 live。

如果您将 liveBroadcast 资源的 contentDetails.enableAutoStart 属性设置为 true，则无需调用 liveBroadcasts.transition 方法。

进行此 API 调用后（或者，如果您已将 contentDetails.enableAutoStart 属性设置为 true），那么在开始流式传输后，您通常需要等待 5 到 10 秒，以完成过渡。过渡最多可能需要一分钟。在此期间，您应轮询该 API 以检查广播状态。在转换完成之前，广播的状态为 liveStarting。过渡完成后，状态将变为 live，从该时间点开始，观看者可以在您的监控信息流中观看您的广播。

请注意此命令的以下效果：

  • 如果您为广播启用了监控数据流（请参阅第 3.1 步），您将能够在嵌入式播放器中看到该监控数据流。
  • 如果您为广播的 contentDetails.streamDetails.broadcastStreamDelayMs 属性设置了值，则其他观看者可以看到的广播流将延迟一段时间。

第 4.4 步：在广告插播时间点插入广告插播时间点

调用 liveBroadcasts.cuepoint 方法可插入广告插入点。广告插入点可能会触发广告插播时间点。在请求正文中提供的 cuepoint 资源中，将 durationSecs 属性设置为您希望显示的广告插播时长（以秒为单位）。（默认值为 30。）

目前，YouTube 会尝试在视频播放器中播放广告，以供在插入广告插入点时观看广播的任何观看者观看。广告是否播放取决于多种因素，例如广告可用性和观看者的广告浏览记录。插播广告的观看者在广告插播结束后会回到您的广播，而没有看到广告的观看者会在广告插播期间继续观看广播。

使用入门指南详细介绍了在直播广告插播时段的观看体验。

第 5 阶段：结束直播

第 5.1 步：停止流式传输

您的 YouTube 直播系统测试到此结束。

第 5.2 步：将广播状态转换为“已完成”

准备好停止广播后，请调用 API 的 liveBroadcasts.transition 方法来更新广播状态。将 id 参数值设为第 1.1 步中获取的广播 ID，并将 broadcastStatus 参数值设为 complete。

如果您已将广播的 contentDetails.recordFromStart 和 contentDetails.enableDvr 属性设置为 true，则当直播活动结束后，您的观众可以立即观看直播活动播放。

第 6 阶段：创建引用

直播录制完成后，您可以根据录制的视频创建参考文件。此操作会指示 YouTube 查找与广播匹配的用户上传视频，并根据您在第 2.3 步中设置的匹配政策处理这些视频。

重要提示：如需创建引用，必须将广播的 contentDetails.recordFromStart 属性设置为 true。

第 6.1 步：轮询 Data API 以获取视频状态

YouTube 必须先处理广播或上传的视频，然后您才能基于该视频创建参考文件。如需确定视频是否已处理完毕，请轮询 YouTube Data API 的 videos.list 方法，将 part 参数设置为 status，并将 id 参数设置为您在第 1.1 步中存储的广播 ID。

对您的轮询请求的 API 响应将包含 video 资源。当该资源的 status.uploadStatus 属性的值为 processed 时，请继续执行第 6.2 步。

第 6.2 步：根据处理后的视频创建参考文件

如需创建参考文件，请调用 Content ID API 的 references.insert 方法，并将 claimId 参数设置为您在第 2.4 步中存储的版权主张 ID。

直播 Content ID 传送

某些 YouTube 合作伙伴可以在其广播转换为 testing 状态之前创建参考文件，但并非所有合作伙伴都可以使用该功能。在该流程中，YouTube 会在直播活动的播放过程中生成并持续更新直播活动的直播视频流中的参考文件。此外，YouTube 会在广播仍在进行时查找用户上传的视频的匹配视频。请注意，在广播开始前创建参考文件会自动为广播开启录制功能，并且录制内容一经创建便无法关闭。

如需启用直播 Content ID 直播功能，请尝试在第 2.4 步中声明视频版权后执行第 6.2 步中所述的操作。如果您的合作伙伴帐号尚未获准在广播开始前为直播广播创建参考，则该 API 会返回 fingerprintingNotAllowed 错误。在这种情况下，您需要等到广播完成后（如第 6.1 步和第 6.2 步所述）才能创建引用。