LiveStreams
透過集合功能整理內容
你可以依據偏好儲存及分類內容。
liveStream
資源包含傳送至 YouTube 的影片串流相關資訊。這項串流會提供要向 YouTube 使用者播送的內容。建立後,liveStream
資源可繫結至一或多個 liveBroadcast
資源。
方法
這個 API 支援 liveStreams
資源的下列方法:
- list
- 會傳回與 API 要求參數相符的影片串流清單。立即試用。
- 插入
- 建立影片串流。你可以透過串流將影片傳送至 YouTube,然後向觀眾播放影片。立即試用。
- update
- 更新影片串流。如果無法更新要變更的屬性,則必須使用正確的設定建立新的串流。立即試用。
- 刪除
- 刪除影片串流。立即試用。
資源表示法
以下 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
用於傳輸影片串流的方法或通訊協定。
這個屬性的有效值如下:
|
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 |
原因: | 視訊設定有誤 |
說明: | 請將主影格頻率設為四秒以下。目前的主畫面頻率 (X 秒) 過低,目前的主影格頻率為 %(actual_gop).1f 秒。請注意,如果發生內容擷取錯誤,可能會導致 GOP (圖片組) 大小錯誤。 |
|
gopSizeOver |
原因: | 檢查視訊設定 |
說明: | 請將主影格頻率設為四秒以下。目前的主影格傳送頻率過低,因此可能造成緩衝處理的情況。目前的主影格頻率為 %(actual_gop).1f 秒。請注意,如果發生內容擷取錯誤,可能會導致 GOP (圖片組) 大小錯誤。 |
|
gopSizeShort |
原因: | 檢查視訊設定 |
說明: | GOP (畫面群) 大小過小時,可能會降低影像品質。建議的主畫面頻率為 4 秒,目前的主影格頻率為 %(actual_gop).1f 秒。請注意,如果發生內容擷取錯誤,可能會導致 GOP 大小錯誤。 |
|
multipleAudioStreams |
原因: | 檢查音訊設定 |
說明: | 內容攝入串流中只能有一個音訊串流,但這個內容攝入串流含有多個音訊串流。 |
|
multipleVideoStreams |
原因: | 視訊設定有誤 |
說明: | 內容攝入串流中只能有一個視訊串流,但這個內容攝入串流含有多個視訊串流。 |
|
noAudioStream |
原因: | 沒有音訊 |
說明: | 內容攝入串流中必須含有一個音訊串流,但這個內容攝入串流中沒有任何音訊串流。 |
|
noVideoStream |
原因: | 沒有視訊 |
說明: | 內容攝入串流中必須含有一個視訊串流,但這個內容攝入串流中沒有任何視訊串流。 |
|
openGop |
原因: | 視訊設定有誤 |
說明: | 請將您的視訊編碼器設定改成「封閉式影格組 (GOP)」。YouTube 不支援編碼器目前使用的「開放式 GOP」設定。 |
|
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
簡短說明問題。LiveStream 資源的設定問題文件會說明每種設定問題類型的原因。 |
status.healthStatus.configurationIssues[].description |
string
詳細說明問題。說明中會盡可能提供解決問題的方法。「LiveStream 資源的設定問題」說明文件列出所有設定問題類型及其相關說明。 |
contentDetails |
object
content_details 物件包含串流的相關資訊,包括隱藏式輔助字幕擷取網址。 |
contentDetails.closedCaptionsIngestionUrl |
string
這個串流的隱藏式輔助字幕傳送至攝入網址。 |
contentDetails.isReusable |
boolean
指出串流是否可重複使用,也就是說,串流可綁定至多個廣播。通常,如果廣播內容在不同時間播出,廣播主通常會重複使用相同的串流。
如果您將這個值設為 false ,則串流將無法重複使用,也就是說只能繫結至一個廣播。不可重複使用的串流與可重複使用的串流的差異如下: - 不可重複使用的串流只能繫結至一個廣播。
- 系統會在廣播結束後,自動刪除無法重複使用的串流。
- 如果您呼叫該方法並將
mine 參數設為 true , liveStreams.list 方法就不會列出無法重複使用的串流。使用該方法擷取不可重複使用的串流資源的唯一方法,就是使用 id 參數來識別串流。 |
除非另有註明,否則本頁面中的內容是採用創用 CC 姓名標示 4.0 授權,程式碼範例則為阿帕契 2.0 授權。詳情請參閱《Google Developers 網站政策》。Java 是 Oracle 和/或其關聯企業的註冊商標。
上次更新時間:2025-07-01 (世界標準時間)。
[[["容易理解","easyToUnderstand","thumb-up"],["確實解決了我的問題","solvedMyProblem","thumb-up"],["其他","otherUp","thumb-up"]],[["缺少我需要的資訊","missingTheInformationINeed","thumb-down"],["過於複雜/步驟過多","tooComplicatedTooManySteps","thumb-down"],["過時","outOfDate","thumb-down"],["翻譯問題","translationIssue","thumb-down"],["示例/程式碼問題","samplesCodeIssue","thumb-down"],["其他","otherDown","thumb-down"]],["上次更新時間:2025-07-01 (世界標準時間)。"],[[["A `liveStream` resource represents a video feed being sent to YouTube for live broadcasts, which can be associated with one or more `liveBroadcast` resources to provide content to viewers."],["The `liveStream` resource can be managed through several methods, including `list` to retrieve streams, `insert` to create new streams, `update` to modify existing ones, and `delete` to remove streams."],["The `cdn` property defines critical streaming details such as `ingestionType` (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."],["The `status` property of a `liveStream` 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."],["Configuration issues such as `videoBitrateLow`, `framerateMismatch` or `noAudioStream` might affect the quality or delivery of the broadcast, and can be checked in the `healthStatus` part of the `status` property."]]],["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"]]