はじめに
このドキュメントでは、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: ブロードキャストの準備
ステップ 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 メソッドを呼び出すと、作成した liveBroadcast リソースが API レスポンスに含まれます。コードで id を抽出し、そのリソースから保存する必要があります。この値は、今後の API リクエストでブロードキャストを識別するために必要です。（同じ ID を使用して、liveBroadcast リソースに対応する video リソースを識別することもできます）。
ステップ 1.2: ストリームを作成する
liveStream リソースを使用すると、動画を YouTube に転送できます。また、送信しているコンテンツを記述します。各ブロードキャストは 1 つのストリームに関連付けられる必要があります。
liveStreams.insert メソッドを呼び出して、イベントの動画ストリームを作成します。ストリームを作成する際は、下記のプロパティの値を設定する必要があります。
ストリームのタイトルを除き、これらの値はストリームの作成後に更新できません。変更する必要がある場合は、この手順を繰り返して別のストリームを作成する必要があります。このプロセスについては、このドキュメントの後半のステップ 3.5 で詳しく説明します。
次のプロパティの値を設定することもできます。
snippet.description- ストリームのタイトルと同様に、ストリームの作成後にストリームの説明を更新できます。YouTube のユーザーにはタイトルと説明のどちらも表示されません。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 レスポンスの処理
クレームを挿入すると、作成した claim リソースが API レスポンスに含まれます。コードで 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.3 の
liveBroadcasts.bindメソッドを呼び出します。API リクエストでは、idパラメータをステップ 1.1 で取得したidに設定します。リクエストにstreamIdパラメータを含めないでください。 -
動画ストリームを削除するには、
liveStreams.deleteメソッドを呼び出します。リクエストで、idパラメータをステップ 1.2 で取得したidに設定します。 -
手順 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 です）。
現時点では、広告のキューポイントが挿入されたときにブロードキャストを視聴していたユーザーに対して、動画プレーヤーで広告が再生されます。広告が表示されるかどうかは、広告の可用性や視聴者の広告視聴履歴など、さまざまな要因によって決まります。広告ブレークを取得したユーザーは、広告ブレークが終了するとブロードキャストに戻ります。広告が表示されていない視聴者は、広告ブレークの間も引き続きブロードキャスト ストリームを表示します。
ライブ配信の広告ブレーク中の視聴エクスペリエンスについて詳しくは、スタートガイドをご覧ください。
ステージ 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 Data API の videos.list メソッドをポーリングし、part パラメータを status に設定し、id パラメータをステップ 1.1 で保存したブロードキャスト ID に設定します。
ポーリング リクエストに対する API レスポンスには video リソースが含まれます。このリソースの status.uploadStatus プロパティの値が processed の場合は、ステップ 6.2 に進みます。
ステップ 6.2: 処理された動画から参照を作成する
参照を作成するには、Content ID API の references.insert メソッドを呼び出して、ステップ 2.4 で保存したクレーム ID に claimId パラメータを設定します。
ライブ コンテンツ ID の配信
一部の YouTube パートナーは、ブロードキャストが testing 状態に移行する前に参照を作成できますが、この機能はすべてのパートナーが利用できるわけではありません。そのフローにおいて、YouTube はライブイベントのブロードキャスト ストリームから参照を生成して継続的に更新します。さらに YouTube は、ユーザーのアップロード動画と一致するものがないかどうか検索を行っています。ブロードキャストを開始する前に参照を作成すると、ブロードキャストの記録が自動的にオンになります。また、参照の作成後に録画をオフにすることはできません。
ライブ配信で Content ID の配信を有効にするには、ステップ 2.4 の動画の申し立てを行った後に、ステップ 6.2 の手順をお試しください。ブロードキャスト ブロードキャストの前にパートナー アカウントにライブ ブロードキャストの参照の作成が承認されない場合、API は fingerprintingNotAllowed エラーを返します。その場合は、上記のステップ 6.1 と 6.2 で説明したように、ブロードキャストが完了するまで待ってから参照を作成する必要があります。