LiveBroadcasts

API 現在支援將直播標示為「為兒童打造」，而 liveBroadcast 資源現在包含可識別直播的「為兒童打造」狀態的屬性。我們也於 2020 年 1 月 10 日更新了《YouTube API 服務條款》和《開發人員政策》。如需更多資訊，請參閱 YouTube Live Streaming API 服務和 YouTube API 服務條款的修訂版本歷史記錄。

liveBroadcast 資源代表在 YouTube 上使用直播影片進行串流的活動。

方法

這個 API 支援 liveBroadcasts 資源的下列方法：

list
傳回符合 API 要求參數的 YouTube 直播清單。立即試用。
插入
建立廣播。立即試用。
update
更新廣播。舉例來說，您可以修改 liveBroadcast 資源 contentDetails 物件中定義的廣播設定。立即試用。
刪除
刪除廣播。立即試用。
bind
將 YouTube 直播綁定至串流，或移除直播與串流之間的現有綁定。一個廣播活動只能繫結至一個視訊串流，但視訊串流可以繫結至多個廣播活動。立即試用。
transition
變更 YouTube 直播的狀態，並啟動與新狀態相關的任何程序。舉例來說，當你將直播狀態切換為 testing 時，YouTube 就會開始將影片傳送至該直播的監控串流。呼叫此方法前，請確認與廣播綁定的串流 status.streamStatus 屬性值為 active。立即試用。
Cue Point
在直播中插入提示點。提示點可能會觸發廣告插播。

資源表示法

以下 JSON 結構顯示 liveBroadcasts 資源的格式：

{
  "kind": "youtube#liveBroadcast",
  "etag": etag,
  "id": string,
  "snippet": {
    "publishedAt": datetime,
    "channelId": string,
    "title": string,
    "description": string,
    "thumbnails": {
      (key): {
        "url": string,
        "width": unsigned integer,
        "height": unsigned integer
      }
    },
    "scheduledStartTime": datetime,
    "scheduledEndTime": datetime,
    "actualStartTime": datetime,
    "actualEndTime": datetime,
    "isDefaultBroadcast": boolean,
    "liveChatId": string
  },
  "status": {
    "lifeCycleStatus": string,
    "privacyStatus": string,
    "recordingStatus": string,
    "madeForKids": string,
    "selfDeclaredMadeForKids": string,
  },
  "contentDetails": {
    "boundStreamId": string,
    "boundStreamLastUpdateTimeMs": datetime,
    "monitorStream": {
      "enableMonitorStream": boolean,
      "broadcastStreamDelayMs": unsigned integer,
      "embedHtml": string
    },
    "enableEmbed": boolean,
    "enableDvr": boolean,
    "recordFromStart": boolean,
    "enableClosedCaptions": boolean,
    "closedCaptionsType": string,
    "projection": string,
    "enableLowLatency": boolean,
    "latencyPreference": boolean,
    "enableAutoStart": boolean,
    "enableAutoStop": boolean
  },
  "statistics": {
    "totalChatCount": unsigned long
  },
  "monetizationDetails": {
      "cuepointSchedule": {
        "enabled": boolean,
        "pauseAdsUntil": datetime,
        "scheduleStrategy": string,
        "repeatIntervalSecs": unsigned integer,
      }
    }
  }
}

屬性

下表定義了這個資源中顯示的屬性：

屬性
kind string
識別 API 資源的類型。值為 youtube#liveBroadcast。
etag etag
這項資源的 Etag。
id string
YouTube 指派的 ID，用於唯一識別廣播。
snippet object
snippet 物件包含活動的基本詳細資料，包括標題、說明、開始時間和結束時間。
snippet.publishedAt datetime
直播內容加入 YouTube 直播時間表的日期和時間。這個值採用 ISO 8601 (YYYY-MM-DDThh:mm:ss.sZ) 格式指定。
snippet.channelId string
YouTube 會使用這個 ID 來識別發布直播的頻道。
snippet.title string
廣播的標題。請注意，廣播內容只能代表一部 YouTube 影片。您可以修改廣播資源，或設定對應影片資源的 title 欄位，來設定這個欄位。
snippet.description string
廣播的說明。如同 title，您可以修改廣播資源，或設定對應影片資源的 description 欄位，來設定這個欄位。
snippet.thumbnails object
與廣播相關聯的縮圖圖片對應表。對於這個物件中的每個巢狀物件，鍵是縮圖圖片的名稱，而值則是包含縮圖其他資訊的物件。
snippet.thumbnails.(key) object
有效的鍵值如下：
  • default – 預設縮圖圖片。影片或影片相關資源 (例如播放清單項目或搜尋結果) 的預設縮圖寬度為 120 像素，高度為 90 像素。頻道的預設縮圖寬度和高度為 88 像素。
  • medium：縮圖圖片的高解析度版本。對於影片 (或參照影片的資源)，這張圖片的寬度為 320 像素，高度為 180 像素。頻道的圖片寬度和高度為 240 像素。
  • high – 縮圖圖片的高解析度版本。對於影片 (或參照影片的資源)，這張圖片的寬度為 480 像素，高度為 360 像素。頻道的圖片寬度和高度為 800 像素。
