Les réponses multimédias permettent à vos actions de lire du contenu audio dont la durée de lecture dépasse la limite de 240 secondes définie dans SSML. Les réponses multimédias fonctionnent à la fois sur les appareils audio uniquement et sur les appareils pouvant afficher du contenu visuel. Sur un écran, les réponses multimédias sont accompagnées d'un composant visuel avec des commandes multimédias et (éventuellement) une image fixe.
Lorsque vous définissez une réponse multimédia, utilisez un candidat avec les fonctionnalités de surface RICH_RESPONSE
et LONG_FORM_AUDIO
afin que l'Assistant Google ne renvoie la réponse enrichie que sur les appareils compatibles. Vous ne pouvez utiliser qu'une seule réponse enrichie par objet content
dans une requête.
Le fichier audio à lire doit être dans un fichier MP3 correctement formaté. Les fichiers MP3 doivent être hébergés sur un serveur Web et être accessibles au public via une URL HTTPS. La diffusion en direct n'est compatible qu'avec le format MP3.
Comportement
Le composant principal d'une réponse média est la fiche à piste unique. Cette fiche permet à l'utilisateur d'effectuer les opérations suivantes:
- Relire les 10 dernières secondes
- Avancer de 30 secondes
- Afficher la durée totale du contenu multimédia
- Afficher un indicateur de progression de la lecture des contenus multimédias
- Afficher le temps de lecture écoulé
Les réponses multimédias acceptent les commandes audio suivantes pour les interactions vocales, qui sont toutes gérées par l'Assistant Google:
- "Ok Google, mets."
- "Ok Google, mets en pause."
- "Ok Google, arrête."
- "Ok Google, recommence du début."
Les utilisateurs peuvent également contrôler le volume en disant, par exemple, "Hey Google, augmente le volume" ou "Hey Google, règle le volume sur 50 %". Les intents de votre action sont prioritaires s'ils traitent des phrases d'entraînement similaires. Autorisez l'Assistant à gérer ces demandes des utilisateurs, sauf si votre action a une raison spécifique de le faire.
Comportement sur les téléphones Android
Sur les téléphones Android, les commandes multimédias sont également disponibles lorsque le téléphone est verrouillé. Les commandes multimédias apparaissent également dans la zone de notification, et les utilisateurs peuvent voir les réponses multimédias lorsque l'une des conditions suivantes est remplie:
- L'Assistant Google est au premier plan, et l'écran du téléphone est allumé.
- L'utilisateur quitte l'Assistant Google pendant la lecture du contenu audio et y retourne dans les 10 minutes suivant la fin de la lecture. En retournant dans l'Assistant Google, l'utilisateur voit la carte multimédia et les chips de suggestion.
Propriétés
Les réponses multimédias comportent les propriétés suivantes:
Propriété | Type | Obligatoire ? | Description |
---|---|---|---|
media_type |
MediaType |
Obligatoire | Type de contenu de la réponse fournie. Renvoyez MEDIA_STATUS_ACK lorsque vous confirmez l'état d'un contenu multimédia. |
start_offset |
chaîne | Facultatif | Recherchez la position pour démarrer la première piste multimédia. Indiquez la valeur en secondes, les secondes fractionnaires ne dépassant pas neuf décimales, et se terminant par le suffixe "s". Par exemple, 3 secondes et 1 nanoseconde s'affichent sous la forme "3.000000001s". |
optional_media_controls |
tableau de OptionalMediaControls |
Facultatif | Propriété permettant de recevoir des rappels lorsqu'un utilisateur modifie l'état de la lecture d'un contenu multimédia (par exemple, en mettant en pause ou en arrêtant la lecture). |
media_objects |
tableau de MediaObject |
Obligatoire | Représente les objets multimédias à inclure dans l'invite. Lorsque vous confirmez l'état d'un contenu multimédia avec MEDIA_STATUS_ACK , ne fournissez pas d'objets multimédias. |
first_media_object_index |
integer | Facultatif | Index de base 0 des premiers MediaObject de media_objects à lire. Si aucune valeur n'est spécifiée, si elle est nulle ou hors limites, la lecture commence au premier MediaObject .
|
repeat_mode |
RepeatMode |
Facultatif | Mode de répétition pour la liste des objets multimédias. |
Exemple de code
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" } } }
Recevoir l'état du contenu multimédia
Pendant ou après la lecture de contenus multimédias pour un utilisateur, l'Assistant Google peut générer des événements d'état multimédia pour informer votre action de la progression de la lecture. Gérez ces événements d'état dans votre code de webhook pour acheminer de manière appropriée les utilisateurs lorsqu'ils mettent en pause, arrêtent ou terminent la lecture de contenus multimédias.
L'Assistant Google renvoie un événement d'état à partir de la liste suivante en fonction de la progression de la lecture des contenus multimédias et des requêtes des utilisateurs:
FINISHED
:l'utilisateur a terminé la lecture d'un contenu multimédia (ou passe au contenu multimédia suivant), et la transition ne mène pas à une sortie de conversation. Cet état est également mappé à l'intent systèmeMEDIA_STATUS_FINISHED
.PAUSED
:l'utilisateur a mis en pause la lecture des contenus multimédias. Activez la réception de cet événement d'état avec la propriétéoptional_media_controls
. Cet état est également mappé à l'intent systèmeMEDIA_STATUS_PAUSED
.STOPPED
:l'utilisateur a arrêté ou interrompu la lecture du contenu multimédia. Activez la réception de cet événement d'état avec la propriétéoptional_media_controls
. Cet état est également mappé à l'intent systèmeMEDIA_STATUS_STOPPED
.FAILED
:échec de la lecture du contenu multimédia. Cet état est également mappé à l'intent systèmeMEDIA_STATUS_FAILED
.
Lors de la lecture d'un contenu multimédia, un utilisateur peut fournir une requête pouvant être interprétée à la fois comme un événement de mise en pause et d'arrêt multimédia (comme "arrêter", "annuler" ou "quitter"). Dans ce cas, l'Assistant fournit l'intent système actions.intent.CANCEL
à votre action, génère un événement d'état multimédia avec la valeur d'état "STOPPED" et quitte complètement votre action.
Lorsque l'Assistant génère un événement d'état multimédia avec la valeur d'état PAUSED
ou STOPPED
, répondez par une réponse multimédia qui ne contient qu'un accusé de réception (de type MEDIA_STATUS_ACK
).
Progression du contenu multimédia
La progression actuelle de la lecture des contenus multimédias est disponible dans le champ context.media.progress
pour les requêtes de webhook. Vous pouvez utiliser la progression multimédia comme décalage de début pour reprendre la lecture là où elle s'est terminée. Pour appliquer le décalage horaire de début à une réponse média, utilisez la propriété start_offset
.
Exemple de code
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.'); } });
Renvoyer une playlist
Vous pouvez ajouter plusieurs fichiers audio à votre réponse pour créer une playlist. Lorsque la lecture de la première piste est terminée, la piste suivante est lue automatiquement, et le processus se poursuit jusqu'à ce que chaque piste soit lue. Les utilisateurs peuvent également appuyer sur le bouton Suivant à l'écran ou dire Suivant ou une phrase similaire pour passer au titre suivant.
Le bouton Suivant est désactivé sur le dernier titre de la playlist. Toutefois, si vous activez le mode boucle, la playlist reprend à partir du premier titre. Pour en savoir plus sur le mode boucle, consultez la section Implémenter le mode boucle.
Pour créer une playlist, incluez plusieurs MediaObject
dans le tableau media_objects
. L'extrait de code suivant montre une invite qui renvoie une playlist de trois pistes:
{ "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 } } } ], } } } ] }
Implémenter le mode de lecture en boucle
Le mode boucle vous permet de fournir une réponse audio qui se répète automatiquement. Vous pouvez utiliser ce mode pour répéter un seul titre ou pour lire une playlist en boucle. Si l'utilisateur dit Suivant ou une phrase similaire pour une seule piste en boucle, la chanson reprend. Pour les playlists en boucle, un utilisateur qui dit "Next" (Suivant) lance le titre suivant de la playlist.
Pour implémenter le mode de lecture en boucle, ajoutez le champ repeat_mode
à votre requête et définissez sa valeur sur ALL
. Cela permet à votre réponse multimédia d'être lue en boucle jusqu'au début du premier objet multimédia lorsque la fin du dernier objet multimédia est atteinte.
L'extrait de code suivant montre une invite qui renvoie une piste en boucle:
{ "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" } } } ] }