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.listliveBroadcasts.list 方法标识这些资源。

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

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

请改为使用 cdn.frameRatecdn.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
确定影响数据流的错误类型。
配置问题
audioBitrateHigh
原因:检查音频设置
说明:音频流当前的比特率 %(actual) 高于建议的比特率。我们建议您使用%(expected)s的音频流比特率。
audioBitrateLow
原因:检查音频设置
说明:音频流当前的比特率 (%(actual)s) 低于建议的比特率。我们建议您使用%(expected)s的音频流比特率。
audioBitrateMismatch
原因:检查辅助视频流
说明:在当前配置下,视频的主视频流和备用视频流的音频比特率不同。您需要为这些音频流配置相同的音频比特率。
audioCodec
原因:检查音频设置
说明:音频流编码所用的编解码器不受支持。请将音频流的音频编解码器设置为受支持的编解码器(AAC、MP3)。
audioCodecMismatch
原因:辅助视频流有误
说明:在当前配置下,视频的主视频流和备用视频流采用不同的音频编解码器。您需要将这些视频流配置为使用相同的音频编解码器。
audioSampleRate
原因:检查音频设置
说明:当前采样率为 %(actual)。建议的采样率为 44.1kHz 和 48kHz。
audioSampleRateMismatch
原因:辅助视频流有误
说明:在当前配置下,视频的主视频流和备用视频流的音频采样率不同。您需要为这些音频流配置相同的音频采样率。
audioStereoMismatch
原因:辅助视频流有误
说明:在当前配置下,视频的主视频流和备用视频流所使用的声道不同。您需要将这两种视频流配置为使用相同的声道。
audioTooManyChannels
原因:检查音频设置
说明:音频具有两个以上的声道,但仅支持一个(单声道)或两个(立体声)声道。请更正声道的数量。
badContainer
原因:视频设置有误
说明:请更改视频的容器格式。此容器的当前容器格式不正确。
bitrateHigh
原因:检查视频设置
说明:当前音频/视频流的比特率 (%(actual)s) 高于建议的比特率。我们建议您使用 %(expected)s 的流比特率。
bitrateLow
原因:视频输出率低
说明:当前音频/视频流的比特率 (%(actual)s) 低于建议的比特率。我们建议您使用 %(expected)s 的流比特率。
framerateMismatch
原因:检查辅助视频流
说明:在当前配置下,视频的主视频流和备用视频流的帧速率不同。您需要将这两个视频流配置为相同的帧速率。
frameRateHigh
原因:帧速率过高
说明:当前帧速率过高。请将帧速率设为 %(framerate)s fps 或更低。
gopMismatch
原因:辅助视频流有误
说明:在当前配置下,视频的主视频流和备用视频流的关键帧频率不同。您需要将这两种视频流配置为相同的关键帧频率。
gopSizeLong
原因:视频设置有误
说明:请使用不超过 4 秒的关键帧频率。当前的关键帧发送频率不够高,这会使视频流进入缓冲状态。当前的关键帧频率为 %(actual_gop).1f 秒。注意,如果发生提取错误,则会造成画面组 (GOP) 尺寸错误。
gopSizeOver
原因:检查视频设置
说明:请使用不超过 4 秒的关键帧频率。当前的关键帧发送频率不够高,这会使视频流进入缓冲状态。当前的关键帧频率为 %(actual_gop).1f 秒。注意,如果发生提取错误,则会造成画面组 (GOP) 尺寸错误。
gopSizeShort
原因:检查视频设置
说明:画面组 (GOP) 尺寸太小,这会降低画面质量。建议的关键帧频率为 4 秒。当前的关键帧频率为 %(actual_gop).1f 秒。注意,如果发生提取错误,则会造成 GOP 尺寸错误。
multipleAudioStreams
原因:检查音频设置
说明:提取流包含多个音频流,但它只能包含一个音频流。
multipleVideoStreams
原因:视频设置有误
说明:提取流包含多个视频流,但它只能包含一个视频流。
noAudioStream
原因:无音频
说明:提取流未包含任何音频流,但它必须包含(且只能包含)一个音频流。
noVideoStream
原因:无视频
说明:提取流未包含任何视频流,但它必须包含(且只能包含)一个视频流。
openGop
原因:视频设置有误
说明:请将您的视频编码器配置改为“封闭画面组 (GOP)”。它似乎设置为“开放 GOP”,YouTube 不支持。
resolutionMismatch
原因:辅助视频流有误
说明:在当前配置下,视频的主视频流和备用视频流的分辨率不同。您需要将视频流配置为相同的分辨率。
videoBitrateMismatch
原因:检查辅助视频流
说明:在当前配置下,视频的主视频流和备用视频流的视频比特率不同。您需要将这两个视频流配置为相同的视频比特率。
videoCodec
原因:视频设置有误
说明:视频编码所用的编解码器不受支持。请将视频流的视频编解码器设置为受支持的编解码器 (H.264)。
videoCodecMismatch
原因:辅助视频流有误
说明:在当前配置下,视频的主视频流和备用视频流的视频编解码器不同。您需要将这两个视频流配置为具有相同的视频编解码器。
videoIngestionStarved
原因:视频输出率低
说明:YouTube 未收到足够的视频来维持流畅的流式传输。因此,观看者会遇到缓冲问题。
videoInterlaceMismatch
原因:辅助视频流有误
说明:在当前配置下,视频的主视频流和备用视频流的隔行扫描方式不同。您需要将这两个流配置为具有相同的交错。
videoProfileMismatch
原因:辅助视频流有误
说明:在当前配置下,视频的主视频流和备用视频流的配置文件不同。您需要将这些数据流配置为具有相同的配置文件。
videoResolutionSuboptimal
原因:检查分辨率
说明:请检查视频分辨率。当前的分辨率是 (%(actual_w)dx%(actual_h)d),这不是最佳分辨率。
videoResolutionUnsupported
原因:分辨率不受支持
说明:您需要更改视频分辨率。当前的分辨率是 (%(actual_w)dx%(actual_h)d),此配置不支持该分辨率。预期的视频分辨率为 (%(expected_w)dx%(expected_h)d)
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 参数标识数据流。