媒體回應可讓動作播放播放時間超過 SSML 240 秒的音訊內容。媒體回應適用於僅限音訊裝置和可顯示視覺內容的裝置。在螢幕上,媒體回應會隨附具有媒體控制項的視覺元件,以及 (選用) 靜態圖片。
定義媒體回應時,請使用候選項目,並搭配 RICH_RESPONSE
和 LONG_FORM_AUDIO
途徑功能,讓 Google 助理只會在支援的裝置上傳回複合式回應。在提示中,每個 content
物件只能使用一個複合式回應。
要播放的音訊必須使用正確的 MP3 格式檔案。MP3 檔案必須託管於網路伺服器,並透過 HTTPS 網址公開存取。直播功能僅支援 MP3 格式。
行為
媒體回應的主要元件是單軌資訊卡。這張資訊卡可讓使用者執行下列操作:
- 重播最後 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 助理產生狀態為 PAUSED
或 STOPPED
的媒體狀態事件時,請傳送僅包含 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" } } } ] }