YouTube Live Streaming API 總覽

YouTube Live Streaming API 可讓你建立、更新及管理 YouTube 上的現場直播。這個 API 可讓您安排活動 (廣播)，並將這些活動與代表實際廣播內容的影片串流建立關聯。

Live Streaming API 實際上是由 YouTube Data API 和 YouTube Content ID API 的元件組成。YouTube 使用者能運用 Data API 管理 YouTube 帳戶，而 YouTube Content ID API 則可與 YouTube 版權管理系統互動。不過，組成 Live Streaming API 的所有資源只能用於建立及管理現場活動。

本文件可協助開發人員編寫應用程式，以便在 YouTube 上即時播送。並說明 YouTube 和 API 本身的基本概念。並概略介紹 API 支援的不同功能。

核心概念

廣播
廣播訊息代表活動發生當下可在 YouTube 上播放。您亦可錄製播送內容並儲存為 YouTube 影片，以便使用者之後觀看。
小溪
「串流」則是指要傳達給 YouTube 的影音內容。每個廣播都與一個影片串流相關聯。
提示點
提示點代表可插入直播活動的廣告插播。

API 用途

以下清單列出在應用程式中使用 API 的幾種方式：

  • 排定廣播時間並定義播送設定。您的應用程式會讓使用者預先定義廣播設定，然後選取要套用至特定廣播訊息的設定。

  • 為影片串流和廣播建立關聯。

  • 讓電視台使用 YouTube Data API 同時定義廣播和其影片的相關資訊。

  • 簡化廣播狀態 (例如 testing 或 live) 之間的轉換，並讓使用者插入提示點。

事前準備

  1. 您必須擁有 Google 帳戶才能存取 Google API Console、要求 API 金鑰，並註冊應用程式。

  2. 向 Google 註冊您的應用程式，以便提交 API 要求。

  3. 註冊應用程式後，請選取 YouTube Data API 做為應用程式使用的其中一個服務：

    1. 前往 API Console 並選取您剛註冊的專案。
    2. 前往已啟用的 API 頁面。 在 API 清單中，請確認 YouTube Data API v3 的狀態已設為「ON」；如果您是 YouTube 內容合作夥伴，請確認 YouTube Content ID API 的狀態。

  4. 熟悉 JavaScript Object Notation (JSON) 資料格式的核心概念。JSON 是不涉及語言的常見資料格式，可提供任意資料結構的簡單文字表示法。詳情請參閱 json.org。

授權 API 要求

如前所述，Live Streaming API 所使用的功能在技術上屬於 YouTube Data API 或 YouTube Content ID API。您可以使用 Content ID API，向 YouTube 提供資產的中繼資料、擁有權資訊和政策資訊。(即時影像廣播就屬於資產的一種)。這個 API 也可讓您聲明影片版權，以及為影片設定廣告政策。

本節說明對 Content ID API 提出的要求授權規定，這與授權其他 Live Streaming API 要求不同。

呼叫 Data API
API 要求必須取得廣播 YouTube 頻道的 Google 帳戶授權。
呼叫 Content ID API
API 要求必須取得帳戶授權，且該帳戶必須和擁有廣播 YouTube 頻道的內容擁有者相連結。

資源和資源類型

資源是具有專屬 ID 的個別資料實體。下表說明 透過 GCP 控制台 Live Streaming API。就技術層面而言，這些資源涵蓋的資源 已實際定義為 YouTube Data API 的一部分 或 YouTube Content ID API。不過， liveBroadcast, liveStream和 cuepoint 項資源 只能用於建立及管理現場活動。

資源
liveBroadcast 包含你在 YouTube 上播送的活動相關資訊。A 罩杯 liveBroadcast 資源是 YouTube 影片資源的延伸，會設定為 影片中繼資料 與現場直播相關，但不適用於其他 YouTube 影片。

因此，liveBroadcast 資源只會對應一個 YouTube 影片資源。 事實上，liveBroadcast 和 video 資源會共用 相同的 ID。使用 Live Streaming API 建立廣播後，就可以運用 YouTube 資料 API，提供影片的其他中繼資料。
liveStream 包含已傳送至 YouTube 的影片串流相關資訊。訊息串 提供要播送給 YouTube 使用者的內容。建立後，liveStream 資源只能繫結至一項 liveBroadcast 資源。同樣地， liveBroadcast 資源只能繫結至一項 liveStream 資源。
cuepoint 在廣播影片串流中插入提示點，這可能會觸發廣告插播。使用 liveBroadcasts.cuepoint 方法，在廣播期間插入提示點。
video 代表單一 YouTube 影片。如上所述，liveBroadcast 資源是 video 資源的擴充功能。YouTube Data API 可用來更新影片的中繼資料，例如錄影位置或直播可觀看的區域。
videoAdvertisingOptions 定義影片 (或播送) 的廣告設定。您可以使用 YouTube Content ID API 設定廣告選項。
asset 代表智慧財產，例如電影或電視節目劇集。在這個案例中，廣播影片即為資產。您將使用 YouTube Content ID API 建立及管理 asset 資源。
claim 將影片連結到與影片相符的資產。您可以使用 YouTube Content ID API 建立著作權聲明，表明自己是廣播影片的擁有者。
policy 定義規則，指定您的內容在哪些情況下可在 YouTube 上供人觀看，或禁止出現在 YouTube 上。此外，你必須對播送影片套用政策，並指定 YouTube 針對與播送影片相符的使用者上傳影片套用政策。

