この API は、ライブ配信を「子ども向け」としてマークする機能をサポートするようになりました。また、
liveBroadcast
リソースには、そのライブ配信の「子ども向け」ステータスを識別するプロパティが含まれるようになりました。YouTube API サービス利用規約とデベロッパー ポリシーも 2020 年 1 月 10 日に更新されました。詳細については、YouTube Live Streaming API サービスのリビジョン履歴と YouTube API サービスの利用規約をご覧ください。liveBroadcast
リソースは、YouTube でライブ動画を介してストリーミングされるイベントを表します。
メソッド
この API は、liveBroadcasts
リソースの次のメソッドをサポートしています。
- list
- API リクエスト パラメータに一致する YouTube ブロードキャストのリストを返します。今すぐ試す
- insert
- ブロードキャストを作成します。今すぐ試す
- update
- ブロードキャストを更新します。たとえば、
liveBroadcast
リソースのcontentDetails
オブジェクトで定義されたブロードキャスト設定を変更できます。こちらから今すぐお試しください。 - delete
- ブロードキャストを削除します。今すぐ試す
- bind
- YouTube ブロードキャストをストリームにバインドするか、ブロードキャストとストリーム間の既存のバインドを削除します。ブロードキャストには 1 つの動画ストリームのみをバインドできますが、動画ストリームは複数のブロードキャストにバインドできます。今すぐ試す
- transition
- YouTube ライブ配信のステータスを変更し、新しいステータスに関連するプロセスを開始します。たとえば、ブロードキャストのステータスを
testing
に変更すると、YouTube はブロードキャストのモニター ストリームに動画の送信を開始します。このメソッドを呼び出す前に、ブロードキャスト バインド ストリームのstatus.streamStatus
プロパティの値がactive
であることを確認する必要があります。今すぐお試しください。 - キューポイント
- ライブ配信にキューポイントを挿入します。キューポイントによってミッドロール挿入点がトリガーされることがあります。
リソース表現
次の JSON 構造は、liveBroadcasts
リソースの形式を示しています。
{ "kind": "youtube#liveBroadcast", "etag": etag, "id": string, "snippet": { "publishedAt": datetime, "channelId": string, "title": string, "description": string, "thumbnails": { (key): { "url": string, "width": unsigned integer, "height": unsigned integer } }, "scheduledStartTime": datetime, "scheduledEndTime": datetime, "actualStartTime": datetime, "actualEndTime": datetime, "isDefaultBroadcast": boolean, "liveChatId": string }, "status": { "lifeCycleStatus": string, "privacyStatus": string, "recordingStatus": string, "madeForKids": string, "selfDeclaredMadeForKids": string, }, "contentDetails": { "boundStreamId": string, "boundStreamLastUpdateTimeMs": datetime, "monitorStream": { "enableMonitorStream": boolean, "broadcastStreamDelayMs": unsigned integer, "embedHtml": string }, "enableEmbed": boolean, "enableDvr": boolean, "recordFromStart": boolean, "enableClosedCaptions": boolean, "closedCaptionsType": string, "projection": string, "enableLowLatency": boolean, "latencyPreference": boolean, "enableAutoStart": boolean, "enableAutoStop": boolean }, "statistics": { "totalChatCount": unsigned long }, "monetizationDetails": { "cuepointSchedule": { "enabled": boolean, "pauseAdsUntil": datetime, "scheduleStrategy": string, "repeatIntervalSecs": unsigned integer, } } } }
プロパティ
次の表は、このリソースで使用されているプロパティの定義を示したものです。
プロパティ | |
---|---|
kind |
string API リソースのタイプを識別します。値は youtube#liveBroadcast になります。 |
etag |
etag このリソースの Etag。 |
id |
string ブロードキャストを一意に識別するために YouTube が割り当てる ID。 |
snippet |
object snippet オブジェクトには、タイトル、説明、開始時間、終了時間など、イベントに関する基本的な詳細情報が含まれます。 |
snippet.publishedAt |
datetime YouTube のライブ配信スケジュールに配信が追加された日時。値は ISO 8601( YYYY-MM-DDThh:mm:ss.sZ )形式で指定します。 |
snippet.channelId |
string YouTube がブロードキャストを公開しているチャンネルを一意に識別するために使用する ID。 |
snippet.title |
string ブロードキャストのタイトル。なお、ブロードキャストでは 1 つの YouTube 動画のみを配信できます。このフィールドは、ブロードキャスト リソースを変更するか、対応する動画リソースの title フィールドを設定することで設定できます。 |
snippet.description |
string ブロードキャストの説明。 title と同様に、このフィールドは、ブロードキャスト リソースを変更するか、対応する動画リソースの description フィールドを設定することで設定できます。 |
snippet.thumbnails |
object ブロードキャスト関連のサムネイル画像のマップ。このオブジェクト内のネストされたオブジェクトごとに、キーはサムネイル画像の名前で、値はサムネイルに関するその他の情報が含まれるオブジェクトです。 |
snippet.thumbnails.(key) |
object 有効なキー値は次のとおりです。
|
snippet.thumbnails.(key).url |
string 画像の URL。 |
snippet.thumbnails.(key).width |
unsigned integer 画像の幅。 |
snippet.thumbnails.(key).height |
unsigned integer 画像の高さ。 |
snippet.scheduledStartTime |
datetime ブロードキャストの開始日時。値は ISO 8601( YYYY-MM-DDThh:mm:ss.sZ )形式で指定します。クリエイター ツールでは、開始時間をスケジュール設定せずにライブ配信を作成できます。この場合、チャンネル所有者が配信を開始するたびに配信が開始されます。これらのブロードキャストでは、datetime の値は UNIX 時刻のゼロに対応します。この値を API または YouTube Studio で変更することはできません。 |
snippet.scheduledEndTime |
datetime ブロードキャストの終了日時。値は ISO 8601( YYYY-MM-DDThh:mm:ss.sZ )形式で指定します。liveBroadcast リソースでこのプロパティの値が指定されていない場合、ブロードキャストは無期限に続行するようにスケジュールされます。同様に、このプロパティの値を指定しない場合、YouTube はライブ配信が無期限に続くものとして扱います。 |
snippet.actualStartTime |
datetime ブロードキャストの実質的な開始日時。この情報は、ブロードキャストの状態が live の場合にのみ使用できます。値は ISO 8601(YYYY-MM-DDThh:mm:ss.sZ )形式で指定します。 |
snippet.actualEndTime |
datetime ブロードキャストの実質的な終了日時。この情報は、ブロードキャストの状態が complete になった場合にのみ利用できます。値は ISO 8601(YYYY-MM-DDThh:mm:ss.sZ )形式で指定します。 |
snippet.isDefaultBroadcast |
boolean
このプロパティは 2020 年 9 月 1 日以降に非推奨となります。その時点から、チャンネルでライブ配信が有効になっている場合、デフォルトのストリームとデフォルトのブロードキャストの作成は停止されます。詳しくは、サポート終了のお知らせをご覧ください。
このプロパティは、このブロードキャストがデフォルトのブロードキャストかどうかを示します。デフォルトのブロードキャストの機能 YouTube チャンネルでライブ配信が有効になっている場合、YouTube はチャンネルのデフォルトのストリームとデフォルトのブロードキャストを作成します。ストリームは、チャンネル所有者がライブ動画を YouTube に送信する方法を定義します。ブロードキャストとは、視聴者がデフォルトのストリームを視聴する方法です。チャンネル所有者は、 liveStreams.list メソッドと liveBroadcasts.list メソッドを使用してこれらのリソースを特定できます。チャンネルがデフォルト ストリームへの動画ストリーミングを開始すると、その動画はチャンネルのデフォルト ブロードキャスト上に表示されます。配信が終了すると、完了したブロードキャストが YouTube 動画に変換され、その動画に YouTube 動画 ID が割り当てられます。 変換が完了すると、その動画はチャンネル内のアップロード動画リストに追加されます。動画は放送終了直後には視聴できません。遅延時間は放送の実際の長さに関連しています。 |
snippet.liveChatId |
string ブロードキャストの YouTube チャットの ID。この ID を使用すると、 liveChatMessage リソースのメソッドを使用して、チャット メッセージを取得、挿入、削除できます。チャット モデレーターの追加や削除、ライブチャットへの参加を禁止するユーザーの指定、既存の禁止措置の解除も可能です。 |
status |
object status オブジェクトには、イベントのステータスに関する情報が含まれます。 |
status.lifeCycleStatus |
string ブロードキャストのステータス。ステータスは、API の liveBroadcasts.transition メソッドを使用して更新できます。このプロパティの有効な値は次のとおりです。
|
status.privacyStatus |
string ブロードキャストのプライバシー ステータス。なお、ライブ配信は 1 つの YouTube 動画を表すため、プライバシー設定は動画でサポートされている設定と同じです。また、ブロードキャスト リソースを変更するか、対応する動画リソースの privacyStatus フィールドを設定して、このフィールドを設定できます。このプロパティの有効な値は次のとおりです。
|
status.recordingStatus |
string ブロードキャストの録画ステータス。 このプロパティの有効な値は次のとおりです。
|
status.madeForKids |
boolean この値は、ブロードキャストが子ども向けとして指定されているかどうかを示します。このプロパティの値は読み取り専用です。 |
status.selfDeclaredMadeForKids |
boolean liveBroadcasts.insert リクエストで、このプロパティを使用すると、チャンネル所有者はブロードキャストを子ども向けとして指定できます。liveBroadcasts.list リクエストでは、チャンネル所有者が API リクエストを承認した場合にのみ、プロパティ値が返されます。 |
contentDetails |
object contentDetails オブジェクトには、イベントの動画コンテンツに関する情報が含まれます。たとえば、埋め込み動画プレーヤーでコンテンツを表示できるかどうか、アーカイブされるかどうか、イベント終了後に視聴できるかどうかなどです。 |
contentDetails.boundStreamId |
string この値は、ブロードキャストにバインドされた live stream を一意に識別します。 |
contentDetails.boundStreamLastUpdateTimeMs |
datetime boundStreamId が参照するライブ ストリームが最後に更新された日時。 |
contentDetails.monitorStream |
object monitorStream オブジェクトには、モニター ストリームに関する情報が含まれます。ブロードキャスターは、ブロードキャスト ストリームを一般公開する前に、この情報を使用してイベント コンテンツを確認できます。 |
contentDetails.monitorStream.enableMonitorStream |
boolean この値は、ブロードキャストに対してモニター ストリームが有効かどうかを決定します。モニター ストリームが有効になっている場合、YouTube はブロードキャスター専用の特別なストリームでイベント コンテンツをブロードキャストします。ブロードキャスターは、このストリーミングを使用してイベント コンテンツを確認したり、キューポイントを挿入する最適なタイミングを特定したりできます。 ブロードキャストに testing ステージを設定する場合や、イベントにブロードキャストの遅延を設定する場合は、この値を true に設定する必要があります。また、このプロパティの値が true の場合、ブロードキャストを live 状態に移行する前に、ブロードキャストを testing 状態に移行する必要があります。(プロパティの値が false の場合、ブロードキャストには testing ステージを設定できないため、ブロードキャストを live 状態に直接移行できます)。update a broadcast の場合、API リクエストの part パラメータ値に contentDetails 部分が含まれている場合は、このプロパティを設定する必要があります。ただし、insert a broadcast の場合、このプロパティは省略可能で、デフォルト値は true です。重要: ブロードキャスト ステータスが testing または live になると、このプロパティを更新できなくなります。 |
contentDetails.monitorStream.broadcastStreamDelayMs |
unsigned integer enableMonitorStream プロパティを true に設定した場合、このプロパティによってライブ放送の遅延時間が決まります。update a broadcast を設定する際に、API リクエストの part パラメータ値に contentDetails 部分が含まれている場合は、このプロパティを設定する必要があります。ただし、insert a broadcast の場合、このプロパティは省略可能で、デフォルト値は 0 です。この値は、ブロードキャスト ディレイがないことを示します。注: ブロードキャスト状態が testing または live になると、このプロパティを更新できなくなります。 |
contentDetails.monitorStream.embedHtml |
string モニター ストリームを再生するプレーヤーを埋め込む HTML コード。 |
contentDetails.enableEmbed |
boolean この設定は、埋め込みプレーヤーでブロードキャスト動画を再生できるかどうかを示します。動画をアーカイブ( enableArchive プロパティを使用)することを選択した場合、この設定はアーカイブされた動画にも適用されます。update a broadcast の場合、API リクエストの part パラメータ値に contentDetails 部分が含まれている場合は、このプロパティを設定する必要があります。ただし、insert a broadcast の場合、このプロパティは省略可能で、デフォルト値は true です。注: ブロードキャスト ストリームが testing または live の状態になると、このプロパティを更新できなくなります。 |
contentDetails.enableDvr |
boolean この設定では、視聴者が動画の視聴中に DVR コントロールを利用できるかどうかを指定します。DVR コントロールを使用すると、視聴者はコンテンツを一時停止、巻き戻し、早送りして動画の再生を操作できます。このプロパティのデフォルト値は true です。update a broadcast の場合、API リクエストの part パラメータ値に contentDetails 部分が含まれている場合は、このプロパティを設定する必要があります。ただし、insert a broadcast の場合、このプロパティは省略可能で、デフォルト値は true です。重要: 放送終了直後に再生を開始できるようにするには、値を true に設定し、enableArchive プロパティの値も true に設定する必要があります。また、ブロードキャスト メッセージが testing 状態または live 状態になると、このプロパティを更新することはできません。 |
contentDetails.recordFromStart |
boolean この設定は、イベントのステータスがライブに変わった後に YouTube が配信の録画を自動的に開始するかどうかを指定します。 このプロパティのデフォルト値は true です。ライブ配信の録画を無効にすることをブロードキャスト チャンネルが許可されている場合にのみ、false に設定できます。チャンネルに録画を無効にする権限がなく、 recordFromStart プロパティを false に設定してブロードキャストを挿入しようとすると、API から Forbidden エラーが返されます。また、チャンネルにその権限がない場合に、recordFromStart プロパティを false に設定するようにブロードキャストを更新しようとすると、API から modificationNotAllowed エラーが返されます。update a broadcast の場合、API リクエストの part パラメータ値に contentDetails 部分が含まれている場合は、このプロパティを設定する必要があります。ただし、insert a broadcast の場合、このプロパティは省略可能で、デフォルト値は true です。重要: 放送終了直後に再生を開始できるようにするには、 enableDvr プロパティの値を true に設定する必要があります。このプロパティの値を true に設定しても、enableDvr プロパティを true に設定していない場合、アーカイブされた動画を再生できるようになるまでに 1 日ほどかかることがあります。注: ブロードキャスト ストリームが testing または live の状態になると、このプロパティを更新できなくなります。 |
contentDetails.enableClosedCaptions |
boolean このプロパティは 2015 年 12 月 17 日をもって非推奨になりました。代わりに contentDetails.closedCaptionsType プロパティを使用してください。この設定は、このブロードキャストで HTTP POST 字幕を有効にするかどうかを示します。このプロパティをすでに使用している API クライアントの場合:
|
contentDetails.closedCaptionsType |
string 注: このプロパティは contentDetails.enableClosedCaptions プロパティに代わるものです。このプロパティは、ブロードキャストに対して字幕が有効になっているかどうか、有効になっている場合はどのような種類の字幕を提供しているかを示します。
|
contentDetails.projection |
string このブロードキャストの投影形式。このプロパティのデフォルト値は rectangular です。このプロパティの有効な値は次のとおりです。
|
contentDetails.enableLowLatency |
boolean このブロードキャストを低レイテンシ ストリーミング用にエンコードするかどうかを示します。低レイテンシ ストリームを使用すると、ブロードキャストを視聴しているユーザーに動画が表示されるまでの時間が短縮されますが、ストリームの視聴者の解像度に影響することもあります。 |
contentDetails.latencyPreference |
string このブロードキャストに対して使用するレイテンシ設定を示します。このプロパティは、 ultraLow をサポートしていない enableLowLatency の代わりに使用できます。低遅延のストリームでは、ブロードキャストを視聴するユーザーに動画が表示されるまでの時間を短縮できますが、再生の滑らかさにも影響します。 超低遅延のストリームは、動画が表示されるまでの時間をさらに短縮するため、視聴者とのやり取りが容易になります。ただし、超低遅延は
|
contentDetails.enableAutoStart |
boolean バインドされた live stream で動画のストリーミングを開始したときに、このブロードキャストを自動的に開始するかどうかを示します。 |
contentDetails.enableAutoStop |
boolean チャンネル所有者がバインドされた動画ストリームで動画のストリーミングを停止してから 1 分後に、このブロードキャストを自動的に停止するかどうかを示します。 |
statistics |
object statistics オブジェクトには、ライブ配信に関連する統計情報が含まれます。これらの統計情報の値は配信中に変更される可能性があり、取得できるのは配信中のみです。 |
statistics.totalChatCount |
unsigned long 配信に関連付けられているチャット メッセージの合計数。このプロパティとその値は、ブロードキャストがユーザーに表示され、チャット機能が有効で、メッセージが 1 つ以上ある場合に存在します。このプロパティは、ブロードキャストの終了後に値を指定しません。そのため、このプロパティでは終了したライブ配信のアーカイブ動画のチャット メッセージ数は識別されません。 |
monetizationDetails |
object monetizationDetails オブジェクトには、広告オートマタがオンになっているかどうか、ミッドロール広告の挿入が遅れているかどうかなど、ストリームの収益化の詳細に関する情報が含まれます。 |
monetizationDetails.cuepointSchedule |
object cuepointSchedule オブジェクトは、ブロードキャストの広告自動化設定を指定します。 |
monetizationDetails.cuepointSchedule.enabled |
boolean この値は、広告をブロードキャストに自動的に挿入するかどうかを決定します。値が true の場合、ミッドロール広告がライブ配信に自動的に挿入されます。広告の配信スケジュールは、monetizationDetails.cuepointSchedule オブジェクトの他のフィールドの値によって決まります。 |
monetizationDetails.cuepointSchedule.pauseAdsUntil |
datetime この値は、指定した日時まで YouTube がミッドロール広告をブロードキャスト内に挿入しないように指定します。値は ISO 8601(YYYY-MM-DDThh:mm:ss.sZ)形式で指定します。広告を一時停止するには、値を将来の日時(タイムスタンプ)に設定する必要があります。また、フィールド値を近い将来の日時(タイムスタンプ)に設定して、時間が経過したときに広告を一時停止解除することもできます。 |
monetizationDetails.cuepointSchedule.scheduleStrategy |
string この値は、キューポイントのスケジュール設定に YouTube が従う戦略を指定します。有効な値は次のとおりです。
|
monetizationDetails.cuepointSchedule.repeatIntervalSecs |
unsigned integer この値は、ブロードキャスト中の自動広告挿入の間隔を秒単位で指定します。たとえば、値が 300 の場合、YouTube は 5 分間隔でミッドロール広告のキューポイントを挿入できます。この値は、連続するキューポイントを開始するまでの時間を指定します。つまり、間隔は 1 つのキューポイントの終了から次のキューポイントの開始まで測定されるわけではありません。 |