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
用于传输视频流的方法或协议。
此属性的有效值如下:
|
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.1 kHz 和 48 kHz 的采样率。 |
|
audioSampleRateMismatch |
原因: | 辅助视频流有误 |
说明: | 在当前配置下,视频的主视频流和备用视频流的音频采样率不同。您需要将这两种视频流配置为相同的音频采样率。 |
|
audioStereoMismatch |
原因: | 辅助视频流有误 |
说明: | 在当前配置下,视频的主视频流和备用视频流所使用的声道不同。您需要将这两种视频流配置为使用相同的声道。 |
|
audioTooManyChannels |
原因: | 检查音频设置 |
说明: | 音频的声道数量超过了两个,但系统仅支持 1 个(单声道)或 2 个(立体声)声道。请更正音频的声道数量。 |
|
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 ,则该串流将不可重复使用,这意味着它只能绑定到一个广播。不可重复使用的串流与可重复使用的串流的不同之处如下: - 不可重复使用的串流只能绑定到一个广播。
- 在直播结束后,系统可能会通过自动化流程删除不可重复使用的直播。
- 如果您调用
liveStreams.list 方法并将 mine 参数设置为 true ,则 liveStreams.list 方法不会列出不可重复使用的串流。若要使用该方法检索不可重复使用的串流的资源,唯一的方法是使用 id 参数标识串流。 |
如未另行说明,那么本页面中的内容已根据知识共享署名 4.0 许可获得了许可,并且代码示例已根据 Apache 2.0 许可获得了许可。有关详情,请参阅 Google 开发者网站政策。Java 是 Oracle 和/或其关联公司的注册商标。
最后更新时间 (UTC):2025-07-01。
[null,null,["最后更新时间 (UTC):2025-07-01。"],[[["\u003cp\u003eA \u003ccode\u003eliveStream\u003c/code\u003e resource represents a video feed being sent to YouTube for live broadcasts, which can be associated with one or more \u003ccode\u003eliveBroadcast\u003c/code\u003e resources to provide content to viewers.\u003c/p\u003e\n"],["\u003cp\u003eThe \u003ccode\u003eliveStream\u003c/code\u003e resource can be managed through several methods, including \u003ccode\u003elist\u003c/code\u003e to retrieve streams, \u003ccode\u003einsert\u003c/code\u003e to create new streams, \u003ccode\u003eupdate\u003c/code\u003e to modify existing ones, and \u003ccode\u003edelete\u003c/code\u003e to remove streams.\u003c/p\u003e\n"],["\u003cp\u003eThe \u003ccode\u003ecdn\u003c/code\u003e property defines critical streaming details such as \u003ccode\u003eingestionType\u003c/code\u003e (e.g., RTMP, HLS), primary and backup stream URLs, resolution, and frame rate, and it is essential for configuring how the video stream is delivered to YouTube.\u003c/p\u003e\n"],["\u003cp\u003eThe \u003ccode\u003estatus\u003c/code\u003e property of a \u003ccode\u003eliveStream\u003c/code\u003e provides information on the current status of the stream, including whether it is active, created, or in error, as well as its overall health status and any detected issues.\u003c/p\u003e\n"],["\u003cp\u003eConfiguration issues such as \u003ccode\u003evideoBitrateLow\u003c/code\u003e, \u003ccode\u003eframerateMismatch\u003c/code\u003e or \u003ccode\u003enoAudioStream\u003c/code\u003e might affect the quality or delivery of the broadcast, and can be checked in the \u003ccode\u003ehealthStatus\u003c/code\u003e part of the \u003ccode\u003estatus\u003c/code\u003e property.\u003c/p\u003e\n"]]],["A `liveStream` resource represents a video stream sent to YouTube for live broadcasts, linked to `liveBroadcast` resources. Key actions include listing, creating, updating, and deleting streams. Streams are defined by properties like `id`, `title`, `description`, `ingestionType` (`rtmp`, `dash`, `hls`), and URLs for primary and backup ingestion. The resource contains status and health information, with `configurationIssues` detailing problems, categorized by video or audio issues, resolution, framerate, keyframe frequency or codec. The stream can also be `isReusable`.\n"],null,[]]