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 用於傳遞影片串流的方法或通訊協定。 這項屬性的有效值如下： 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 找出影響串流的錯誤類型。 查看有效值 設定問題 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 參數來識別串流。