Medienantworten

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.

Behavior

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:

Beispielcode

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

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

// 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'
  }));
});

{
  "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-Intent MEDIA_STATUS_FINISHED zugeordnet.
• PAUSED:Der Nutzer hat die Medienwiedergabe pausiert. Aktiviere den Empfang dieses Statusereignisses mit der Property optional_media_controls. Dieser Status ist auch dem System-Intent MEDIA_STATUS_PAUSED zugeordnet.
• STOPPED:Der Nutzer hat die Medienwiedergabe beendet oder beendet. Aktiviere den Empfang dieses Statusereignisses mit der Property optional_media_controls. Dieser Status ist auch dem System-Intent MEDIA_STATUS_STOPPED zugeordnet.
• FAILED:Fehler bei der Medienwiedergabe. Dieser Status ist auch dem System-Intent MEDIA_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

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