YouTube Live Streaming API 可讓你在 YouTube 上建立、更新及管理現場活動。只要使用 API,您就可以安排活動 (廣播內容),並將活動與代表實際播送內容的影片串流建立關聯。
Live Streaming API 其實是由 YouTube Data API 和 YouTube Content ID API 兩個元件組成。Data API 可讓 YouTube 使用者管理自己的 YouTube 帳戶,YouTube Content ID API 則可讓 YouTube 使用者與 YouTube 的版權管理系統互動。不過,Live Streaming API 的所有資源僅用於建立及管理現場直播。
本文件可協助開發人員編寫應用程式,以便進行 YouTube 現場直播。說明 YouTube 和 API 本身的基本概念。並概略介紹 API 支援的各種功能。
核心概念
- 廣播
- 「廣播」是指可在 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 要求
如上所述,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 頻道的內容擁有者所連結的 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 | |
liveBroadcast | |||||||
liveStream |
部分資源
這個 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 無法精確插入提示點時,Δ
是可能的時間偏移值的開始和結束時間五秒的緩衝區。例如:
- 廣播訊息有五分鐘的測試階段。
- 廣播串流在監控串流之後延遲 60 秒。
- 廣播器在廣播轉換為
live
狀態後的四分鐘後插入提示點。(距離播送串流顯示後三分鐘後)。
在這種情況下,偏移時間的範圍可能為 [(485,000), (535,000)]
。
這些時間以毫秒指定,並使用下列值進行計算:
elapsed_time=540000
- 呼叫liveBroadcasts.cuepoint
方法時,監控串流已執行 9 分鐘 (540 秒、540000 毫秒)。broadcast_delay=60000
:廣播串流延遲了 60 秒 (60000 毫秒)。Δ=5000
:無法穩定插入提示點時的五秒緩衝區。
疑難排解與錯誤處理
下列指南說明如何解決可能發生的特定問題。您也可以���閱錯誤說明文件,查看各種 API 方法可能傳回的錯誤清單。
-
當廣播內容從某個狀態轉為另一個狀態時,在 YouTube 完成與轉換相關的動作時,可能會暫時將播送狀態指派給其他狀態。舉例來說,如果你傳送
liveBroadcasts.transition
要求,將廣播狀態從ready
變更為testing
,YouTube 就會將播送狀態設為「testStarting
」,然後完成與狀態變更相關的動作。所有動作都完成後,YouTube 就會將播送狀態更新為testing
,表示轉場完畢。如果廣播訊息進入
testStarting
或liveStarting
狀態,就需要呼叫liveBroadcasts.delete
方法,並刪除廣播訊息。接著,建立新的直播影片並繫結至直播活動,然後繼續進行測試程序。如
liveBroadcasts.transition
方法的說明文件所述,您應在呼叫該方法之前,確認繫結至廣播的串流status.streamStatus
屬性值為active
。