媒體回應

媒體回應可讓動作播放播放時間超過 SSML 240 秒的音訊內容。媒體回應適用於僅限音訊裝置和可顯示視覺內容的裝置。在螢幕上,媒體回應會隨附具有媒體控制項的視覺元件,以及 (選用) 靜態圖片。

定義媒體回應時,請使用候選項目,並搭配 RICH_RESPONSELONG_FORM_AUDIO 途徑功能,讓 Google 助理只會在支援的裝置上傳回複合式回應。在提示中,每個 content 物件只能使用一個複合式回應。

要播放的音訊必須使用正確的 MP3 格式檔案。MP3 檔案必須託管於網路伺服器,並透過 HTTPS 網址公開存取。直播功能僅支援 MP3 格式。

智慧螢幕的媒體回應範例
圖 1. 智慧螢幕的媒體回應範例

行為

智慧型手機上的媒體回應範例
圖 2. 智慧型手機上的媒體回應範例

媒體回應的主要元件是單軌資訊卡。這張資訊卡可讓使用者執行下列操作:

  • 重播最後 10 秒
  • 快轉 30 秒
  • 查看媒體內容的總長度
  • 查看媒體播放進度指標
  • 查看播放時間

媒體回應支援下列語音互動音訊控制項,這些控制項都由 Google 助理處理:

  • 「Ok Google,播放。」
  • 「Ok Google,暫停。」
  • 「Ok Google,停止。」
  • 「Ok Google,重新開始。」

使用者也可以說出「Ok Google,調高音量」或「Ok Google,將音量設為 50%」等指令來控制音量。如果動作中的意圖處理類似的訓練詞組,系統會優先採用意圖。除非您的動作有特定原因,否則讓 Google 助理處理這些使用者要求。

Android 手機上的行為

在 Android 手機上,手機鎖定時仍可使用媒體控制選項。 媒體控制項也會顯示在通知區域中,而只要符合下列任一條件,使用者即可查看媒體回應:

  • Google 助理位於前景,且手機螢幕已開啟。
  • 使用者在播放音訊時離開 Google 助理,並在播放完畢後的 10 分鐘內返回 Google 助理。返回 Google 助理時,使用者會看到媒體資訊卡和建議方塊。

屬性

媒體回應具備以下屬性:

屬性 類型 必要性 說明
media_type MediaType 需要 所提供回應的媒體類型。在確認媒體狀態時傳回 MEDIA_STATUS_ACK
start_offset 字串 選用 跳轉至開始播放第一個媒體音軌的位置。請提供以秒為單位的值,且小數點後的數字不得超過九個小數位數,且結尾為「s」。例如,3 秒和 1 奈秒以「3.000000001s」表示。
optional_media_controls OptionalMediaControls 的陣列 選用 選擇加入屬性,就能在使用者變更媒體播放狀態 (例如暫停或停止播放媒體) 時接收回呼。
media_objects MediaObject 的陣列 需要 代表要納入提示中的媒體物件。使用 MEDIA_STATUS_ACK 確認媒體狀態時,請勿提供媒體物件。
first_media_object_index 整數 選用 要播放的 media_objects 中第一個 MediaObject 的索引 (從 0 開始)。如未指定、零或超出範圍,播放作業會從第一個 MediaObject 開始。
repeat_mode RepeatMode 選用 針對媒體物件清單重複播放模式。

程式碼範例

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

正在接收媒體狀態

在使用者的媒體播放期間或播放後,Google 助理可以產生媒體狀態事件,告知播放進度。在 Webhook 程式碼中處理這些狀態事件,即可在使用者暫停、停止或結束媒體播放時正確轉送使用者。

Google 助理會根據媒體播放進度和使用者查詢,從以下清單傳回狀態事件:

  • FINISHED使用者已完成媒體播放 (或跳到下一個媒體內容),且轉場時不會進入對話結束。這個狀態也對應至 MEDIA_STATUS_FINISHED 系統意圖。
  • PAUSED使用者暫停播放媒體。選擇透過 optional_media_controls 屬性接收這個狀態事件。這個狀態也對應至 MEDIA_STATUS_PAUSED 系統意圖。
  • STOPPED使用者停止或退出媒體播放。選擇透過 optional_media_controls 屬性接收這個狀態事件。這個狀態也對應至 MEDIA_STATUS_STOPPED 系統意圖。
  • FAILED無法播放媒體。這個狀態也對應至 MEDIA_STATUS_FAILED 系統意圖。

在媒體播放期間,使用者可能會提供的查詢,可同時解讀為媒體暫停和停止事件 (例如「停止」、「取消」或「結束」)。在這種情況下,Google 助理會為動作提供 actions.intent.CANCEL 系統意圖,並產生狀態為「STOPPED」狀態的媒體狀態事件,並完全結束您的動作。

當 Google 助理產生狀態為 PAUSEDSTOPPED 的媒體狀態事件時,請傳送僅包含 MEDIA_STATUS_ACK 類型的確認媒體回應。

媒體進度

目前的媒體播放進度可在 Webhook 要求的 context.media.progress 欄位中取得。您可以將媒體進度當做開始時間偏移使用,以便在媒體播放結束的時間點繼續播放。如要為媒體回應套用開始時間偏移,請使用 start_offset 屬性。

程式碼範例

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

回傳播放清單

您可以在回覆中加入多個音訊檔案來建立播放清單。 第一個音軌播放完畢後,系統會自動播放下一首曲目,而此曲目會持續到每首曲目播放完畢。使用者也可以按下畫面上的「Next」按鈕,或是說出「Next」或類似的指令,直接跳到下一首曲目。

播放清單中最後一首曲目的「繼續」按鈕處於停用狀態。不過,如果您啟用循環模式,播放清單會從第一個音軌重新開始。如要進一步瞭解循環模式,請參閱「實作循環模式」。

如要建立播放清單,請在 media_objects 陣列中加入多個 MediaObject。下列程式碼片段顯示傳回三個曲目播放清單的提示:

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

實作循環模式

循環模式可讓您提供可自動重複播放的音訊回應。您可以利用這個模式重複播放單一曲目或循環播放播放清單。如果使用者說出「下一首」或單一循環曲目的類似內容,歌曲就會重新開始。若是循環播放清單,使用者說出「Next」會在播放清單中播放下一首曲目。

如要實作循環模式,請在提示中加入 repeat_mode 欄位,並將其值設為 ALL。這可讓媒體回應在到達最後一個媒體物件的結尾時,循環播放第一個媒體物件的開頭。

下列程式碼片段顯示傳回循環音軌的提示:

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