廣播生活

簡介

本文將逐步說明如何使用 YouTube Live Streaming API 和 YouTube Content ID API，建立及管理 YouTube 直播。

資源和資源類型

如入門指南所述，資源是具有專屬 ID 的個別資料實體。如要在 YouTube 上建立及管理直播活動，您需要使用多種資源，這些資源定義於 YouTube Data API 或 YouTube Content ID API。「YouTube Live Streaming API」標題下方列出的資源，在技術上是定義於其他 API 中，但由於這些資源僅用於直播，因此會分開列出。

YouTube Live Streaming API 資源

YouTube Data API 資源

YouTube Content ID API 資源

建立及管理現場直播

下列步驟說明如何在 YouTube 建立及管理直播活動。 步驟分為下列階段：

  1. 設定廣播
  2. 聲明內容擁有權
  3. 測試
  4. 廣播
  5. 結束廣播
  6. 建立參考檔案

第 1 階段：設定廣播

步驟 1.1：建立廣播

呼叫 liveBroadcasts.insert 方法，將廣播新增至 YouTube 的直播活動時間表。您要插入的 liveBroadcast 資源必須定義下列屬性的值。

設定廣播時，請參考下列指南：

  • 如要為廣播進行測試，在其他觀眾無法觀看廣播的情況下查看影片廣播，請將 contentDetails.monitorStream.enableMonitorStream 屬性設為 true，並將 contentDetails.enableAutoStart 屬性設為 false。這兩項屬性的預設值都是 0。

  • 如要從錄製的廣播建立參照，請將廣播的 contentDetails.recordFromStart 屬性設為 true。如要讓錄製的影片在直播結束後立即播放，請將 contentDetails.enableDvr 屬性設為 true。(這兩項屬性的預設值都是 true)。

  • 只要廣播狀態仍為 created 或 ready，您就可以更新任何 contentDetails 屬性。

  • 只要廣播狀態為 created、ready 或 testing，你就能更新廣播的排定開始時間和結束時間。

  • 你可以隨時更新廣播的標題、說明、隱私權狀態，以及廣播video資源的其他中繼資料欄位。

    注意：如果只希望特定 YouTube 使用者能觀看影片，請視需求將 status.privacyStatus 屬性值設為 unlisted 或 private。

處理 API 回應

呼叫 liveBroadcasts.insert 方法時，API 回應會包含您建立的 liveBroadcast 資源。您的程式碼應從該資源擷取並儲存 id。您需要這個值，才能在日後的 API 要求中識別廣播。(您也可以使用相同 ID，找出對應 liveBroadcast 資源的 video 資源)。

步驟 1.2：建立串流

liveStream 資源可讓你將影片傳輸至 YouTube，並說明傳輸的內容。每場播送都必須與一個串流建立關聯。

呼叫 liveStreams.insert 方法，為活動建立影片串流。建立串流時，您必須為下列屬性設定值：

除了直播標題外，直播建立後就無法更新這些值。如要變更，請重複這個步驟，建立不同的串流。本文稍後的步驟 3.5 將詳細說明這個程序。

您也可以選擇為下列屬性設定值：

  • snippet.description - 與直播標題一樣，直播說明可以在直播建立後更新。YouTube 使用者不會看到標題和說明。

  • contentDetails.isReusable - 指出串流是否可重複使用，也就是說，串流是否可繫結至多個廣播。這項屬性的值會有效決定管道在 liveBroadcast 和 liveStream 資源之間，是否具有多對一或一對一關係：

    • 如果使用 true 的屬性預設值，則可對頻道的所有廣播使用相同的 liveStream 資源。也就是說，您不必為每場直播重複執行步驟 1.2。您只需在後續的廣播中重複使用串流 ID 即可。
    • 如果將屬性值設為 false，則必須為每場直播建立新的串流。

發出 API 要求後，API 回應會包含您建立的 liveStream 資源。您的程式碼應從該資源擷取並儲存 id。您需要這個值，才能在日後的 API 要求中識別串流。

步驟 1.3：將廣播節目繫結至串流

