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
用於傳輸影片串流的方法或通訊協定。

這個屬性的有效值如下：
  • 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 參數來識別串流。