Reakcje na multimedia

Dzięki odpowiedziom multimedialnym czynności w ramach akcji mogą odtwarzać treści audio o dłuższym niż 240-sekundowym limicie SSML. Reakcje na multimedia działają zarówno na urządzeniach, które obsługują tylko dźwięk, jak i na urządzeniach z treściami wizualnymi. Wyświetlane odpowiedzi dotyczące kreacji multimedialnej są powiązane z elementem wizualnym na potrzeby sterowania multimediami oraz (opcjonalnie) nieruchomym obrazem.

Podczas definiowania odpowiedzi multimedialnych używaj kandydatu z właściwościami RICH_RESPONSE i LONG_FORM_AUDIO. Dzięki temu Asystent Google będzie zwracać odpowiedź multimedialną tylko na obsługiwanych urządzeniach. W wierszu poleceń możesz użyć tylko 1 odpowiedzi z elementami rozszerzonymi na każdy obiekt content.

Dźwięk do odtworzenia musi być zapisany w prawidłowym formacie MP3. Pliki MP3 muszą być przechowywane na serwerze WWW i publicznie dostępne pod adresem URL HTTPS. Transmisje na żywo są obsługiwane tylko w przypadku formatu MP3.

Sposób działania

Głównym elementem odpowiedzi na multimedia jest karta z jednym utworem. Karta ta pozwala:

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

Reakcje na multimedia obsługują te opcje interakcji głosowych, z których każdy jest obsługiwany przez Asystenta Google:

• „OK Google, Play”
• „OK Google, wstrzymaj”
• „OK Google, zatrzymaj”
• „OK Google, zacznij od nowa”.

Użytkownicy mogą też sterować głośnością, mówiąc na przykład „OK Google, zwiększ głośność” lub „OK Google, ustaw głośność na 50 procent”. Intencje w działaniu mają pierwszeństwo, jeśli obsługują podobne wyrażenia treningowe. Pozwól Asystentowi obsługiwać te żądania użytkownika, chyba że ma to uzasadnienie.

Działanie na telefonach z Androidem

Na telefonach z Androidem opcje sterowania multimediami są dostępne również wtedy, gdy telefon jest zablokowany. Opcje sterowania multimediami pojawiają się też w obszarze powiadomień, a użytkownicy mogą wyświetlać odpowiedzi, gdy spełniony jest dowolny z tych warunków:

• Asystent Google jest na pierwszym planie, a ekran telefonu jest włączony.
• Użytkownik opuści Asystenta podczas odtwarzania dźwięku i powróci do Asystenta Google w ciągu 10 minut od zakończenia odtwarzania. Gdy użytkownik wróci do Asystenta Google, zobaczy kartę multimedialną i elementy z podpowiedzi.

Właściwości

Odpowiedzi na pytania dotyczące multimediów mają te właściwości:

Przykładowy kod

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

Odbieranie stanu multimediów

Podczas odtwarzania multimediów lub po jego zakończeniu Asystent Google może generować zdarzenia stanu multimediów, aby informować o postępach odtwarzania. Obsługuj te zdarzenia stanu w kodzie webhooka, aby prawidłowo kierować użytkowników po wstrzymaniu, zatrzymaniu lub zakończeniu odtwarzania multimediów.

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

• FINISHED: użytkownik ukończył odtwarzanie multimediów (lub przeskoczył do następnego elementu multimedialnego), a przejście nie jest wyjściem do 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 zakoń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że zostać zinterpretowane jako zdarzenie wstrzymania i zatrzymania multimediów (np. „zatrzymaj”, „anuluj” lub „zamknij”). W takiej sytuacji Asystent przekazuje intencję systemową actions.intent.CANCEL do działania, generuje zdarzenie stanu mediów o wartości „STOPPED” i całkowicie wychodzi z działania.

Gdy Asystent wygeneruje zdarzenie stanu multimediów o wartości stanu PAUSED lub STOPPED, w odpowiedzi prześlij multimedia, które zawierają tylko potwierdzenie (typu MEDIA_STATUS_ACK).

Postęp mediów

Bieżący postęp odtwarzania multimediów jest dostępny w polu context.media.progress w przypadku żądań webhooka. Postęp odtwarzania multimediów można wykorzystać jako przesunięcie czasu rozpoczęcia, aby wznowić odtwarzanie od miejsca, w którym odtwarzanie się zakończyło. Aby zastosować przesunięcie czasu rozpoczęcia do odpowiedzi multimedialnej, użyj właściwości start_offset.

Przykładowy kod

// 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

Do odpowiedzi możesz dodać więcej niż 1 plik audio. Po zakończeniu pierwszej ścieżki kolejna jest odtwarzana automatycznie Użytkownicy mogą też nacisnąć przycisk Dalej na ekranie lub powiedzieć „Dalej” lub podobny tekst, aby przejść do następnej ścieżki.

Przycisk Dalej jest wyłączony na ostatniej ścieżce playlisty. Jeśli jednak włączysz odtwarzanie w pętli, playlista zacznie się od początku z pierwszej ścieżki. Więcej informacji o trybie zapętlania znajdziesz w artykule Implementowanie trybu pętli.

Aby utworzyć playlistę, dodaj do tablicy media_objects więcej niż 1 element MediaObject. Ten fragment kodu zawiera 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
                }
              }
            }
          ],
        }
      }
    }
  ]
}

Włącz tryb zapętlenia

Tryb zapętlenia pozwala wyświetlić automatyczną odpowiedź głosową. W ten sposób możesz powtórzyć pojedynczą ścieżkę lub pętlę playlisty. Jeśli użytkownik powie Next (Dalej) lub podobny tekst w przypadku pojedynczej pętli, utwór znów się zacznie. W przypadku playlist w pętli, użytkownik mówiący „Dalej” rozpoczyna następną ścieżkę na playliście.

Aby zaimplementować tryb zapętlenia, dodaj w wierszu pola repeat_mode i ustaw jego wartość na ALL. Dzięki temu odpowiedź multimediów zostanie zapętlona na początku pierwszego obiektu multimedialnego po osiągnięciu końca ostatniego obiektu multimedialnego.

W tym fragmencie kodu pojawia się wiersz z pętlą:

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