Respons media memungkinkan Action Anda memutar konten audio dengan durasi pemutaran lebih lama dari batas SSML 240 detik. Respons media berfungsi di perangkat khusus audio dan perangkat yang dapat menampilkan konten visual. Pada layar, respons media disertai dengan komponen visual dengan kontrol media dan (opsional) gambar diam.
Saat menentukan respons media, gunakan kandidat dengan
kemampuan platform RICH_RESPONSE
dan LONG_FORM_AUDIO
sehingga Asisten
Google hanya menampilkan respons lengkap di perangkat yang didukung. Anda hanya dapat menggunakan
satu respons kaya per objek content
dalam satu perintah.
Audio untuk pemutaran harus dalam file MP3 yang diformat dengan benar. File MP3 harus dihosting di server web dan tersedia untuk publik melalui URL HTTPS. Live streaming hanya didukung untuk format MP3.
![Contoh respons media di layar smart](https://developers.google.cn/static/assistant/conversational/images/smart-display/media.png?authuser=6&hl=id)
Perilaku
![Contoh respons media di smartphone](https://developers.google.cn/static/assistant/conversational/images/media.png?authuser=6&hl=id)
Komponen utama respons media adalah kartu trek tunggal. Kartu ini memungkinkan pengguna melakukan hal berikut:
- Putar ulang 10 detik terakhir
- Lewati maju 30 detik
- Melihat panjang total konten media
- Melihat indikator progres untuk pemutaran media
- Melihat waktu pemutaran yang berlalu
Respons media mendukung kontrol audio berikut untuk interaksi suara, yang semuanya ditangani oleh Asisten Google:
- "Ok Google, putar”.
- “Ok Google, jeda”.
- “Ok Google, berhenti”.
- “Ok Google, mulai dari awal.”
Pengguna juga dapat mengontrol volume dengan mengucapkan frasa seperti, "Ok Google, naikkan volume" atau "Ok Google, setel volume ke 50 persen". Intent dalam Action Anda akan diprioritaskan jika menangani frasa pelatihan yang serupa. Izinkan Asisten menangani permintaan pengguna ini kecuali jika Action Anda memiliki alasan khusus.
Perilaku pada ponsel Android
Di ponsel Android, kontrol media juga tersedia saat ponsel terkunci. Kontrol media juga muncul di area notifikasi, dan pengguna dapat melihat respons media jika salah satu kondisi berikut terpenuhi:
- Asisten Google ada di latar depan, dan layar ponsel aktif.
- Pengguna keluar dari Asisten Google saat audio diputar dan kembali ke Asisten Google dalam waktu 10 menit setelah pemutaran selesai. Saat kembali ke Asisten Google, pengguna akan melihat kartu media dan chip saran.
Properti
Respons media memiliki properti berikut:
Properti | Jenis | Persyaratan | Deskripsi |
---|---|---|---|
media_type |
MediaType |
Wajib | Jenis media respons yang diberikan. Tampilkan MEDIA_STATUS_ACK saat mengonfirmasi status media. |
start_offset |
string | Opsional | Cari posisi untuk memulai trek media pertama. Berikan nilai dalam detik, dengan detik pecahan yang dinyatakan dengan tidak lebih dari sembilan angka desimal, dan diakhiri dengan akhiran "s". Misalnya, 3 detik dan 1 nanodetik dinyatakan sebagai "3,000000001 detik". |
optional_media_controls |
array OptionalMediaControls |
Opsional | Ikut sertakan properti untuk menerima callback saat pengguna mengubah status pemutaran media (seperti dengan menjeda atau menghentikan pemutaran media). |
media_objects |
array MediaObject |
Wajib | Menampilkan objek media untuk disertakan dalam perintah. Saat
mengonfirmasi status media dengan MEDIA_STATUS_ACK , jangan
sediakan objek media. |
first_media_object_index |
bilangan bulat | Opsional | indeks berbasis 0 dari MediaObject pertama di
media_objects untuk diputar. Jika tidak ditentukan, nol, atau di luar batas,
pemutaran akan dimulai dari MediaObject pertama.
|
repeat_mode |
RepeatMode |
Opsional | Mode berulang untuk daftar objek media. |
Kode contoh
YAML
candidates: - first_simple: variants: - speech: This is a media response. content: media: start_offset: 2.12345s optional_media_controls: - PAUSED - STOPPED media_objects: - name: Media name description: Media description url: 'https://storage.googleapis.com/automotive-media/Jazz_In_Paris.mp3' image: large: url: 'https://storage.googleapis.com/automotive-media/album_art.jpg' alt: Jazz in Paris album art media_type: AUDIO
JSON
{ "candidates": [ { "first_simple": { "variants": [ { "speech": "This is a media response." } ] }, "content": { "media": { "start_offset": "2.12345s", "optional_media_controls": [ "PAUSED", "STOPPED" ], "media_objects": [ { "name": "Media name", "description": "Media description", "url": "https://storage.googleapis.com/automotive-media/Jazz_In_Paris.mp3", "image": { "large": { "url": "https://storage.googleapis.com/automotive-media/album_art.jpg", "alt": "Jazz in Paris album art" } } } ], "media_type": "AUDIO" } } } ] }
Node.js
// Media response app.handle('media', (conv) => { conv.add('This is a media response'); conv.add(new Media({ mediaObjects: [ { name: 'Media name', description: 'Media description', url: 'https://storage.googleapis.com/automotive-media/Jazz_In_Paris.mp3', image: { large: JAZZ_IN_PARIS_IMAGE, } } ], mediaType: 'AUDIO', optionalMediaControls: ['PAUSED', 'STOPPED'], startOffset: '2.12345s' })); });
JSON
{ "session": { "id": "session_id", "params": {}, "languageCode": "" }, "prompt": { "override": false, "content": { "media": { "mediaObjects": [ { "name": "Media name", "description": "Media description", "url": "https://storage.googleapis.com/automotive-media/Jazz_In_Paris.mp3", "image": { "large": { "alt": "Jazz in Paris album art", "height": 0, "url": "https://storage.googleapis.com/automotive-media/album_art.jpg", "width": 0 } } } ], "mediaType": "AUDIO", "optionalMediaControls": [ "PAUSED", "STOPPED" ] } }, "firstSimple": { "speech": "This is a media response", "text": "This is a media response" } } }
Menerima status media
Selama atau setelah pemutaran media untuk pengguna, Asisten Google dapat membuat peristiwa status media untuk menginformasikan progres pemutaran Action Anda. Tangani peristiwa status ini di kode webhook Anda untuk mengarahkan pengguna dengan tepat saat mereka menjeda, menghentikan, atau menyelesaikan pemutaran media.
Asisten Google menampilkan peristiwa status dari daftar berikut berdasarkan progres pemutaran media dan kueri pengguna:
FINISHED
: Pengguna menyelesaikan pemutaran media (atau melewati ke bagian media berikutnya) dan transisi tidak menuju keluar dari percakapan. Status ini juga dipetakan ke intent sistemMEDIA_STATUS_FINISHED
.PAUSED
: Pengguna menjeda pemutaran media. Pilih untuk menerima peristiwa status ini dengan propertioptional_media_controls
. Status ini juga dipetakan ke intent sistemMEDIA_STATUS_PAUSED
.STOPPED
: Pengguna berhenti atau keluar dari pemutaran media. Pilih untuk menerima peristiwa status ini dengan propertioptional_media_controls
. Status ini juga memetakan ke intent sistemMEDIA_STATUS_STOPPED
.FAILED
: Pemutaran media gagal. Status ini juga dipetakan ke intent sistemMEDIA_STATUS_FAILED
.
Selama pemutaran media, pengguna mungkin memberikan kueri yang dapat ditafsirkan sebagai
peristiwa jeda dan perhentian media (seperti "stop", "cancel", atau "exit"). Dalam situasi
tersebut, Asisten memberikan intent sistem actions.intent.CANCEL
ke
Action Anda, membuat peristiwa status media dengan nilai status "STOPPED", dan
keluar dari Action Anda sepenuhnya.
Saat Asisten menghasilkan peristiwa status media dengan nilai status
PAUSED
atau STOPPED
, respons dengan respons media yang hanya berisi
konfirmasi (jenis MEDIA_STATUS_ACK
).
Progres media
Progres pemutaran media saat ini tersedia di kolom
context.media.progress
untuk permintaan webhook. Anda
dapat menggunakan progres media sebagai offset waktu mulai untuk melanjutkan pemutaran pada
titik tempat pemutaran media berakhir. Untuk menerapkan offset waktu mulai ke respons
media, gunakan properti start_offset
.
Kode contoh
Node.js
// Media status app.handle('media_status', (conv) => { const mediaStatus = conv.intent.params.MEDIA_STATUS.resolved; switch(mediaStatus) { case 'FINISHED': conv.add('Media has finished playing.'); break; case 'FAILED': conv.add('Media has failed.'); break; case 'PAUSED' || 'STOPPED': if (conv.request.context) { // Persist the media progress value const progress = conv.request.context.media.progress; } // Acknowledge pause/stop conv.add(new Media({ mediaType: 'MEDIA_STATUS_ACK' })); break; default: conv.add('Unknown media status received.'); } });
Menampilkan playlist
Anda dapat menambahkan lebih dari satu file audio dalam respons untuk membuat playlist. Saat trek pertama selesai diputar, trek berikutnya akan otomatis diputar, dan ini berlanjut hingga setiap trek diputar. Pengguna juga dapat menekan tombol Berikutnya di layar, atau mengucapkan "Berikutnya" atau yang serupa untuk melewati ke jalur berikutnya.
Tombol Berikutnya dinonaktifkan pada trek terakhir playlist. Namun, jika Anda mengaktifkan mode loop, playlist akan dimulai lagi dari lagu pertama. Untuk mempelajari mode loop lebih lanjut, lihat Mengimplementasikan mode loop.
Untuk membuat playlist, sertakan lebih dari satu MediaObject
dalam array media_objects
. Cuplikan kode berikut menampilkan perintah yang menampilkan playlist
yang berisi tiga lagu:
{ "candidates": [ { "content": { "media": { "media_objects": [ { "name": "1. Jazz in Paris", "description": "Song 1 of 3", "url": "https://storage.googleapis.com/automotive-media/Jazz_In_Paris.mp3", "image": { "large": { "url": "https://storage.googleapis.com/automotive-media/album_art.jpg", "alt": "Album cover of an ocean view", "height": 1600, "width": 1056 } } }, { "name": "2. Jazz in Paris", "description": "Song 2 of 3", "url": "https://storage.googleapis.com/automotive-media/Jazz_In_Paris.mp3", "image": { "large": { "url": "https://storage.googleapis.com/automotive-media/album_art.jpg", "alt": "Album cover of an ocean view", "height": 1600, "width": 1056 } } }, { "name": "3. Jazz in Paris", "description": "Song 3 of 3", "url": "https://storage.googleapis.com/automotive-media/Jazz_In_Paris.mp3", "image": { "large": { "url": "https://storage.googleapis.com/automotive-media/album_art.jpg", "alt": "Album cover of an ocean view", "height": 1600, "width": 1056 } } } ], } } } ] }
Mengimplementasikan mode looping
Mode loop memungkinkan Anda memberikan respons audio yang berulang secara otomatis. Anda dapat menggunakan mode ini untuk mengulangi satu lagu atau melakukan loop pada sebuah {i>playlist<i}. Jika pengguna mengucapkan "Next" atau sesuatu yang serupa untuk satu trek berulang, lagu tersebut akan dimulai lagi. Untuk playlist ulang, pengguna yang mengucapkan "Next" akan memulai lagu berikutnya dalam playlist tersebut.
Untuk menerapkan mode loop, tambahkan kolom repeat_mode
ke perintah Anda dan setel nilainya ke ALL
. Penambahan ini memungkinkan respons
media Anda melakukan loop ke awal objek media pertama saat akhir
objek media terakhir tercapai.
Cuplikan kode berikut menunjukkan perintah yang mengembalikan jalur berulang:
{ "candidates": [ { "content": { "media": { "media_objects": [ { "name": "Jazz in Paris", "description": "Single song (repeated)", "url": "https://storage.googleapis.com/automotive-media/Jazz_In_Paris.mp3", "image": { "large": { "url": "https://storage.googleapis.com/automotive-media/album_art.jpg", "alt": "Album cover of an ocean view", "height": 1600, "width": 1056 } } } ], "repeat_mode": "ALL" } } } ] }