Reakcje na multimedia

Odpowiedzi dotyczące multimediów umożliwiają akcjom odtwarzanie treści dźwiękowych o czasie odtwarzania dłuższym niż 240 sekund określony w SSML. Odpowiedzi multimedialne działają zarówno na urządzeniach, które obsługują tylko dźwięk, jak i na urządzeniach, które mogą wyświetlać treści wizualne. Na wyświetlaczu reakcjom multimedialnym towarzyszy komponent wizualny z elementami sterującymi multimediami i (opcjonalnie) nieruchomy obraz.

Podczas definiowania odpowiedzi multimedialnych użyj kandydatów z funkcjami platformy RICH_RESPONSE i LONG_FORM_AUDIO. Dzięki temu Asystent Google będzie zwracał odpowiedzi rozszerzone tylko na obsługiwanych urządzeniach. W prompcie możesz użyć tylko 1 odpowiedzi z elementami rozszerzonymi na obiekt content.

Dźwięk do odtwarzania musi być prawidłowo sformatowany w pliku MP3. Pliki MP3 muszą być hostowane na serwerze WWW i dostępne publicznie za pomocą adresu URL HTTPS. Transmitowanie na żywo jest obsługiwane tylko w formacie MP3.

Przykład odpowiedzi dotyczącej multimediów na inteligentnym ekranie
Rysunek 1. Przykład odpowiedzi multimedialnej na inteligentnym ekranie

Sposób działania

Przykład odpowiedzi multimedialnej na smartfonie
Rysunek 2. Przykład odpowiedzi multimedialnej na smartfonie

Podstawowym komponentem odpowiedzi multimedialnej jest karta z jednym utworem. Umożliwia ona użytkownikowi:

  • Powtórz ostatnie 10 sekund
  • Przeskocz o 30 sekund do przodu
  • Wyświetlanie łącznej długości treści multimedialnych
  • Wyświetlanie wskaźnika postępu odtwarzania multimediów
  • Wyświetlanie czasu odtwarzania

Odpowiedzi multimedialne obsługują te elementy sterujące dźwiękiem w przypadku interakcji głosowych. Wszystkie te funkcje są obsługiwane przez Asystenta Google:

  • „OK Google, odtwarzaj”
  • „OK Google, wstrzymaj”
  • „OK Google, zatrzymaj”
  • „OK Google, zacznijmy od początku”.

Użytkownicy mogą też regulować głośność za pomocą poleceń takich jak „OK Google, zwiększ głośność” lub „OK Google, ustaw głośność na 50 procent”. Intencje w Akcji mają pierwszeństwo, jeśli obsługują podobne wyrażenia na potrzeby trenowania. Pozwól Asystentowi na obsługę tych próśb, chyba że akcja ma konkretny powód.

Działanie na telefonach z Androidem

Na telefonach z Androidem opcje sterowania multimediami są też dostępne, gdy telefon jest zablokowany. Opcje sterowania multimediami są też widoczne w obszarze powiadomień, a użytkownicy mogą zobaczyć odpowiedzi multimedialne, gdy spełniony jest dowolny z tych warunków:

  • Asystent Google działa na pierwszym planie, a ekran telefonu jest włączony.
  • Użytkownik opuszcza Asystenta Google podczas odtwarzania dźwięku i wraca do Asystenta Google w ciągu 10 minut od zakończenia odtwarzania. Po powrocie do Asystenta Google użytkownik widzi kartę multimediów i elementy sugestii.

Właściwości

Odpowiedzi multimedialne mają te właściwości:

Właściwość Typ Wymaganie Opis
media_type MediaType Wymagane Typ multimediów przesłanej odpowiedzi. Zwróć MEDIA_STATUS_ACK po potwierdzeniu stanu multimediów.
start_offset ciąg znaków Opcjonalnie Wyszukaj pozycję, aby rozpocząć pierwszą ścieżkę multimediów. Podaj wartość w sekundach, z ułamkami sekund wyrażonymi maksymalnie z więcej niż 9 miejscami po przecinku, i kończ się sufiksem „s”. Na przykład 3 sekundy i 1 nanosekunda są zapisywane jako „3.000000001s”.
optional_media_controls tablica OptionalMediaControls Opcjonalnie Wyraź zgodę na otrzymywanie wywołań zwrotnych, gdy użytkownik zmieni stan odtwarzania multimediów (np. wstrzyma lub zatrzyma odtwarzanie multimediów).
media_objects tablica MediaObject Wymagane Reprezentuje obiekty multimedialne, które mają być uwzględnione w prompcie. Podczas potwierdzania stanu multimediów za pomocą MEDIA_STATUS_ACK nie podawaj obiektów multimediów.
first_media_object_index Liczba całkowita Opcjonalnie Indeks oparty na 0 pierwszych elementów MediaObject w media_objects do odtworzenia. Jeśli wartość nie jest określona, wartość zero lub jest poza granicami, odtwarzanie rozpoczyna się w pierwszym polu MediaObject.
repeat_mode RepeatMode Opcjonalnie Tryb powtarzania dla listy obiektów multimedialnych.

