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