snippet.thumbnails.(key).url string
圖片的網址。
snippet.thumbnails.(key).width unsigned integer
圖片的寬度。
snippet.thumbnails.(key).height unsigned integer
圖片的高度。
snippet.scheduledStartTime datetime
廣播節目預定開始的日期和時間。這個值採用 ISO 8601 (YYYY-MM-DDThh:mm:ss.sZ) 格式指定。Creator Studio 支援不排定開始時間，直接建立直播的功能。在這種情況下，只要頻道擁有者開始串流，直播就會開始。對於這類直播，datetime 值會對應至 Unix 紀元時間零，且無法透過 API 或 Creator Studio 變更這個值。
snippet.scheduledEndTime datetime
廣播節目預定結束的日期和時間。這個值採用 ISO 8601 (YYYY-MM-DDThh:mm:ss.sZ) 格式指定。如果 liveBroadcast 資源未指定此屬性的值，則系統會排定廣播訊息無限期持續執行。同樣地，如果未指定這個屬性的值，YouTube 會將該直播視為無限期播放。
snippet.actualStartTime datetime
廣播實際開始的日期和時間。這項資訊只會在廣播狀態為 live 時提供。這個值採用 ISO 8601 (YYYY-MM-DDThh:mm:ss.sZ) 格式指定。
snippet.actualEndTime datetime
廣播實際結束的日期和時間。這項資訊只會在廣播狀態為 complete 時提供。這個值採用 ISO 8601 (YYYY-MM-DDThh:mm:ss.sZ) 格式指定。
snippet.isDefaultBroadcast boolean
這項資源將於 2020 年 9 月 1 日當天或之後淘汰。屆時，YouTube 會停止在頻道啟用直播功能時建立預設串流和預設廣播。詳情請參閱淘汰公告。
此屬性指出這項廣播是否為預設廣播。

預設直播的運作方式

啟用 YouTube 頻道直播功能後，YouTube 會為頻道建立預設串流和預設直播。串流會定義頻道擁有者將直播影片傳送至 YouTube 的方式，而廣播則是觀眾觀看預設串流的方式。頻道擁有者可以使用 liveStreams.list 和 liveBroadcasts.list 方法來識別這些資源。

當頻道開始將影片串流至預設串流時，影片就會顯示在頻道的預設廣播中。串流結束後，YouTube 會將完成的直播內容轉換為 YouTube 影片，並為影片指派 YouTube 影片 ID。

轉換完成後，影片就會列入頻道的已上傳影片清單。影片不會在直播結束後立即上傳，延遲時間長短取決於直播的實際長度。
snippet.liveChatId string
直播的 YouTube 聊天室 ID。有了這個 ID，您就可以使用 liveChatMessage 資源的方法擷取、插入或刪除即時通訊訊息。你也可以新增或移除聊天室管理員、禁止使用者參與直播聊天，或移除現有的封鎖。
status object
status 物件包含事件狀態的相關資訊。
status.lifeCycleStatus string
廣播的狀態。您可以使用 API 的 liveBroadcasts.transition 方法更新狀態。

這個屬性的有效值如下：
  • complete – 廣播已結束。
  • created：廣播的設定不完整，因此無法轉換為 live 或 testing 狀態，但已建立且有效。
  • live – 廣播處於有效狀態。
  • liveStarting：廣播正在轉換為 live 狀態。
  • ready：廣播設定已完成，廣播可以轉換為 live 或 testing 狀態。
  • revoked：管理員已移除這則直播。
  • testStarting：廣播正在轉換為 testing 狀態。
  • testing：只有合作夥伴可看見廣播內容。
status.privacyStatus string
廣播的隱私權狀態。請注意，直播代表單一 YouTube 影片，因此隱私設定與影片相同。此外，您也可以修改廣播資源，或設定對應影片資源的 privacyStatus 欄位來設定這個欄位。

這個屬性的有效值如下：
  • private
  • public
  • unlisted
status.recordingStatus string
廣播的錄製狀態。

這個屬性的有效值如下：
  • notRecording
  • recorded
  • recording