建立 liveBroadcast 和 liveStream 資源後，您現在需要使用 liveBroadcasts.bind 方法將兩者建立關聯。這項動作會將你傳輸至 YouTube 的影片位元，連結至該影片的活動直播。

呼叫 liveBroadcasts.bind 方法時，請將 id 參數設為步驟 1.1 中取得的廣播 ID，並將 streamId 參數設為步驟 1.2 中取得的串流 ID。

第 2 階段：聲明內容擁有權

如要在直播期間顯示廣告，請務必在活動開始前聲明直播影片的擁有權。以下步驟說明這個程序。請注意，本階段討論的所有 API 呼叫都定義在 YouTube Content ID API 中。

步驟 2.1：建立資產

asset 資源代表一項智慧財產。以本例來說，資產就是你的廣播。呼叫 assets.insert 方法來建立資產。

API 回應會包含您建立的 asset 資源。您的程式碼應從該資源中擷取並儲存 id，因為您需要該值才能在日後的 API 要求中識別資產。

步驟 2.2：定義資產擁有權

資產擁有權資料會指出資產擁有者，以及擁有資產的地區。YouTube 會根據這項資料，判斷擁有者可以在何處為已聲明著作權的影片設定政策。

舉例來說，假設您有權在美國播送某項活動，而另一位播送者擁有在加拿大播送該活動的權利，那麼您和對方可以分別為播送影片，以及與播送影片相符的使用者上傳影片，定義不同的政策。在美國，系統會對相符的使用者上傳影片套用你的配對政策；在加拿大，則會套用其他擁有者的政策。

如要為資產定義擁有權地域，請呼叫 ownership.update 方法。在該要求中，將 assetId 參數設為您在步驟 2.1 中儲存的 id。

步驟 2.3：設定資產的比對政策

資產的配對政策會說明使用者上傳的影片與資產相關聯的參考檔案相符時，YouTube 應採取的行動。在這種情況下，比對政策會指出 YouTube 應如何處理與直播內容相符的上傳影片。

注意：如果你打算從廣播影片建立參考檔案，並使用該參考檔案找出與廣播內容相符的使用者上傳影片，請設定配對政策。您也可以略過這個步驟。

如要設定比對政策，請先找出要套用的政策。您可以呼叫 policies.list 方法來擷取現有政策清單，也可以呼叫 policies.insert 方法定義新政策。無論是哪種情況，您都需要擷取要套用的政策 id。

找出政策後，請呼叫 assetMatchPolicy.update 方法。在該要求中，將 assetId 參數設為您在步驟 2.1 中儲存的 id。

步驟 2.4：聲明影片著作權

在這個步驟中，您會建立版權聲明，將要播送的影片連結至在步驟 2.1 中建立的資產。這項著作權聲明會設定政策，且只會套用至你的直播影片。(與你的廣播影片相符的使用者上傳影片，適用於上一個步驟中設定的配對政策)。

如要建立聲明，請呼叫 claims.insert 方法。在您插入的 claim 資源中，需要為下列屬性設定值：

  • assetId：您在步驟 2.1 中取得這個值。
  • videoId：這是您在步驟 1.1 中取得的廣播 ID。
  • policy - 這是 policy 資源。如要套用現有政策，請將該資源的 id 屬性設為現有政策的 ID。上一個步驟說明如何擷取現有政策的 ID。
  • contentType：將這個值設為 audiovisual。

處理 API 回應

插入著作權聲明時，API 回應會包含您建立的 claim 資源。您的程式碼應從該資源擷取並儲存 id。您稍後會使用該值，從處理後的影片建立參照。

步驟 2.5：更新廣播的廣告設定

如要在觀眾開始觀看直播時放送前置廣告，或在直播期間的休息時間放送廣告，請為影片設定廣告選項。

  • 如果為直播啟用前置廣告，所有觀眾在開始觀看直播時都會看到廣告，即使是從直播中途開始觀看也一樣。
  • 如果啟用廣播的片中廣告，就能在廣播期間插入廣告提示點。

如要啟用廣告，請呼叫 videoAdvertisingOptions.update 方法。在要求中，將 videoId 參數設為您在步驟 1.1 中取得的廣播 id。使用 videoAdvertisingOption 資源的 adFormats[] 屬性，找出要啟用的廣告格式 (preroll、midroll 或 postroll)。

