メディア再生メッセージ

Google Cast 送信者アプリは、レシーバー アプリに JSON 形式でメッセージを送信することにより、レシーバー デバイスでの再生を制御します。同様に、レシーバーは、送信者にも JSON 形式でメッセージを送信します。メッセージには、プレーヤーの状態を変更するコマンド、受信機からのコマンドへの応答、受信側アプリケーションのメディアを記述したデータ構造などがあります。

キャスト メディア アプリは、Google Cast SDK 追加デベロッパー利用規約に基づき、レシーバーでのメディア再生を制御するために、ここで定義されているメッセージを使用する必要があります。これにより、メディアアプリでプラットフォーム間で一貫したユーザー エクスペリエンスが実現し、キャスト アプリが新しいユースケースと将来のユースケースをサポートできるようになります。これらの構造は、必要に応じてカスタムデータもサポートします。アプリは、SDK でサポートされていないコマンドに対して独自のメッセージを定義することもできます。

メディア再生メッセージの名前空間は urn:x-cast:com.google.cast.media として定義されます。

注: この仕様のメッセージと構造は、トランスポート メッセージの最大サイズによって決定される暗黙的な最大サイズがあります。個々のフィールドに制限はありません。現在、トランスポート メッセージの最大サイズは 64 KB です。

一般的な名前空間データ構造

すべてのメディア名前空間アーティファクトで使用されるデータ構造のスーパーセットは、共通の名前空間で定義されています。

画像

画像の説明です。少量のメタデータを含み、レンダリング方法に応じて送信者のアプリケーションに画像の選択を許可しています。

画像の配列に含まれる 1 つのアイテムのみ、高さと幅を指定できます。たとえば、返された商品アイテムが 1 つの場合、その商品アイテムは省略可能です。2 つの商品アイテムが返される場合は、高さと幅を指定する必要があります。送信者は「default」オプションを使用できます。

名前 説明
url URI イメージの URI
高さ 整数 省略可 画像の高さ
整数 (省略可)画像の幅

音量

メディア ストリームの音量。メディア ストリームのフェードイン/フェードアウト効果に使用されます。(注: システムの音量は送信側の API を使用して変更されます)。デバイスの音量を調節するには、ストリームの音量を音量スライダーや音量ボタンと併用しないでください。ストリーム ボリュームを変更するには、次のパラメータのうち少なくとも 1 つを渡す必要があります。

名前 説明
level 倍精度 省略可 - 現在のストリームの音量レベルを 0.0 ~ 1.0 の値で指定します。1.0 は最大音量です。
ミュート boolean 省略可: キャスト デバイスがミュートされているかどうか(音量に関係なく)

メディア名前空間のデータ構造

これらのメッセージは、メディア プレーヤーの状態を記述します。名前空間は urn:x-cast:com.google.cast.media です。

メディア情報

このデータ構造はメディア ストリームを表します。

名前 説明
contentId 文字列 メディア プレーヤーによって現在読み込まれているコンテンツのサービス固有の識別子。これは自由形式の文字列で、アプリケーションに固有のものです。ほとんどの場合、これはメディアへの URL になりますが、送信者は、受信者が正確に解釈できる文字列を渡すこともできます。最大文字数: 1,000
streamType 列挙型
(文字列)

メディア アーティファクトのタイプを示します。次のいずれかになります。

  • なし
  • バッファ済み
  • ライブ
contentType 文字列 再生中のメディアの MIME コンテンツ タイプ
metadata オブジェクト

省略可: メディア メタデータ オブジェクト。次のいずれかです。

duration 倍精度 省略可: 現在再生中のストリームの長さ(秒)
カスタムデータ オブジェクト オプション 送信者のアプリケーションまたは受信者のアプリケーションにより定義された、アプリケーション固有の blob。

汎用メディア メタデータ

汎用メディア アーティファクトを記述します。

名前 説明
metadataType 整数 0(唯一の値)
title 文字列 省略可: コンテンツの説明的なタイトル。プレーヤーは content_id を使用してタイトルを個別に取得することも、Load メッセージで送信者が指定することもできます。
サブタイトル 文字列 省略可: コンテンツの字幕。プレーヤーは content_id を使用してタイトルを個別に取得することも、Load メッセージで送信者が指定することもできます。
画像 画像[] 省略可: コンテンツに関連付けられた画像の URL の配列。このフィールドの初期値は、送信者が [Load] メッセージで指定できます。推奨サイズ
releaseDate string(ISO 8601) 省略可: このコンテンツがリリースされた ISO 8601 の日時。プレーヤーは content_id を使用してタイトルを個別に取得することも、Load メッセージで送信者が指定することもできます。

