Cast SDK には、ライブ コンテンツをサポートする API が組み込まれています。これには、柔軟ですぐに使える UI と、デベロッパーがわずか数行のコードで豊かなライブ エクスペリエンスを実現する API が含まれています。Live API は、開始時刻と終了時刻、プログラム メタデータ、DVR コントロール、シーク可能なウィンドウの表示をサポートします。
このガイドでは、ライブ API へのストリームを構成する方法を説明します。これには、主要なライブシナリオを構成するコードサンプルとメタデータ サンプル、各シナリオの概要を示すスクリーンショットが含まれます。
Prerequisites
このガイドを読む前に、Web Receiver の実装の基本を理解しておく必要があります。また、コードサンプルを実行するには、Cast でサポートされているメディアタイプのいずれかを遵守しているライブ ストリームにアクセスする必要があります。一般に、ライブ機能はサポートされているメディアの典型的なライブ ストリーム構成をサポートしています。
このガイド全体で使用される用語は次のとおりです。
- シーク可能なウィンドウ - ユーザーがシークできるライブ ストリームの範囲。
- Live Edge - プレーヤーがアクセスできるライブ配信の最新部分。
- Play Head - 現在の再生位置の UI タイムスタンプ。
ライブ ストリームのキャスト
Live API をコンテンツに使用するように Web Receiver SDK を構成するには、次の 2 つの方法があります。
- Web Receiver アプリケーションで
LOAD
メッセージ インターセプタを使用します。(推奨) - 送信者側または受信者側が生成した読み込みリクエストを使用する。
インターセプトは、読み込みリクエストに関するすべての重要なメタデータを含む LoadRequestData
オブジェクトを提供します。読み込みリクエストがライブ ストリームに対するものであることを示すには、mediaInformation
オブジェクトの streamType
を StreamType.LIVE
に設定します。プレーヤー インスタンスは、コンテンツが LIVE
の場合に計算を行うため、MediaInformation.duration
は -1
にする必要があります。
/*
* This interceptor is called before your content is loaded by a Cast device
*/
playerManager.setMessageInterceptor(
cast.framework.messages.MessageType.LOAD,
request => { /* cast.framework.messages.LoadRequestData */
request.media.streamType = cast.framework.messages.StreamType.LIVE;
return request;
});
番組ガイドデータの追加
ライブ配信、特にテレビ チャンネルのような長時間実行されるライブ配信では、ライブ配信の現在の再生位置に基づいて画面上のガイド/番組メタデータを表示できます。エンドユーザーのエクスペリエンスを向上させるために、コンテンツ プロバイダはウェブ レシーバ アプリケーションにプログラム メタデータを含めることを強く推奨しています。
ストリームの初期ガイドデータは、前の例でストリームがライブ ストリームであることを示すのと同じ方法で、LOAD メッセージ インターセプタで構成できます。ライブ ストリーム内の個々のセクションまたはプログラムは MediaMetadata
オブジェクトとして表され、キューに格納されます。プログラムの種類によって、MediaMetadata
クラスが異なります。たとえば、TvShowMediaMetadata
、MovieMediaMetadata
、MusicTrackMediaMetadata
などです。
次のコード スニペットでは、MediaMetadata
オブジェクトを使用して、sectionStartAbsoluteTime
プロパティの UNIX タイムスタンプで各番組の開始時間を指定しています。プログラムの期間は秒単位で表されます。
// The metadata for a single TV show
const currentShow = new cast.framework.messages.TvShowMediaMetadata();
currentShow.episode = 15;
currentShow.seriesTitle = 'The Odyssey';
currentShow.title = 'Scylla and Charybdis';
currentShow.sectionStartAbsoluteTime = toUnixTimestamp('9:00 PM');
currentShow.sectionDuration = HOUR_IN_SECONDS;
const previousShow = new ...;
const nextShow = new ...;
const containerMetadata = new cast.framework.messages.ContainerMetadata();
containerMetadata.title = 'My TV Channel';
containerMetadata.sections = [previousShow, currentShow, nextShow];
playerManager.getQueueManager().setContainerMetadata(containerMetadata);
ライブシーク範囲
Cast SDK には、ユーザーが拡張コントローラや、タップ対応デバイスのタップ コントロールを使用してストリーム内でプレイヘッドを移動できるようにする UI 要素とコントロールが含まれています。
LiveSeekableRange
は、ユーザーがシークできるストリーム内の時間の範囲を表します。ウェブ レシーバでは、LiveSeekableRange
オブジェクトを返す PlayerManager.getLiveSeekableRange()
を介して、シーク可能な範囲に関する情報にアクセスできます。オブジェクトの主なプロパティは次のとおりです。
- start - ストリームの開始時点を基準とした範囲の開始時刻(秒)。
- end - 利用可能なセグメントに基づいて、ストリームの開始時点を基準に、プレーヤーがシークできる最大時間(秒単位)です。
- isMoveWindow - ストリームでシーク可能な範囲が移動する(マニフェストから古いセグメントが削除される)かどうかを示すブール値。すべてのライブ ストリームで true にする必要があります。
- isLiveDone - ライブ ストリームが終了したかどうかを示すブール値(新しいセグメントが生成されない)。
start
~end
の時間で表されるシーク可能な範囲のサイズは、ストリーム内で使用できるセグメントの数によって決まり、ストリームとともに移動します。たとえば、ストリームの開始時にシーク可能な範囲が {start:0, end: 600, isMovingWindow: false, isLiveDone: false}
の場合、ストリームの開始から 10 秒後に {start: 10, end: 610,
isMovingWindow: true, isLiveDone: false}
になります。シーク可能な範囲の開始時刻と終了時刻は、新しいセグメントの生成にかかった時間に基づいて更新されます。たとえば、ストリームのセグメントの長さが通常 10 秒である場合、開始時間と終了時間も約 10 秒ごとに更新されます。
シークの無効化
ストリーム内のシークを無効にするには、Web Receiver でサポートされているメディア コマンドからシーク機能を削除する必要があります。
// disable seeking in the LOAD messageInterceptor
playerManager.removeSupportedMediaCommands(cast.framework.messages.Command.SEEK, true);
送信者のアプリにサポートされている SEEK
コマンドとディスプレイをタップしてシークを無効化しますが、「OK Google, 30 秒巻き戻し」などの音声コマンドは無効にしません。音声のメディア コマンドを無効にする方法については、音声対応メディア コマンドのガイドをご覧ください。
ライブ フレームワーク イベント
Live API には LIVE_ENDED
と LIVE_IS_MOVING_WINDOW_CHANGED
の 2 つのイベントが含まれています。どちらのイベントにも、現在のライブシーク可能な範囲を含む LiveStatusEvent
オブジェクトが渡されます。
イベント | 説明 |
---|---|
LIVE_ENDED |
ライブ ストリームが終了するとトリガーされます。この時点で、LiveSeekableRange の end 値の更新が停止します。ユーザーは、ライブシーク可能な範囲内でコンテンツを表示できます。 |
LIVE_IS_MOVING_WINDOW_CHANGED |
ライブ ストリームのシーク可能な範囲が固定ウィンドウから移動ウィンドウへ(またはその逆に)変わったときにトリガーされます。ライブ ストリームの場合、マニフェストがそれ以前のセグメントを削除していることをプレーヤーが検出した場合に発生します。 |
ライブ配信のシナリオ
ライブ配信には 8 つのシナリオがあり、それぞれが 3 つの基本設定によって構成されます。
- ストリームの開始時間があります
- ストリームの終了時間です
- ユーザーはライブ配信のシーク可能な時間枠内でシークできます
これらの値の構成方法については、プログラム ガイドのデータを追加するをご覧ください。
Live API でサポートされているシナリオの説明とスクリーンショットは以下のとおりです。変数 T1 と T2 は、それぞれ UI の左側と右側のタイムスタンプを表すために使用されます。
開始時間 | 終了時間 | Seekable(シーク可能) | T1 | T2 | |
---|---|---|---|---|---|
シナリオ 1 | × | × | × | 再生ヘッド | 非表示 |
シナリオ 7 | ○ | ○ | × | 開始時間を表示 | 終了時間を表示 |
シナリオ 8 | ○ | ○ | ○ | 開始時間を表示 | 終了時間を表示 |
シナリオ 1
開始時間 | 終了時間 | Seekable(シーク可能) | T1 | T2 |
---|---|---|---|---|
× | × | × | 再生ヘッド | 非表示 |
シナリオ 1 には開始時間または終了時間がなく、ユーザーがストリーム内でシークすることはできません。ユーザーがストリームを停止すると、ストリームが一時停止した場所ではなく、ライブエッジから再生が再開されます。
シナリオ 7
開始時間 | 終了時間 | Seekable(シーク可能) | T1 | T2 |
---|---|---|---|---|
○ | ○ | × | 再生ヘッド | プログラムの期間 |
シナリオ 7 は、開始時刻と終了時刻はありますが、シークできません。UI の 2 つのタイムスタンプ、T1 と T2 は、それぞれ現在のプレイヘッド時間とプログラムの合計継続時間を表します。ユーザーが再生を一時停止または再開すると、ストリームのライブエッジでストリームが再開されます。上記の例では、シークバーの赤色の部分は、ユーザーが視聴を開始してからのストリームの部分を表しています。
シナリオ 8
開始時間 | 終了時間 | Seekable(シーク可能) | T1 | T2 |
---|---|---|---|---|
○ | ○ | ○ | 再生ヘッド | プログラムの期間 |
シナリオ 7 は、開始時刻と終了時刻があり、シーク可能です。UI の 2 つのタイムスタンプ、T1 と T2 は、それぞれ現在のプレイヘッド時間とプログラムの合計時間を表します。ユーザーが再生を一時停止/再開した場合、シーク可能なウィンドウ内であれば一時停止した時間にストリームが再開されます。シークバーの赤色の領域はユーザーが戻れる場所、白色の領域は再生できる場所を表します。
シナリオの構成
ストリームを特定のライブシナリオとして構成するには、次の 3 つの手順を行います。
- ストリームのタイプを設定 - ストリームをライブ ストリームとしてマークできます。
- プログラム ガイドのデータを追加する -
MediaMetadata
オブジェクトに開始時間と期間を設定します。 - シーク機能の設定 - シークを有効または無効にします。
再生動作
一時停止中、UI では引き続き再生メタデータが更新されます(再生ヘッドやライブエッジ時間も含まれます)。ストリームを再開すると、ストリーム構成に応じていくつかの動作が変化することがあります。
シークできるストリーム
シーク可能なストリームの再開時:
- ライブエッジがライブ ロケーションに更新され、それに応じてシーク可能な範囲が調整されます。
- プレイヘッドが現在の番組からジャンプすると、スクラブバーが新しい番組のメタデータ(開始時間や終了時間など)で更新されます。
- シーク可能なウィンドウの長さが「X」の場合、シーク可能な範囲は最大「X」まで、または番組の先頭まで、いずれか小さい方まで範囲を広げます。
- 現在の時刻がシーク可能なウィンドウに表示されなくなるまでユーザーが一時停止していた場合、シーク可能なウィンドウの最も早いポイント(左端)からストリームが再開されます。
一時停止を解除した後、ライブエッジで再生を再開するには、LiveSeekableRange.end
にシークします。
let playerManager = cast.framework.CastReceiverContext.getInstance().getPlayerManager();
// Intercept the message to PLAY
playerManager.setMessageInterceptor(cast.framework.messages.MessageType.PLAY, (requestData) => {
...
if (playerManager.getLiveSeekableRange()) {
// Resume playback at the live edge
playerManager.seek(playerManager.getLiveSeekableRange().end);
} else {
return requestData;
}
...
});
シークできないストリーム
シーク不能なストリームの再開時:
- この場合、ライブエッジで再生が再開されます。
- ライブエッジが現在の番組を飛び越えた場合、スクラブバーを新しい番組のメタデータ(開始時刻や終了時刻など)で更新する必要があります。
API サーフェスの変更とライブ UI のカスタマイズ
Cast SDK には、すぐに使える UI を使用せずにカスタム ユーザー インターフェースを作成するためのサポートが組み込まれています。ただし、インターフェースをカスタマイズする際は、キャスト UX デザイン チェックリストを遵守することが重要です。
ウェブレシーバー
ウェブ レシーバの PlayerData
には、デベロッパーがライブ ストリーム用のカスタム インターフェースを拡張するための次のフィールドが含まれています。
- isLive - 現在のストリームが VOD ではなくライブ ストリームかどうかを示します。
- liveSeekableRange - DVR ウィンドウを区切る画面に表示するシーク可能な範囲。
- mediaStartAbsoluteTime - セクションが絶対時間で開始した時刻(UNIX エポック)。
- sectionStartTimeInMedia - メディアの開始時刻を基準としたセクション開始時刻(秒)。
- sectionDuration - セクション期間(秒単位)。
また、UI をカスタマイズする場合は、2 つのライブイベントも考慮してください。
Android SDK
ライブ機能の一部として、UIMediaController
での Android Seekbar ウィジェットの使用は非推奨になりました。代わりに CastSeekBar
を使用してください。