Aplikasi pengirim Google Cast mengontrol pemutaran di perangkat penerima dengan mengirimkan pesan dalam format JSON ke aplikasi penerima. Demikian pula, penerima akan mengirim pesan kembali ke pengirim, juga dalam JSON. Pesan dapat berupa perintah dari pengirim yang mengubah status pemutar, respons terhadap perintah tersebut dari penerima, atau struktur data yang mendeskripsikan media untuk aplikasi penerima.
Dengan mematuhi Persyaratan Layanan Developer Tambahan Google Cast SDK, aplikasi media Cast harus menggunakan pesan ini seperti yang dijelaskan di sini untuk mengontrol pemutaran media pada penerima. Tindakan ini akan memberi aplikasi media pengalaman pengguna yang konsisten di seluruh platform dan memastikan bahwa aplikasi Cast akan mendukung kasus penggunaan baru dan mendatang. Struktur ini juga mendukung data kustom, jika sesuai, 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 oleh ukuran maksimum pesan transportasi, tidak ada batasan untuk setiap kolom. Ukuran maksimum pesan transportasi saat ini adalah 64 KBytes.
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 yang memungkinkan aplikasi pengirim memilih gambar, bergantung pada cara gambar dirender.
Tinggi dan lebar bersifat opsional pada satu item saja dalam array Gambar. Misalnya, jika ada satu item yang dikembalikan, item tersebut bersifat opsional; jika ada dua item yang dikembalikan, satu item harus menentukan tinggi dan lebar, tetapi pengirim dapat memilih untuk menggunakan opsi "default" jika tidak seperti yang diteruskan dengan parameter tertentu.
| Name | Jenis | Deskripsi |
|---|---|---|
| url | URI | URI untuk gambar |
| tinggi | 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 dengan penggeser volume atau tombol volume untuk mengontrol volume perangkat. Setidaknya salah satu parameter berikut harus diteruskan untuk mengubah volume streaming.
| Name | Jenis | Deskripsi |
|---|---|---|
| level | dobel | opsional Tingkat volume streaming saat ini sebagai nilai antara 0,0 dan 1,0 dengan 1,0 adalah volume maksimum. |
| dibisukan | boolean | opsional Apakah perangkat Cast dibisukan, terlepas dari tingkat volume |
Struktur data namespace media
Pesan ini mendeskripsikan status pemutar media. Namespacenya adalah urn:x-cast:com.google.cast.media.
InformasiMedia
Struktur data ini menjelaskan aliran media.
| Name | Jenis | Deskripsi |
|---|---|---|
| IDKonten | string | ID khusus layanan untuk konten yang saat ini dimuat oleh pemutar media. Ini adalah string bentuk bebas dan ditujukan khusus untuk aplikasi. Umumnya, ini akan menjadi URL ke media, tetapi pengirim dapat memilih untuk meneruskan string yang dapat ditafsirkan penerima dengan benar. Panjang maks.: 1k |
| streamType | enum (string) |
Menjelaskan jenis artefak media sebagai salah satu dari yang berikut:
|
| jenisKonten | string | Jenis konten MIME media yang sedang diputar |
| metadata | Objek | opsional Objek metadata media, salah satu dari berikut ini: |
| durasi | dobel | opsional Durasi streaming yang sedang diputar dalam hitungan detik |
| datakustom | Objek | opsional Blob spesifik aplikasi pada data yang ditentukan oleh aplikasi pengirim atau aplikasi penerima |
GenericMediaMetadata
Menjelaskan artefak media generik.
| Name | Jenis | Deskripsi |
|---|---|---|
| metadataType | bilangan bulat | 0 (satu-satunya nilai) |
| title | string | opsional Judul konten yang deskriptif. Pemutar dapat mengambil judul secara independen menggunakan content_id atau dapat diberikan oleh pengirim dalam pesan Load |
| subtitel | string | opsional Subjudul konten yang deskriptif. Pemutar dapat mengambil judul secara independen menggunakan content_id atau dapat diberikan oleh pengirim dalam pesan Load |
| gambar | Gambar[] | opsional Array URL ke gambar yang terkait dengan konten. Nilai awal kolom dapat diberikan oleh pengirim dalam pesan Muat. Harus memberikan ukuran yang direkomendasikan |
| Tanggal rilis | string (ISO 8601) | opsional Tanggal dan waktu ISO 8601 konten ini dirilis. Pemutar dapat mengambil judul secara independen menggunakan content_id atau dapat diberikan oleh pengirim dalam pesan Load |
FilmMediaMetadata
Menjelaskan artefak media film.
| Name | Jenis | Deskripsi |
|---|---|---|
| metadataType | bilangan bulat | 1 (satu-satunya nilai) |
| title | string | opsional Judul konten yang deskriptif. Pemutar dapat mengambil judul secara independen menggunakan content_id atau dapat diberikan oleh pengirim dalam pesan Load |
| subtitel | string | opsional Subjudul konten yang deskriptif. Pemutar dapat mengambil judul secara independen menggunakan content_id atau dapat diberikan oleh pengirim dalam pesan Load |
| studio | string | opsional Studio yang merilis konten. Pemutar dapat mengambil studio secara independen 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 memberikan ukuran yang direkomendasikan |
| Tanggal rilis | string (ISO 8601) | opsional Tanggal dan waktu ISO 8601 konten ini dirilis. Pemutar dapat mengambil judul secara independen menggunakan content_id atau dapat diberikan oleh pengirim dalam pesan Load |
TvShowMediaMetadata
Mendeskripsikan artefak media episode acara televisi.
| Name | Jenis | Deskripsi |
|---|---|---|
| metadataType | bilangan bulat | 2 (satu-satunya nilai) |
| serialTitle | string | opsional Judul deskriptif dari serial t.v. Pemutar dapat mengambil judul secara independen menggunakan content_id atau dapat diberikan oleh pengirim dalam pesan Load |
| subtitel | string | opsional Subjudul deskriptif dari episode t.v. Pemutar dapat mengambil judul secara independen menggunakan content_id atau dapat diberikan oleh pengirim dalam pesan Load |
| musim | bilangan bulat | opsional Nomor season acara t.v. |
| episode | bilangan bulat | opsional Nomor episode (dalam 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 memberikan ukuran yang direkomendasikan |
| OriginalAirDate | string (ISO 8601) | opsional Tanggal dan waktu ISO 8601 episode ini dirilis. Pemutar dapat mengambil originalAirDate secara independen menggunakan content_id atau dapat diberikan oleh pengirim dalam pesan Muat |
MusicTrackMediaMetadata
Menjelaskan artefak media trek musik.
| Name | Jenis | Deskripsi |
|---|---|---|
| metadataType | bilangan bulat | 3 (satu-satunya nilai) |
| namaalbum | string | opsional Album atau koleksi tempat lagu ini diambil. Pemutar dapat mengambil albumName secara independen menggunakan content_id atau dapat diberikan oleh pengirim dalam pesan Muat |
| title | string | opsional Nama trek (misalnya, judul lagu). Pemutar dapat mengambil judul secara independen menggunakan content_id atau dapat diberikan oleh pengirim dalam pesan Load |
| albumArtis | string | opsional Nama artis yang terkait dengan album yang menampilkan lagu ini. Pemutar dapat mengambil albumArtist secara independen menggunakan content_id atau dapat diberikan oleh pengirim dalam pesan Load |
| artis | string | opsional Nama artis yang terkait dengan trek media. Pemutar dapat mengambil artis secara terpisah menggunakan content_id atau dapat diberikan oleh pengirim dalam pesan Load |
| komposer | string | opsional Nama komposer yang terkait dengan trek media. Pemutar dapat mengambil komposer secara independen menggunakan content_id atau dapat diberikan oleh pengirim dalam pesan Load |
| nomorPelacakan | bilangan bulat | opsional Jumlah lagu di 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 memberikan ukuran yang direkomendasikan |
| Tanggal rilis | string (ISO 8601) | opsional Tanggal dan waktu ISO 8601 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.
| Name | Jenis | Deskripsi |
|---|---|---|
| metadataType | bilangan bulat | 4 (satu-satunya nilai) |
| title | string | opsional Judul foto. Pemutar dapat mengambil judul secara independen menggunakan content_id atau dapat diberikan oleh pengirim dalam pesan Load |
| artis | string | opsional Nama fotografer. Pemutar dapat mengambil artis secara terpisah menggunakan content_id atau dapat diberikan oleh pengirim dalam pesan Load |
| lokasi | string | opsional Lokasi lisan tempat foto diambil; misalnya, "Madrid, Spanyol". Pemutar dapat mengambil lokasi secara independen menggunakan content_id atau dapat diberikan oleh pengirim dalam pesan Load |
| latitude | dobel | opsional Nilai lintang geografis untuk lokasi tempat foto diambil. Pemutar dapat mengambil garis lintang secara mandiri menggunakan content_id atau dapat diberikan oleh pengirim dalam pesan Muat |
| longitude | dobel | opsional Nilai bujur geografis untuk lokasi tempat foto diambil. Pemutar dapat mengambil bujur secara independen menggunakan content_id atau dapat diberikan oleh pengirim dalam pesan Muat |
| lebar | bilangan bulat | opsional Lebar dalam piksel foto. Pemutar dapat mengambil lebar secara independen menggunakan content_id atau dapat diberikan oleh pengirim dalam pesan Load |
| tinggi | bilangan bulat | opsional Tinggi dalam piksel foto. Pemutar dapat mengambil tinggi secara mandiri menggunakan content_id atau dapat diberikan oleh pengirim dalam pesan Muat |
| CreationDateTime | string (ISO 8601) | opsional Tanggal dan waktu ISO 8601 foto ini diambil. Pemutar dapat mengambil creationDateTime secara independen menggunakan content_id atau dapat diberikan oleh pengirim dalam pesan Load |
StatusMedia
Menjelaskan status artefak media saat ini sehubungan dengan sesi.
| Name | Jenis | Deskripsi |
|---|---|---|
| IDSesi | bilangan bulat | ID unik untuk pemutaran sesi tertentu ini. ID ini ditetapkan oleh penerima di 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 yang unik. |
| media | Informasi Media | opsional (untuk pesan status) Deskripsi lengkap tentang konten yang sedang diputar. Hanya dikembalikan dalam pesan status jika MediaInformation telah berubah. |
| rasio pemutaran | float | Menunjukkan apakah waktu media sedang berlangsung, dan berapa rasionya. Hal ini tidak bergantung pada status pemutar karena waktu media dapat berhenti dalam status apa pun. 1,0 adalah waktu reguler, 0,5 adalah gerakan lambat |
| playerState | enum (string) | Menjelaskan status pemutar sebagai salah satu dari yang berikut:
|
| idleAlasan | enum (string) | opsional Jika playerState adalah IDLE dan alasan IDLE diketahui, properti ini akan disediakan. Jika pemutar IDLE karena baru saja dimulai, properti ini tidak akan diberikan; jika pemutar berada dalam status lain, properti ini tidak boleh diberikan. Nilai berikut berlaku:
|
| waktusaat ini | dobel | Posisi pemutar media saat ini sejak awal konten, dalam detik. Jika ini konten live stream, kolom ini mewakili waktu dalam detik dari awal acara yang harus diketahui pemain. |
| supportedMediaCommands | flags | Tanda yang menjelaskan perintah media yang didukung oleh pemutar media:
Kombinasi dijelaskan sebagai penjumlahan; misalnya, Jeda+Cari+StreamVolume+Bisukan == 15. |
| volume | Volume | Volume aliran |
| datakustom | Objek | opsional Blob khusus aplikasi di data yang ditentukan oleh aplikasi penerima |
Perintah dari pengirim ke penerima
Perintah ini mengontrol pemutar media. Semua objek customData pada pesan di bawah harus bersifat opsional (misalnya, penerima harus melakukan downgrade dengan benar jika data tidak diteruskan). Tindakan ini akan memungkinkan aplikasi remote control generik berfungsi dengan benar.
Pemuatan
Memuat konten baru ke pemutar media.
| Name | Jenis | Deskripsi |
|---|---|---|
| ID permintaan | bilangan bulat | ID permintaan, untuk menghubungkan permintaan dan respons |
| jenis | string | LOAD (hanya nilai) |
| media | Informasi Media | Metadata yang akan dimuat (termasuk contentId) media |
| putar otomatis | boolean | opsional (default-nya adalah benar) Jika parameter putar otomatis ditentukan, pemutar media akan mulai memutar konten ketika dimuat. Meskipun putar otomatis tidak ditentukan, penerapan pemutar media dapat memilih untuk segera memulai pemutaran. Jika pemutaran dimulai, status pemutar dalam respons harus ditetapkan ke BUFFERING, jika tidak, status harus disetel ke PAused |
| waktusaat ini | dobel | opsional Detik sejak awal konten. Jika konten merupakan konten live, dan posisi tidak ditentukan, streaming akan dimulai di posisi live |
| datakustom | Objek | opsional Blob data khusus aplikasi yang ditentukan oleh aplikasi pengirim |
| Tanggapan | Pemicu | Siaran | Error |
|---|---|---|---|
| Tidak ada | Perubahan status penerima | Pesan Perubahan Status Media | Status Pemain Tidak Valid Pemuatan Gagal Pemuatan Dibatalkan |
Jeda
Menjeda pemutaran konten saat ini. Memicu notifikasi peristiwa STATUS ke semua aplikasi pengirim.
| Name | Jenis | Deskripsi |
|---|---|---|
| IDSesi | bilangan bulat | ID sesi media yang akan dijeda |
| ID permintaan | bilangan bulat | ID permintaan, yang akan digunakan untuk menghubungkan permintaan/respons |
| jenis | string | JEDA (hanya nilai) |
| datakustom | Objek | opsional Blob data khusus aplikasi yang ditentukan oleh aplikasi pengirim |
| Tanggapan | Pemicu | Siaran | Error |
|---|---|---|---|
| Tidak ada | Perubahan status penerima | Pesan Perubahan Status Media | Status Pemain Tidak Valid |
Cari
Menetapkan posisi saat ini dalam aliran. Memicu notifikasi peristiwa STATUS ke semua aplikasi pengirim. Jika posisi yang diberikan berada di luar rentang posisi yang valid untuk konten saat ini, pemutar harus memilih posisi yang valid sedekat mungkin dengan posisi yang diminta.
| Name | Jenis | Deskripsi |
|---|---|---|
| IDSesi | bilangan bulat | ID sesi media tempat posisi aliran data ditetapkan |
| ID permintaan | 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 akan berlaku:
|
| waktusaat ini | dobel | opsional Detik sejak awal konten. Jika konten merupakan konten live, dan posisi tidak ditentukan, streaming akan dimulai di posisi live |
| datakustom | Objek | opsional Blob data khusus aplikasi yang ditentukan oleh aplikasi pengirim |
| Tanggapan | Pemicu | Siaran | Error |
|---|---|---|---|
| Tidak ada | Perubahan status penerima | Pesan Perubahan Status Media | Status Pemain 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.
| Name | Jenis | Deskripsi |
|---|---|---|
| IDSesi | bilangan bulat | ID sesi media untuk konten yang akan dihentikan |
| ID permintaan | bilangan bulat | ID permintaan, untuk menghubungkan permintaan dan respons |
| jenis | string | STOP (hanya nilai) |
| datakustom | Objek | opsional Blob data khusus aplikasi yang ditentukan oleh aplikasi pengirim |
| Tanggapan | Pemicu | Siaran | Error |
|---|---|---|---|
| Tidak ada | Perubahan status penerima | Pesan Perubahan Status Media | Status Pemain Tidak Valid |
Putar
Memulai pemutaran konten yang dimuat dengan panggilan pemuatan, pemutaran dilanjutkan dari posisi waktu saat ini.
| Name | Jenis | Deskripsi |
|---|---|---|
| IDSesi | bilangan bulat | ID sesi media untuk konten yang akan diputar |
| ID permintaan | bilangan bulat | ID permintaan, untuk menghubungkan permintaan dan respons |
| jenis | string | PLAY (hanya nilai) |
| datakustom | Objek | opsional Blob data khusus aplikasi yang ditentukan oleh aplikasi pengirim |
| Tanggapan | Pemicu | Siaran | Error |
|---|---|---|---|
| Tidak ada | Perubahan status penerima | Pesan Perubahan Status Media | Status Pemain Tidak Valid |
Mendapatkan Status
Mengambil status media.
| Name | Jenis | Deskripsi |
|---|---|---|
| IDSesi | bilangan bulat | opsional ID sesi media dari media yang harus mengembalikan status media. Jika tidak ada yang disediakan, status untuk semua ID sesi media akan diberikan. |
| ID permintaan | bilangan bulat | ID permintaan, untuk menghubungkan permintaan dan respons |
| jenis | string | GET_STATUS (hanya nilai) |
| datakustom | Objek | opsional Blob data khusus aplikasi yang ditentukan oleh aplikasi pengirim |
| Tanggapan | Pemicu | Siaran | Error |
|---|---|---|---|
| Pesan MediaStatus kepada pengirim yang memintanya | Tidak ada | Tidak ada | Tidak ada |
SetelVolume
Menyetel volume aliran media. Digunakan untuk efek fade-in/fade-out pada streaming media. (Catatan: volume penerima diubah menggunakan pengirim Web set setVolume.) Volume aliran tidak boleh digunakan bersama dengan penggeser volume atau tombol volume untuk mengontrol volume perangkat. Perubahan volume streaming tidak akan memicu UI apa pun di penerima.
| Name | Jenis | Deskripsi |
|---|---|---|
| IDSesi | bilangan bulat | ID Sesi Media dari media yang volume streaming-nya diubah |
| ID permintaan | bilangan bulat | ID permintaan, untuk menghubungkan permintaan dan respons |
| jenis | string | VOLUME (hanya nilai) |
| volume | Volume | Volume aliran |
| datakustom | Objek | opsional Blob data khusus aplikasi yang ditentukan oleh aplikasi pengirim |
| Tanggapan | Pemicu | Siaran | Error |
|---|---|---|---|
| Tidak ada | Perubahan status penerima | Pesan Perubahan Status Media | Status Pemain Tidak Valid |
Pesan dari penerima ke pengirim
Penerima mengirim dua jenis pesan:
- Error: Pesan Unicast yang dikirim saat ada respons error terhadap permintaan pengirim.
- Status: Pesan siaran.
- Konsekuensi dari tindakan yang dimulai pengirim. Akan berisi requestId permintaan yang menyebabkan perubahan.
- Spontan: Misalnya, karena perubahan yang dipicu oleh aplikasi penerima. RequestId akan menjadi 0.
Error: Status Pemain Tidak Valid
Dikirim saat permintaan dari pengirim tidak dapat dipenuhi karena pemutar tidak dalam status yang valid. Misalnya, jika aplikasi belum membuat elemen media.
| Name | Jenis | Deskripsi |
|---|---|---|
| ID permintaan | bilangan bulat | ID permintaan yang menyebabkan error ini |
| jenis | string | INVALID_MAIN_STATE(hanya nilai) |
| datakustom | Objek | opsional Blob khusus aplikasi di data yang ditentukan oleh aplikasi penerima |
Error: Pemuatan Gagal
Dikirim saat permintaan pemuatan gagal. Status pemutar akan menjadi IDLE.
| Name | Jenis | Deskripsi |
|---|---|---|
| ID permintaan | bilangan bulat | ID permintaan yang menyebabkan error ini |
| jenis | string | LOAD_ GAGAL (hanya nilai) |
| datakustom | Objek | opsional Blob khusus aplikasi di data yang ditentukan oleh aplikasi penerima |
Kesalahan: Pemuatan Dibatalkan
Dikirim saat permintaan pemuatan dibatalkan (permintaan pemuatan kedua diterima).
| Name | Jenis | Deskripsi |
|---|---|---|
| ID permintaan | bilangan bulat | ID permintaan yang menyebabkan error ini |
| jenis | string | LOAD_CANCELLED (hanya nilai) |
| datakustom | Objek | opsional Blob khusus aplikasi di data yang ditentukan oleh aplikasi penerima |
Error: Permintaan Tidak Valid
Dikirim saat permintaan tidak valid (misalnya, jenis permintaan tidak diketahui).
| Name | Jenis | Deskripsi |
|---|---|---|
| ID permintaan | bilangan bulat | ID permintaan yang menyebabkan error ini |
| jenis | string | INVALID_REQUEST (hanya nilai) |
| alasan | Enum (string) | Nilai:
|
| datakustom | Objek | opsional Blob khusus aplikasi di data 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.
| Name | Jenis | Deskripsi |
|---|---|---|
| ID permintaan | bilangan bulat | ID yang digunakan untuk mengaitkan respons status ini dengan permintaan yang menghasilkannya atau 0 jika pesan status bersifat spontan (tidak dipicu oleh permintaan pengirim). Aplikasi pengirim akan menghasilkan ID permintaan unik dengan memilih angka acak dan terus meningkatkannya (tidak akan menggunakan 0). |
| jenis | string | MEDIA_STATUS (hanya nilai) |
| status | StatusMedia[] | Array objek Status Media. CATATAN: elemen media di MediaStatus hanya akan ditampilkan jika telah berubah. |
| datakustom | Objek | opsional Blob khusus aplikasi di data yang ditentukan oleh aplikasi penerima |