Respons media

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.

Gambar 1. Contoh respons media di layar smart

Perilaku

Gambar 2. Contoh respons media di smartphone

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.

Catatan: Webhook Anda tidak akan menerima callback dari Asisten Google jika pengguna meninggalkan layar Asisten Google selama pemutaran media dan pemutaran media selesai saat pengguna pergi. Sertakan chip saran untuk memungkinkan pengguna terus berinteraksi dengan Action Anda saat mereka kembali ke layar Asisten Google.

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". Catatan: Saat ini tidak tersedia di iOS.
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. Catatan: Saat ini tidak tersedia di iOS.
repeat_mode	RepeatMode	Opsional	Mode berulang untuk daftar objek media. Catatan: Saat ini tidak tersedia di iOS.

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 sistem MEDIA_STATUS_FINISHED.
• PAUSED: Pengguna menjeda pemutaran media. Pilih untuk menerima peristiwa status ini dengan properti optional_media_controls. Status ini juga dipetakan ke intent sistem MEDIA_STATUS_PAUSED.
• STOPPED: Pengguna berhenti atau keluar dari pemutaran media. Pilih untuk menerima peristiwa status ini dengan properti optional_media_controls. Status ini juga memetakan ke intent sistem MEDIA_STATUS_STOPPED.
• FAILED: Pemutaran media gagal. Status ini juga dipetakan ke intent sistem MEDIA_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).

Catatan: Developer tidak boleh merespons peristiwa jeda media dan penghentian dengan respons media, kecuali untuk mengonfirmasi penerimaan.

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.

Tips: Pengambilan progres media tidak terbatas pada peristiwa status media. Misalnya, Anda dapat mengakses progres media dari context.media.progress untuk intent yang tidak cocok yang terjadi selama pemutaran media.

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.

Catatan: Mode pengulangan saat ini tidak tersedia di iOS.

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"
        }
      }
    }
  ]
}