Mithilfe von Medienantworten können mit Ihrer Aktion Audioinhalte mit einer Wiedergabedauer von mehr als die 240-Sekunden-Grenze von SSML wiedergegeben werden. Medienantworten funktionieren sowohl auf Audiogeräten als auch auf Geräten, die visuelle Inhalte anzeigen können. Auf einem Display werden Medienantworten von einer visuellen Komponente mit Mediensteuerelementen und (optional) einem Standbild begleitet.
Verwenden Sie beim Definieren einer Medienantwort einen Kandidaten mit den Oberflächenfunktionen RICH_RESPONSE
und LONG_FORM_AUDIO
, damit Google Assistant die Rich-Antwort nur auf unterstützten Geräten zurückgibt. Sie können in einer Aufforderung nur eine Rich-Media-Antwort pro content
-Objekt verwenden.
Das Audio für die Wiedergabe muss in einer korrekt formatierten MP3-Datei vorliegen. MP3-Dateien müssen auf einem Webserver gehostet und über eine HTTPS-URL öffentlich verfügbar sein. Livestreaming wird nur für das MP3-Format unterstützt.
![Beispiel für eine Medienantwort auf einem Smart Display](https://developers.google.cn/static/assistant/conversational/images/smart-display/media.png?authuser=5&hl=de)
Behavior
![Beispiel für eine Medienantwort auf einem Smartphone](https://developers.google.cn/static/assistant/conversational/images/media.png?authuser=5&hl=de)
Die Hauptkomponente einer Medienantwort ist die Karte mit einem Track. Die Karte ermöglicht dem Nutzer Folgendes:
- Die letzten 10 Sekunden noch einmal abspielen
- 30 Sekunden vorspulen
- Gesamtlänge der Medieninhalte ansehen
- Fortschrittsanzeige für die Medienwiedergabe einblenden
- Verstrichene Wiedergabezeit ansehen
Medienantworten unterstützen die folgenden Audiosteuerelemente für Sprachinteraktionen, die alle von Google Assistant gesteuert werden:
- „Hey Google, spiel ab.“
- „Hey Google, Pause.“
- „Hey Google, stopp.“
- „Hey Google, fang von vorne an.“
Nutzer können die Lautstärke auch mit Befehlen wie „Hey Google, mach lauter.“ oder „Hey Google, stell die Lautstärke auf 50 %“ regeln. Intents in Ihrer Aktion haben Vorrang, wenn sie ähnliche Trainingsformulierungen verarbeiten. Lass Assistant diese Nutzeranfragen verarbeiten, es sei denn, deine Aktion hat einen bestimmten Grund dafür.
Verhalten auf Android-Smartphones
Auf Android-Smartphones ist die Mediensteuerung auch bei gesperrtem Smartphone verfügbar. Die Mediensteuerelemente werden auch im Benachrichtigungsbereich angezeigt und Nutzer können Medienantworten sehen, wenn eine der folgenden Bedingungen erfüllt ist:
- Google Assistant ist im Vordergrund und das Display des Smartphones ist eingeschaltet.
- Der Nutzer verlässt Google Assistant während der Audiowiedergabe und kehrt innerhalb von 10 Minuten nach Abschluss der Wiedergabe zu Google Assistant zurück. Bei der Rückkehr zu Google Assistant werden dem Nutzer die Medienkarte und die Vorschlags-Chips angezeigt.
Attribute
Medienantworten haben die folgenden Eigenschaften:
Property | Typ | Anforderung | Beschreibung |
---|---|---|---|
media_type |
MediaType |
Erforderlich | Medientyp der bereitgestellten Antwort. Gibt MEDIA_STATUS_ACK zurück, wenn ein Medienstatus bestätigt wird. |
start_offset |
String | Optional | Suche nach Position, um den ersten Mediatrack zu starten. Geben Sie den Wert in Sekunden an, wobei Sekundenbruchteile mit maximal neun Dezimalstellen angegeben werden und mit dem Suffix „s“ enden. Beispielsweise werden 3 Sekunden und 1 Nanosekunde als "3.000000001s" ausgedrückt. |
optional_media_controls |
Array mit OptionalMediaControls |
Optional | Aktivierungseigenschaft für den Empfang von Callbacks, wenn ein Nutzer den Status der Medienwiedergabe ändert (z. B. durch Pausieren oder Anhalten der Medienwiedergabe). |
media_objects |
Array mit MediaObject |
Erforderlich | Stellt die Medienobjekte dar, die in den Prompt aufgenommen werden sollen. Geben Sie beim Bestätigen eines Medienstatus mit MEDIA_STATUS_ACK keine Medienobjekte an. |
first_media_object_index |
Ganzzahl | Optional | Der 0-basierte Index der ersten MediaObject in media_objects , die wiedergegeben werden soll. Wenn nicht angegeben, null oder außerhalb der Grenzen, beginnt die Wiedergabe beim ersten MediaObject .
|
repeat_mode |
RepeatMode |
Optional | Wiederholungsmodus für die Liste der Medienobjekte. |
Beispielcode
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" } } }
Medienstatus werden empfangen
Während oder nach der Medienwiedergabe für einen Nutzer kann Google Assistant Medienstatusereignisse generieren, um Ihre Aktion über den Wiedergabefortschritt zu informieren. Verarbeiten Sie diese Statusereignisse im Webhook-Code, um Nutzer entsprechend weiterzuleiten, wenn sie die Medienwiedergabe anhalten, beenden oder beenden.
Google Assistant gibt basierend auf dem Wiedergabefortschritt von Medien und Nutzeranfragen ein Statusereignis aus der folgenden Liste zurück:
FINISHED
: Der Nutzer hat die Medienwiedergabe abgeschlossen (oder springt zum nächsten Element) und der Übergang ist kein Beenden der Unterhaltung. Dieser Status ist auch dem System-IntentMEDIA_STATUS_FINISHED
zugeordnet.PAUSED
:Der Nutzer hat die Medienwiedergabe pausiert. Aktiviere den Empfang dieses Statusereignisses mit der Propertyoptional_media_controls
. Dieser Status ist auch dem System-IntentMEDIA_STATUS_PAUSED
zugeordnet.STOPPED
:Der Nutzer hat die Medienwiedergabe beendet oder beendet. Aktiviere den Empfang dieses Statusereignisses mit der Propertyoptional_media_controls
. Dieser Status ist auch dem System-IntentMEDIA_STATUS_STOPPED
zugeordnet.FAILED
:Fehler bei der Medienwiedergabe. Dieser Status ist auch dem System-IntentMEDIA_STATUS_FAILED
zugeordnet.
Während der Medienwiedergabe kann ein Nutzer eine Abfrage bereitstellen, die als Medienpausen- und Stoppereignis interpretiert werden kann (z. B. „Stopp“, „Abbrechen“ oder „Beenden“). In diesem Fall übergibt Assistant den System-Intent actions.intent.CANCEL
an Ihre Aktion, generiert ein Medienstatusereignis mit dem Statuswert „STOPPED“ und beendet die Aktion vollständig.
Wenn Assistant ein Medienstatusereignis mit dem Statuswert PAUSED
oder STOPPED
generiert, antworten Sie mit einer Medienantwort, die nur eine Bestätigung vom Typ MEDIA_STATUS_ACK
enthält.
Medienfortschritt
Der aktuelle Fortschritt der Medienwiedergabe ist im Feld context.media.progress
für Webhook-Anfragen verfügbar. Sie können den Medienfortschritt als Startzeitversatz verwenden, um die Wiedergabe an dem Punkt fortzusetzen, an dem die Medienwiedergabe beendet wurde. Mit dem Attribut start_offset
können Sie die Startzeitverschiebung auf eine Medienantwort anwenden.
Beispielcode
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.'); } });
Playlist zurückgeben
Du kannst deiner Antwort mehrere Audiodateien hinzufügen, um eine Playlist zu erstellen. Wenn der erste Titel beendet ist, wird der nächste automatisch abgespielt. Dies wird so lange fortgesetzt, bis jeder Titel abgespielt wurde. Nutzer können auch die Schaltfläche Weiter auf dem Bildschirm drücken oder Weiter oder etwas Ähnliches sagen, um zum nächsten Titel zu springen.
Die Schaltfläche Weiter ist für den letzten Titel der Playlist deaktiviert. Wenn Sie jedoch den Schleifenmodus aktivieren, beginnt die Playlist wieder beim ersten Titel. Weitere Informationen zum Schleifenmodus finden Sie unter Schleifenmodus implementieren.
Um eine Playlist zu erstellen, musst du mehr als ein MediaObject
-Element in das media_objects
-Array einfügen. Das folgende Code-Snippet zeigt eine Eingabeaufforderung, die eine Playlist mit drei Titeln zurückgibt:
{ "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 } } } ], } } } ] }
Schleifenmodus implementieren
Im Schleifenmodus können Sie eine Audioantwort bereitstellen, die sich automatisch wiederholt. In diesem Modus kannst du einzelne Titel wiederholen oder eine Playlist als Schleife wiedergeben. Wenn der Nutzer bei einer einzelnen Schleife "Next" oder etwas Ähnliches sagt, beginnt der Song von vorn. Bei Playlists in Schleife startet ein Nutzer, der "Next" sagt, den nächsten Titel der Playlist.
Zur Implementierung des Schleifenmodus fügen Sie das Feld repeat_mode
in Ihre Eingabeaufforderung ein und setzen dessen Wert auf ALL
. Durch diese Ergänzung kann Ihre Medienantwort an den Anfang des ersten Medienobjekts als Schleife wiedergegeben werden, wenn das Ende des letzten Medienobjekts erreicht ist.
Das folgende Code-Snippet zeigt eine Eingabeaufforderung, die eine Titelschleife zurückgibt:
{ "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" } } } ] }