Réponses multimédias

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.

Exemple de réponse multimédia sur un écran connecté
Figure 1 : Exemple de réponse multimédia sur un écran connecté

Comportement

Exemple de réponse multimédia sur un smartphone
Figure 2. Exemple de réponse multimédia sur un smartphone

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ème MEDIA_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ème MEDIA_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ème MEDIA_STATUS_STOPPED.
  • FAILED:échec de la lecture du contenu multimédia. Cet état est également mappé à l'intent système MEDIA_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"
        }
      }
    }
  ]
}