YouTube Live Streaming API の概要

YouTube Live Streaming API を使用すると、YouTube 上のライブイベントを作成、更新、管理できます。また、イベント(ブロードキャスト)のスケジュール設定や、実際のブロードキャスト コンテンツを表す動画ストリームとイベントとの関連付けも実行できます。

Live Streaming API は、実際には YouTube Data API と YouTube Content ID API のコンポーネントで構成されています。Data API を使用すると YouTube ユーザーは YouTube アカウントを管理でき、YouTube Content ID API を使用すると YouTube の著作権管理システムを操作できます。ただし、Live Streaming API を構成するすべてのリソースは、ライブイベントの作成と管理にのみ使用されます。

このドキュメントは、YouTube でのライブ配信を円滑にするアプリケーションを作成するデベロッパーを対象としています。このドキュメントでは、YouTube および API 自体の基本的な概念について説明します。また、API がサポートするさまざまな機能の概要についても説明します。

基本コンセプト

ブロードキャスト
ブロードキャストは、YouTube 上でリアルタイムで視聴できるイベントを表します。イベント終了後にユーザーが視聴できるよう、ブロードキャストを YouTube 動画として録画および保存することもできます。
ストリーム
ストリームは、YouTube に通知される音声動画コンテンツを識別します。各ブロードキャストは 1 つの動画ストリームに関連付けられます。
キューポイント
キューポイントは、ライブ配信に挿入できる広告ブレークを表します。

API のユースケース

アプリケーションでの API の使い方として、次のような例が挙げられます。

  • ブロードキャストのスケジュールを設定し、ブロードキャスト設定を定義する。ユーザーがアプリケーションを使用していくつかのブロードキャスト設定を事前に定義し、定義済みの設定を選んで特定のブロードキャストに適用できるようにすることができます。

  • 動画ストリームとブロードキャストを関連付ける。

  • 放送局が配信とその動画に関する情報を同時に定義できるようにする(YouTube Data API を使用)。

  • ブロードキャストの状態(testinglive など)の遷移を簡素化し、ユーザーがキューポイントを挿入できるようにします。

始める前に

  1. Google API Console へのアクセス、API キーのリクエスト、アプリケーションの登録を行うには、Google アカウントが必要です。

  2. API リクエストを送信できるようにするため、Google にアプリケーションを登録します。

  3. アプリケーションを登録したら、アプリケーションで使用するサービスとして YouTube Data API を選択します。

    1. API Console に移動し、登録したプロジェクトを選択します。
    2. [有効な API] ページにアクセスします。 API のリストで、YouTube Data API v3(YouTube コンテンツ パートナーの場合は YouTube Content ID API)のステータスが [オン] になっていることを確認します。

  4. JSON(JavaScript Object Notation)データ形式のコア コンセプトについて理解しておきます。JSON は言語に依存しない一般的なデータ形式で、任意のデータ構造をシンプルなテキストで表現します。詳しくは json.org をご覧ください。

API リクエストの承認

前述のとおり、Live Streaming API は、技術的には YouTube Data API または YouTube Content ID API の一部である機能を使用します。Content ID API を使用して、アセットのメタデータ、所有権情報、ポリシー情報を YouTube に提供できます。(アセットとは、ライブ動画ブロードキャストなどです)。また、自分の動画の申し立てや広告ポリシーの設定も行うことができます。

このセクションでは、Content ID API へのリクエストの認証要件について説明します。これは、他の Live Streaming API リクエストを承認するための要件とは異なります。

Data API の呼び出し
API リクエストは、配信元の YouTube チャンネルを所有する Google アカウントによって承認される必要があります。
Content ID API の呼び出し
API リクエストは、配信元の YouTube チャンネルを所有するコンテンツ所有者にリンクされている Google アカウントによる承認を受ける必要があります。

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

リソースとは、一意の識別子を持つ個別のデータ エンティティです。以下の表は、Live Streaming API を使用して操作するさまざまな種類のリソースを示しています。技術的には、これらのリソースはすべて YouTube Data API または YouTube Content ID API の一部として定義されます。ただし、liveBroadcastliveStreamcuepoint リソースは、ライブイベントの作成と管理にのみ使用されます。

関連情報
liveBroadcast YouTube で配信しているイベントに関する情報が含まれています。liveBroadcast リソースは YouTube 動画リソースを拡張したもので、ライブ配信に関係する動画メタデータを設定しますが、他の YouTube 動画には関係しない動画メタデータを設定します。

