Google Cast センダー アプリは、JSON 形式のメッセージをレシーバー アプリに送信することで、レシーバー デバイスでの再生を制御します。同様に、受信側も JSON 形式でメッセージを送信側に返します。メッセージは、プレーヤーの状態を変更する送信者からのコマンド、受信者からのコマンドに対するレスポンス、受信者アプリケーションのメディアを記述するデータ構造である場合があります。
Google Cast SDK のデベロッパー向け追加利用規約に沿って、キャスト メディア アプリケーションは、ここで定義されているメッセージを使用して、レシーバーでのメディア再生を制御する必要があります。これにより、メディアアプリはプラットフォーム全体で一貫したユーザー エクスペリエンスを提供でき、また、Cast アプリケーションは新しいユースケースや将来のユースケースをサポートできるようになります。これらの構造は、必要に応じてカスタムデータもサポートします。また、アプリケーションは、SDK でサポートされていないコマンドに対して独自のメッセージを定義できます。
メディア再生メッセージの Namespace は urn:x-cast:com.google.cast.media として定義されています。
注: この仕様のメッセージと構造には、トランスポート メッセージの最大サイズによって決まる暗黙的な最大サイズがあり、個々のフィールドに制限はありません。転送メッセージの最大サイズは現在 64 K バイトです。
一般的な Namespace データ構造
すべてのメディア Namespace アーティファクトで使用されるデータ構造のスーパーセットは、共通の Namespace で定義されます。
画像
これは、送信側アプリがレンダリング方法に応じて画像を選択できるように、少量のメタデータを含む画像の説明です。
高さと幅は、Image の配列内の 1 つのアイテムでのみ省略可能です。たとえば、1 つのアイテムが返された場合は省略可能です。2 つのアイテムが返された場合は、1 つのアイテムで高さと幅を指定する必要がありますが、特定のパラメータで渡されたアイテムが気に入らない場合は、送信者は「デフォルト」オプションを選択できます。
| 名前 | タイプ | 説明 |
|---|---|---|
| url | URI | 画像の URI |
| height | integer | 省略可 : 画像の高さ |
| width | integer | 省略可 : 画像の幅 |
音量
メディア ストリームの音量。メディア ストリームのフェードイン/フェードアウト効果に使用されます。（注: システム音量は送信側 API を使用して変更されます）。ストリームの音量を音量スライダーや音量ボタンと組み合わせてデバイスの音量を制御してはなりません。ストリームの音量を変更するには、次のパラメータの少なくとも 1 つを渡す必要があります。
| 名前 | タイプ | 説明 |
|---|---|---|
| level | double | 省略可 現在のストリームの音量レベル。0.0 ～ 1.0 の値で、1.0 は最大音量を表します。 |
| muted | ブール値 | 省略可 音量レベルに関係なく、Google Cast デバイスがミュートされているかどうか |
メディア名前空間のデータ構造
これらのメッセージは、メディア プレーヤーの状態を表します。名前空間は urn:x-cast:com.google.cast.media です。
MediaInformation
このデータ構造はメディア ストリームを表します。
| 名前 | タイプ | 説明 |
|---|---|---|
| contentId | 文字列 | メディア プレーヤーによって現在読み込まれているコンテンツのサービス固有の識別子。これは自由形式の文字列で、アプリケーションに固有のものです。ほとんどの場合、これはメディアの URL になりますが、送信側は受信側が適切に解釈できる文字列を渡すこともできます。最大長: 1,000 |
| streamType | enum （文字列） |
メディア アーティファクトのタイプを次のいずれかで説明します。
|
| contentType | 文字列 | 再生中のメディアの MIME コンテンツ タイプ |
| metadata | オブジェクト | 省略可 。メディア メタデータ オブジェクト。次のいずれかになります。 |
| duration | double | 省略可 現在再生中のストリームの長さ（秒単位） |
| customData | オブジェクト | 省略可 送信側アプリまたは受信側アプリのいずれかによって定義されるアプリ固有のデータ blob |
GenericMediaMetadata
一般的なメディア アーティファクトを表します。
| 名前 | タイプ | 説明 |
|---|---|---|
| metadataType | integer | 0（唯一の値） |
| title | 文字列 | 省略可 コンテンツのわかりやすいタイトル。プレーヤーは content_id を使用してタイトルを個別に取得できます。また、送信者が Load メッセージでタイトルを指定することもできます。 |
| サブタイトル | 文字列 | 省略可 コンテンツの説明的なサブタイトル。プレーヤーは content_id を使用してタイトルを個別に取得できます。また、送信者が Load メッセージでタイトルを指定することもできます。 |
| 画像 | Image[] | 省略可 。コンテンツに関連付けられた画像への URL の配列。フィールドの初期値は、送信者が Load メッセージで指定できます。推奨サイズを提供する必要がある |
| releaseDate | 文字列（ISO 8601） | 省略可 : このコンテンツがリリースされた ISO 8601 の日時。プレーヤーは content_id を使用してタイトルを個別に取得できます。また、送信者が Load メッセージでタイトルを指定することもできます。 |
MovieMediaMetadata
映画メディア アーティファクトを説明します。
| 名前 | タイプ | 説明 |
|---|---|---|
| metadataType | integer | 1（唯一の値） |
| title | 文字列 | 省略可 コンテンツのわかりやすいタイトル。プレーヤーは content_id を使用してタイトルを個別に取得できます。また、送信者が Load メッセージでタイトルを指定することもできます。 |
| サブタイトル | 文字列 | 省略可 コンテンツの説明的なサブタイトル。プレーヤーは content_id を使用してタイトルを個別に取得できます。また、送信者が Load メッセージでタイトルを指定することもできます。 |
| studio | 文字列 | コンテンツをリリースしたオプションの スタジオ。プレーヤーは content_id を使用してスタジオを個別に取得できます。また、送信側から Load メッセージで渡すこともできます。 |
| 画像 | Image[] | 省略可 。コンテンツに関連付けられた画像への URL の配列。フィールドの初期値は、送信者が Load メッセージで指定できます。推奨サイズを提供する必要がある |
| releaseDate | 文字列（ISO 8601） | 省略可 : このコンテンツがリリースされた ISO 8601 の日時。プレーヤーは content_id を使用してタイトルを個別に取得できます。また、送信者が Load メッセージでタイトルを指定することもできます。 |
TvShowMediaMetadata
テレビ番組のエピソードのメディア アーティファクトについて説明します。
| 名前 | タイプ | 説明 |
|---|---|---|
| metadataType | integer | 2（唯一の値） |
| seriesTitle | 文字列 | 省略可 テレビシリーズの説明的なタイトル。プレーヤーは content_id を使用してタイトルを個別に取得できます。また、送信者が Load メッセージでタイトルを指定することもできます。 |
| サブタイトル | 文字列 | 省略可 。テレビ番組のエピソードの説明的なサブタイトル。プレーヤーは content_id を使用してタイトルを個別に取得できます。また、送信者が Load メッセージでタイトルを指定することもできます。 |
| season | integer | 省略可 。テレビ番組のシーズン番号 |
| episode | integer | 省略可 : テレビ番組のエピソード番号（シーズン内） |
| 画像 | Image[] | 省略可 。コンテンツに関連付けられた画像への URL の配列。フィールドの初期値は、送信者が Load メッセージで指定できます。推奨サイズを提供すべき |
| originalAirDate | 文字列（ISO 8601） | 省略可 。このエピソードがリリースされた ISO 8601 の日時。プレーヤーは content_id を使用して originalAirDate を個別に取得できます。また、送信側が Load メッセージで指定することもできます。 |
MusicTrackMediaMetadata
音楽トラックのメディア アーティファクトを表します。
| 名前 | タイプ | 説明 |
|---|---|---|
| metadataType | integer | 3（唯一の値） |
| albumName | 文字列 | 省略可 - このトラックが属するアルバムまたはコレクション。プレーヤーは、content_id を使用して albumName を個別に取得できます。また、送信者が Load メッセージで指定することもできます。 |
| title | 文字列 | 省略可 。トラックの名前（曲のタイトルなど）。プレーヤーは content_id を使用してタイトルを個別に取得できます。また、送信者が Load メッセージでタイトルを指定することもできます。 |
| albumArtist | 文字列 | 省略可 このトラックが収録されているアルバムに関連付けられているアーティストの名前。プレーヤーは content_id を使用して albumArtist を個別に取得できます。また、送信者が Load メッセージで指定することもできます。 |
| アーティスト | 文字列 | 省略可 。メディア トラックに関連付けられたアーティストの名前。プレーヤーは content_id を使用してアーティストを個別に取得できます。また、送信者から Load メッセージで提供することもできます。 |
| composer | 文字列 | 省略可 。メディア トラックに関連付けられた作曲家の名前。プレーヤーは content_id を使用してコンポーザーを個別に取得できます。また、送信者が Load メッセージでコンポーザーを指定することもできます。 |
| trackNumber | integer | 省略可 アルバム内のトラックの番号 |
| discNumber | integer | 省略可 アルバムのボリューム（ディスクなど）の番号 |
| 画像 | Image[] | 省略可 。コンテンツに関連付けられた画像への URL の配列。フィールドの初期値は、送信者が Load メッセージで指定できます。推奨サイズを提供する必要がある |
| releaseDate | 文字列（ISO 8601） | 省略可 : このコンテンツがリリースされた ISO 8601 の日時。プレーヤーは、content_id を使用して releaseDate を個別に取得できます。また、送信者が Load メッセージで指定することもできます。 |
PhotoMediaMetadata
写真メディア アーティファクトについて説明します。
| 名前 | タイプ | 説明 |
|---|---|---|
| metadataType | integer | 4（唯一の値） |
| title | 文字列 | 省略可 写真のタイトル。プレーヤーは content_id を使用してタイトルを個別に取得できます。また、送信者が Load メッセージでタイトルを指定することもできます。 |
| アーティスト | 文字列 | 省略可 : 写真家の名前。プレーヤーは content_id を使用してアーティストを個別に取得できます。また、送信者から Load メッセージで提供することもできます。 |
| location | 文字列 | 省略可 : 写真が撮影された場所（「スペイン、マドリード」など）。プレーヤーは content_id を使用して位置情報を個別に取得することも、送信者から Load メッセージで渡されることもあります。 |
| latitude | double | 省略可 。写真が撮影された場所の地理的な緯度の値。プレーヤーは content_id を使用して緯度を個別に取得できます。また、送信者が Load メッセージで緯度を指定することもできます。 |
| longitude | double | 省略可 。写真が撮影された場所の地理的な経度の値。プレーヤーは content_id を使用して経度を個別に取得できます。また、送信者が Load メッセージで経度を指定することもできます。 |
| width | integer | 省略可 写真の幅（ピクセル単位）。プレーヤーは content_id を使用して幅を個別に取得できます。また、送信側から Load メッセージで幅が渡されることもあります。 |
| height | integer | 省略可 。写真の高さ（ピクセル単位）。プレーヤーは content_id を使用して高さを個別に取得することも、送信側から Load メッセージで渡されることもあります。 |
| creationDateTime | 文字列（ISO 8601） | 省略可 : この写真が撮影された ISO 8601 の日時。プレーヤーは content_id を使用して creationDateTime を個別に取得できます。また、送信者が Load メッセージで指定することもできます。 |
MediaStatus
セッションに関するメディア アーティファクトの現在のステータスを説明します。
| 名前 | タイプ | 説明 |
|---|---|---|
| mediaSessionId | integer | この特定のセッションの再生の一意の ID。この ID は、読み込み時にレシーバーによって設定され、再生の特定のインスタンスを識別するために使用できます。たとえば、同じセッション内で「Wish you were here」を 2 回再生した場合、それぞれに一意の mediaSessionId が割り当てられます。 |
| media | MediaInformation | 省略可（ステータス メッセージの場合） 再生中のコンテンツの完全な説明。MediaInformation が変更された場合にのみ、ステータス メッセージで返されます。 |
| playbackRate | float | メディアの時間が進行しているかどうか、またその速度を示します。メディア時間はどの状態でも停止できるため、プレーヤーの状態とは無関係です。1.0 は通常速度、0.5 はスローモーション |
| playerState | enum（文字列） | プレーヤーの状態を次のいずれかで表します。
|
| idleReason | enum（文字列） | 省略可 : playerState が IDLE で、IDLE になった理由がわかっている場合、このプロパティが提供されます。プレーヤーが起動したばかりで IDLE 状態の場合、このプロパティは提供されません。プレーヤーが他の状態の場合、このプロパティは提供されません。次の値が適用されます。
|
| currentTime | double | コンテンツの開始からのメディア プレーヤーの現在の位置（秒単位）。ライブ配信コンテンツの場合、このフィールドはイベントの開始からプレーヤーに認識させるまでの時間（秒単位）を表します。 |
| supportedMediaCommands | flags | メディア プレーヤーがサポートするメディア コマンドを示すフラグ:
組み合わせは合計として記述されます。たとえば、Pause+Seek+StreamVolume+Mute == 15 です。 |
| ボリューム | Volume | ストリームの音量 |
| customData | オブジェクト | 省略可 : レシーバ アプリケーションによって定義されたアプリケーション固有のデータ blob |
送信者から受信者へのコマンド
これらのコマンドはメディア プレーヤーを制御します。以下のメッセージ内のすべての customData オブジェクトは省略可能である必要があります（つまり、データが渡されなかった場合、受信側は適切にデグレードする必要があります）。これにより、汎用リモコン アプリが正しく動作するようになります。
読み込み
新しいコンテンツをメディア プレーヤーに読み込みます。
| 名前 | タイプ | 説明 |
|---|---|---|
| requestId | integer | リクエストとレスポンスを関連付けるためのリクエストの ID |
| type | 文字列 | LOAD （値のみ） |
| media | MediaInformation | 読み込むメディアのメタデータ（contentId を含む） |
| autoplay | ブール値 | 省略可 （デフォルトは true）自動再生パラメータが指定されている場合、メディア プレーヤーはコンテンツが読み込まれると再生を開始します。自動再生が指定されていない場合でも、メディア プレーヤーの実装で直ちに再生を開始することを選択できます。再生が開始された場合、レスポンスのプレーヤーの状態は BUFFERING に設定されます。それ以外の場合は、PAUSED に設定されます。 |
| currentTime | double | 省略可 : コンテンツの開始からの秒数。コンテンツがライブ コンテンツで、位置が指定されていない場合、ストリームはライブ位置から開始されます。 |
| customData | オブジェクト | 省略可 送信側アプリによって定義されたアプリ固有のデータ blob |
| レスポンス | トリガー | ブロードキャスト | エラー |
|---|---|---|---|
| なし | 受信者の状態変更 | メディア ステータス変更メッセージ | Invalid Player State Load Failed Load Cancelled |
一時停止
現在のコンテンツの再生を一時停止します。すべての送信側アプリに STATUS イベント通知をトリガーします。
| 名前 | タイプ | 説明 |
|---|---|---|
| mediaSessionId | integer | 一時停止するメディア セッションの ID |
| requestId | integer | リクエスト/レスポンスの関連付けに使用するリクエストの ID |
| type | 文字列 | PAUSE （唯一の値） |
| customData | オブジェクト | 省略可 送信側アプリによって定義されたアプリ固有のデータ blob |
| レスポンス | トリガー | ブロードキャスト | エラー |
|---|---|---|---|
| なし | 受信者の状態変更 | メディア ステータス変更メッセージ | プレーヤーの状態が無効です |
シーク
ストリーム内の現在位置を設定します。すべての送信側アプリに STATUS イベント通知をトリガーします。指定された位置が現在のコンテンツの有効な位置の範囲外である場合、プレーヤーはリクエストされた位置にできるだけ近い有効な位置を選択する必要があります。
| 名前 | タイプ | 説明 |
|---|---|---|
| mediaSessionId | integer | ストリームの位置が設定されているメディア セッションの ID |
| requestId | integer | リクエストとレスポンスを関連付けるためのリクエストの ID |
| type | 文字列 | SEEK （値のみ） |
| resumeState | enum（文字列） | 省略可 : 設定されていない場合、再生ステータスは変更されません。次の値が適用されます。
|
| currentTime | double | 省略可 : コンテンツの開始からの秒数。コンテンツがライブ コンテンツで、位置が指定されていない場合、ストリームはライブ位置から開始されます。 |
| customData | オブジェクト | 省略可 送信側アプリによって定義されたアプリ固有のデータ blob |
| レスポンス | トリガー | ブロードキャスト | エラー |
|---|---|---|---|
| なし | 受信者の状態変更 | メディア ステータス変更メッセージ | プレーヤーの状態が無効です |
停止
現在のコンテンツの再生を停止します。すべての送信側アプリに STATUS イベント通知をトリガーします。このコマンドの後、コンテンツは読み込まれなくなり、mediaSessionId は無効になります。
| 名前 | タイプ | 説明 |
|---|---|---|
| mediaSessionId | integer | 停止するコンテンツのメディア セッションの ID |
| requestId | integer | リクエストとレスポンスを関連付けるためのリクエストの ID |
| type | 文字列 | STOP （値のみ） |
| customData | オブジェクト | 省略可 送信側アプリによって定義されたアプリ固有のデータ blob |
| レスポンス | トリガー | ブロードキャスト | エラー |
|---|---|---|---|
| なし | 受信者の状態変更 | メディア ステータス変更メッセージ | プレーヤーの状態が無効です |
再生
load 呼び出しで読み込まれたコンテンツの再生を開始します。再生は現在の時間位置から続行されます。
| 名前 | タイプ | 説明 |
|---|---|---|
| mediaSessionId | integer | 再生するコンテンツのメディア セッションの ID |
| requestId | integer | リクエストとレスポンスを関連付けるためのリクエストの ID |
| type | 文字列 | PLAY （値のみ） |
| customData | オブジェクト | 省略可 送信側アプリによって定義されたアプリ固有のデータ blob |
| レスポンス | トリガー | ブロードキャスト | エラー |
|---|---|---|---|
| なし | 受信者の状態変更 | メディア ステータス変更メッセージ | プレーヤーの状態が無効です |
ステータスを取得する
メディアのステータスを取得します。
| 名前 | タイプ | 説明 |
|---|---|---|
| mediaSessionId | integer | 省略可 : メディア ステータスを返すメディアのメディア セッション ID。指定されていない場合は、すべてのメディア セッション ID のステータスが提供されます。 |
| requestId | integer | リクエストとレスポンスを関連付けるためのリクエストの ID |
| type | 文字列 | GET_STATUS （値のみ） |
| customData | オブジェクト | 省略可 送信側アプリによって定義されたアプリ固有のデータ blob |
| レスポンス | トリガー | ブロードキャスト | エラー |
|---|---|---|---|
| リクエストした送信者への MediaStatus メッセージ | なし | なし | なし |
SetVolume
メディア ストリームの音量を設定します。メディア ストリームのフェードイン/フェードアウト効果に使用されます。（注: レシーバーの音量は、ウェブ送信者の setVolume を使用して変更されます）。ストリームの音量を音量スライダーや音量ボタンと組み合わせてデバイスの音量を制御してはなりません。ストリームの音量を変更しても、レシーバーの UI はトリガーされません。
| 名前 | タイプ | 説明 |
|---|---|---|
| mediaSessionId | integer | ストリームの音量が変更されたメディアのメディア セッション ID |
| requestId | integer | リクエストとレスポンスを関連付けるためのリクエストの ID |
| type | 文字列 | VOLUME （値のみ） |
| ボリューム | Volume | ストリームの音量 |
| customData | オブジェクト | 省略可 送信側アプリによって定義されたアプリ固有のデータ blob |
| レスポンス | トリガー | ブロードキャスト | エラー |
|---|---|---|---|
| なし | 受信者の状態変更 | メディア ステータス変更メッセージ | プレーヤーの状態が無効です |
受信者から送信者へのメッセージ
レシーバは次の 2 種類のメッセージを送信します。
- エラー: 送信者のリクエストに対するエラー レスポンスがある場合に送信されるユニキャスト メッセージ。
- ステータス: ブロードキャスト メッセージ。
- 送信者が開始したアクションの結果。変更の原因となったリクエストの requestId が含まれます。
- 自発的: たとえば、レシーバー アプリケーションによってトリガーされた変更による場合。RequestId は 0 になります。
エラー: 無効なプレーヤーの状態
プレーヤーが無効な状態のため、送信者によるリクエストを処理できない場合に送信されます。たとえば、アプリがまだメディア要素を作成していない場合などです。
| 名前 | タイプ | 説明 |
|---|---|---|
| requestId | integer | このエラーを生成したリクエストの ID |
| type | 文字列 | INVALID_PLAYER_STATE （唯一の値） |
| customData | オブジェクト | 省略可 : レシーバ アプリケーションによって定義されたアプリケーション固有のデータ blob |
エラー: 読み込みに失敗しました
読み込みリクエストが失敗したときに送信されます。プレーヤーの状態は IDLE になります。
| 名前 | タイプ | 説明 |
|---|---|---|
| requestId | integer | このエラーを生成したリクエストの ID |
| type | 文字列 | LOAD_FAILED （値のみ） |
| customData | オブジェクト | 省略可 : レシーバ アプリケーションによって定義されたアプリケーション固有のデータ blob |
エラー: Load Cancelled
読み込みリクエストがキャンセルされた（2 回目の読み込みリクエストが受信された）ときに送信されます。
| 名前 | タイプ | 説明 |
|---|---|---|
| requestId | integer | このエラーを生成したリクエストの ID |
| type | 文字列 | LOAD_CANCELLED （値のみ） |
| customData | オブジェクト | 省略可 : レシーバ アプリケーションによって定義されたアプリケーション固有のデータ blob |
エラー: 無効なリクエスト
リクエストが無効な場合（不明なリクエスト タイプなど）に送信されます。
| 名前 | タイプ | 説明 |
|---|---|---|
| requestId | integer | このエラーを生成したリクエストの ID |
| type | 文字列 | INVALID_REQUEST （値のみ） |
| reason | Enum（文字列） | 値:
|
| customData | オブジェクト | 省略可 : レシーバ アプリケーションによって定義されたアプリケーション固有のデータ blob |
メディア ステータス
状態が変化した後、またはメディア ステータス リクエストの後に送信されます。変更された MediaStatus オブジェクトまたはリクエストされた MediaStatus オブジェクトのみが送信されます。
| 名前 | タイプ | 説明 |
|---|---|---|
| requestId | integer | このステータス レスポンスを、そのレスポンスの発生元となったリクエストと関連付けるために使用される ID。ステータス メッセージが自発的なもの（送信者のリクエストによってトリガーされたものではない）場合は 0。送信側アプリケーションは、乱数を選択して継続的に増加させることで、一意のリクエスト ID を生成します（0 は使用しません）。 |
| type | 文字列 | MEDIA_STATUS （値のみ） |
| status | MediaStatus[] | メディア ステータス オブジェクトの配列。注: MediaStatus のメディア要素は、変更された場合にのみ返されます。 |
| customData | オブジェクト | 省略可 : レシーバ アプリケーションによって定義されたアプリケーション固有のデータ blob |