LiveStreams

liveStream 资源包含有关您要传输到 YouTube 的视频串流的信息。该数据流提供将向 YouTube 用户广播的内容。创建后，liveStream 资源可以绑定到一个或多个 liveBroadcast 资源。

方法

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

list
返回与 API 请求参数匹配的视频串流列表。 立即试用。
insert
创建视频流。借助此流式传输功能，您可以将视频发送到 YouTube，然后 YouTube 会将视频广播给您的观众。 立即试用。
update
更新视频流。如果您要更改的属性无法更新，则需要使用正确的设置创建新的数据流。 立即试用。
delete
删除视频流。 立即试用。

资源表示法

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

{
  "kind": "youtube#liveStream",
  "etag": etag,
  "id": string,
  "snippet": {
    "publishedAt": datetime,
    "channelId": string,
    "title": string,
    "description": string,
    "isDefaultStream": boolean
  },
  "cdn": {
    "ingestionType": string,
    "ingestionInfo": {
      "streamName": string,
      "ingestionAddress": string,
      "backupIngestionAddress": string
    },
    "resolution": string,
    "frameRate": string
  },
  "status": {
    "streamStatus": string,
    "healthStatus": {
      "status": string,
      "lastUpdateTimeSeconds": unsigned long,
      "configurationIssues": [
        {
          "type": string,
          "severity": string,
          "reason": string,
          "description": string
        }
      ]
    }
  },
  "contentDetails": {
    "closedCaptionsIngestionUrl": string,
    "isReusable": boolean
  }
}

属性

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

属性
kind string
用于标识 API 资源的类型。该值将为 youtube#liveStream。
etag etag
此资源的 ETag。
id string
由 YouTube 分配的 ID，用于唯一标识直播。
snippet object
snippet 对象包含有关直播的基本详细信息，包括其频道、标题和说明。
snippet.publishedAt datetime
数据流的创建日期和时间。该值采用 ISO 8601 (YYYY-MM-DDThh:mm:ss.sZ) 格式指定。
snippet.channelId string
此 ID 由 YouTube 用于唯一标识正在传输直播的频道。
snippet.title string
直播的标题。该值的长度必须介于 1 到 128 个字符之间。
snippet.description string
数据流的说明。值不得超过 10,000 个字符。
snippet.isDefaultStream boolean
此媒体资源将于 2020 年 9 月 1 日当天或之后弃用。届时，当频道启用直播功能后，YouTube 将停止创建默认直播和默认直播。如需了解详情，请参阅弃用公告。
此属性指示此数据流是否为频道的默认数据流。

默认直播的运作方式

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

频道的默认直播会无限期存在，没有关联的开始或结束时间，并且无法删除。频道所有者只需开始发送视频数据，直播就会自动继续。

直播结束后，YouTube 会将已完成的直播转换为 YouTube 视频，并为该视频分配一个 YouTube 视频 ID。转换完成后，该视频会包含在频道上传的视频列表中。视频不会在直播结束后立即可用，延迟时间与直播的实际时长相关。
cdn object
cdn 对象用于定义直播的 content delivery network (CDN) 设置。这些设置详细说明了您将内容流式传输到 YouTube 的方式。
cdn.format string
此属性自 2016 年 4 月 18 日起已废弃，自 2020 年 8 月 17 日起将不再受支持。在该日期之后，仍使用此属性的请求将会失败。

请改为使用 cdn.frameRate 和 cdn.resolution 属性分别指定帧速率和分辨率。
cdn.ingestionType string
用于传输视频流的方法或协议。

此属性的有效值如下：
  • dash
  • hls
  • rtmp（包括 RTMPS）
cdn.ingestionInfo object
ingestionInfo 对象包含 YouTube 提供的信息，您需要这些信息才能将直播传输到 YouTube。
cdn.ingestionInfo.streamName string
YouTube 为视频流分配的流名称。
cdn.ingestionInfo.ingestionAddress string
如果您使用的是 RTMP、DASH 或 HLS，则应使用此主要提取网址将视频流式传输到 YouTube。您必须将视频流式传输到此网址。

