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 | 列挙型（文字列） | プレーヤーの状態を次のいずれかとして表します。
|
| idleReason | 列挙型（文字列） | 省略可 playerState が IDLE で、IDLE になった理由がわかっている場合は、このプロパティが提供されます。開始直後の IDLE の場合、このプロパティは提供されません。プレーヤーが他の状態の場合は、このプロパティを指定しないでください。次の値が適用されます。
|
| 現在の時刻 | 倍精度 | コンテンツの開始時点からのメディア プレーヤーの現在の位置（秒）。ライブ ストリーム コンテンツの場合、このフィールドは、イベント開始からプレーヤーにわかる時間（秒）を表します。 |
| supportedMediaCommands | flags | メディア プレーヤーでサポートされているメディア コマンドを示すフラグ:
組み合わせは、合計として表されます（例: 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 | 列挙型（文字列） | 省略可: 設定しない場合、再生ステータスは変更されません。値は次のとおりです。
|
| 現在の時刻 | 倍精度 | 省略可: コンテンツの開始からの経過時間。コンテンツがライブ コンテンツであり、位置が指定されていない場合、ストリームはライブ位置から開始されます。 |
| カスタムデータ | オブジェクト | 省略可: 送信者のアプリケーションで定義されたデータのアプリケーション固有の 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（値のみ） |
| 理由 | 列挙型（文字列） | 値:
|
| カスタムデータ | オブジェクト | （省略可）受信側アプリケーションによって定義されるデータのアプリケーション固有の blob。 |
メディアのステータス
状態の変更後またはメディア ステータス リクエストの後に送信されます。変更またはリクエストされた MediaStatus オブジェクトのみが送信されます。
| 名前 | 型 | 説明 |
|---|---|---|
| requestId | 整数 | このステータス レスポンスを、それを生成したリクエストに関連付けるために使用される ID。ステータス メッセージが自発的である場合は 0（送信者のリクエストによってトリガーされません）。送信者のアプリケーションは、乱数を選択して継続的に増加することによって、一意のリクエスト ID を生成します（0 は使用しません）。 |
| type | 文字列 | MEDIA_STATUS（値のみ） |
| status | MediaStatus | メディア ステータス オブジェクトの配列。注: MediaStatus のメディア要素は、変更された場合にのみ返されます。 |
| カスタムデータ | オブジェクト | （省略可）受信側アプリケーションによって定義されるデータのアプリケーション固有の blob。 |