LiveBroadcasts

该 API 现在支持将直播标记为“面向儿童的内容”，并且 liveBroadcast 资源现在包含一个用于标识该直播的“面向儿童的内容”状态的属性。YouTube API 服务的《服务条款》和《开发者政策》也于 2020 年 1 月 10 日更新。如需了解详情，请参阅 YouTube Live Streaming API 服务的修订历史记录和 YouTube API 服务条款。

liveBroadcast 资源表示将在 YouTube 上通过实时视频流式传输的活动。

方法

该 API 支持对 liveBroadcasts 资源使用以下方法：

list
返回与 API 请求参数匹配的 YouTube 广播的列表。立即试用。
insert
创建广播。 立即试用。
update
更新广播。例如，您可以修改 liveBroadcast 资源的 contentDetails 对象中定义的广播设置。立即试用。
delete
删除广播。 立即试用。
bind
将 YouTube 直播与直播绑定，或者解除直播与直播之间的现有绑定。一个直播只能绑定到一个视频流，但一个视频流可以绑定到多个直播。 立即试用。
transition
更改 YouTube 直播的状态，并启动与新状态相关的所有进程。例如，当您将直播的状态转换为 testing 时，YouTube 会开始向该直播的监控数据流传输视频。在调用此方法之前，您应确认绑定到广播的串流的 status.streamStatus 属性的值为 active。立即试用。
cuepoint
将 cue 点插入直播中。该 cue 点可能会触发广告插播时间点。

资源表示法

以下 JSON 结构显示了 liveBroadcasts 资源的格式：

{
  "kind": "youtube#liveBroadcast",
  "etag": etag,
  "id": string,
  "snippet": {
    "publishedAt": datetime,
    "channelId": string,
    "title": string,
    "description": string,
    "thumbnails": {
      (key): {
        "url": string,
        "width": unsigned integer,
        "height": unsigned integer
      }
    },
    "scheduledStartTime": datetime,
    "scheduledEndTime": datetime,
    "actualStartTime": datetime,
    "actualEndTime": datetime,
    "isDefaultBroadcast": boolean,
    "liveChatId": string
  },
  "status": {
    "lifeCycleStatus": string,
    "privacyStatus": string,
    "recordingStatus": string,
    "madeForKids": string,
    "selfDeclaredMadeForKids": string,
  },
  "contentDetails": {
    "boundStreamId": string,
    "boundStreamLastUpdateTimeMs": datetime,
    "monitorStream": {
      "enableMonitorStream": boolean,
      "broadcastStreamDelayMs": unsigned integer,
      "embedHtml": string
    },
    "enableEmbed": boolean,
    "enableDvr": boolean,
    "recordFromStart": boolean,
    "enableClosedCaptions": boolean,
    "closedCaptionsType": string,
    "projection": string,
    "enableLowLatency": boolean,
    "latencyPreference": boolean,
    "enableAutoStart": boolean,
    "enableAutoStop": boolean
  },
  "statistics": {
    "totalChatCount": unsigned long
  },
  "monetizationDetails": {
      "cuepointSchedule": {
        "enabled": boolean,
        "pauseAdsUntil": datetime,
        "scheduleStrategy": string,
        "repeatIntervalSecs": unsigned integer,
      }
    }
  }
}

属性

下表定义了此资源中显示的属性：

属性
kind string
用于标识 API 资源的类型。该值将为 youtube#liveBroadcast。
etag etag
此资源的 Etag。
id string
由 YouTube 分配的 ID，用于唯一标识直播。
snippet object
snippet 对象包含活动的基本详情，包括标题、说明、开始时间和结束时间。
snippet.publishedAt datetime
直播添加到 YouTube 直播时间表的日期和时间。该值采用 ISO 8601 (YYYY-MM-DDThh:mm:ss.sZ) 格式指定。
snippet.channelId string
此 ID 是 YouTube 用来唯一标识发布直播的频道的 ID。
snippet.title string
广播的标题。请注意，该广播只能代表一个 YouTube 视频。您可以通过修改直播资源或设置相应视频资源的 title 字段来设置此字段。
snippet.description string
广播的说明。与 title 一样，您可以通过修改直播资源或设置相应视频资源的 description 字段来设置此字段。
snippet.thumbnails object
与直播相关联的缩略图的映射。对于此对象中的每个嵌套对象，键是缩略图的名称，值是包含有关缩略图的其他信息的对象。
snippet.thumbnails.(key) object
有效的键值包括：
  • default - 默认缩略图。视频或提及视频的资源（例如播放列表项或搜索结果）的默认缩略图宽度为 120 像素，高度为 90 像素。频道的默认缩略图宽度为 88 像素，高度为 88 像素。
  • medium - 缩略图的更高分辨率版本。对于视频（或引用视频的资源），此图片的宽度为 320 像素，高度为 180 像素。对于频道来说，该图片宽为 240 像素，高为 240 像素。
  • high - 缩略图的较高分辨率版本。对于视频（或提及视频的资源），此图片的宽度为 480 像素，高度为 360 像素。对于频道来说，该图片宽 800 像素，高 800 像素。