MovieMediaMetadata

ムービーのメディア アーティファクトを記述します。

名前 説明
metadataType 整数 1(値のみ)
title 文字列 省略可: コンテンツの説明的なタイトル。プレーヤーは content_id を使用してタイトルを個別に取得することも、Load メッセージで送信者が指定することもできます。
サブタイトル 文字列 省略可: コンテンツの字幕。プレーヤーは content_id を使用してタイトルを個別に取得することも、Load メッセージで送信者が指定することもできます。
studio 文字列 省略可: コンテンツをリリースしたスタジオ。プレーヤーは、content_id を使用してスタジオを個別に取得することも、送信者が [読み込み] メッセージで指定することもできます。
画像 画像[] 省略可: コンテンツに関連付けられた画像の URL の配列。このフィールドの初期値は、送信者が [Load] メッセージで指定できます。推奨サイズ
releaseDate string(ISO 8601) 省略可: このコンテンツがリリースされた ISO 8601 の日時。プレーヤーは content_id を使用してタイトルを個別に取得することも、Load メッセージで送信者が指定することもできます。

テレビ番組のメタデータ

テレビ番組のエピソードのメディア アーティファクトを記述します。

名前 説明
metadataType 整数 2(唯一の値)
seriesTitle 文字列 省略可: テレビシリーズのタイトル。プレーヤーは content_id を使用してタイトルを個別に取得することも、Load メッセージで送信者が指定することもできます。
サブタイトル 文字列 省略可: テレビ番組のエピソードを説明する字幕。プレーヤーは content_id を使用してタイトルを個別に取得することも、Load メッセージで送信者が指定することもできます。
シーズン 整数 省略可: テレビ番組のシーズン番号
エピソード 整数 省略可: テレビ番組のエピソード番号(シーズン中)
画像 画像[] 省略可: コンテンツに関連付けられた画像の URL の配列。このフィールドの初期値は、送信者が [Load] メッセージで指定できます。推奨サイズ
originalAirDate string(ISO 8601) 省略可: このエピソードがリリースされた日時(ISO 8601)。プレーヤーは content_id を使用して originalAirDate を独自に取得できます。または、Load メッセージで送信者から送信することもできます。

音楽トラック メディア メタデータ

音楽トラックのメディア アーティファクトを記述します。

名前 説明
metadataType 整数 3(唯一の値)
AlbumName 文字列 省略可 このトラックの元のアルバムまたはコレクション。プレーヤーは content_id を使用して calendarName を個別に取得できます。または、送信者が Load メッセージでアルバム名を取得できます。
title 文字列 省略可: トラックの名前(曲のタイトルなど)。プレーヤーは content_id を使用してタイトルを個別に取得することも、Load メッセージで送信者が指定することもできます。
AlbumArtist 文字列 省略可: このトラックを扱っているアルバムに関連付けられているアーティストの名前。プレーヤーは content_id を使用して calendarArtist を個別に取得できます。または、Load メッセージで送信者から指定できます。
アーティスト 文字列 省略可: メディア トラックに関連付けられているアーティストの名前。プレーヤーは content_id を使用して独立してアーティストを取得することも、送信者が [読み込み] メッセージで指定することもできます。
composer 文字列 省略可: メディア トラックに関連付けられている作曲者の名前。プレーヤーは、content_id を使用してコンポーザブルを独自に取得することも、送信者が Load メッセージで指定することもできます。
trackNumber 整数 省略可: アルバムの曲番号。
discNumber 整数 省略可: アルバムの音量(ディスクなど)
画像 画像[] 省略可: コンテンツに関連付けられた画像の URL の配列。このフィールドの初期値は、送信者が [Load] メッセージで指定できます。推奨サイズ
releaseDate string(ISO 8601) 省略可: このコンテンツがリリースされた ISO 8601 の日時。プレーヤーは content_id を使用して releaseDate を独自に取得できます。または、読み込みメッセージで送信者が指定できます。

写真メディアのメタデータ

写真メディア アーティファクトを記述します。

