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

はじめに

このドキュメントでは、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 です）。

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

    • プロパティのデフォルト値である 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 リソースが含まれます。このリソースから 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 プロパティの値を抽出します。この値には、モニターストリームを表示する 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: 参照の作成

ライブ録画が完了したら、録画した動画から参照を作成できます。このアクションは、ブロードキャストに一致するユーザー アップロード動画を検索し、ステップ 2.3 で設定した一致ポリシーに従って処理するよう YouTube に指示します。

重要: 参照を作成するには、ブロードキャストの 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 は、ブロードキャストの進行中に、一致するユーザー アップロード動画を探します。ブロードキャストの開始前にリファレンスを作成すると、ブロードキャストの録画が自動的にオンになります。リファレンスの作成後に録画をオフにすることはできません。

ライブ Content ID 配信用にブロードキャストを有効にするには、ステップ 2.4 で動画の所有権を主張した後、ステップ 6.2 で説明されているアクションを試してください。パートナー アカウントがライブブロードキャストの参照を作成する承認をブロードキャストの前に受けていない場合、API は fingerprintingNotAllowed エラーを返します。その場合は、上記の手順 6.1 と 6.2 で説明したように、ブロードキャストが完了するまで待ってから参照を作成する必要があります。