snippet.thumbnails.(key).url string
图片的网址。
snippet.thumbnails.(key).width unsigned integer
图片的宽度。
snippet.thumbnails.(key).height unsigned integer
图片的高度。
snippet.scheduledStartTime datetime
直播的预定开始日期和时间。该值以 ISO 8601 (YYYY-MM-DDThh:mm:ss.sZ) 格式指定。创作者工作室支持无需安排开始时间即可创建直播活动。在这种情况下，只要频道所有者开始直播，直播就会开始。对于此类直播，datetime 值对应的是 UNIX 时间零，此值无法通过 API 或创作者工作室中更改。
snippet.scheduledEndTime datetime
直播的预定结束日期和时间。该值以 ISO 8601 (YYYY-MM-DDThh:mm:ss.sZ) 格式指定。如果 liveBroadcast 资源未指定此属性的值，则广播将无限期地继续。同样，如果您未为此属性指定值，YouTube 会将直播视为无限期播放。
snippet.actualStartTime datetime
直播的实际开始日期和时间。只有当广播的状态为 live 时，此信息才可用。该值以 ISO 8601 (YYYY-MM-DDThh:mm:ss.sZ) 格式指定。
snippet.actualEndTime datetime
直播实际结束的日期和时间。只有当广播的状态为 complete 时，此信息才可用。该值以 ISO 8601 (YYYY-MM-DDThh:mm:ss.sZ) 格式指定。
snippet.isDefaultBroadcast boolean
此媒体资源将于 2020 年 9 月 1 日当天或之后弃用。届时，如果频道启用了直播功能，YouTube 将停止创建默认直播和默认直播。如需了解详情，请参阅弃用公告。
此属性指示此广播是否为默认广播。

默认直播的运作方式

为 YouTube 频道启用直播功能后，YouTube 会为该频道创建一个默认直播和一个默认广播。直播定义了频道所有者将直播视频发送到 YouTube 的方式，而广播则是观看者观看默认直播的方式。频道所有者可以使用 liveStreams.list 和 liveBroadcasts.list 方法来识别这些资源。

当频道开始向其默认直播流传输视频时，该视频会显示在频道的默认直播中。当直播结束后，YouTube 会将完成的直播转换为 YouTube 视频，并为该视频分配一个 YouTube 视频 ID。

转换完成后，该视频就会出现在频道的已上传视频列表中。视频不会在直播结束后立即播放，延迟时间与直播的实际时长相关。
snippet.liveChatId string
直播的 YouTube 实时聊天 ID。有了此 ID，您就可以使用 liveChatMessage 资源的方法检索、插入或删除聊天消息。您还可以添加或移除聊天管理员，禁止用户参与实时聊天，或移除现有禁令。
status object
status 对象包含有关事件状态的信息。
status.lifeCycleStatus string
直播的状态。您可以使用 API 的 liveBroadcasts.transition 方法更新状态。

此属性的有效值为：
  • complete - 广播已结束。
  • created - 广播的设置不完整，因此尚不符合转换为 live 或 testing 状态的条件，但已创建且在其他方面有效。
  • live - 广播正在进行。
  • liveStarting - 广播正在转换为 live 状态。
  • ready - 广播设置已完成，广播可以转换为 live 或 testing 状态。
  • revoked - 此直播已被管理员移除。
  • testStarting - 广播正在转换为 testing 状态。
  • testing – 广播仅对合作伙伴可见。
status.privacyStatus string
广播的隐私权状态。请注意，直播仅代表一个 YouTube 视频，因此其隐私设置与视频支持的隐私设置相同。此外，您还可以通过修改直播资源或设置相应视频资源的 privacyStatus 字段来设置此字段。

此属性的有效值为：
  • private
  • public
  • unlisted
status.recordingStatus string
直播的录制状态。

此属性的有效值如下：
  • notRecording
  • recorded
  • recording