そのため、liveBroadcast リソースは 1 つの YouTube 動画リソースに対応します。 実際、liveBroadcast リソースと video リソースは同じ ID を共有しています。Live Streaming API を使って配信を作成したら、YouTube Data API を使って動画に関する追加のメタデータを提供できます。
liveStream YouTube に送信する動画ストリームに関する情報が含まれます。このストリームは、YouTube ユーザーにブロードキャストするコンテンツを提供します。作成した liveStream リソースは、1 つの liveBroadcast リソースだけにバインドできます。(同様に、liveBroadcast リソースは 1 つの liveStream リソースにのみバインドできます。
cuepoint ブロードキャスト動画ストリームにキューポイントを挿入します。これにより、ミッドロール挿入点が表示される場合があります。ブロードキャスト中にキューポイントを挿入するには、liveBroadcasts.cuepoint メソッドを使用します。
video 単一の YouTube 動画を表します。前述のとおり、liveBroadcast リソースは video リソースの拡張版です。YouTube Data API を使用して、収録場所やブロードキャストを視聴可能な地域など、動画に関するメタデータを更新できます。
videoAdvertisingOptions 動画(またはブロードキャスト)の広告設定を定義します。広告オプションを設定するには、YouTube Content ID API を使用します。
asset 映画やテレビ エピソードなどの知的財産を表します。この場合、ブロードキャスト動画がアセットです。YouTube Content ID API を使用して、asset リソースの作成と管理を行います。
claim 一致するアセットに動画をリンクします。YouTube Content ID API を使用して申し立てを作成し、ブロードキャスト動画の所有者であることを確認します。
policy YouTube でコンテンツを視聴できる環境、または YouTube で表示をブロックする環境を指定するルールを定義します。ブロードキャスト動画にはポリシーを適用する必要があります。また、自分のブロードキャスト動画と一致するユーザー動画に YouTube が適用するポリシーを指定することもできます。

サポートされているオペレーション

次の表は、この API がサポートするメソッドを示したものです。

運用
list 0 個以上のリソースのリストを取得(GET)します。
insert 新しいリソースを作成(POST)します。
update リクエストのデータに応じて既存のリソースを変更(PUT)します。
bind liveBroadcast リソースを liveStream リソースにリンクするか、そのようなリンクを削除します。
transition liveBroadcast リソースのステータスを変更し、新しいステータスに関連付けられたプロセスを開始します。たとえば、ブロードキャストのステータスを testing に移行すると、YouTube はそのブロードキャストのモニター ストリームへの動画の送信を開始します。
delete 特定のリソースを削除(DELETE)します。

次の表は、各種リソースでサポートされている操作を示したものです。リソースの挿入、更新、または削除を実行する操作の場合は、常にユーザーによる承認が必要になります。list メソッドは、承認済みリクエストと未承認リクエストの両方をサポートする場合があります。このようなリクエストでは、未承認のリクエストは一般公開データのみを取得し、承認済みリクエストは現在認証されているユーザーに限定された情報を取得することもできます。

サポートされている操作
list insert update bind transition cuepoint delete
liveBroadcast
liveStream

リソースのパーツ

この API ではリソースのパーツの取得が可能で、実際にこれを要求することにより、アプリケーションが不要なデータの転送、解析、保存を実行しないようにしています。このアプローチにより、API はネットワーク、CPU}、メモリの各リソースをより効率的に使用できます。

part パラメータは、YouTube Data API リソースを取得または返す API リクエストに必須のパラメータです。API レスポンスに含める最上位レベル(ネストされていない)のリソース プロパティを 1 つ以上指定します。たとえば、liveStream リソースは次の部分から構成されます。

  • snippet
  • cdn
  • status

これらのパーツはすべて、ネストされたプロパティを含むオブジェクトであり、API サーバーが取得する(または取得しない)メタデータ フィールドのグループと考えることができます。そのため、part パラメータでは、アプリケーションが実際に使用するリソース コンポーネントを選択する必要があります。この要件は次の 2 つの重要な目的を果たします。

  • アプリケーションが使用しないメタデータ フィールドの取得に API サーバーが時間を費やすのを防ぐことで、反応時間を短縮できます。
  • アプリケーションが取得する不要なデータの量を低減(または排除)することで、帯域幅使用量を節減できます。

