LiveBroadcasts

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

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

方法

API 支援下列 liveBroadcasts 資源方法：

list
傳回符合 API 要求參數的 YouTube 廣播訊息清單。立即試用。
插入
建立廣播。立即試用。
更新
更新廣播。舉例來說，您可以修改 liveBroadcast 資源 contentDetails 物件中定義的廣播設定。立即試用。
刪除
刪除廣播。立即試用。
bind
將 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 像素。
  • 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) 格式指定。創作者工作室能在不排定開始時間的情況下建立直播影片。在這種情況下，只要頻道擁有者開始串流播放，直播就會開始。這些廣播訊息的 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
指出要為此廣播使用哪種延遲設定。這個屬性可用於取代 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 開始的時間長度。