根据您用于编码视频流的应用或工具，您可能需要单独输入流式传输网址和流式传输名称，或者您可能需要按以下格式将它们串联起来： 
STREAM_URL/STREAM_NAME
cdn.ingestionInfo.backupIngestionAddress string
如果您使用 RTMP、DASH 或 HLS，则应使用此备用提取网址将视频流式传输到 YouTube。您可以选择将要发送到 ingestionAddress 的内容同时流式传输到此网址。
cdn.ingestionInfo.rtmpsIngestionAddress string
如果您使用 RTMPS，则应使用此主要提取网址将视频流式传输到 YouTube。您必须将视频流式传输到此网址。

根据您用于编码视频流的应用或工具，您可能需要单独输入流式传输网址和流式传输名称，或者您可能需要按以下格式将它们串联起来： 
STREAM_URL/STREAM_NAME
cdn.ingestionInfo.rtmpsBackupIngestionAddress string
如果您使用 RTMPS，则应使用此备用提取网址将视频流式传输到 YouTube。
cdn.resolution string
入站视频数据的分辨率。

此属性的有效值如下：
  • 240p
  • 360p
  • 480p
  • 720p
  • 1080p
  • 1440p
  • 2160p
  • variable：使用此设置可指示 YouTube 应自动检测流式传输视频的分辨率。您还必须将 cdn.frameRate 设置为 variable。
    如需了解推荐的编码器设置，请访问 YouTube 帮助中心。
cdn.frameRate string
入站视频数据的帧速率。

此属性的有效值如下：
  • 30fps
  • 60fps
  • variable：使用此设置可指示 YouTube 应自动检测流式传输视频的帧速率。您还必须将 cdn.resolution 设置为 variable。
    如需了解推荐的编码器设置，请访问 YouTube 帮助中心。
status object
status 对象包含有关直播状态的信息。
status.streamStatus string
数据流的状态。

此属性的有效值如下：
  • active - 数据流处于活跃状态，这意味着用户正在通过数据流接收数据。
  • created - 数据流已创建，但没有有效的 CDN 设置。
  • error - 直播中存在错误情况。
  • inactive - 数据流处于非活跃状态，这意味着用户未通过数据流接收数据。
  • ready - 直播具有有效的 CDN 设置。
status.healthStatus object
此对象包含有关直播运行状况的信息，可用于识别、诊断和解决直播问题。
status.healthStatus.status string
此数据流的状态代码。

此属性的有效值包括：
  • good - 没有严重级别为 warning 或更高的配置问题。
  • ok - 没有严重级别为 error 的配置问题。
  • bad - 直播存在一些问题，严重程度为 error。
  • noData - YouTube 的直播后端服务器不具备任何有关直播健康状态的信息。
status.healthStatus.lastUpdateTimeSeconds unsigned long
上次更新数据流运行状况的时间。该值反映的是 Unix 时间戳（以秒为单位）。
status.healthStatus.configurationIssues[] list
此对象包含影响数据流的配置问题列表。
status.healthStatus.configurationIssues[].type string
标识影响数据流的错误类型。
status.healthStatus.configurationIssues[].severity string
表示问题对数据流的严重程度。

此属性的有效值如下：
  • info - 视频会向观看者播放，对广告效果没有不利影响。
  • warning - 视频已向观看者播放，但效果不佳。
  • error - 视频无法向观看者播放。
status.healthStatus.configurationIssues[].reason string
对问题的简要说明。直播资源的配置问题文档介绍了与每种配置问题类型相关的原因。
status.healthStatus.configurationIssues[].description string
对问题的详细说明。说明应尽可能提供有关如何解决问题的信息。直播资源的配置问题文档列出了所有配置问题类型及其相关说明。
contentDetails object
content_details 对象包含有关直播的信息，包括字幕提取网址。
contentDetails.closedCaptionsIngestionUrl string
用于发送此直播字幕的内容提取网址。
contentDetails.isReusable boolean
指示数据流是否可重复使用，这意味着它可以绑定到多个广播。如果直播在不同时间进行，直播者通常会为许多不同的直播重复使用同一直播。

如果您将此值设置为 false，则该串流将不可重复使用，这意味着它只能绑定到一个广播。不可重复使用的串流与可重复使用的串流的不同之处如下：
  • 不可重复使用的串流只能绑定到一个广播。
  • 在直播结束后，系统可能会通过自动化流程删除不可重复使用的直播。
  • 如果您调用 liveStreams.list 方法并将 mine 参数设置为 true，则 liveStreams.list 方法不会列出不可重复使用的串流。若要使用该方法检索不可重复使用的串流的资源，唯一的方法是使用 id 参数标识串流。