名前 説明
metadataType 整数 4(唯一の値)
title 文字列 (省略可)写真のタイトル。プレーヤーは content_id を使用してタイトルを個別に取得することも、Load メッセージで送信者が指定することもできます。
アーティスト 文字列 省略可: 写真家の名前。プレーヤーは content_id を使用して独立してアーティストを取得することも、送信者が [読み込み] メッセージで指定することもできます。
地域 文字列 省略可: 写真が撮影された口頭での場所(「マドリッド、スペイン」など)。プレーヤーは、content_id を使用して個別に位置情報を取得することも、Load メッセージで送信者が指定することもできます。
latitude 倍精度 (省略可)写真の撮影場所の地理的緯度の値。プレーヤーは、content_id を使用して個別に緯度を取得することも、Load メッセージで送信者が指定することもできます。
longitude 倍精度 (省略可)写真が撮影された場所の経度の経度値。プレーヤーは content_id を使用して個別に経度を取得するか、Load メッセージで送信者が指定します。
整数 省略可: ピクセル単位の幅。プレーヤーは content_id を使用して個別に幅を取得することも、Load メッセージで送信者が指定することもできます。
高さ 整数 省略可: ピクセル単位の高さ。プレーヤーは content_id を使用して個別に高さを取得することも、Load メッセージで送信者が指定することもできます。
CreationDateTime string(ISO 8601) 省略可能: 写真が撮影された ISO 8601 の日時。プレーヤーは content_id を使用して creationDateTime を個別に取得するか、送信者が Load メッセージで取得できます。

MediaStatus

セッションに関するメディア アーティファクトの現在のステータスを示します。

名前 説明
mediaSessionId 整数 この特定のセッションを再生するための一意の ID。この ID はレシーバーが LOAD で設定し、再生の特定のインスタンスを識別するために使用できます。たとえば、同じセッション内で「Wish you here?」と 2 回再生した場合、それぞれ固有の mediaSessionId になります。
media MediaInformation(メディア情報) 省略可(ステータス メッセージの場合)再生中のコンテンツの詳細な説明。MediaInformation が変更された場合にのみ、ステータス メッセージで返されます。
playbackRate float メディアの時間が進行しているかどうかと、その速度を示します。メディア時間はどの状態でも停止する可能性があるため、プレーヤーの状態とは無関係です。1.0 は通常の時間、0.5 はスローモーションです
playerState 列挙型(文字列)

プレーヤーの状態を次のいずれかとして表します。

  • IDLE プレーヤーはまだ読み込まれていません
  • PLAYING: プレーヤーがコンテンツを積極的に再生している
  • BUFFERING: プレーヤーは Play モードですが、コンテンツを積極的に再生していません(currentTime は変わりません)。
  • 一時停止中 プレーヤーは一時停止されています
idleReason 列挙型(文字列)

省略可 playerState が IDLE で、IDLE になった理由がわかっている場合は、このプロパティが提供されます。開始直後の IDLE の場合、このプロパティは提供されません。プレーヤーが他の状態の場合は、このプロパティを指定しないでください。次の値が適用されます。

  • CANCELLED 送信者が STOP コマンドを使用して再生を停止するようリクエストした
  • INTERRUPTED: 送信者は LOAD コマンドを使用して別のメディアの再生をリクエストしました。
  • FINISHED: メディアの再生が完了しました。
  • ERROR - エラー(メディアの問題によりプレーヤーがメディアをダウンロードできない場合など)により、メディアが中断されました
現在の時刻 倍精度 コンテンツの開始時点からのメディア プレーヤーの現在の位置(秒)。ライブ ストリーム コンテンツの場合、このフィールドは、イベント開始からプレーヤーにわかる時間(秒)を表します。
supportedMediaCommands flags

メディア プレーヤーでサポートされているメディア コマンドを示すフラグ:

  • 1 一時停止
  • 2 シーク
  • 4 ストリーミングの音量
  • 8 ストリームのミュート
  • 16 早送りする
  • 32 後方にスキップ

組み合わせは、合計として表されます(例: Pause+Seek+StreamVolume+ミュート == 15)。

ボリューム Volume ストリームの音量
カスタムデータ オブジェクト (省略可)受信側アプリケーションによって定義されるデータのアプリケーション固有の blob。

送信者から受信者へのコマンド

これらのコマンドはメディア プレーヤーを制御します。以下のメッセージ内のすべての customData オブジェクトはオプションでなければなりません(つまり、データが渡されない場合、レシーバが適切に低下する必要があります)。これにより、一般的なリモコンアプリを正常に動作させることができます。

読み込み

メディア プレーヤーに新しいコンテンツを読み込みます。

