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.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
識別影響串流的錯誤類型。
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 參數來識別串流。