status.madeForKids boolean
這個值會指出廣播內容是否指定為兒童導向內容。這個屬性值為唯讀。
status.selfDeclaredMadeForKids boolean
在 liveBroadcasts.insert 要求中，這個屬性可讓頻道擁有者將廣播內容指定為兒童導向。在 liveBroadcasts.list 要求中，只有在頻道擁有者授權 API 要求時，系統才會傳回屬性值。
contentDetails object
contentDetails 物件包含活動影片內容的相關資訊，例如內容是否可在嵌入式影片播放器中顯示，或是是否會封存，以便在活動結束後供觀眾觀看。
contentDetails.boundStreamId string
這個值可用來識別與廣播綁定的 live stream。
contentDetails.boundStreamLastUpdateTimeMs datetime
boundStreamId 參照的直播上次更新的日期和時間。
contentDetails.monitorStream object
monitorStream 物件包含監控串流的相關資訊，主播者可在公開播送串流之前，先查看事件內容。
contentDetails.monitorStream.enableMonitorStream boolean
這個值會決定是否為廣播啟用監控串流。啟用監控串流後，YouTube 會在專屬於直播主使用的串流中播放活動內容。直播主可以透過串流查看活動內容，並找出插入提示點的最佳時機。

如果您想為廣播訊息設定 testing 階段，或是想為事件設定廣播延遲時間，請將這個值設為 true。此外，如果這項屬性的值為 true，則必須先將廣播轉換為 testing 狀態，才能轉換為 live 狀態。(如果屬性值為 false，則廣播活動就無法有 testing 階段，因此您可以直接將廣播活動轉換為 live 狀態)。

在 update a broadcast 時，如果 API 要求在 part 參數值中包含 contentDetails 部分，則必須設定此屬性。不過，在 insert a broadcast 中，該屬性為選用屬性，且預設值為 true。

重要事項：廣播處於 testing 或 live 狀態時，就無法更新這個屬性。
contentDetails.monitorStream.broadcastStreamDelayMs unsigned integer
如果您將 enableMonitorStream 屬性設為 true，則這個屬性會決定直播延遲的長度。

當您 update a broadcast 時，如果 API 要求在 part 參數值中包含 contentDetails 部分，則必須設定此屬性。不過，在 insert a broadcast 中，該屬性為選用屬性，預設值為 0。這個值表示直播沒有延遲。注意：廣播處於 testing 或 live 狀態時，就無法更新這項屬性。
contentDetails.monitorStream.embedHtml string
HTML 程式碼，用於嵌入播放監控串流的播放器。
contentDetails.enableEmbed boolean
這項設定會指出廣播影片是否可在嵌入式播放器中播放。如果您選擇封存影片 (使用 enableArchive 屬性)，這項設定也會套用至封存的影片。

在 update a broadcast 時，如果 API 要求在 part 參數值中包含 contentDetails 部分，則必須設定此屬性。不過，在 insert a broadcast 中，該屬性為選用屬性，且預設值為 true。

注意：廣播處於 testing 或 live 狀態時，就無法更新這項屬性。
contentDetails.enableDvr boolean
這項設定會決定觀眾是否能在觀看影片時使用 DVR 控制選項。觀眾可透過 DVR 控制項，暫停、倒轉或快轉內容，以便控制影片播放體驗。此屬性的預設值為 true。

在 update a broadcast 時，如果 API 要求在 part 參數值中包含 contentDetails 部分，則必須設定此屬性。不過，在 insert a broadcast 中，該屬性為選用屬性，且預設值為 true。

重要事項：如要讓播映內容在廣播結束後立即播放，請務必將值設為 true，並將 enableArchive 屬性的值設為 true。此外，廣播處於 testing 或 live 狀態時，這項屬性就無法更新。
contentDetails.recordFromStart boolean
這項設定會指出 YouTube 是否會在活動狀態變更為「直播」後，自動開始錄製直播。

這項屬性的預設值為 true，只有在廣播管道允許停用直播錄影功能時，才能將其設為 false。

如果頻道沒有停用錄影權限，而您嘗試插入的廣播內容 recordFromStart 屬性設為 false，API 就會傳回 Forbidden 錯誤。此外，如果頻道沒有該權限，且您嘗試更新廣播，將 recordFromStart 屬性設為 false，API 會傳回 modificationNotAllowed 錯誤。

在 update a broadcast 時，如果 API 要求在 part 參數值中包含 contentDetails 部分，則必須設定此屬性。不過，在 insert a broadcast 中，該屬性為選用屬性，且預設值為 true。

重要事項：如要讓播放內容在廣播結束後立即開始，您必須將 enableDvr 屬性的值設為 true。如果您將這個屬性的值設為 true，但未將 enableDvr 屬性設為 true，則封存的影片可能會延遲約一天才可播放。

