YouTube Live Streaming API 總覽

透過集合功能整理內容 你可以依據偏好儲存及分類內容。

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

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

這份文件旨在協助開發人員撰寫應用程式，協助他們在 YouTube 上進行現場直播。內容說明 YouTube 和 API 本身的基本概念。以及 API 支援的不同函式總覽。

核心概念

廣播
廣播是指事件發生時可在 YouTube 上觀看的活動。您也可以將錄製內容錄製為 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 的狀態顯示為「開啟」；如果您是 YouTube 內容合作夥伴，則 YouTube Content ID API 為「啟用」狀態。

  4. 熟悉 JSON (JavaScript 物件標記法) 資料格式的核心概念。JSON 是一種與語言無關的通用資料格式，能夠以簡單的文字表示任意資料結構。詳情請參閱 json.org 網站。

授權 API 要求

如上文所述，直播 API 在技術上屬於 YouTube Data API 或 YouTube Content ID API 的一部分。你可以透過 Content ID API 為資產提供中繼資料、擁有權資訊和政策資訊。(即時視訊畫面是一種資產範例)。這個 API 也能讓您聲明影片版權，並設定影片的廣告政策。

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

呼叫 Data API
API 要求必須由擁有 YouTube 廣播頻道之 Google 帳戶的授權。
呼叫 Content ID API
API 要求必須獲得與播送播送 YouTube 頻道內容擁有者的 Google 帳戶連結的授權。

資源和資源類型

資源是具有專屬 ID 的個別資料實體。下表說明您將使用 Live Streaming API 進行互動的各種資源類型。從技術上，這些資源實際上都是定義為 YouTube Data API 或 YouTube Content ID API 的一部分。不過，liveBroadcast、liveStream 和 cuepoint 資源只會用於建立及管理現場直播。

資源
liveBroadcast 含有您在 YouTube 上廣播的活動相關資訊。liveBroadcast 資源是 YouTube 影片資源的延伸，可設定與現場直播相關的影片中繼資料，但不得與其他 YouTube 影片相關。

因此，liveBroadcast 資源只能對應至一個 YouTube 影片資源。 事實上，liveBroadcast 資源與 video 資源共用相同的 ID。使用 Live Streaming API 建立廣播後，您可以使用 YouTube Data 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
現場直播
直播

部分資源

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

part 參數是擷取或傳回 YouTube Data API 資源的任何 API 要求的必要參數。這個參數可識別應納入 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 無法精確插入提示點時，Δ 是可能的時間偏移開始和結束的緩衝區，長度為 5 秒。例如：

  • 播送內容設有 5 分鐘的測試階段。
  • 監控串流會在監控串流的 60 秒後延遲。
  • 電視台在廣播轉換為 live 狀態後，會在 4 分鐘內插入提示點。(系統會在直播串流顯示前 3 分鐘顯示相關資訊)。

在這種情況下，可能的時間偏移範圍為 [(485,000), (535,000)]。

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

  • elapsed_time=540000 - 呼叫 liveBroadcasts.cuepoint 方法時，監控串流已執行 9 分鐘 (540 秒，540000 毫秒)。
  • broadcast_delay=60000 – 播送串流延遲 60 秒，也就是 60000 毫秒。
  • Δ=5000 - 無法插入插入提示點的 5 秒緩衝區。

疑難排解與錯誤處理

以下指南說明如何解決可能發生的問題。另請參閱錯誤說明文件，瞭解各個 API 方法可能傳回的錯誤清單。

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

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

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