LiveBroadcasts

この 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
有効なキー値は次のとおりです。
  • default - デフォルトのサムネイル画像。動画（または、再生リストのアイテムや検索結果など、動画を参照するリソース）のデフォルト サムネイルは幅 120px、高さ 90px です。チャンネルのデフォルト サムネイルは幅 88px、高さ 88px です。
  • medium - サムネイル画像の高解像度バージョン。動画（または動画を参照するリソース）の場合、この画像は幅 320px、高さ 180px です。チャンネルの場合は、幅 240px、高さ 240px です。
  • high - サムネイル画像の高解像度バージョン。動画（または動画を参照するリソース）の場合、この画像は幅 480px、高さ 360px です。チャンネルの場合、幅 800px、高さ 800px です。
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 エポック時間 0 に対応しています。この値は、API またはクリエイター ツールで変更できません。
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 メソッドを使用して更新できます。

このプロパティの有効な値は次のとおりです。
  • complete - ブロードキャストが終了しました。
  • created - ブロードキャストの設定が不完全であるため、live または testing ステータスに移行する準備ができていませんが、作成されており、それ以外は有効です。
  • live - ブロードキャスト メッセージがアクティブです。
  • liveStarting - ブロードキャスト ステータスが live に移行中です。
  • ready - ブロードキャストの設定が完了し、ブロードキャストは live または testing のステータスに移行できます。
  • revoked - このブロードキャストは管理者の操作によって削除されました。
  • testStarting - ブロードキャスト ステータスが testing に移行中です。
  • testing - ブロードキャストの内容はパートナーにのみ表示されます。
status.privacyStatus string
ブロードキャストのプライバシー ステータス。なお、ライブ配信は 1 つの YouTube 動画を表すため、プライバシー設定は動画でサポートされている設定と同じです。また、ブロードキャスト リソースを変更するか、対応する動画リソースの privacyStatus フィールドを設定することで、このフィールドを設定することもできます。

このプロパティの有効な値は次のとおりです。
  • private
  • public
  • unlisted
status.recordingStatus string
ブロードキャストの録画ステータス。

このプロパティの有効な値は次のとおりです。
  • notRecording
  • recorded
  • recording
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 クライアントの場合:
  • プロパティ値を true に設定することは、contentDetails.closedCaptionsType プロパティを closedCaptionsHttpPost に設定することと同じです。
  • プロパティ値を false に設定することは、contentDetails.closedCaptionsType プロパティを closedCaptionsDisabled に設定することと同じです。
contentDetails.closedCaptionsType string
注: このプロパティは contentDetails.enableClosedCaptions プロパティに代わるものです。

このプロパティは、ブロードキャストに対して字幕が有効になっているかどうか、有効になっている場合はどのような種類の字幕を提供しているかを示します。
  • closedCaptionsDisabled: ライブ配信で字幕が使用できません。
  • closedCaptionsHttpPost: HTTP POST を使用して、ライブ配信に関連付けられた取り込み URL に字幕を送信します。
  • closedCaptionsEmbedded: 字幕は、EIA-608 形式または CEA-708 形式を使用して動画ストリームにエンコードされます。
contentDetails.projection string
このブロードキャストの投影形式。このプロパティのデフォルト値は rectangular です。

このプロパティの有効な値は次のとおりです。
  • 360
  • rectangular
contentDetails.enableLowLatency boolean
このブロードキャストを低レイテンシ ストリーミング用にエンコードするかどうかを示します。低レイテンシ ストリームを使用すると、ブロードキャストを視聴しているユーザーに動画が表示されるまでの時間が短縮されますが、ストリームの視聴者の解像度に影響することもあります。
contentDetails.latencyPreference string
このブロードキャストに対して使用するレイテンシ設定を示します。このプロパティは、ultraLow をサポートしていない enableLowLatency の代わりに使用できます。

低レイテンシ ストリームでは、放送を視聴しているユーザーに動画が表示されるまでの時間が短縮されますが、再生のスムーズさに影響することもあります。

超低レイテンシ ストリームでは、視聴者に動画が表示されるまでの時間がさらに短縮され、視聴者とのやり取りが容易になりますが、超低レイテンシでは字幕や 1080p を超える解像度はサポートされていません。

このプロパティの有効な値は次のとおりです。
  • normal
  • low
  • ultraLow
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 の場合、YouTube はミッドロール広告をブロードキャスト内に自動的に挿入します。広告の配信スケジュールは、monetizationDetails.cuepointSchedule オブジェクトの他のフィールドの値によって決まります。
monetizationDetails.cuepointSchedule.pauseAdsUntil datetime
この値は、指定した日時まで YouTube が放送にミッドロール広告を挿入しないように指定します。値は ISO 8601（YYYY-MM-DDThh:mm:ss.sZ）形式で指定します。広告を一時停止するには、値を将来の日時（タイムスタンプ）に設定する必要があります。また、フィールド値を近い将来の日時（タイムスタンプ）に設定して、時間が経過したときに広告を一時停止解除することもできます。
monetizationDetails.cuepointSchedule.scheduleStrategy string
この値は、キューポイントのスケジュール設定に YouTube が従う戦略を指定します。有効な値は次のとおりです。
  • CONCURRENT: キューポイントはすべての視聴者に対して同時にスケジュールされます
  • NON_CONCURRENT: キューポイントは、視聴者ごとに異なるタイミングでスケジュールされます。このアプローチにより、広告の表示率を高め、視聴者が対象となる場合はキューポイントを受け取ることができるようになります。
monetizationDetails.cuepointSchedule.repeatIntervalSecs unsigned integer
この値は、ブロードキャスト中の自動広告挿入の間隔（秒単位）を指定します。たとえば、値が 300 の場合、YouTube は 5 分間隔でミッドロール広告のキューポイントを挿入できます。

この値は、連続するキューポイントの開始時間間の時間を指定します。つまり、間隔は 1 つのキューポイントの終了から次のキューポイントの開始まで測定されるわけではありません。