Aplikasi pengirim Google Cast mengontrol pemutaran pada perangkat penerima dengan mengirimkan pesan dalam format JSON ke aplikasi penerima. Demikian juga, penerima mengirim pesan kembali ke pengirim, juga dalam JSON. Pesan mungkin berupa perintah dari pengirim yang mengubah status pemutar, merespons perintah tersebut dari penerima, atau struktur data yang menjelaskan media untuk aplikasi penerima.
Setelah Persyaratan Layanan Developer Tambahan Google Cast SDK, aplikasi media Cast harus menggunakan pesan tersebut seperti yang dijelaskan di sini untuk mengontrol pemutaran media pada penerima. Cara ini akan memberi aplikasi media pengalaman pengguna yang konsisten di seluruh platform dan memastikan aplikasi Cast akan mendukung kasus penggunaan baru dan mendatang. Struktur ini juga mendukung data kustom, jika perlu, dan aplikasi dapat menentukan pesannya sendiri untuk perintah yang tidak didukung oleh SDK.
Namespace untuk pesan pemutaran media ditentukan sebagai urn:x-cast:com.google.cast.media.
Catatan: Pesan dan struktur dalam spesifikasi ini memiliki ukuran maksimum implisit yang ditentukan dengan ukuran maksimum pesan transpor, tidak ada batas untuk masing-masing kolom. Ukuran maksimum pesan transportasi saat ini adalah 64 KByte.
Struktur data namespace umum
Superset struktur data yang digunakan oleh semua artefak namespace media ditentukan dalam namespace umum.
Gambar
Ini adalah deskripsi gambar, termasuk sejumlah kecil metadata untuk memungkinkan aplikasi pengirim memilih gambar, tergantung pada bagaimana gambar akan dirender.
Tinggi dan lebar bersifat opsional hanya pada satu item dalam array Gambar. Misalnya, jika ada satu item yang ditampilkan, item tersebut bersifat opsional; jika ada dua item yang ditampilkan, satu item harus menentukan tinggi dan lebar, tetapi pengirim dapat memilih untuk menggunakan opsi "default" jika tidak menyukai item yang diteruskan dengan parameter tertentu.
| Nama | Jenis | Deskripsi |
|---|---|---|
| url | URI | URI untuk gambar |
| height | bilangan bulat | opsional Tinggi gambar |
| lebar | bilangan bulat | opsional Lebar gambar |
Volume
Volume streaming media. Digunakan untuk efek fade-in/fade-out pada streaming media. (Catatan: volume sistem diubah menggunakan API pengirim.) Volume streaming tidak boleh digunakan bersama penggeser volume atau tombol volume untuk mengontrol volume perangkat. Setidaknya salah satu dari parameter berikut harus diteruskan untuk mengubah volume streaming.
| Nama | Jenis | Deskripsi |
|---|---|---|
| level | ganda | opsional Tingkat volume streaming saat ini sebagai nilai antara 0,0 dan 1,0 dengan 1,0 adalah volume maksimum. |
| dinonaktifkan | boolean | opsional Apakah perangkat Transmisi dibisukan, terlepas dari level volumenya |
Struktur data namespace media
Pesan ini menjelaskan status pemutar media. Namespacenya adalah urn:x-cast:com.google.cast.media.
MediaInformation
Struktur data ini menjelaskan aliran media.
| Nama | Jenis | Deskripsi |
|---|---|---|
| contentId | string | ID khusus layanan untuk konten yang saat ini dimuat oleh pemutar media. Ini adalah string bentuk bebas dan khusus untuk aplikasi. Umumnya, ini akan menjadi URL ke media, tetapi pengirim dapat memilih untuk meneruskan string yang dapat ditafsirkan dengan benar oleh penerima. Panjang maks: 1k |
| streamType | enum (string) |
Menjelaskan jenis artefak media sebagai salah satu dari berikut ini:
|
| contentType | string | Jenis konten MIME dari media yang diputar |
| metadata | objek | opsional Objek metadata media, salah satu dari yang berikut: |
| duration | ganda | opsional Durasi streaming yang sedang diputar dalam hitungan detik |
| customData | objek | opsional Blob data khusus aplikasi yang ditentukan oleh aplikasi pengirim atau aplikasi penerima |
GenericMediaMetadata
Menjelaskan artefak media generik.
| Nama | Jenis | Deskripsi |
|---|---|---|
| metadataType | bilangan bulat | 0 (satu-satunya nilai) |
| title | string | opsional Judul deskriptif konten. Pemutar dapat mengambil judul secara mandiri menggunakan content_id, atau dapat diberikan oleh pengirim dalam pesan Muat |
| subtitel | string | opsional Subtitel deskriptif konten. Pemutar dapat mengambil judul secara mandiri menggunakan content_id, atau dapat diberikan oleh pengirim dalam pesan Muat |
| gambar | Gambar[] | opsional Array URL ke gambar yang terkait dengan konten. Nilai awal kolom dapat diberikan oleh pengirim dalam pesan Muat. Harus menyediakan ukuran yang direkomendasikan |
| releaseDate | string (ISO 8601) | opsional ISO 8601 tanggal dan waktu konten ini dirilis. Pemutar dapat mengambil judul secara mandiri menggunakan content_id, atau dapat diberikan oleh pengirim dalam pesan Muat |
MovieMediaMetadata
Menjelaskan artefak media film.
| Nama | Jenis | Deskripsi |
|---|---|---|
| metadataType | bilangan bulat | 1 (satu-satunya nilai) |
| title | string | opsional Judul deskriptif konten. Pemutar dapat mengambil judul secara mandiri menggunakan content_id, atau dapat diberikan oleh pengirim dalam pesan Muat |
| subtitel | string | opsional Subtitel deskriptif konten. Pemutar dapat mengambil judul secara mandiri menggunakan content_id, atau dapat diberikan oleh pengirim dalam pesan Muat |
| studio | string | opsional Studio yang merilis konten tersebut. Pemutar dapat mengambil studio sendiri menggunakan content_id atau dapat diberikan oleh pengirim dalam pesan Muat |
| gambar | Gambar[] | opsional Array URL ke gambar yang terkait dengan konten. Nilai awal kolom dapat diberikan oleh pengirim dalam pesan Muat. Harus menyediakan ukuran yang direkomendasikan |
| releaseDate | string (ISO 8601) | opsional ISO 8601 tanggal dan waktu konten ini dirilis. Pemutar dapat mengambil judul secara mandiri menggunakan content_id, atau dapat diberikan oleh pengirim dalam pesan Muat |
TvShowMediaMetadata
Menjelaskan artefak media episode acara televisi.
| Nama | Jenis | Deskripsi |
|---|---|---|
| metadataType | bilangan bulat | 2 (satu-satunya nilai) |
| seriesTitle | string | opsional Judul deskriptif serial t.v. Pemutar dapat mengambil judul secara mandiri menggunakan content_id, atau dapat diberikan oleh pengirim dalam pesan Muat |
| subtitel | string | opsional Subtitel deskriptif episode t.v. Pemutar dapat mengambil judul secara mandiri menggunakan content_id, atau dapat diberikan oleh pengirim dalam pesan Muat |
| musim | bilangan bulat | opsional Nomor season acara t.v. |
| episode | bilangan bulat | opsional Nomor episode (di season) acara t.v. |
| gambar | Gambar[] | opsional Array URL ke gambar yang terkait dengan konten. Nilai awal kolom dapat diberikan oleh pengirim dalam pesan Muat. Harus menyediakan ukuran yang direkomendasikan |
| originalAirDate | string (ISO 8601) | opsional ISO 8601 tanggal dan waktu episode ini dirilis. Pemutar dapat mengambil originalAirDate secara independen menggunakan content_id atau dapat diberikan oleh pengirim dalam pesan Load |
MusicTrackMediaMetadata
Menjelaskan artefak media trek musik.
| Nama | Jenis | Deskripsi |
|---|---|---|
| metadataType | bilangan bulat | 3 (satu-satunya nilai) |
| albumName | string | opsional Album atau koleksi yang digunakan untuk mengambil lagu ini. Pemutar dapat mengambil albumName secara mandiri menggunakan content_id, atau dapat diberikan oleh pengirim dalam pesan Muat |
| title | string | opsional Nama lagu (misalnya, judul lagu). Pemutar dapat mengambil judul secara mandiri menggunakan content_id, atau dapat diberikan oleh pengirim dalam pesan Muat |
| albumArtist | string | opsional Nama artis yang terkait dengan album yang menampilkan lagu ini. Pemutar dapat mengambil albumArtist secara mandiri menggunakan content_id, atau dapat diberikan oleh pengirim dalam pesan Muat |
| artis | string | opsional Nama artis yang terkait dengan trek media. Pemutar dapat mengambil artis sendiri menggunakan content_id, atau dapat diberikan oleh pengirim dalam pesan Muat |
| composer | string | opsional Nama komposer yang terkait dengan trek media. Pemutar dapat mengambil komposer secara mandiri menggunakan content_id, atau dapat diberikan oleh pengirim dalam pesan Load |
| trackNumber | bilangan bulat | opsional Jumlah lagu dalam album |
| discNumber | bilangan bulat | opsional Jumlah volume (misalnya, disk) album |
| gambar | Gambar[] | opsional Array URL ke gambar yang terkait dengan konten. Nilai awal kolom dapat diberikan oleh pengirim dalam pesan Muat. Harus menyediakan ukuran yang direkomendasikan |
| releaseDate | string (ISO 8601) | opsional ISO 8601 tanggal dan waktu konten ini dirilis. Pemutar dapat mengambil releaseDate secara independen menggunakan content_id atau dapat diberikan oleh pengirim dalam pesan Load |
PhotoMediaMetadata
Menjelaskan artefak media fotografi.
| Nama | Jenis | Deskripsi |
|---|---|---|
| metadataType | bilangan bulat | 4 (satu-satunya nilai) |
| title | string | opsional Judul foto. Pemutar dapat mengambil judul secara mandiri menggunakan content_id, atau dapat diberikan oleh pengirim dalam pesan Muat |
| artis | string | opsional Nama fotografer. Pemutar dapat mengambil artis sendiri menggunakan content_id, atau dapat diberikan oleh pengirim dalam pesan Muat |
| lokasi | string | opsional Lokasi lisan tempat foto diambil; misalnya, "Madrid, Spanyol". Pemutar dapat mengambil lokasi secara mandiri menggunakan content_id atau dapat diberikan oleh pengirim dalam pesan Muat |
| latitude | ganda | opsional Nilai lintang geografis untuk lokasi tempat foto diambil. Pemutar dapat mengambil lintang secara mandiri menggunakan content_id atau dapat diberikan oleh pengirim dalam pesan Muat |
| longitude | ganda | opsional Nilai bujur geografis untuk lokasi tempat foto diambil. Pemutar dapat mengambil garis bujur secara terpisah menggunakan content_id atau dapat diberikan oleh pengirim dalam pesan Muat |
| lebar | bilangan bulat | opsional Lebar foto dalam piksel. Pemutar dapat mengambil lebar secara terpisah menggunakan content_id atau dapat diberikan oleh pengirim dalam pesan Muat |
| height | bilangan bulat | opsional Tinggi dalam piksel foto. Pemutar dapat mengambil tinggi secara terpisah menggunakan content_id atau dapat diberikan oleh pengirim dalam pesan Muat |
| creationDateTime | string (ISO 8601) | opsional ISO 8601 tanggal dan waktu pengambilan foto ini. Pemutar dapat mengambil creationDateTime secara independen menggunakan content_id atau dapat diberikan oleh pengirim dalam pesan Load |
MediaStatus
Menjelaskan status artefak media saat ini sehubungan dengan sesi.
| Nama | Jenis | Deskripsi |
|---|---|---|
| mediaSessionId | bilangan bulat | ID unik untuk pemutaran sesi khusus ini. ID ini disetel oleh penerima pada saat LOAD dan dapat digunakan untuk mengidentifikasi instance pemutaran tertentu. Misalnya, dua pemutaran "Wish you were here" dalam sesi yang sama masing-masing akan memiliki mediaSessionId unik. |
| media | MediaInformation | opsional (untuk pesan status) Deskripsi lengkap konten yang sedang diputar. Hanya ditampilkan dalam pesan status jika MediaInformation telah berubah. |
| playbackRate | float | Menunjukkan apakah waktu media sedang berlangsung, dan kecepatannya. Hal ini tidak bergantung pada status pemutar karena waktu media dapat berhenti dalam status apa pun. 1.0 adalah waktu biasa, 0.5 adalah gerak lambat |
| playerState | enum (string) | Menjelaskan status pemutar sebagai salah satu dari yang berikut:
|
| idleReason | enum (string) | opsional Jika playerState berstatus IDLE dan alasannya menjadi IDLE diketahui, properti ini akan diberikan. Jika pemain menganggur karena baru saja dimulai, properti ini tidak akan diberikan; jika pemain berada dalam negara lain, properti ini tidak boleh diberikan. Nilai-nilai berikut berlaku:
|
| currentTime | ganda | Posisi saat ini pemutar media sejak awal konten, dalam detik. Jika ini adalah konten live stream, kolom ini menunjukkan waktu dalam detik dari awal acara yang harus diketahui oleh pemain. |
| supportedMediaCommands | flag | Tanda yang menjelaskan perintah media yang didukung pemutar media:
Kombinasi dijelaskan sebagai penjumlahan; misalnya, Pause+Seek+StreamVolume+Mute == 15. |
| volume | Volume | Volume streaming |
| customData | objek | opsional Blob data khusus aplikasi yang ditentukan oleh aplikasi penerima |
Perintah dari pengirim ke penerima
Perintah ini mengontrol pemutar media. Semua objek customData dalam pesan di bawah harus bersifat opsional (yaitu penerima harus melakukan degradasi dengan benar jika data tidak diteruskan). Tindakan ini akan memungkinkan aplikasi remote control umum berfungsi dengan baik.
Muat
Memuat konten baru ke pemutar media.
| Nama | Jenis | Deskripsi |
|---|---|---|
| requestId | bilangan bulat | ID permintaan, untuk menghubungkan permintaan dan respons |
| jenis | string | LOAD (hanya nilai) |
| media | MediaInformation | Metadata (termasuk contentId) media yang akan dimuat |
| putar otomatis | boolean | opsional (defaultnya adalah true) Jika parameter putar otomatis ditentukan, pemutar media akan mulai memutar konten saat dimuat. Bahkan jika putar otomatis tidak ditentukan, penerapan pemutar media dapat memilih untuk segera memulai pemutaran. Jika pemutaran dimulai, status pemutar dalam respons harus disetel ke BUFFERING. Jika tidak, status pemutar harus DIJEDA |
| currentTime | ganda | opsional Detik sejak awal konten. Jika konten adalah konten live, dan posisinya tidak ditentukan, streaming akan dimulai pada posisi live |
| customData | objek | opsional Blob data khusus aplikasi yang ditentukan oleh aplikasi pengirim |
| Respons | Pemicu | Siaran | Error |
|---|---|---|---|
| Tidak ada | Perubahan status penerima | Pesan Perubahan Status Media | Status Pemutar Tidak Valid Pemuatan Gagal Pemuatan Dibatalkan |
Jeda
Menjeda pemutaran konten saat ini. Memicu notifikasi peristiwa STATUS ke semua aplikasi pengirim.
| Nama | Jenis | Deskripsi |
|---|---|---|
| mediaSessionId | bilangan bulat | ID sesi media yang akan dijeda |
| requestId | bilangan bulat | ID permintaan, yang digunakan untuk menghubungkan permintaan/respons |
| jenis | string | JEDA (hanya nilai) |
| customData | objek | opsional Blob data khusus aplikasi yang ditentukan oleh aplikasi pengirim |
| Respons | Pemicu | Siaran | Error |
|---|---|---|---|
| Tidak ada | Perubahan status penerima | Pesan Perubahan Status Media | Status Pemutar tidak valid |
Cari
Menetapkan posisi saat ini dalam aliran data. Memicu notifikasi peristiwa STATUS ke semua aplikasi pengirim. Jika posisi yang diberikan berada di luar rentang posisi yang valid untuk konten saat ini, maka pemutar harus memilih posisi yang valid sedekat mungkin dengan posisi yang diminta.
| Nama | Jenis | Deskripsi |
|---|---|---|
| mediaSessionId | bilangan bulat | ID sesi media tempat posisi streaming ditetapkan |
| requestId | bilangan bulat | ID permintaan, untuk menghubungkan permintaan dan respons |
| jenis | string | SEEK (hanya nilai) |
| resumeState | enum (string) | opsional Jika tidak disetel, status pemutaran tidak akan berubah; nilai berikut berlaku:
|
| currentTime | ganda | opsional Detik sejak awal konten. Jika konten adalah konten live, dan posisinya tidak ditentukan, streaming akan dimulai pada posisi live |
| customData | objek | opsional Blob data khusus aplikasi yang ditentukan oleh aplikasi pengirim |
| Respons | Pemicu | Siaran | Error |
|---|---|---|---|
| Tidak ada | Perubahan status penerima | Pesan Perubahan Status Media | Status Pemutar tidak valid |
Hentikan
Menghentikan pemutaran konten saat ini. Memicu notifikasi peristiwa STATUS ke semua aplikasi pengirim. Setelah perintah ini, konten tidak akan lagi dimuat dan mediaSessionId menjadi tidak valid.
| Nama | Jenis | Deskripsi |
|---|---|---|
| mediaSessionId | bilangan bulat | ID sesi media untuk konten yang akan dihentikan |
| requestId | bilangan bulat | ID permintaan, untuk menghubungkan permintaan dan respons |
| jenis | string | STOP (hanya nilai) |
| customData | objek | opsional Blob data khusus aplikasi yang ditentukan oleh aplikasi pengirim |
| Respons | Pemicu | Siaran | Error |
|---|---|---|---|
| Tidak ada | Perubahan status penerima | Pesan Perubahan Status Media | Status Pemutar tidak valid |
Putar
Memulai pemutaran konten yang dimuat dengan panggilan pemuatan, pemutaran dilanjutkan dari posisi waktu saat ini.
| Nama | Jenis | Deskripsi |
|---|---|---|
| mediaSessionId | bilangan bulat | ID sesi media untuk konten yang akan diputar |
| requestId | bilangan bulat | ID permintaan, untuk menghubungkan permintaan dan respons |
| jenis | string | PLAY (hanya nilai) |
| customData | objek | opsional Blob data khusus aplikasi yang ditentukan oleh aplikasi pengirim |
| Respons | Pemicu | Siaran | Error |
|---|---|---|---|
| Tidak ada | Perubahan status penerima | Pesan Perubahan Status Media | Status Pemutar tidak valid |
Mendapatkan Status
Mengambil status media.
| Nama | Jenis | Deskripsi |
|---|---|---|
| mediaSessionId | bilangan bulat | opsional ID sesi media dari media yang status medianya harus ditampilkan. Jika tidak ada yang disediakan, status untuk semua ID sesi media akan diberikan. |
| requestId | bilangan bulat | ID permintaan, untuk menghubungkan permintaan dan respons |
| jenis | string | GET_STATUS (hanya nilai) |
| customData | objek | opsional Blob data khusus aplikasi yang ditentukan oleh aplikasi pengirim |
| Respons | Pemicu | Siaran | Error |
|---|---|---|---|
| Pesan MediaStatus kepada pengirim yang memintanya | Tidak ada | Tidak ada | Tidak ada |
SetVolume
Menyetel volume streaming media. Digunakan untuk efek fade-in/fade-out pada streaming media. (Catatan: volume penerima diubah menggunakan setVolume pengirim Web.) Volume aliran tidak boleh digunakan bersama penggeser volume atau tombol volume untuk mengontrol volume perangkat. Perubahan volume aliran data tidak akan memicu UI apa pun pada penerima.
| Nama | Jenis | Deskripsi |
|---|---|---|
| mediaSessionId | bilangan bulat | ID Sesi Media dari media yang volume streaming-nya diubah |
| requestId | bilangan bulat | ID permintaan, untuk menghubungkan permintaan dan respons |
| jenis | string | VOLUME (hanya nilai) |
| volume | Volume | Volume streaming |
| customData | objek | opsional Blob data khusus aplikasi yang ditentukan oleh aplikasi pengirim |
| Respons | Pemicu | Siaran | Error |
|---|---|---|---|
| Tidak ada | Perubahan status penerima | Pesan Perubahan Status Media | Status Pemutar tidak valid |
Pesan dari penerima ke pengirim
Penerima mengirim dua jenis pesan:
- Error: Pesan unicast dikirim saat ada respons error terhadap permintaan pengirim.
- Status: Siarkan pesan.
- Konsekuensi dari tindakan yang dimulai pengirim. Akan berisi requestId permintaan yang menyebabkan perubahan.
- Spontan: Misalnya, karena perubahan yang dipicu oleh aplikasi penerima. IDPermintaan akan menjadi 0.
Error: Status Pemutar Tidak Valid
Dikirim saat permintaan dari pengirim tidak dapat dipenuhi karena pemutar tidak dalam status yang valid. Misalnya, jika aplikasi belum membuat elemen media.
| Nama | Jenis | Deskripsi |
|---|---|---|
| requestId | bilangan bulat | ID permintaan yang menghasilkan error ini |
| jenis | string | INVALID_Player_STATE (hanya nilai) |
| customData | objek | opsional Blob data khusus aplikasi yang ditentukan oleh aplikasi penerima |
Error: Pemuatan Gagal
Dikirim saat permintaan pemuatan gagal. Status pemutar akan menjadi IDLE.
| Nama | Jenis | Deskripsi |
|---|---|---|
| requestId | bilangan bulat | ID permintaan yang menghasilkan error ini |
| jenis | string | LOAD_FAILED (hanya nilai) |
| customData | objek | opsional Blob data khusus aplikasi yang ditentukan oleh aplikasi penerima |
Kesalahan: Muatan Dibatalkan
Dikirim saat permintaan pemuatan dibatalkan (permintaan pemuatan kedua diterima).
| Nama | Jenis | Deskripsi |
|---|---|---|
| requestId | bilangan bulat | ID permintaan yang menghasilkan error ini |
| jenis | string | LOAD_CANCELLED (hanya nilai) |
| customData | objek | opsional Blob data khusus aplikasi yang ditentukan oleh aplikasi penerima |
Error: Permintaan Tidak Valid
Dikirim saat permintaan tidak valid (misalnya, jenis permintaan yang tidak diketahui).
| Nama | Jenis | Deskripsi |
|---|---|---|
| requestId | bilangan bulat | ID permintaan yang menghasilkan error ini |
| jenis | string | INVALID_REQUEST (hanya nilai) |
| alasan | Enum (string) | Nilai:
|
| customData | objek | opsional Blob data khusus aplikasi yang ditentukan oleh aplikasi penerima |
Status media
Dikirim setelah perubahan status atau setelah permintaan status media. Hanya objek MediaStatus yang berubah atau diminta yang akan dikirim.
| Nama | Jenis | Deskripsi |
|---|---|---|
| requestId | bilangan bulat | ID yang digunakan untuk menghubungkan respons status ini dengan permintaan yang berasal darinya atau 0 jika pesan status spontan (tidak dipicu oleh permintaan pengirim). Aplikasi pengirim akan membuat ID permintaan unik dengan memilih angka acak dan terus meningkatkannya (tidak akan menggunakan 0). |
| jenis | string | MEDIA_STATUS (hanya nilai) |
| status | MediaStatus[] | Array objek Status Media. CATATAN: elemen media di MediaStatus hanya akan ditampilkan jika telah berubah. |
| customData | objek | opsional Blob data khusus aplikasi yang ditentukan oleh aplikasi penerima |