注意：廣播處於 testing 或 live 狀態時，就無法更新這項屬性。
contentDetails.enableClosedCaptions boolean
這項屬性已於 2015 年 12 月 17 日淘汰。請改用 contentDetails.closedCaptionsType 屬性。

這項設定會指出是否為此廣播啟用 HTTP POST 隱藏式輔助字幕。針對已使用此屬性的 API 用戶端：
  • 將屬性值設為 true 等同於將 contentDetails.closedCaptionsType 屬性設為 closedCaptionsHttpPost。
  • 將屬性值設為 false 等同於將 contentDetails.closedCaptionsType 屬性設為 closedCaptionsDisabled。
contentDetails.closedCaptionsType string
注意：這個屬性取代 contentDetails.enableClosedCaptions 屬性。

這個屬性會指出是否已為廣播內容啟用隱藏式輔助字幕，如果已啟用，則會指出你提供哪種隱藏式輔助字幕：
  • closedCaptionsDisabled：直播已停用隱藏式輔助字幕。
  • closedCaptionsHttpPost：您會使用 HTTP POST 將字幕傳送至與直播相關聯的擷取網址。
  • closedCaptionsEmbedded：字幕會使用 EIA-608 和/或 CEA-708 格式，在影片串流中編碼。
contentDetails.projection string
這項廣播的投影格式。屬性的預設值為 rectangular。

此屬性的有效值如下：
  • 360
  • rectangular
contentDetails.enableLowLatency boolean
指明這項廣播活動是否應經過編碼，以便進行低延遲串流。低延遲串流可縮短觀看直播的使用者看到影片的時間，但也會影響串流觀眾的解析度。
contentDetails.latencyPreference string
指出要為此廣播使用哪種延遲設定。這個屬性可用於取代 enableLowLatency (不支援 ultraLow)。

低延遲串流可縮短觀眾觀看直播時看到影片的時間，但可能會影響播放流暢度。

超低延遲串流可進一步縮短觀眾看到影片的時間，讓觀眾更容易與你互動，但超低延遲串流不支援隱藏式字幕或高於 1080p 的解析度。

這個屬性的有效值如下：
  • normal
  • low
  • ultraLow
contentDetails.enableAutoStart boolean
指出在已綁定的 live stream 上開始串流播放影片時，是否應自動開始這項廣播。
contentDetails.enableAutoStop boolean
指出頻道擁有者停止在已綁定影片串流上串流影片後，系統是否應在約一分鐘後自動停止這項廣播。
statistics object
statistics 物件包含與直播相關的統計資料。這些統計資料的值可能會在直播期間變更，且只能在直播期間擷取。
statistics.totalChatCount unsigned long
與直播相關聯的即時通訊訊息總數。如果使用者可看到直播、已啟用即時通訊功能，且至少有一個訊息，系統就會顯示這項資源及其值。請注意，這個屬性不會在廣播結束後指定值。因此，這項資源不會識別已完成直播的封存影片中聊天訊息的數量。
monetizationDetails object
monetizationDetails 物件包含串流的營利詳細資料，例如廣告自動插入功能是否已開啟，或片中廣告插入作業是否延遲。
monetizationDetails.cuepointSchedule object
cuepointSchedule 物件會指定廣播的廣告自動化設定。
monetizationDetails.cuepointSchedule.enabled boolean
這個值會決定廣播內容是否會自動插入廣告。如果值為 true，YouTube 會自動在直播中插入片中廣告。放送廣告的時間表將取決於 monetizationDetails.cuepointSchedule 物件中其他欄位的值。
monetizationDetails.cuepointSchedule.pauseAdsUntil datetime
這個值會指定 YouTube 在指定日期和時間之前，不得在直播中插入片中廣告。值採用 ISO 8601 格式 (YYYY-MM-DDThh:mm:ss.sZ) 指定。這個值必須設為未來的日期時間，才能暫停廣告；欄位值也可以設為不久後的日期時間，在時間過後取消暫停廣告。
monetizationDetails.cuepointSchedule.scheduleStrategy string
這個值會指定 YouTube 應遵循的排程提示點策略。有效值如下：
  • CONCURRENT：Cuepoint 會在同一時間安排給所有觀眾
  • NON_CONCURRENT：Cuepoint 會在不同時間排定給不同的觀眾。這麼做可提高廣告顯示率，讓觀眾在符合資格時收到提示點。
monetizationDetails.cuepointSchedule.repeatIntervalSecs unsigned integer
這個值會以秒為單位，指定廣播期間自動插入廣告的間隔。舉例來說，如果值為 300，YouTube 就能以五分鐘的間隔插入片中廣告提示點。

請注意，該值會指定連續提示點開始之間的時間。也就是說，間隔並非從一個 Cue Point 結束到下一個 Cue Point 開始的時間長度。