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 を使用して)放送とその動画に関する情報を同時に定義できます。
-
ブロードキャスト状態(
testing
、live
など)間の遷移を簡略化し、ユーザーがキューポイントを挿入できるようにします。
始める前に
-
Google API Console へのアクセス、API キーのリクエスト、アプリケーションの登録には、Google アカウントが必要です。
-
API リクエストを送信できるようにするため、Google にアプリケーションを登録します。
-
アプリケーションを登録したら、アプリケーションが使用するサービスの 1 つとして YouTube Data API を選択します。
- API Console に移動し、登録したプロジェクトを選択します。
- 有効な API のページにアクセスします。 API のリストで、YouTube Data API v3 のステータスと、YouTube Content Partner の場合は YouTube Content ID API のステータスがオンになっていることを確認します。
-
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 の一部として定義されます。ただし、liveBroadcast
、liveStream
、cuepoint
リソースは、ライブイベントの作成と管理にのみ使用されます。
リソース | |
---|---|
liveBroadcast |
YouTube でブロードキャストしているイベントに関する情報が含まれています。liveBroadcast リソースは、YouTube 動画リソースを拡張し、ライブ配信に関連する動画メタデータを設定しますが、他の YouTube 動画には設定しません。したがって、 liveBroadcast リソースは 1 つの YouTube 動画リソースに対応します。実際、liveBroadcast リソースと video リソースは同じ ID を共有します。また、Live Streaming API を使用してブロードキャストを作成した後で、YouTube Data API を使用して動画に関する追加メタデータを指定できます。 |
liveStream |
YouTube に送信する動画ストリームに関する情報が含まれています。このストリームでは、YouTube ユーザーにブロードキャストされるコンテンツを提供します。作成された liveStream リソースは、単一の 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 に移行すると、そのブロードキャストのモニタリング ストリームへの動画送信が開始されます。 |
delete |
特定のリソースを削除(DELETE )します。 |
次の表は、各種リソースでサポートされている操作を示したものです。リソースの挿入、更新、または削除を実行する操作の場合は、常にユーザーによる承認が必要になります。場合によっては、list
メソッドは承認済みリクエストと未承認リクエストの両方をサポートします。未承認リクエストは、パブリック データのみを取得します。承認済みリクエストは、現在認証されているユーザーに制限された情報を取得することもできます。
サポートされている操作 | |||||||
---|---|---|---|---|---|---|---|
list | insert | update | bind | transition | cuepoint | delete | |
liveBroadcast | |||||||
ライブ配信 |
リソースのパーツ
この 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
フェーズに移行できます。監視ストリームでは広告休憩は表示されません。 -
ブロードキャスト ストリームはユーザーが視聴可能なストリームです。ブロードキャストのプライバシー ステータスは、
public
、private
、unlisted
のいずれかに設定できます。(非公開ブロードキャストは明示的に招待されたユーザーのみが視聴できるのに対して、限定公開ブロードキャストは視聴用のリンクを知っているユーザーであれば誰でも視聴できます)。ブロードキャスト ストリームは、監視ストリームと同時に実行されないように遅延させることができます。ブロードキャスト ストリームを遅延させると、ブロードキャストにキューポイントを挿入してよりきめ細かくコントロールできます。
ただしブロードキャスト ストリームを遅延させると、ライブのプレゼンターが視聴中のユーザーとやり取りすることが難しくなります。また、視聴者がそのブロードキャスト以外のソースからイベントに関する重要な情報を見つける可能性が高くなります。たとえば、60 秒の遅延でスポーツ イベントをブロードキャストすると、視聴者はそのブロードキャストで決定的瞬間を目撃する前に、他のリアルタイム ニュース ソースからその情報を知ってしまう可能性があります。
監視ストリームは、ブロードキャストするコンテンツをテストする目的で有効にすることをお勧めします。また、ユーザーとのやり取りやイベントのリアルタイム ブロードキャストを重視するか、それよりもキューポイントのタイミングを細かくコントロールすることを優先させるかどうかも選択する必要があります。
ブロードキャスト ストリーミング中にミッドロール広告を掲載する
ブロードキャスト中、キューポイントを挿入して、広告ブレークをできるだけ早く、または指定した時間に開始できます。広告ブレークにより、YouTube はブロードキャスト中にミッドロール広告を掲載できます。
ミッドロール挿入点には次の特徴があります。
-
事前に定義された期間があり、これは
cuepoint
リソースのdurationSecs
プロパティを使用して設定します。広告ブレークが終了すると、視聴者はライブ配信に戻ります。 -
広告ブレークが発生すると、キューポイントが挿入されたときにブロードキャストを視聴している視聴者に対してのみ、広告が動画プレーヤーで再生されます。視聴者がブロードキャストを再生しているページを更新したとき、またはキューポイントを挿入した後にユーザーがブロードキャストの視聴を開始したとき、広告は掲載されません。
以下のステップは、ブロードキャスト中に広告休憩を挿入するためのベスト プラクティスです。
時間オフセットの設定
キューポイントを挿入する際、キューポイントをすぐに挿入するか、ブロードキャストの特定の位置に挿入するかを指定できます。オプションは、動画のブロードキャスト ストリームが遅延しているかどうかによって異なります。
-
ブロードキャスト ストリームが遅延しない場合は、キューポイントをすぐに挿入するか、
walltimeMs
プロパティを使用して特定の時間に広告ブレークを開始できます。-
広告ブレークをすぐに開始するには、
liveBroadcasts.cuepoint
メソッドを呼び出します。リクエスト本文のリソースで、insertionOffsetTimeMs
プロパティの値を0
に設定するか、そのプロパティの値を指定せず、walltimeMs
プロパティの値を指定しないでください。重要: 生成される広告コンテンツは視聴者に表示されません。広告コンテンツがユーザーに表示されるまでに 30 秒程度の遅延が発生する場合があります。この遅延中、配信ストリームは視聴者に表示されますが、監視ストリームではなく実際に広告コンテンツが表示されるタイミングを判断するには、配信ストリームを視聴する必要があります。
-
特定の時間に広告ブレークを開始するには、
liveBroadcasts.cuepoint
メソッドを呼び出し、walltimeMs
プロパティを使用して目的の時間を指定します。プロパティ値は、エポック タイムスタンプを表す整数です。
-
広告ブレークをすぐに開始するには、
-
ブロードキャスト ストリームが遅延する場合は、上記のようにキューポイントを直ちに挿入するか、上記のように時計の時刻を指定するか、時間オフセットを指定して広告ブレークの開始タイミングを指定します。タイム オフセットでは、視聴者に広告を表示するタイミングをブロードキャストで指定します。
このオフセット値は、ブロードキャストのモニタリング ストリームの開始時点からミリ秒単位で測定されます。ブロードキャストにテストフェーズがある場合は、ブロードキャストが
testing
ステータスに遷移するとモニター ストリームが開始されます。それ以外の場合は、ブロードキャストがlive
ステータスに移行するとモニタリング ストリームが開始されます。キューポイントを挿入する場合は、
cuepoint
リソースのinsertionOffsetTimeMs
プロパティを目的のオフセットに設定します。
時間オフセット値を計算する
オフセット値を取得するには、モニタリング ストリームを再生しているプレーヤーに対して YouTube Player API の getCurrentTime
関数を呼び出します。取得した値を使用して、その時点のブロードキャスト ストリームにキューポイントを挿入します。
オフセット値の範囲は、次のように計算できます。
[(elapsed_time - broadcast_delay + Δ), (elapsed_time - Δ)]
Δ
は、キューポイントを正確に挿入できない可能性のあるタイム オフセットの開始時点と終了時点の 5 秒間のバッファです。例:
- ブロードキャストに 5 分間のテスト フェーズがある。
- ブロードキャスト ストリームは監視ストリームよりも 60 秒遅延している。
- 放送局は、ブロードキャストが
live
ステータスに遷移してから 4 分後にキューポイントを挿入します。(つまり、ブロードキャスト ストリームの表示開始から 3 分後に該当する)。
この場合、オフセット時間の範囲は [(485,000), (535,000)]
です。
時間はミリ秒単位で指定します。この計算に使用された値は次のとおりです。
elapsed_time=540000
–liveBroadcasts.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
であることを確認してください。