今後リソースのパーツが追加された場合でも、アプリケーションがサポートしていない新たに導入されたプロパティをリクエストすることはないため、上記の利点が損なわれることはありません。

おすすめの方法やお役立ち情報

コンテンツの申し立て

ブロードキャスト中に広告を表示する場合、イベントの開始前にブロードキャスト動画に対して申し立てを行う必要があります。コンテンツについて申し立てを行うには、Content ID プログラムに参加している YouTube コンテンツ パートナーである必要があります。

ライブ ブロードキャスト動画と通常の動画では、申し立てのプロセスが少し異なります。ライブ動画の申し立てでは、動画を作成する前に申し立てを行う必要があります。API はこれをサポートしています。ブロードキャストのライフサイクルのドキュメントでは、クレームを作成できるようにする YouTube Content ID API 呼び出しについて説明しています。

コンテンツのプレビューとテスト

YouTube で受信した動画のインバウンド ストリームは、次の 2 種類のアウトバウンド ストリームのいずれかで動画をブロードキャストできます。

  • 監視ストリームでは動画ブロードキャストをプレビュー(およびテスト)できます。このストリームは所有者のみがアクセスできる非公開ストリームです。ブロードキャストのモニター ストリームが有効になっている場合にのみ、ブロードキャストを testing フェーズに移行できます。監視ストリームでは広告休憩は表示されません。

  • ブロードキャスト ストリームはユーザーが視聴可能なストリームです。ブロードキャストのプライバシー ステータスは、publicprivateunlisted のいずれかに設定できます。(非公開ブロードキャストは明示的に招待されたユーザーのみが視聴できるのに対して、限定公開ブロードキャストは視聴用のリンクを知っているユーザーであれば誰でも視聴できます)。

    ブロードキャスト ストリームは、監視ストリームと同時に実行されないように遅延させることができます。ブロードキャスト ストリームを遅延させると、ブロードキャストにキューポイントを挿入してよりきめ細かくコントロールできます。

    ただしブロードキャスト ストリームを遅延させると、ライブのプレゼンターが視聴中のユーザーとやり取りすることが難しくなります。また、視聴者がそのブロードキャスト以外のソースからイベントに関する重要な情報を見つける可能性が高くなります。たとえば、60 秒の遅延でスポーツ イベントをブロードキャストすると、視聴者はそのブロードキャストで決定的瞬間を目撃する前に、他のリアルタイム ニュース ソースからその情報を知ってしまう可能性があります。

監視ストリームは、ブロードキャストするコンテンツをテストする目的で有効にすることをお勧めします。また、ユーザーとのやり取りやイベントのリアルタイム ブロードキャストを重視するか、それよりもキューポイントのタイミングを細かくコントロールすることを優先させるかどうかも選択する必要があります。

ブロードキャスト ストリーム中のミッドロール広告の表示

ブロードキャスト中、キューポイントを挿入して、ブロードキャストの可能な限り早い時間または指定された時間に広告ブレークを開始するよう指定できます。ミッドロール挿入点を設定すると、配信中に YouTube がミッドロール広告を表示できるようになります。

ミッドロール挿入点には次の特徴があります。

  1. 有効期間が事前定義されており、cuepoint リソースの durationSecs プロパティを使用して設定します。ミッドロール挿入点が終了すると、視聴者はライブ配信に戻ります。

  2. 広告ブレークが発生した場合、キューポイントが挿入された時点で、ブロードキャストを視聴している視聴者に対してのみ広告が動画プレーヤーで再生されます。ブロードキャストが再生されているページを視聴者が更新した場合や、キューポイントを挿入した後にユーザーがブロードキャストの視聴を開始した場合、広告は実行されません。

以下のステップは、ブロードキャスト中に広告休憩を挿入するためのベスト プラクティスです。

時間オフセットを設定する