Przykładowy kod

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

Stan odbierania multimediów

Podczas odtwarzania multimediów lub po nim Asystent Google może generować zdarzenia dotyczące stanu multimediów, aby informować akcję o postępie odtwarzania. Obsługuj te zdarzenia stanu w kodzie webhooka, aby odpowiednio kierować użytkowników, gdy wstrzymają, zatrzymują lub kończą odtwarzanie multimediów.

Asystent Google zwraca zdarzenie stanu z tej listy na podstawie postępu odtwarzania multimediów i zapytań użytkownika:

  • FINISHED: użytkownik zakończył odtwarzanie multimediów (lub przechodzi do następnego materiału), a przejście nie powoduje zakończenia rozmowy. Ten stan jest też mapowany na intencję systemową MEDIA_STATUS_FINISHED.
  • PAUSED: użytkownik wstrzymał odtwarzanie multimediów. Włącz otrzymywanie tego zdarzenia stanu za pomocą właściwości optional_media_controls. Ten stan jest też mapowany na intencję systemową MEDIA_STATUS_PAUSED.
  • STOPPED: użytkownik zatrzymał lub wyłączył odtwarzanie multimediów. Włącz otrzymywanie tego zdarzenia stanu za pomocą właściwości optional_media_controls. Ten stan jest też mapowany na intencję systemową MEDIA_STATUS_STOPPED.
  • FAILED: nie udało się odtworzyć multimediów. Ten stan jest też mapowany na intencję systemową MEDIA_STATUS_FAILED.

Podczas odtwarzania multimediów użytkownik może podać zapytanie, które można zinterpretować jako zdarzenie wstrzymania i zatrzymania (np. „stop”, „cancel” lub „exit”). W takiej sytuacji Asystent przekazuje intencję systemową actions.intent.CANCEL do akcji, generuje zdarzenie stanu multimediów z wartością stanu „STOPPED” i całkowicie zamyka akcję.

Gdy Asystent wygeneruje zdarzenie stanu multimediów o wartości stanu PAUSED lub STOPPED, w odpowiedzi prześlij odpowiedź związaną z multimediami, która zawiera tylko potwierdzenie (typu MEDIA_STATUS_ACK).

Postęp multimediów

Bieżący postęp odtwarzania multimediów jest podany w polu context.media.progress (w przypadku żądań webhooka). Postęp odtwarzania multimediów możesz wykorzystać jako przesunięcie czasu rozpoczęcia, aby wznowić odtwarzanie od momentu, w którym odtwarzanie multimediów zostało zakończone. Aby zastosować przesunięcie czasu rozpoczęcia do odpowiedzi dotyczącej multimediów, użyj właściwości start_offset.

Przykładowy kod

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

Zwracanie playlisty

Aby utworzyć playlistę, w odpowiedzi możesz dodać więcej niż 1 plik audio. Po zakończeniu odtwarzania pierwszej ścieżki automatycznie odtwarzany jest kolejny utwór, który jest odtwarzany automatycznie. Użytkownicy mogą też nacisnąć przycisk Dalej na ekranie lub powiedzieć „Dalej”, aby przejść do następnego utworu.

Przy ostatnim utworze playlisty przycisk Dalej jest nieaktywny. Jeśli jednak włączysz tryb odtwarzania w pętli, playlista zacznie się od pierwszego utworu. Więcej informacji o trybie zapętlania znajdziesz w artykule o implementowaniu trybu pętli.

Aby utworzyć playlistę, umieść w tablicy media_objects więcej niż 1 element MediaObject. Ten fragment kodu wyświetla komunikat z prośbą o zwrócenie playlisty z 3 utworami:

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

Wdrażanie trybu zapętlania

Tryb pętlania umożliwia Ci odtworzenie odpowiedzi audio, która będzie się automatycznie powtarzać. W tym trybie możesz powtarzać pojedynczy utwór lub całą playlistę. Jeśli w przypadku pojedynczego zapętlonego utworu użytkownik powie „Dalej” lub podobnego, utwór zacznie się od nowa. W przypadku playlist zapętlonych użytkownik mówiący „Dalej” włącza następny utwór na playliście.

Aby wdrożyć tryb w pętli, dodaj do promptu pole repeat_mode i ustaw jego wartość na ALL. To dodanie umożliwia pętlę odpowiedzi multimediów na początek pierwszego obiektu multimedialnego po osiągnięciu końca ostatniego obiektu multimedialnego.

Ten fragment kodu wyświetla komunikat z prośbą o zapętlenie ścieżki:

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