ブロードキャストのライフサイクル

はじめに

このドキュメントでは、YouTube Live Streaming API と YouTube Content ID API を使用して作成、管理される YouTube のライブ配信のライフサイクルについて説明します。

リソースとリソースの種類

スタートガイドで説明したように、リソースは固有識別子を持つ個別のデータ エンティティです。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 に設定する必要があります。これらは、両方のプロパティのデフォルト値です。

  • 録画したブロードキャストから参照を作成する場合は、ブロードキャストの contentDetails.recordFromStart プロパティを true に設定する必要があります。ブロードキャストの終了直後に録画した動画を再生できるようにするには、contentDetails.enableDvr プロパティを true に設定する必要があります。（これらのプロパティのデフォルト値はどちらも true です）。

  • ブロードキャストを視聴できるリージョンを制限する場合は、contentDetails.availabilityConfig プロパティを設定します。このプロパティを使用すると、特定の地域をブロックするか、利用可能な地域を定義済みのリストに制限できます。リージョンの可用性の時間枠を指定することもできます。

  • 必要に応じて、snippet.categoryId プロパティを使用して、ブロードキャストの動画カテゴリを指定できます。指定しない場合、カテゴリはデフォルトで Entertainment になります。

  • ブロードキャストのステータスが 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 に送信できます。このリソースは、送信するコンテンツを記述します。各ブロードキャストは、1 つのストリームに関連付ける必要があります。

liveStreams.insert メソッドを呼び出して、イベントの動画ストリームを作成します。ストリームを作成する際は、以下のプロパティの値を設定する必要があります。

ストリームのタイトルを除き、これらの値はストリームの作成後に更新できません。変更する必要がある場合は、この手順を繰り返して別のストリームを作成する必要があります。このプロセスについては、このドキュメントの後半のステップ 3.5 で詳しく説明します。

次のプロパティの値を設定することもできます。

  • snippet.description - ストリームのタイトルと同様に、ストリームの説明はストリームの作成後に更新できます。タイトルも説明も YouTube ユーザーには表示されません。

  • [contentDetails.isReusable](

    /youtube/data/live/reference/rest/v3/liveStreams#contentDetails.isReusable)

    ストリームが再利用可能かどうかを示します。再利用可能な場合、複数のブロードキャストにバインドできます。このプロパティの値は、チャンネルの liveBroadcast リソースと liveStream リソースの間に多対 1 の関係があるか、1 対 1 の関係があるかを効果的に決定します。

    • プロパティのデフォルト値 true を使用する場合は、チャンネルのすべてのブロードキャストに同じ liveStream リソースを使用できます。つまり、ブロードキャストごとにこのステップ（1.2）を繰り返す必要はありません。代わりに、後続のブロードキャストでストリーム ID を再利用できます。
    • プロパティ値を false に設定した場合は、ブロードキャストごとに新しいストリームを作成する必要があります。

API リクエストをストリームに送信すると、API レスポンスに作成した liveStream リソースが含まれます。コードは、そのリソースから id を抽出して保存する必要があります。この値は、今後の API リクエストでストリームを識別するために必要になります。

ステップ 1.3: ブロードキャストをストリームにバインドする

liveBroadcast リソースと liveStream リソースを作成したら、liveBroadcasts.bind メソッドを使用して 2 つを関連付ける必要があります。この操作により、YouTube に送信する動画ビットが、その動画のイベント ブロードキャストにリンクされます。

liveBroadcasts.bind メソッドを呼び出す際に、id パラメータをステップ 1.1 で取得したブロードキャスト ID に設定し、streamId パラメータをステップ 1.2 で取得したストリーム ID に設定します。

ステージ 2: コンテンツの申し立て

ブロードキャスト中に広告を表示する場合は、イベントが始まる前にブロードキャスト動画を申し立てる必要があります。 次の手順に沿って、ブロードキャスト、動画、広告を設定します。 なお、ブロードキャスト所有者のチャンネルは、広告を表示する資格を満たしている必要があります。

このステージで説明する API 呼び出しはすべて、YouTube Content ID API で定義されています。

ステップ 2.1: アセットを作成する

asset リソースは、知的財産の一部を表します。この場合はブロードキャストがアセットになります。assets.insert メソッドを呼び出してアセットを作成します。

API レスポンスには、作成した asset リソースが含まれます。今後の API リクエストでアセットを識別するためにその値が必要になるため、コードでそのリソースから id を抽出して保存する必要があります。

ステップ 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 プロパティの値を抽出します。この値には、モニターストリームを表示する YouTube プレーヤーを埋め込むために必要な HTML が含まれています。

ステップ 3.2: 動画を開始する

動画ストリームへの動画の転送を開始します。

ステップ 3.3: 動画ストリームがアクティブであることを確認する

liveStreams.list メソッドを呼び出して、ブロードキャストに関連付けられた liveStream リソースを取得します。status.streamStatus プロパティの値が active であることを確認します。これは、YouTube サーバーがエンコーダからデータを正しく受信していることを示します。

ステップ 3.4: ブロードキャストのステータスをテストに移行する

liveBroadcasts.transition メソッドを呼び出して、ブロードキャストのステータスを更新します。id パラメータ値をステップ 1.1 で取得したブロードキャスト ID に設定し、broadcastStatus パラメータ値を testing に設定します。

liveBroadcasts.transition メソッドを呼び出した後、その移行が完了するまでに数秒から 1 分ほどかかることがあります。この間、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 秒待つ必要があります。移行には最大 1 分かかることがあります。この間、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 で説明したように、ブロードキャストが完了するまで待ってから参照を作成する必要があります。