支援作業

下表列出這個 API 支援的不同方法：

作業
list 擷取零或多個資源的清單 (GET)。
insert 建立新資源 (POST)。
update 修改 (PUT) 現有資源以反映要求中的資料。
bind 連結 liveBroadcast 資源與 liveStream 資源，或移除這類連結。
transition 變更 liveBroadcast 資源的狀態，並啟動與新狀態相關聯的所有程序。舉例來說，如果你將廣播的狀態轉換為「testing」，YouTube 就會開始將影片傳輸至該廣播的螢幕串流。
delete 移除 (DELETE) 特定資源。

下表列出了不同資源類型支援的作業。插入、更新或刪除資源的作業一律需要使用者授權。在某些情況下，list 方法支援已授權和未經授權的要求，在此情況下，未經授權的要求只有在取得已授權的要求時，才能擷取公開資料，同時只有目前驗證的使用者可存取的資訊。

支援的作業
list insert update bind transition cuepoint delete
liveBroadcast
liveStream

部分資源

這個 API 允許 (且實際上需要) 擷取部分資源，避免應用程式傳輸、剖析及儲存不需要的資料。這種做法也能確保 API 更有效率地使用網路、CPU 和記憶體資源。

凡是擷取或傳回 YouTube Data API 資源的 API 要求，part 參數都是必要參數。參數可識別應納入 API 回應中的一或多個頂層 (非巢狀) 資源屬性。舉例來說，liveStream 資源包含下列部分：

  • snippet
  • cdn
  • status

這些部分都是包含巢狀屬性的物件，您可以將其視為 API 伺服器可能 (或可能不會) 擷取的中繼資料欄位群組。因此，part 參數會要求您選取應用程式實際使用的資源元件。這項要求有兩個重要目的：

  • 可防止 API 伺服器花時間擷取應用程式未使用的中繼資料欄位，藉此縮短延遲時間。
  • 可減少 (或排除) 應用程式可能擷取的非必要資料量，進而減少頻寬用量。

隨著資源加入更多部分，這些好處只會增加，因為您的應用程式不會要求支援的新導入資源。

提示與最佳做法

聲明內容著作權

如果想在播送期間顯示廣告，您必須在活動開始前就對直播影片聲明著作權。如要對內容提出著作權聲明，您必須是加入「Content ID」計畫的 YouTube 內容合作夥伴。

聲明直播影片的版權與聲明影片版權的程序並不相同。對直播影片提出版權聲明時，您必須先建立版權聲明，影片才會真正存在。API 支援這種做法，廣播節目生命週期文件則會說明可讓您建立聲明的 YouTube Content ID API 呼叫。

預覽及測試內容

收到您的傳入影片串流後，YouTube 即可在兩個不同的輸出串流上播送該影片：

  • 「監控串流」可以讓您預覽 (及測試) 影片播送內容。這是只有你能存取的私人串流。您必須先啟用廣播的監控串流，才能將廣播訊息轉換至「testing」階段。監控串流不會顯示廣告插播。

  • 廣播串流是觀眾能看見的直播內容。您可以將廣播的隱私狀態設為 public、private 或 unlisted。(私人直播影片只會向您已明確邀請觀看的使用者顯示，而不公開的播送內容則只有知道連結的人才能觀看)。

    您可以選擇延遲廣播串流，使其不會與監控串流同時執行。藉由延遲廣播串流，您可以更精細地控管將提示點插入廣播訊息的時間。

    不過，如果延遲直播內容，即時簡報者難以與觀眾互動。此外，延遲直播會更有可能從直播以外的來源發現該事件的重要詳細資訊。舉例來說，假設你以 60 秒的直播播送體育賽事，觀眾可能會在實際播送之前，透過其他即時新聞來源得知活動資訊。

YouTube 建議你為播送內容啟用監控串流，以便測試內容。因此，您應基於自己想要控制提示點的時間點，選擇是否也延後播送，而非想要與觀眾互動或提供事件的即時報導。