status.madeForKids boolean
此值表示直播是否被指定为面向儿童的直播。此属性值为只读。
status.selfDeclaredMadeForKids boolean
在 liveBroadcasts.insert 请求中，此属性可让频道所有者将直播指定为面向儿童。在 liveBroadcasts.list 请求中，只有在频道所有者授权了 API 请求时，系统才会返回属性值。
contentDetails object
contentDetails 对象包含与活动视频内容相关的信息，例如内容是否可以显示在嵌入式视频播放器中，或者内容是否可以归档以便可在活动结束后观看。
contentDetails.boundStreamId string
此值用于唯一标识绑定到广播的 live stream。
contentDetails.boundStreamLastUpdateTimeMs datetime
上次更新 boundStreamId 引用的直播的日期和时间。
contentDetails.monitorStream object
monitorStream 对象包含监控串流的相关信息，直播者可以在公开显示直播串流之前使用这些信息来查看事件内容。
contentDetails.monitorStream.enableMonitorStream boolean
此值决定是否为广播启用监控流。如果启用了监控直播，YouTube 将通过一个仅供直播者使用的特殊直播来播放活动内容。直播者可以使用该直播流查看活动内容，还可以确定插入 cue 点的最佳时间。

如果您打算为直播设置 testing 阶段，或者希望为活动设置直播延迟时间，则需要将此值设置为 true。此外，如果此属性的值为 true，则您必须先将广播转换为 testing 状态，然后才能将其转换为 live 状态。（如果该属性的值为 false，您的广播不能有 testing 阶段，因此您可以直接将广播转换为 live 状态。）

update a broadcast 时，如果您的 API 请求在 part 参数值中包含 contentDetails 部分，则必须设置此属性。不过，当您 insert a broadcast 时，该属性是可选的，默认值为 true。

重要提示：广播处于 testing 或 live 状态后，此属性将无法更新。
contentDetails.monitorStream.broadcastStreamDelayMs unsigned integer
如果您已将 enableMonitorStream 属性设置为 true，则此属性将决定直播延迟时间的时长。

update a broadcast 时，如果您的 API 请求在 part 参数值中包含 contentDetails 部分，则必须设置此属性。不过，在 insert a broadcast 中，该属性是可选属性，默认值为 0。该值表示广播没有广播延迟。注意：一旦广播处于 testing 或 live 状态，便无法更新此属性。
contentDetails.monitorStream.embedHtml string
用于嵌入用于播放监控流的播放器的 HTML 代码。
contentDetails.enableEmbed boolean
此设置用于指明直播视频是否可以在嵌入式播放器中播放。如果您选择归档视频（使用 enableArchive 属性），此设置也将应用于已归档的视频。

update a broadcast 时，如果您的 API 请求在 part 参数值中包含 contentDetails 部分，则必须设置此属性。不过，在 insert a broadcast 中，该属性是可选属性，默认值为 true。

注意：一旦广播处于 testing 或 live 状态，便无法更新此属性。
contentDetails.enableDvr boolean
此设置决定了观看者在观看视频时能否使用 DVR 控件。借助 DVR 控件，观看者可以通过暂停、快退或快进内容来控制视频播放体验。此属性的默认值为 true。

update a broadcast 时，如果您的 API 请求在 part 参数值中包含 contentDetails 部分，则必须设置此属性。不过，当您 insert a broadcast 时，该属性是可选的，默认值为 true。

重要提示：如果您希望在直播结束后立即提供播放功能，则必须将此值设置为 true，同时将 enableArchive 属性的值设置为 true。此外，广播一旦处于 testing 或 live 状态，此属性便无法更新。
contentDetails.recordFromStart boolean
此设置用于指明在活动状态变为正在直播后，YouTube 是否会自动开始录制直播。

此属性的默认值为 true，只有在允许广播频道停用直播录制功能时，才能将其设置为 false。

如果您的频道无权停用录制功能，当您尝试插入将 recordFromStart 属性设置为 false 的直播时，API 会返回 Forbidden 错误。此外，如果您的频道没有此权限，并且您尝试更新直播以将 recordFromStart 属性设置为 false，则 API 会返回 modificationNotAllowed 错误。

update a broadcast 时，如果您的 API 请求在 part 参数值中包含 contentDetails 部分，则必须设置此属性。不过，在 insert a broadcast 中，该属性是可选属性，默认值为 true。

重要提示：如果您希望在直播结束后立即开始播放，还必须将 enableDvr 属性的值设置为 true。如果您将此属性的值设为 true，但又没有将 enableDvr 属性设置为 true，那么归档视频可能会延迟一天左右才可供播放。

