LiveStreams
透過集合功能整理內容
你可以依據偏好儲存及分類內容。
liveStream
資源包含您傳送給 YouTube 的影片串流相關資訊。直播將向 YouTube 使用者播送內容。建立完成後,liveStream
資源可繫結至一或多項 liveBroadcast
資源。
方法
這個 API 支援下列 liveStreams
資源的方法:
- list
- 傳回符合 API 要求參數的影片串流清單。立即試用。
- 插入
- 建立影片串流。直播功能可讓您將影片傳送至 YouTube,以便向觀眾播送影片。
立即試用。
- 更新
- 更新影片串流。如果要更新的屬性無法更新,則必須使用正確的設定建立新串流。
立即試用。
- 刪除
- 刪除影片串流。
立即試用。
資源表示法
以下 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 或 HTTP 即時串流,請將主要串流擷取網址上傳到 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 以下。 |
|
gopMismatch |
原因: | 次要串流設定有誤 |
說明: | 在目前設定中,影片的主要串流和備份串流的主影格頻率不同。您必須設定串流的主影格頻率相同。 |
|
gopSizeLong |
原因: | 視訊設定有誤 |
說明: | 請將主影格頻率設為四秒以下。目前的主畫面頻率 (X 秒) 過低,目前的主影格頻率為 %(actual_gop).1f 秒。請注意,如果發生內容擷取錯誤,可能會導致 GOP (圖片組) 大小錯誤。 |
|
gopSizeOver |
原因: | 檢查視訊設定 |
說明: | 請將主影格頻率設為四秒以下。目前的主影格傳送頻率過低,因此可能造成緩衝處理的情況。目前的主影格頻率為 %(actual_gop).1f 秒。請注意,如果發生內容擷取錯誤,可能會導致 GOP (圖片組) 大小錯誤。 |
|
gopSizeShort |
原因: | 檢查視訊設定 |
說明: | GOP (畫面群) 大小過小時,可能會降低影像品質。建議的主影格頻率為四秒,目前的主影格頻率為 %(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
問題的簡短說明。「Live Stream 資源的設定問題」文件會說明與各種設定問題類型相關的原因。 |
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 和/或其關聯企業的註冊商標。
上次更新時間:2023-02-22 (世界標準時間)。
[[["容易理解","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"]],["上次更新時間:2023-02-22 (世界標準時間)。"],[[["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."]]],[]]