LiveStreams

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

方法

该 API 支持 liveStreams 资源的以下方法：

list
返回与 API 请求参数匹配的视频流列表。 立即试用。
插入
创建视频流。通过视频流，您可以将视频发送给 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
YouTube 用来唯一标识正在传输直播的频道的 ID。
snippet.title string
信息流的标题。值必须介于 1 到 128 个字符之间。
snippet.description string
数据流说明。值不得超过 10000 个字符。
snippet.isDefaultStream boolean
此媒体资源将于 2020 年 9 月 1 日或之后弃用。届时，如果频道启用了直播功能，YouTube 将停止创建默认直播和默认直播。如需了解详情，请参阅弃用公告。
此属性用于指明此直播是否是频道的默认直播。

默认直播的运作方式

为 YouTube 频道启用直播功能后，YouTube 会为频道创建默认直播和默认直播。直播定义了频道所有者向 YouTube 发送直播视频的方式，直播是观看者查看默认直播的方式。频道所有者可以使用 liveStreams.list 和 liveBroadcasts.list 方法标识这些资源。

频道的默认直播无限期存在，没有关联的开始时间或结束时间，因此无法删除。频道所有者只需要开始发送视频位，直播会自动进行。

直播结束后，YouTube 会将已完成的直播转换为 YouTube 视频，并为该视频分配一个 YouTube 视频 ID。完成转换后，相应视频就会纳入该频道的上传视频列表中。在广播结束后，视频不会立即播放，延迟时间的长度与广播的实际长度相关。
cdn object
cdn 对象用于定义直播的内容分发网络 (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，该数据流将无法重复使用，这意味着它只能绑定到一个广播。不可重复使用的信息流与可重复使用的信息流在以下几个方面有所不同：
  • 不可重复使用的流只能绑定到一个广播。
  • 广播结束后，自动化流程可能会删除不可重复使用的视频流。
  • 如果您调用该方法并将 mine 参数设置为 true，则 liveStreams.list 方法不会列出不可重复使用的数据流。使用该方法检索不可重复使用的数据流的资源的唯一方法是使用 id 参数标识数据流。