預設廣播和串流淘汰遷移指南

注意： 本指南與 2020 年 4 月 16 日發布的淘汰公告有關，該公告將於 2020 年 9 月 1 日起生效。變更實際生效的日期在下文中稱為「淘汰日期」。公告詳細說明瞭可能造成破壞的 API 變更，這項變更會影響特定 YouTube Live Streaming API 用戶端。

總覽

本指南適用於 API 用戶端應用程式的開發人員，這類應用程式會使用 YouTube 頻道的預設 liveStream 和 liveBroadcast 資源串流直播內容。這項工具旨在協助您確保應用程式能妥善處理預設廣播和預設串流淘汰作業，如果您的應用程式符合下列任一情況，就適用這項工具：

• 它會檢查 liveBroadcast 資源的 isDefaultBroadcast 屬性值。
• 它會檢查 liveStream 資源的 isDefaultStream 屬性值。

• 它會呼叫 liveBroadcasts.list 方法，並將 broadcastType 參數值設為 persistent。淘汰日期生效後：

  • 如果 broadcastType 參數值為 persistent，則 liveBroadcasts.list 方法不會傳回任何結果。
  • 如果 broadcastType 參數值為 all，則 liveBroadcasts.list 方法不會傳回在該時間之前存在的永久廣播。

如果您的應用程式受到影響，請參閱「更新應用程式」一節，瞭解應用程式可能需要進行的程序變更，以因應這項淘汰作業。該節會指出「廣播生命週期」指南中的特定步驟，如果 API 用戶端目前使用預設廣播和串流，可能不會遵循這些步驟。

異動簡介

自 2015 年起，YouTube 會在頻道啟用直播功能時，自動為頻道建立預設串流和預設直播。預設串流會永久存在，無法刪除。同樣地，預設廣播會視為「持續性」。這類資料一律存在，沒有相關聯的開始或結束時間，也不會繫結至特定事件。

自上述停用日期起，YouTube 將不再建立預設串流和廣播。這項異動會影響依賴這些資源直播內容的用戶端應用程式。此外，如果應用程式的使用者介面經過自訂，可區分這些預設資源與頻道擁有者建立的其他直播和串流，也會受到影響。

API 用戶端必須建立及管理 liveBroadcast 和 liveStream 資源，並將這些資源繫結在一起，而不是依賴預設資源。

更新應用程式

快速複習一下術語：「直播」代表可在 YouTube 上即時觀看的活動，「串流」則是將實際影片內容傳送至 YouTube 的機制。直播可以且必須繫結至一個串流。

從預設廣播遷移

在淘汰前，API 用戶端可以選擇使用頻道的預設直播，或建立特定活動的直播。預設的廣播是可重複用於多個活動的持續性資源，而活動專屬的廣播資源是單次使用的資源，對應至一個 YouTube 影片。

如果用戶端應用程式呼叫 liveBroadcasts.list 方法，並執行下列任一操作，就會使用預設廣播：

• 這會將 broadcastType 參數值設為 persistent。這項要求只會擷取預設直播。
• 這會將 broadcastType 參數值設為 all，然後在 API 回應中找出 isDefaultBroadcast 屬性值為 true 的 liveBroadcast 資源。

淘汰後，YouTube 只會支援特定活動的直播。 也就是說，用戶端應用程式必須為每個直播活動建立 liveBroadcast 資源，而不是依賴預設直播。

如要建立 liveBroadcast 資源，請呼叫 liveBroadcasts.insert 方法。如要瞭解這個程序，請參閱「廣播的生命週期」指南的步驟 1.1。

如果使用者介面尚未提供相關機制，請務必加入，讓使用者能夠區分及選取即將播出的特定活動。

從預設串流遷移

你可以透過串流將音訊/視訊內容傳輸至 YouTube，並定義將內容串流至 YouTube 的設定。如果廣播時間不同，廣播主通常會重複使用同一個串流進行多次廣播。

雖然應用程式無法使用預設串流，但可以建立可重複使用的串流，用於每次直播。如要建立 liveStream 資源，請按照「直播生命週期」指南的步驟 1.2 操作說明，呼叫 liveStreams.insert 方法。根據預設，新建立的串流可重複使用。不過，您也可以視需要將 contentDetails.isReusable 屬性設為 false，建立單次使用的串流，並在直播和串流之間建立一對一關係。

建立新直播時，除了直播標題和直播說明，你還可以設定下列四項屬性。這份清單會顯示預設串流為各項屬性使用的值，如果您要從預設串流遷移，這些值可能就是您要在用戶端應用程式中使用的設定。

• cdn.frameRate - variable
• cdn.ingestionType - rtmp
• cdn.resolution - variable
• contentDetails.isReusable
  • true

將廣播內容繫結至串流

每個 liveBroadcast 資源都必須繫結至一個串流，才能在 YouTube 上開始現場直播。(建立時，廣播不會繫結至任何串流。)

預設直播會自動處理繫結程序，與預設串流密不可分。不過，在淘汰日期之後，用戶端應用程式必須管理所有直播的程序。

如要將直播繫結至串流，請按照「直播的生命週期」指南第 1.3 節所述，呼叫 liveBroadcasts.bind 方法。

• 如果使用可重複使用的串流，只要建立一次串流，然後將所有廣播繫結至該串流即可。
• 如果未使用可重複使用的串流，則需要建立廣播和串流，然後將兩者繫結在一起。

測試直播

如果不使用預設廣播，可以選擇測試廣播。如要進行測試，請嵌入播放器，預覽廣播影片在 YouTube 觀眾眼中的樣貌，但其他觀眾看不到廣播。

如果 API 用戶端先前使用預設直播和串流，而您想在串流處理程序中加入測試階段，請參閱「直播生命週期」指南的第 3 階段。

如要測試直播，請在插入直播時，將 contentDetails.monitorStream.enableMonitorStream 屬性設為 true，並將 contentDetails.enableAutoStart 屬性設為 false。這兩個屬性的預設值。

使用自動啟動和自動停止功能

只要開始在預設串流上串流播放影片，預設直播就會自動開始。同樣地，停止串流影片後，預設直播也會結束。使用這些預設資源的每場直播工作階段，隨後都會成為頻道中的影片。

雖然自動開始和自動停止功能是預設直播的預設行為，但這些功能為選用，其他直播必須啟用。如要使用這些功能，請在插入直播時，將 contentDetails.enableAutoStart 和 contentDetails.enableAutoStop 屬性值設為 true。這些功能彼此獨立，因此您可以選擇使用其中一項，而不使用另一項。

如果未啟用新直播的自動開始和自動結束功能，API 用戶端就必須在開始和結束串流影片時，呼叫 liveBroadcasts.transition 方法來更新直播狀態。如需在廣播開始和結束時管理這些轉場效果的操作說明，請參閱「廣播生命週期」指南中的步驟 4.3和步驟 5.2。