LiveBroadcasts

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

liveBroadcast 资源代表将通过直播视频在 YouTube 上直播的活动。

方法

对于 liveBroadcasts 资源,该 API 支持以下方法:

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

资源表示法

以下 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
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 px,高度为 240 px。
  • high - 缩略图的高分辨率版本。对于视频(或引用视频的资源),此图片的宽度为 480 像素,高度为 360 像素。对于频道,此图片的宽度为 800 px,高度为 800 px。
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 时间 0,并且无法通过 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.listliveBroadcasts.list 方法来标识这些资源。

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

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

此属性的有效值包括:
  • complete – 直播已结束。
  • created – 广播的设置不完整,因此尚未准备好转换为 livetesting 状态,但是广播已创建且在其他方面有效。
  • live – 广播正在进行。
  • liveStarting – 广播正在转换为 live 状态。
  • ready – 广播设置已完成,广播可以转换为 livetesting 状态。
  • 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 将通过一个仅供广播公司观看的特殊视频流来播送活动内容。直播方可以根据视频流查看活动内容,并确定插入广告插入点的最佳时机。

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

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

重要提示:一旦广播处于 testinglive 状态,此属性便无法更新。
contentDetails.monitorStream.broadcastStreamDelayMs unsigned integer
如果您已将 enableMonitorStream 属性设置为 true,则此属性会确定直播延迟的时长。

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

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

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

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

重要提示:如果您希望在直播结束后立即播放,则必须将值设置为 true 并将 enableArchive 属性的值设置为 true。此外,一旦广播处于 testinglive 状态,此属性便无法更新。
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,则归档视频可能会延迟一天左右才能播放。

注意:一旦广播处于 testinglive 状态,此属性便无法更新。
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
指示要为此广播使用哪种延迟时间设置。此属性可用于代替 enableLowLatency,后者不支持 ultraLow

低延迟的数据流可以缩短向观看直播的用户显示视频所需的时间,但也可能会影响播放的流畅性。

超低延迟时间数据流可进一步缩短视频向观看者显示的时间,使与观看者的互动更加轻松,但超低延迟时间与字幕相比,
0 的有效分辨率不支持字幕。
    0
  • 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 在安排广告插入点时应遵循的策略。有效值包括:
  • CONCURRENT:为所有观看者安排在同一时间显示广告插入点
  • NON_CONCURRENT:为不同的观看者安排不同的广告插入点。这种方法可以提高广告展示频率,让观看者在符合条件时收到广告插入点。
monetizationDetails.cuepointSchedule.repeatIntervalSecs unsigned integer
此值指定广播期间自动插入广告的时间间隔(以秒为单位)。例如,如果值为 300,YouTube 可以每隔 5 分钟插入中贴片广告插入点。

请注意,该值指定的是连续广告插入点的开始时间之间的时间间隔。也就是说,不会测量从一个广告插入点结束到下一个广告插入点的开始的时间间隔。