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
等) 之間的轉場效果,並讓使用者插入提示點。
事前準備
-
您必須擁有 Google 帳戶才能存取 Google API Console、要求 API 金鑰並註冊應用程式。
-
向 Google 註冊應用程式,以便提交 API 要求。
-
註冊應用程式後,請選取 YouTube Data API 做為應用程式使用的其中一個服務:
- 前往 API Console 並選取您剛註冊的專案。
- 前往「已啟用的 API」頁面。 在 API 清單中,確認 YouTube Data API v3 的狀態顯示為「開啟」;如果您是 YouTube 內容合作夥伴,則 YouTube Content ID API 為「啟用」狀態。
-
熟悉 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 在播送期間放送片中廣告。
廣告插播具備下列特性:
-
其中包含預先定義的時間長度,您可使用
cuepoint
資源的durationSecs
屬性進行設定。廣告插播結束後,觀眾就會返回現場直播。 -
廣告插播時間點時,只有當您插入提示點時,播放器才會在影片播放器中播放廣告。觀眾重新整理播放正在播放的頁面,或訪客在插入提示點後開始觀看廣播時,廣告才會放送。
以下順序為您在廣播期間插入廣告插播時段的最佳做法:
設定時間偏移
插入提示點時,您可以指定立即插入提示點,或是將其插入廣播的特定時間點。可用選項取決於影片的廣播串流是否延遲。
-
如果直播串流沒有延遲,你可以立即插入提示點,也可以使用
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
。