在廣播串流期間放送片中廣告

在直播期間，您可以插入提示點，表示廣告插播應於 提高廣播訊息的速度廣告插播可讓 YouTube 順利放送 片中廣告。

廣告插播具有以下特點：

  1. 它具有預先定義的時間長度，請使用 cuepoint 資源的 durationSecs 資源。廣告插播結束後，觀眾會返回現場直播。

  2. 廣告插播發生時，只有正在觀看內容的觀眾，才會在影片播放器中播放廣告。 將提示點插入提示點觀眾重新整理網頁時並不會放送廣告 用於播送內容，或是觀眾在直播結束後開始觀看播送內容 已插入提示點

以下步驟可反映在播送期間插入廣告插播的最佳做法：

設定時間偏移

插入提示點時，您可以指定立即插入提示點，或是提示點 應該插入廣播節目的特定時間點。您的選項取決於 影片的廣播串流發生延遲。

  • 如果廣播沒有延遲，您可以立即插入提示點，或使用 walltimeMs 屬性來讓廣告時段在特定時間開始。

    • 如要立即啟動廣告插播，請呼叫 liveBroadcasts.cuepoint 方法。在 將資源放在要求主體中 insertionOffsetTimeMs 個資源的 值設為 0，或是未指定該屬性的值，也未指定 walltimeMs 的值 資源。

      重要事項：請注意，觀眾不會看到即將放送的廣告 內容。因此廣告內容可能會延遲約 30 秒才顯示 並不會向使用者顯示在這段期間，您仍可透過 需要先觀看廣播串流，才能判斷 而不是顯示監控串流

    • 如要在特定時間開始廣告插播，請呼叫 liveBroadcasts.cuepoint 方法，然後使用 walltimeMs 屬性指定所需的時間。屬性值是一個整數 Epoch 時間戳記。

  • 如果播送串流發生延遲，你可以立即插入提示點， 指定時鐘時間 (如上所述)，或者您也可以指定 決定廣告插播的開始時間時間偏移可指定播送的時間點 何時向觀眾顯示廣告

    偏移值是從監控串流開始時起算，以毫秒為單位的， 廣播訊息。請注意，如果您的直播設有測試階段，則監控串流 廣播轉成 testing 狀態時就會開始。否則 監控串流會在廣播轉成 live 狀態後開始啟動。

    插入提示點時，請設定 cuepoint 資源的 insertionOffsetTimeMs 設為需要的位移。

計算時間偏移值

如要擷取偏移值，請針對播放監控串流的播放器呼叫 YouTube Player API 的 getCurrentTime 函式。使用擷取的值，在該時間的廣播串流中插入提示點。

偏移時間的可能值能以下列範圍計算：

[(elapsed_time - broadcast_delay + Δ), (elapsed_time - Δ)]

當 YouTube 無法精確插入提示點時，Δ 會在可能的時間偏移的開頭和結尾保留五秒的緩衝區。例如：

  • 廣播訊息的測試階段為五分鐘。
  • 廣播串流會在監控器串流後延遲 60 秒。
  • 播送者會在廣播轉換開始的 4 分鐘後插入提示點 live狀態。(顯示播送串流後 3 分鐘)。

在本例中，偏移時間的可能範圍是 [(485,000), (535,000)]。

這些時間是以毫秒為單位，並使用下列值計算：

  • elapsed_time=540000 - 監控串流已執行 9 次 呼叫 liveBroadcasts.cuepoint 方法時每分鐘 (長為 540 秒，540000 毫秒)。
  • broadcast_delay=60000 - 廣播串流延遲 60 秒或 60000 毫秒。
  • Δ=5000：無法穩定插入提示點時的五秒緩衝區。

疑難排解及錯誤處理

下列指南說明如何解決特定問題。關於清單 各種 API 方法可能傳回的錯誤，請參閱 YouTube Live Streaming API - 錯誤。

  • 播送內容從某個狀態轉換成其他狀態時，在 YouTube 完成與轉換作業相關的動作時，系統可能會暫時為其他狀態指派其他狀態。舉例來說，如果你傳送 liveBroadcasts.transition 要求，將廣播狀態從 ready 變更為 testing，YouTube 會將廣播的狀態設為 testStarting，然後完成與狀態變更相關的動作。完成所有動作後，YouTube 會將廣播狀態更新為 testing，表示轉換作業已完成。

    如果廣播訊息停滯在 testStarting 或 liveStarting 狀態，您需要呼叫 liveBroadcasts.delete 方法並刪除廣播訊息。接著建立新的直播、繫結至直播，然後繼續測試程序。

    如 liveBroadcasts.transition 方法的說明文件所述，在呼叫該方法之前，您應確認繫結至廣播的串流 status.streamStatus 屬性值為 active。