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 8601YYYY-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 8601YYYY-MM-DDThh:mm:ss.sZ)形式で指定します。クリエイター ツールでは、開始時間をスケジュール設定せずにライブ配信を作成できます。この場合、チャンネル所有者が配信を開始するたびに配信が開始されます。これらのブロードキャストでは、datetime の値は UNIX 時刻のゼロに対応します。この値を API または YouTube Studio で変更することはできません。
snippet.scheduledEndTime datetime
ブロードキャストの終了日時。値は ISO 8601YYYY-MM-DDThh:mm:ss.sZ)形式で指定します。liveBroadcast リソースでこのプロパティの値が指定されていない場合、ブロードキャストは無期限に続行するようにスケジュールされます。同様に、このプロパティの値を指定しない場合、YouTube はライブ配信が無期限に続くものとして扱います。
snippet.actualStartTime datetime
ブロードキャストの実質的な開始日時。この情報は、ブロードキャストの状態が live の場合にのみ使用できます。値は ISO 8601YYYY-MM-DDThh:mm:ss.sZ)形式で指定します。
snippet.actualEndTime datetime
ブロードキャストの実質的な終了日時。この情報は、ブロードキャストの状態が complete になった場合にのみ利用できます。値は ISO 8601YYYY-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 の代わりに使用できます。

低遅延のストリームでは、ブロードキャストを視聴するユーザーに動画が表示されるまでの時間を短縮できますが、再生の滑らかさにも影響します。

超低遅延のストリームは、動画が表示されるまでの時間をさらに短縮するため、視聴者とのやり取りが容易になります。ただし、超低遅延は
    クローズド キャプションの値よりも 08 高い値しかサポートしません。

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

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