YouTube Data API v3でライブ配信の状態を取得する
【追記：2022年1月13日】プレミア公開動画の判定方法について追記しました。
YouTubeのライブ配信は、普通の動画と同じようにYouTube Data API v3で取得することができます。
今回は、ライブ配信が現在、どの状態なのかを取得する方法を紹介します。
ライブ配信の状態とは
まず、YouTubeライブの配信状態には、3つの種類があります。
- ライブ配信予約
- ライブ配信終了
ライブ配信中に関しては言うまでもないと思いますが、赤い文字でライブ配信中というマークが出ているのですぐに分かります。
ライブ配信予約は、YouTube上ではリマインダーっていう表示になっており、何日の何時に配信するよ～というのを予約しておくものです。実際に放送開始しない限り、なにも始まりません。
ライブ配信終了は、放送主が配信を切り終了した状態です。この後、少し時間が経つとアーカイブとして動画が残ります。この動画は普通に投稿した動画と何ら変わりません。
では、取得方法を説明する前にAPIで返ってくるステータス値は以下の通りです。
- live （ライブ配信中）
- upcoming （ライブ配信予約）
- none （ライブ配信終了）
noneに関しては通常投稿された動画にも設定されていることに注意してください。
ライブ配信の状態を取得する
では、ライブ配信の状態を取得してみましょう。
いずれも、snippet.liveBroadcastContentから取得することができます。
partパラメータにおいて、snippetを指定することを忘れないようにしてください。
プレミア公開動画の判定方法
プレミア公開動画の状態はライブ配信と同じステータス値を返します。つまり上記のステータス値だけではプレミア公開の動画か、ライブ配信の予約なのか判定できません。
そこで以下で紹介されているプレミア公開動画を判定する方法があります。
配信前または配信中のとき、
アップロードされた動画のステータスを返すstatus.uploadStatusは、
プレミア公開動画の場合、processed
ライブ配信の場合、uploaded
となります。
これを使ってプレミア公開動画の判定ができます。
また、プレミア公開とライブ配信ともに配信終了後にはステータスがprocessedとなるようです。
この方法は、APIの仕様変更によって返す動画のステータスが変わった場合判定できなくなる恐れがあるので注意が必要でしょう。
（番外編）ライブ配信の詳細な情報を取得する
ライブ配信の状態を取得する方法は分かったと思いますが、実は詳細な情報を取得することもできます。
取得できる情報は、ライブ開始時間、ライブ開始予定時間、ライブ終了時間、リアルタイム視聴者数、チャット取得用IDです。
これを取得できるAPIはVideos: listのみで、partパラメータにliveStreamingDetailsを指定します。
各プロパティは、
- liveStreamingDetails.actualStartTime （ライブ開始時間）
- liveStreamingDetails.scheduledStartTime （ライブ開始予定時間）
- liveStreamingDetails.actualEndTime （ライブ終了時間）
- liveStreamingDetails.concurrentViewers （リアルタイム視聴者数）
- liveStreamingDetails.activeLiveChatId （チャット取得用ID）
のようになっています。
当たり前ですが、ライブ配信中ではライブ終了時間を、ライブ配信予定ではリアルタイム視聴者数を、ライブ配信終了ではライブ開始予定時間・リアルタイム視聴者数・チャット取得用IDを取得することができません。
時間に関しては、 datetimeのISO 8601形式で、視聴者数はlong型、チャット取得用IDは、string型で返ってきます。
チャット取得用IDは、YouTube Live Streaming APIを利用してチャット内容を取得するために使います。