注意：一旦广播处于 testing 或 live 状态，便无法更新此属性。
contentDetails.enableClosedCaptions boolean
此属性自 2015 年 12 月 17 日起已废弃。请改用 contentDetails.closedCaptionsType 属性。

此设置用于指明是否为此直播启用 HTTP POST 字幕。对于已在使用此属性的 API 客户端：
  • 将属性值设置为 true 等同于将 contentDetails.closedCaptionsType 属性设置为 closedCaptionsHttpPost。
  • 将属性值设置为 false 等同于将 contentDetails.closedCaptionsType 属性设置为 closedCaptionsDisabled。
contentDetails.closedCaptionsType string
注意：此属性替换了 contentDetails.enableClosedCaptions 属性。

此属性用于指明您的直播是否启用了字幕，如果启用了，您提供的是哪种类型的字幕：
  • closedCaptionsDisabled：直播的字幕已停用。
  • closedCaptionsHttpPost：您将通过 HTTP POST 将字幕发送到与您的直播关联的提取网址。
  • closedCaptionsEmbedded：字幕将使用 EIA-608 和/或 CEA-708 格式编码到视频串流中。
contentDetails.projection string
此广播的投影格式。此属性的默认值为 rectangular。

此属性的有效值包括：
  • 360
  • rectangular
contentDetails.enableLowLatency boolean
指明是否应对此广播进行编码以实现低延迟流式传输。低延迟串流可以缩短观看直播的用户看到视频所需的时间，但也可能会影响观看者看到的串流分辨率。
contentDetails.latencyPreference string
指示此广播要使用的延迟时间设置。此属性可用于替代不支持 ultraLow 的 enableLowLatency。

低延迟串流可以缩短观看直播的用户看到视频所需的时间，但也可能会影响播放流畅度。

超低延迟串流可以进一步缩短观看者看到视频所需的时间，让观看者更轻松地与您互动，但超低延迟串流不支持字幕或高于 1080p 的分辨率。

此属性的有效值为：
  • normal
  • low
  • ultraLow
contentDetails.enableAutoStart boolean
指示当您在绑定的 live stream 上开始流式传输视频时，此广播是否应自动开始。
contentDetails.enableAutoStop boolean
指示此广播是否应在频道所有者停止在已绑定的视频流中播放视频大约一分钟后自动停止。
statistics object
statistics 对象包含与直播相关的统计信息。这些统计数据的值可能会在直播期间发生变化，并且只能在直播期间检索。
statistics.totalChatCount unsigned long
与直播相关联的实时聊天消息总数。如果直播对用户可见、已启用实时聊天功能且包含至少一条消息，则系统会提供此属性及其值。请注意，在广播结束后，此属性将不会指定值。因此，此属性不会识别已完成的直播的归档视频的聊天消息数。
monetizationDetails object
monetizationDetails 对象包含有关直播创收详细信息的信息，例如广告自动化程序是否处于开启状态，或插入插播广告是否延迟。
monetizationDetails.cuepointSchedule object
cuepointSchedule 对象用于指定直播的广告自动化设置。
monetizationDetails.cuepointSchedule.enabled boolean
此值用于确定是否在直播中自动插入广告。如果值为 true，YouTube 会自动将中贴片广告插入直播中。广告的投放时间将取决于 monetizationDetails.cuepointSchedule 对象中其他字段的值。
monetizationDetails.cuepointSchedule.pauseAdsUntil datetime
此值指定 YouTube 在指定日期和时间之前不应在直播中插入中贴片广告。该值采用 ISO 8601 (YYYY-MM-DDThh:mm:ss.sZ) 格式指定。此值必须设置为未来的日期时间，才能暂停广告；此字段值也可以设置为近期的日期时间，以便在时间过后解除广告暂停状态。
monetizationDetails.cuepointSchedule.scheduleStrategy string
此值用于指定 YouTube 应遵循的预定 cue 点策略。有效值包括：
  • CONCURRENT：为所有观看者同时安排广告插入点
  • NON_CONCURRENT：为不同观看者安排在不同时间播放的广告插播点。这种方法可以提高广告展示率，让观看者在符合条件时收到 cuepoint。
monetizationDetails.cuepointSchedule.repeatIntervalSecs unsigned integer
此值指定在直播期间自动广告插入之间的间隔（以秒为单位）。例如，如果该值为 300，则 YouTube 可以每隔 5 分钟插入一个中贴片广告 cuepoint。

请注意，此值指定了连续 cue 点开始之间的时间。也就是说，间隔时间不是从一个 cue 点结束到下一个 cue 点开始测量。