As respostas de mídia permitem que suas ações toquem conteúdo de áudio com uma duração de reprodução maior que o limite de 240 segundos de SSML. As respostas de mídia funcionam em dispositivos somente de áudio e que podem mostrar conteúdo visual. Em uma tela, as respostas de mídia são acompanhadas por um componente visual com controles de mídia e (opcionalmente) uma imagem estática.
Ao definir uma resposta de mídia, use um candidato com os
recursos de plataforma RICH_RESPONSE
e LONG_FORM_AUDIO
para que o Google
Assistente retorne a resposta avançada somente em dispositivos com suporte. Só é possível usar
uma resposta avançada por objeto content
em uma solicitação.
O áudio para reprodução deve estar em um arquivo MP3 formatado corretamente. Os arquivos MP3 precisam ser hospedados em um servidor da Web e estar disponíveis publicamente por meio de um URL HTTPS. A transmissão ao vivo só é compatível com o formato MP3.
Comportamento
O componente principal de uma resposta de mídia é o card de faixa única. Ele permite que o usuário faça o seguinte:
- Tocar novamente os últimos 10 segundos
- Avançar 30 segundos
- Conferir a duração total do conteúdo de mídia
- Ver um indicador de progresso para a reprodução de mídia
- Conferir o tempo de reprodução decorrido
As respostas de mídia oferecem suporte aos seguintes controles de áudio para interações por voz, todos processados pelo Google Assistente:
- "Ok Google, abrir."
- "Ok Google, pausar."
- "Ok Google, parar."
- "Ok Google, começar de novo."
Os usuários também podem controlar o volume dizendo frases como "Ok Google, aumente o volume" ou "Ok Google, ajuste o volume para 50%". As intents na sua ação terão precedência se processarem frases de treinamento semelhantes. Permita que o Google Assistente lide com essas solicitações do usuário, a menos que sua ação tenha um motivo específico para isso.
Comportamento em smartphones Android
Em smartphones Android, os controles de mídia também ficam disponíveis enquanto o smartphone está bloqueado. Os controles de mídia também aparecem na área de notificação, e os usuários podem conferir as respostas da mídia quando alguma das seguintes condições é atendida:
- O Google Assistente está em primeiro plano, e a tela do smartphone está ativada.
- O usuário sai do Google Assistente enquanto o áudio está tocando e retorna ao Google Assistente em até 10 minutos após a conclusão da reprodução. Ao retornar ao Google Assistente, o usuário vê o card de mídia e os ícones de sugestão.
Propriedades
As respostas de mídia têm as seguintes propriedades:
Propriedade | Tipo | Requisito | Descrição |
---|---|---|---|
media_type |
MediaType |
Obrigatório | Tipo de mídia da resposta fornecida. Retorne MEDIA_STATUS_ACK
ao confirmar um status de mídia. |
start_offset |
string | Opcional | Procure a posição para iniciar a primeira faixa de mídia. Forneça o valor em segundos, com segundos fracionários expressos em no máximo nove casas decimais, e termine com o sufixo "s". Por exemplo, 3 segundos e 1 nanossegundo são expressos como "3,000000001s". |
optional_media_controls |
matriz de OptionalMediaControls |
Opcional | Propriedade de ativação para receber callbacks quando um usuário mudar o status de reprodução de mídia, por exemplo, pausando ou interrompendo a reprodução. |
media_objects |
matriz de MediaObject |
Obrigatório | Representa os objetos de mídia a serem incluídos no comando. Ao
confirmar um status de mídia com MEDIA_STATUS_ACK , não
forneça objetos de mídia. |
first_media_object_index |
número inteiro | Opcional | Índice baseado em 0 do primeiro MediaObject em media_objects a ser reproduzido. Se não for especificado, zero ou fora dos limites,
a reprodução vai começar na primeira MediaObject .
|
repeat_mode |
RepeatMode |
Opcional | Modo de repetição para a lista de objetos de mídia. |
Exemplo de código
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" } } }
Recebendo status de mídia
Durante ou após a reprodução de mídia para um usuário, o Google Assistente pode gerar eventos de status de mídia para informar sua ação sobre o progresso da reprodução. Processe esses eventos de status no código do webhook para rotear os usuários adequadamente quando eles pausarem, interromperem ou finalizarem a reprodução de mídia.
O Google Assistente retorna um evento de status da lista a seguir com base no progresso da reprodução de mídia e nas consultas do usuário:
FINISHED
:o usuário concluiu a reprodução de mídia (ou pula para a próxima parte) e a transição não é para uma saída de conversa. Esse status também é mapeado para a intent do sistemaMEDIA_STATUS_FINISHED
.PAUSED
:o usuário pausou a reprodução de mídia. Ative o recebimento desse evento de status com a propriedadeoptional_media_controls
. Esse status também é mapeado para a intent do sistemaMEDIA_STATUS_PAUSED
.STOPPED
:o usuário interrompeu ou saiu da reprodução de mídia. Ative o recebimento desse evento de status com a propriedadeoptional_media_controls
. Esse status também é associado à intent do sistemaMEDIA_STATUS_STOPPED
.FAILED
:falha ao abrir a mídia. Esse status também é mapeado para a intent do sistemaMEDIA_STATUS_FAILED
.
Durante a reprodução de mídia, um usuário pode fornecer uma consulta que pode ser interpretada como
um evento de pausa e interrupção de mídia (como "parar", "cancelar" ou "sair"). Nessa
situação, o Google Assistente fornece a intent do sistema actions.intent.CANCEL
para sua
Ação, gera um evento de status de mídia com o valor de status "STOPPED" e
saia completamente da ação.
Quando o Google Assistente gerar um evento de status de mídia com o valor de status PAUSED
ou STOPPED
, responda com uma resposta de mídia que contenha apenas uma
confirmação (do tipo MEDIA_STATUS_ACK
).
Progresso da mídia
O progresso atual da reprodução de mídia está disponível no campo
context.media.progress
para solicitações de webhook. É
possível usar o progresso da mídia como um ajuste de horário de início para retomar a reprodução no
ponto em que ela terminou. Para aplicar o ajuste de horário de início a uma resposta
de mídia, use a propriedade start_offset
.
Exemplo de código
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.'); } });
Retornar uma playlist
Você pode adicionar mais de um arquivo de áudio na sua resposta para criar uma playlist. Quando a primeira faixa termina de ser reproduzida, a próxima faixa é reproduzida automaticamente, e isso continua até que cada faixa seja reproduzida. Os usuários também podem pressionar o botão Next na tela ou dizer "Next" (avançar) ou algo semelhante para pular para a próxima faixa.
O botão Próxima fica desativado na última faixa da playlist. No entanto, se você ativar o modo de looping, a playlist começará novamente a partir da primeira faixa. Para saber mais sobre o modo de looping, consulte Implementar o modo de looping.
Para criar uma playlist, inclua mais de um MediaObject
na matriz
media_objects
. O snippet de código a seguir mostra uma solicitação que retorna uma playlist de
três faixas:
{ "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 } } } ], } } } ] }
Implementar o modo de repetição
O modo de loop permite fornecer uma resposta de áudio que se repete automaticamente. Você pode usar esse modo para repetir uma única faixa ou repetir uma playlist. Se o usuário disser "Next" ou algo semelhante para uma única faixa em loop, a música vai começar novamente. Para playlists em loop, um usuário que diz "Next" inicia a próxima faixa da playlist.
Para implementar o modo de looping, adicione o campo repeat_mode
ao comando e defina o valor dele como ALL
. Essa adição permite que a resposta
de mídia faça um loop para o início do primeiro objeto de mídia quando o fim do
último objeto de mídia for alcançado.
O snippet de código a seguir mostra um comando que retorna uma faixa em repetição:
{ "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" } } } ] }