キューポイントを挿入するときは、すぐに挿入するか、ブロードキャストの特定のポイントに挿入するかを指定できます。オプションは、動画のブロードキャスト ストリームが遅延するかどうかによって異なります。

  • ブロードキャスト ストリームを遅延させない場合は、キューポイントをすぐに挿入するか、walltimeMs プロパティを使用して特定の時間に広告ブレークを開始できます。

    • ミッドロール挿入点をすぐに開始するには、liveBroadcasts.cuepoint メソッドを呼び出します。リクエスト本文のリソースで、insertionOffsetTimeMs プロパティの値を 0 に設定するか、このプロパティに値を指定せず、walltimeMs プロパティの値も指定しないでください。

      重要: 表示される広告コンテンツはすぐに視聴者に表示されません。広告コンテンツがユーザーに表示されるまで 30 秒ほどかかる場合があります。その間もブロードキャスト ストリームは視聴者に表示されますが、監視ストリームではなく実際に広告コンテンツが表示されるタイミングを確認するには、ブロードキャスト ストリームを視聴する必要があります。

    • 特定の時間にミッドロール挿入点を開始するには、liveBroadcasts.cuepoint メソッドを呼び出し、walltimeMs プロパティを使用して目的の時間を指定します。プロパティ値は、エポック タイムスタンプを表す整数です。

  • ブロードキャスト ストリームが遅延する場合は、前述のようにキューポイントをすぐに挿入するか、前述の方法でクロック時刻を指定するか、時間オフセットを指定して広告ブレークの開始タイミングを指定できます。時間オフセットは、ブロードキャスト内で視聴者に広告が表示される時点を指定します。

    このオフセット値は、ブロードキャストのモニター ストリームの先頭からのミリ秒単位で測定されます。ブロードキャストにテストフェーズがある場合は、ブロードキャストが testing ステータスに移行するとモニター ストリームが開始されます。それ以外の場合は、ブロードキャストが live ステータスに移行すると、モニター ストリームが開始されます。

    キューポイントを挿入する場合は、cuepoint リソースの insertionOffsetTimeMs プロパティを目的のオフセットに設定します。

時間オフセット値を計算する

オフセット値を取得するには、モニター ストリームを再生するプレーヤーの YouTube Player API の getCurrentTime 関数を呼び出します。取得した値を使用して、その時点のブロードキャスト ストリームにキューポイントを挿入します。

オフセット値の範囲は、次のように計算できます。

[(elapsed_time - broadcast_delay + Δ), (elapsed_time - Δ)]

Δ は、YouTube がキューポイントを正確に挿入できない場合に考えられる時間オフセットの開始時と終了時に 5 秒間のバッファです。例:

  • ブロードキャストに 5 分間のテスト フェーズがある。
  • ブロードキャスト ストリームは監視ストリームよりも 60 秒遅延している。
  • ブロードキャスターは、ブロードキャストが live ステータスに移行してから 4 分後にキューポイントを挿入します。(つまり、ブロードキャスト ストリームの表示開始から 3 分後に該当する)。

この場合、許容されるオフセット時間の範囲は [(485,000), (535,000)] です。

時間はミリ秒単位で指定します。この計算に使用された値は次のとおりです。

  • elapsed_time=540000liveBroadcasts.cuepoint メソッドが呼び出されたときに、モニター ストリームが 9 分間(540 秒、540, 000 ミリ秒)実行された。
  • broadcast_delay=60000 – ブロードキャスト ストリームが 60 秒(60, 000 ミリ秒)遅延している。
  • Δ=5000 – キューポイントを確実に挿入できない場合の 5 秒のバッファ。

トラブルシューティングとエラー処理

次のガイドラインは、特定の問題が発生した場合の解決方法を示したものです。各 API メソッドから返される可能性のあるエラーの一覧については、エラー ドキュメントも参照してください。

  • ブロードキャストのステータスが別のステータスに移行する場合は、その移行に関連するアクションを YouTube が完了するまで、一時的に他のステータスが割り当てられることがあります。たとえば、ブロードキャストのステータスを ready から testing に変更する liveBroadcasts.transition リクエストを送信すると、YouTube はブロードキャストのステータスを testStarting に設定し、ステータスの変更に関連するアクションを完了します。これらのアクションがすべて完了すると、YouTube はブロードキャストのステータスを testing に更新し、移行が完了したことを示します。

    ブロードキャストが testStarting ステータスまたは liveStarting ステータスで停止する場合は、liveBroadcasts.delete メソッドを呼び出してブロードキャストを削除する必要があります。次に新しいブロードキャストを作成し、ライブ ストリームにバインドして、テスト プロセスを続行します。

    liveBroadcasts.transition メソッドのドキュメントに記載されているとおり、ブロードキャストにバインドされているストリームの status.streamStatus プロパティの値が active であることを確認したうえで、そのメソッドを呼び出す必要があります。