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.
Sposób działania
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ścioptional_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ścioptional_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" } } } ] }