名前 説明
requestId 整数 リクエストとレスポンスを関連付けるリクエスト ID
type 文字列 読み込み(値のみ)
media MediaInformation(メディア情報) 読み込むメディアのメタデータ(contentId を含む)
自動再生 boolean

optional(デフォルトは true)自動再生パラメータが指定されている場合、メディア プレーヤーは読み込まれるとコンテンツの再生を開始します。自動再生が指定されていない場合でも、メディア プレーヤーの実装では再生がすぐに開始される場合があります。再生が開始されると、レスポンスのプレーヤーの状態は BUFFERING に設定され、それ以外の場合は PAUSED に設定されます。

現在の時刻 倍精度 省略可: コンテンツの開始からの経過時間。コンテンツがライブ コンテンツであり、位置が指定されていない場合、ストリームはライブ位置から開始されます。
カスタムデータ オブジェクト 省略可: 送信者のアプリケーションで定義されたデータのアプリケーション固有の blob。
レスポンス Triggers ブロードキャスト エラー
なし 受信者の状態の変更 メディア ステータス変更メッセージ 無効なプレーヤー ステータス
読み込み失敗
読み込みキャンセル

一時停止

現在のコンテンツの再生を一時停止します。すべての送信者アプリケーションへの STATUS イベント通知をトリガーします。

名前 説明
mediaSessionId 整数 一時停止するメディア セッションの ID
requestId 整数 リクエストの ID。リクエスト/レスポンスを関連付けるために使用します。
type 文字列 PAUSE(値のみ)
カスタムデータ オブジェクト 省略可: 送信者のアプリケーションで定義されたデータのアプリケーション固有の blob。
レスポンス Triggers ブロードキャスト エラー
なし 受信者の状態の変更 メディア ステータス変更メッセージ 無効なプレーヤー状態

シーク

ストリーム内の現在の位置を設定します。すべての送信者アプリケーションへの STATUS イベント通知をトリガーします。指定した位置が現在のコンテンツの有効な位置の範囲外である場合、プレーヤーは、リクエストされた位置にできるだけ近い有効な位置を選択する必要があります。

名前 説明
mediaSessionId 整数 ストリームの位置が設定されているメディア セッションの ID
requestId 整数 リクエストとレスポンスを関連付けるリクエスト ID
type 文字列 SEEK(値のみ)
ResumeState 列挙型(文字列)

省略可: 設定しない場合、再生ステータスは変更されません。値は次のとおりです。

  • PLAYBACK_START メディアを強制的に起動
  • PLAYBACK_PAUSE メディアを強制的に一時停止する
現在の時刻 倍精度 省略可: コンテンツの開始からの経過時間。コンテンツがライブ コンテンツであり、位置が指定されていない場合、ストリームはライブ位置から開始されます。
カスタムデータ オブジェクト 省略可: 送信者のアプリケーションで定義されたデータのアプリケーション固有の blob。
レスポンス Triggers ブロードキャスト エラー
なし 受信者の状態の変更 メディア ステータス変更メッセージ 無効なプレーヤー状態

停止

現在のコンテンツの再生を停止します。すべての送信者アプリケーションへの STATUS イベント通知をトリガーします。このコマンドの実行後、コンテンツは読み込まれなくなり、mediaSessionId が無効になります。

名前 説明
mediaSessionId 整数 停止するコンテンツのメディア セッションの ID
requestId 整数 リクエストとレスポンスを関連付けるリクエスト ID
type 文字列 STOP(値のみ)
カスタムデータ オブジェクト 省略可: 送信者のアプリケーションで定義されたデータのアプリケーション固有の blob。
レスポンス Triggers ブロードキャスト エラー
なし 受信者の状態の変更 メディア ステータス変更メッセージ 無効なプレーヤー状態

再生

load 呼び出しで読み込まれたコンテンツの再生を開始します。現在の位置から再生が続行されます。

名前 説明
mediaSessionId 整数 コンテンツが再生されるメディア セッションの ID
requestId 整数 リクエストとレスポンスを関連付けるリクエスト ID
type 文字列 PLAY(value のみ)
カスタムデータ オブジェクト 省略可: 送信者のアプリケーションで定義されたデータのアプリケーション固有の blob。
レスポンス Triggers ブロードキャスト エラー
なし 受信者の状態の変更 メディア ステータス変更メッセージ 無効なプレーヤー状態

ステータスの取得

メディア ステータスを取得します。