階段 3：測試

在這個階段，您會嵌入播放器，顯示廣播的監控串流，以便測試觀看體驗。監控串流是私人串流，可讓你預覽 YouTube 觀眾看到的廣播影片。

請注意，你必須啟用監控串流，才能測試影片廣播。根據預設，系統會啟用廣播的監控串流。建立或更新該場直播時，您可以將 contentDetails.monitorStream.enableMonitorStream 屬性設為 false，停用直播的監控串流。

步驟 3.1：嵌入監控串流播放器

使用 liveBroadcasts.list 方法擷取廣播，並擷取 contentDetails.streamDetails.monitorStreamEmbedHtml 屬性的值。這個值包含 HTML，您需要嵌入 YouTube 播放器，顯示監控畫面串流。

步驟 3.2：開始播放影片

開始傳輸影片串流中的影片。

步驟 3.3：確認影片串流已啟用

呼叫 liveStreams.list 方法，擷取與廣播相關聯的 liveStream 資源。確認 status.streamStatus 屬性的值為 active，這表示 YouTube 伺服器已正確接收編碼器傳送的資料。

步驟 3.4：將廣播狀態轉換為測試

呼叫 liveBroadcasts.transition 方法來更新廣播狀態。將 id 參數值設為步驟 1.1 中取得的廣播 ID，並將 broadcastStatus 參數值設為 testing。

呼叫 liveBroadcasts.transition 方法後，轉換作業可能需要幾秒鐘，甚至一分鐘才能完成。在這段期間，您應輪詢 API 來檢查廣播狀態。在轉換完成前，廣播的狀態會顯示為 testStarting。轉換完成後，狀態會顯示為 testing。

步驟 3.5：完成測試

如果測試順利完成，請繼續進行第 4 階段。 不過，在某些情況下，您可能需要進一步測試。舉例來說，如果測試結果顯示影片串流設定有誤，您必須先修正問題，才能繼續進行廣播。

如果影片串流設定不正確，請取消繫結 (並刪除) 現有串流，然後建立新串流。舉例來說，如果串流指定錯誤的影片格式，可能就表示設定有誤。

  1. 如要取消繫結視訊串流，請呼叫步驟 1.3 中的 liveBroadcasts.bind 方法。在 API 要求中，將 id 參數設為步驟 1.1 中取得的 id。請勿在要求中加入 streamId 參數。

  2. 如要刪除影片串流，請呼叫 liveStreams.delete 方法。在要求中，將 id 參數設為步驟 1.2 中取得的 id。

  3. 重複步驟 1.2，建立新的正確設定 liveStream 資源。然後重複步驟 1.3，將新串流繫結至廣播，並重複步驟 3.1 至 3.3，測試新串流。

步驟 3.6：啟用 autoStart 和 autoStop 屬性

順利完成測試階段後，您可以選擇在實際開始播送前，將播送的 contentDetails.enableAutoStart 和 contentDetails.enableAutoStop 屬性設為 true。測試階段前無法將這些屬性設為 true，因為測試實際上會導致廣播開始。

第 4 階段：播送

在此階段，觀眾可以觀看你的直播影片。

步驟 4.1：開始錄製影片

開始傳輸影片串流中的影片。

步驟 4.2：確認影片串流處於有效狀態

呼叫 liveStreams.list 方法，擷取與廣播相關聯的 liveStream 資源。確認 status.streamStatus 屬性的值為 active，這表示 YouTube 伺服器已正確接收編碼器傳送的資料。

步驟 4.3：將廣播狀態轉換為直播

重要事項：這個步驟會讓觀眾看到你的影片。

呼叫 liveBroadcasts.transition 方法來更新廣播狀態。將 id 參數值設為步驟 1.1 中取得的廣播 ID，並將 broadcastStatus 參數值設為 live。

如果將 liveBroadcast 資源的 contentDetails.enableAutoStart 屬性設為 true，就不需要呼叫 liveBroadcasts.transition 方法。

