LiveBroadcasts

這個 API 現在支援將現場直播標示為「兒童專屬」，而且 liveBroadcast 資源現在包含一項屬性，可用來識別直播中的「兒童專屬」狀態。YouTube API 服務的《服務條款》和《開發人員政策》也已於 2020 年 1 月 10 日更新。詳情請參閱 YouTube Live Streaming API 服務的修訂版本記錄和《YouTube API 服務條款》。

liveBroadcast 資源代表要在 YouTube 上透過直播影片串流的活動。

方法

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

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

資源表示法

下列 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 像素，高度為 88 像素。
  • medium：解析度較高的縮圖版本。影片 (或參照影片資源) 的寬度為 320 像素，高度為 180 像素。頻道圖片的寬度是 240 像素，高度為 240 像素。
  • high：高解析度的縮圖圖片。影片 (或參照影片資源) 的寬度和高度為 480 像素，高度為 360 像素。頻道圖片的寬度是 800 像素，高度為 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) 格式指定。創作者工作室功能可讓您在不需排定開始時間的情況下製作直播。在這種情況下，只要頻道擁有者開始串流播放，系統就會開始播送內容。對於這些廣播訊息，datetime 值會對應至 UNIX 時間零，但無法透過 API 或創作者工作室變更這個值。
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
說明這個廣播訊息要使用的延遲時間設定。這個屬性可能會用在不支援 ultraLow 的 enableLowLatency 上。





  • 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：為所有檢視者同時排定提示點
  • NON_CONCURRENT：為不同的檢視者排定不同時間的提示點。這種做法會提高廣告顯示頻率，讓觀眾在符合資格時能收到提示點。
monetizationDetails.cuepointSchedule.repeatIntervalSecs unsigned integer
這個值可指定在直播期間自動插入廣告插播的間隔時間 (以秒為單位)。舉例來說，如果值為 300，YouTube 就能以五分鐘的間隔插入片中廣告提示點。

請注意，這個值可指定連續提示點開始之間的時間。也就是說，間隔時不會從一個提示點的結尾到下一個提示點開始。