名前 説明
mediaSessionId 整数 省略可: メディア ステータスを返すメディアのメディア セッション ID。設定されていない場合、すべてのメディア セッション ID のステータスが表示されます。
requestId 整数 リクエストとレスポンスを関連付けるリクエスト ID
type 文字列 GET_STATUS(値のみ)
カスタムデータ オブジェクト 省略可: 送信者のアプリケーションで定義されたデータのアプリケーション固有の blob。
レスポンス Triggers ブロードキャスト エラー
リクエストを行った送信者への MediaStatus メッセージ なし なし なし

SetVolume

メディア ストリームの音量を設定します。メディア ストリームのフェードイン/フェードアウト効果に使用されます。(注: レシーバのボリュームはウェブの送信者の setVolume を使用して変更されます)。デバイスの音量を調節するには、ストリームの音量を音量スライダーや音量ボタンと併用しないでください。ストリーム ボリュームを変更しても、レシーバーの UI はトリガーされません。

名前 説明
mediaSessionId 整数 ストリームの音量が変更されたメディアのメディア セッション ID
requestId 整数 リクエストとレスポンスを関連付けるリクエスト ID
type 文字列 VOLUME(値のみ)
ボリューム Volume ストリームの音量
カスタムデータ オブジェクト 省略可: 送信者のアプリケーションで定義されたデータのアプリケーション固有の blob。
レスポンス Triggers ブロードキャスト エラー
なし 受信者の状態の変更 メディア ステータス変更メッセージ 無効なプレーヤー状態

受信者から送信者へのメッセージ

受信者は、次の 2 種類のメッセージを送信します。

  • エラー: 送信者のリクエストに対するエラー応答がある場合に送信されるユニキャスト メッセージ。
  • ステータス: メッセージをブロードキャストする。
    • 送信者によって開始されるアクションの結果。変更の原因となったリクエストの requestId が含まれます。
    • 自発的: など、受信側アプリケーションによってトリガーされた変更など。RequestId は 0 になります。

エラー: プレーヤーの状態が無効です

プレーヤーが有効な状態ではないために、送信者によるリクエストを処理できない場合に送信されます。たとえば、アプリがまだメディア要素を作成していない場合などです。

名前 説明
requestId 整数 このエラーを生成したリクエストの ID
type 文字列 INVALID_Player_STATE(値のみ)
カスタムデータ オブジェクト (省略可)受信側アプリケーションによって定義されるデータのアプリケーション固有の blob。

エラー: 読み込めませんでした

読み込みリクエストが失敗したときに送信されます。プレーヤーの状態は IDLE になります。

名前 説明
requestId 整数 このエラーを生成したリクエストの ID
type 文字列 LOAD_FAILED(値のみ)
カスタムデータ オブジェクト (省略可)受信側アプリケーションによって定義されるデータのアプリケーション固有の blob。

エラー: 読み込みがキャンセルされました

読み込みリクエストがキャンセルされたときに送信されます(2 番目の読み込みリクエストを受信しました)。

名前 説明
requestId 整数 このエラーを生成したリクエストの ID
type 文字列 LOAD_CANCELLED (値のみ)
カスタムデータ オブジェクト (省略可)受信側アプリケーションによって定義されるデータのアプリケーション固有の blob。

エラー: リクエストが無効です

リクエストが無効である場合に送信されます(不明なリクエスト タイプなど)。

名前 説明
requestId 整数 このエラーを生成したリクエストの ID
type 文字列 INVALID_REQUEST(値のみ)
理由 列挙型(文字列)

値:

  • INVALID_Command: このコマンドはサポートされていません。
  • DUPLICATE_REQUESTID リクエスト ID が一意ではありません(受信者が同じ ID のリクエストを処理しています)
カスタムデータ オブジェクト (省略可)受信側アプリケーションによって定義されるデータのアプリケーション固有の blob。

メディアのステータス

状態の変更後またはメディア ステータス リクエストの後に送信されます。変更またはリクエストされた MediaStatus オブジェクトのみが送信されます。

名前 説明
requestId 整数 このステータス レスポンスを、それを生成したリクエストに関連付けるために使用される ID。ステータス メッセージが自発的である場合は 0(送信者のリクエストによってトリガーされません)。送信者のアプリケーションは、乱数を選択して継続的に増加することによって、一意のリクエスト ID を生成します(0 は使用しません)。
type 文字列 MEDIA_STATUS(値のみ)
status MediaStatus メディア ステータス オブジェクトの配列。注: MediaStatus のメディア要素は、変更された場合にのみ返されます。
カスタムデータ オブジェクト (省略可)受信側アプリケーションによって定義されるデータのアプリケーション固有の blob。