呼叫這個 API 後 (或如果您已將 contentDetails.enableAutoStart 屬性設為 true，則是在開始串流後)，通常需要等待 5 到 10 秒，轉換才會完成。這項程序最多可能需要一分鐘才能完成。在這段期間，您應輪詢 API 來檢查廣播狀態。在轉換完成前，廣播的狀態會顯示為 liveStarting。轉換完成後，狀態會顯示為 live，觀眾就能從監控串流的該時間點開始觀看廣播。

請注意這個指令的下列影響：

  • 如果已為廣播啟用監控串流 (請參閱步驟 3.1)，您就能在內嵌播放器中觀看監控串流。
  • 如果你已為廣播的 contentDetails.streamDetails.broadcastStreamDelayMs 屬性設定值，其他觀眾看到的廣播串流就會延遲該時間長度。

步驟 4.4：在廣播中插入廣告插播

呼叫 liveBroadcasts.cuepoint 方法來插入提示點。提示點可能會觸發廣告插播。在要求主體中提供的 cuepoint 資源中，將 durationSecs 屬性設為要顯示的休息時間長度 (以秒為單位)。(預設值為 30。)

此時，YouTube 會嘗試在影片播放器中，為插入廣告提示點時正在觀看直播的觀眾播放廣告。廣告是否會播放取決於多項因素，例如廣告供應情形和觀眾的廣告觀看記錄。廣告休息時間結束後，看到廣告休息的觀眾會返回你的廣播，而未看到廣告的觀眾則會在休息期間繼續觀看廣播串流。

如要進一步瞭解直播廣告插播期間的觀看體驗，請參閱入門指南。

第 5 階段：結束廣播

步驟 5.1：停止串流

YouTube 直播系統測試到此結束。

步驟 5.2：將廣播狀態轉換為完成

準備停止廣播時，請呼叫 API 的 liveBroadcasts.transition 方法，更新廣播的狀態。將 id 參數值設為步驟 1.1 中取得的廣播 ID，並將 broadcastStatus 參數值設為 complete。

如果已將廣播的 contentDetails.recordFromStart 和 contentDetails.enableDvr 屬性設為 true，直播活動結束後，觀眾就能立即觀看直播活動重播。

階段 6：建立參考檔案

即時錄影完成後，即可使用錄製的影片建立參考檔案。這項操作會指示 YouTube 尋找與節目相符的使用者上傳影片，並根據您在步驟 2.3 中設定的相符政策處理這些影片。

重要事項：如要建立參照，請務必將廣播的 contentDetails.recordFromStart 屬性設為 true。

步驟 6.1：輪詢 Data API，取得影片狀態

YouTube 必須先處理完畢直播或上傳的影片，你才能從該影片建立參考資料。如要判斷影片是否已完成處理，請輪詢 YouTube Data API 的 videos.list 方法，將 part 參數設為 status，並將 id 參數設為您在步驟 1.1 中儲存的廣播 ID。

API 對輪詢要求的回應會包含 video 資源。如果該資源的 status.uploadStatus 屬性值為 processed，請繼續執行步驟 6.2。

步驟 6.2：從處理後的影片建立參考檔案

如要建立參照，請呼叫 Content ID API 的 references.insert 方法，並將 claimId 參數設為您在步驟 2.4 中儲存的著作權聲明 ID。

直播內容的 Content ID 提交

部分 YouTube 合作夥伴可以在廣播轉換為 testing 狀態前建立參照，但這項功能並非適用於所有合作夥伴。在該流程中，YouTube 會在直播進行期間，從直播活動的廣播串流產生並持續更新參照內容。此外，YouTube 會在直播期間尋找相符的使用者上傳影片。請注意，在直播開始前建立參照，系統會自動為直播啟用錄製功能，且參照建立完成後，就無法關閉錄製功能。

如要啟用直播的 Content ID 放送功能，請在步驟 2.4 聲明影片著作權後，嘗試執行步驟 6.2 所述的動作。如果合作夥伴帳戶未獲准在直播前建立參照，API 會傳回 fingerprintingNotAllowed 錯誤。在這種情況下，您必須等到廣播完成 (如上述步驟 6.1 和 6.2 所述)，才能建立參照。