Các phản hồi của nội dung đa phương tiện cho phép Hành động của bạn phát nội dung âm thanh có thời lượng phát dài hơn giới hạn 240 giây của SSML. Phản hồi của nội dung đa phương tiện hoạt động trên cả thiết bị chỉ có âm thanh và thiết bị có thể hiển thị nội dung hình ảnh. Trên màn hình, các phản hồi về nội dung đa phương tiện đi kèm với một thành phần hình ảnh có các chế độ điều khiển nội dung nghe nhìn và hình ảnh tĩnh (không bắt buộc).
Khi xác định phản hồi nội dung đa phương tiện, hãy sử dụng một đề xuất với cả khả năng nền tảng RICH_RESPONSE và LONG_FORM_AUDIO để Trợ lý Google chỉ trả về phản hồi nhiều định dạng trên các thiết bị được hỗ trợ. Bạn chỉ có thể sử dụng một phản hồi nhiều định dạng cho mỗi đối tượng content trong một câu lệnh.
Âm thanh để phát phải là tệp MP3 có định dạng chính xác. Tệp MP3 phải được lưu trữ trên máy chủ web và được cung cấp công khai thông qua URL loại HTTPS. Tính năng phát trực tiếp chỉ được hỗ trợ cho định dạng MP3.
Hành vi
Thành phần chính của nội dung phản hồi nội dung đa phương tiện là thẻ một bản nhạc. Thẻ này cho phép người dùng làm những việc sau:
- Phát lại 10 giây trước
- Tua đi 30 giây
- Xem tổng thời lượng của nội dung nghe nhìn
- Xem chỉ báo tiến trình để phát nội dung đa phương tiện
- Xem thời gian phát đã trôi qua
Tính năng phản hồi bằng nội dung nghe nhìn hỗ trợ các chế độ điều khiển âm thanh sau đây cho hoạt động tương tác bằng giọng nói, tất cả đều do Trợ lý Google xử lý:
- "Ok Google, phát".
- “Ok Google, tạm dừng.”
- “Ok Google, dừng lại”.
- “Ok Google, hãy bắt đầu lại.”
Người dùng cũng có thể điều khiển âm lượng bằng cách nói các cụm từ như "Ok Google, tăng âm lượng". hoặc "Ok Google, đặt âm lượng ở mức 50%". Các ý định trong Hành động của bạn sẽ được ưu tiên nếu chúng xử lý các cụm từ huấn luyện tương tự. Hãy để Trợ lý xử lý những yêu cầu này của người dùng, trừ phi Hành động của bạn có lý do cụ thể.
Hành vi trên điện thoại Android
Trên điện thoại Android, bạn cũng có thể sử dụng các chế độ điều khiển nội dung nghe nhìn khi điện thoại đang khoá. Các chế độ điều khiển nội dung đa phương tiện cũng xuất hiện trong khu vực thông báo và người dùng có thể xem phản hồi của nội dung đa phương tiện khi bất kỳ điều kiện nào sau đây được đáp ứng:
- Trợ lý Google đang chạy ở nền trước và màn hình điện thoại đang bật.
- Người dùng rời khỏi Trợ lý Google trong khi âm thanh đang phát và quay lại Trợ lý Google trong vòng 10 phút kể từ khi phát xong. Khi quay lại Trợ lý Google, người dùng sẽ thấy thẻ nội dung đa phương tiện và khối đề xuất.
Thuộc tính
Phản hồi của nội dung nghe nhìn có các thuộc tính sau:
| Tài sản | Loại | Yêu cầu | Nội dung mô tả |
|---|---|---|---|
media_type |
MediaType |
Bắt buộc | Loại nội dung đa phương tiện của câu trả lời đã cung cấp. Trả về MEDIA_STATUS_ACK khi xác nhận trạng thái nội dung nghe nhìn. |
start_offset |
string | Không bắt buộc | Tua đến vị trí để bắt đầu bản nhạc nội dung nghe nhìn đầu tiên. Cung cấp giá trị tính bằng giây, với số giây phân số được biểu thị không quá 9 chữ số thập phân và kết thúc bằng hậu tố "s". Ví dụ: 3 giây và 1 nano giây được biểu thị bằng "3.000000001 giây". |
optional_media_controls |
mảng OptionalMediaControls |
Không bắt buộc | Chọn sử dụng thuộc tính để nhận lệnh gọi lại khi người dùng thay đổi trạng thái phát nội dung đa phương tiện (chẳng hạn như bằng cách tạm dừng hoặc dừng phát nội dung đa phương tiện). |
media_objects |
mảng MediaObject |
Bắt buộc | Đại diện cho các đối tượng nội dung đa phương tiện để đưa vào lời nhắc. Khi xác nhận trạng thái nội dung nghe nhìn bằng MEDIA_STATUS_ACK, đừng cung cấp đối tượng nội dung nghe nhìn. |
first_media_object_index |
số nguyên | Không bắt buộc | chỉ mục dựa trên 0 của MediaObject đầu tiên trong media_objects để phát. Nếu chưa chỉ định, giá trị 0 hoặc nằm ngoài giới hạn, quá trình phát sẽ bắt đầu ở MediaObject đầu tiên.
|
repeat_mode |
RepeatMode |
Không bắt buộc | Chế độ lặp lại cho danh sách đối tượng nội dung nghe nhìn. |
Mã mẫu
Hàm 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"
}
}
}
Đang nhận trạng thái nội dung nghe nhìn
Trong hoặc sau khi người dùng phát nội dung nghe nhìn, Trợ lý Google có thể tạo các sự kiện trạng thái nội dung đa phương tiện để thông báo cho Hành động của bạn về tiến trình phát. Hãy xử lý các sự kiện trạng thái này trong mã webhook của bạn để định tuyến đúng cách người dùng khi họ tạm dừng, dừng hoặc kết thúc việc phát nội dung nghe nhìn.
Trợ lý Google trả về một sự kiện trạng thái từ danh sách sau dựa trên tiến trình phát nội dung đa phương tiện và truy vấn của người dùng:
FINISHED: Người dùng đã phát xong nội dung nghe nhìn (hoặc chuyển sang nội dung nghe nhìn tiếp theo) và quá trình chuyển đổi không phải là thoát khỏi cuộc trò chuyện. Trạng thái này cũng liên kết với ý định của hệ thốngMEDIA_STATUS_FINISHED.PAUSED: Người dùng đã tạm dừng phát nội dung đa phương tiện. Chọn nhận sự kiện trạng thái này bằng thuộc tínhoptional_media_controls. Trạng thái này cũng liên kết với ý định của hệ thốngMEDIA_STATUS_PAUSED.STOPPED: Người dùng đã dừng hoặc thoát khỏi chế độ phát nội dung đa phương tiện. Chọn nhận sự kiện trạng thái này bằng thuộc tínhoptional_media_controls. Trạng thái này cũng liên kết với ý định của hệ thốngMEDIA_STATUS_STOPPED.FAILED: Không phát được nội dung nghe nhìn. Trạng thái này cũng liên kết với ý định của hệ thốngMEDIA_STATUS_FAILED.
Trong khi phát nội dung đa phương tiện, người dùng có thể đưa ra truy vấn có thể được hiểu là cả sự kiện tạm dừng và dừng nội dung đa phương tiện (chẳng hạn như "dừng", "huỷ" hoặc "thoát"). Trong trường hợp đó, Trợ lý sẽ cung cấp ý định của hệ thống actions.intent.CANCEL cho Hành động của bạn, tạo một sự kiện trạng thái nội dung đa phương tiện có giá trị trạng thái "STOPPED" và thoát hoàn toàn khỏi Hành động của bạn.
Khi Trợ lý tạo một sự kiện trạng thái nội dung đa phương tiện có giá trị trạng thái PAUSED hoặc STOPPED, hãy phản hồi bằng nội dung phản hồi nội dung đa phương tiện chỉ chứa thông tin xác nhận (thuộc loại MEDIA_STATUS_ACK).
Tiến trình phát nội dung đa phương tiện
Tiến trình phát nội dung nghe nhìn hiện tại sẽ có trong trường context.media.progress cho các yêu cầu webhook. Bạn có thể sử dụng tiến trình phát nội dung đa phương tiện làm mức chênh lệch thời gian bắt đầu để tiếp tục phát tại thời điểm kết thúc phát nội dung đa phương tiện. Để áp dụng độ lệch thời gian bắt đầu cho phản hồi nội dung nghe nhìn, hãy sử dụng thuộc tính start_offset.
Mã mẫu
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.');
}
});
Trả lại danh sách phát
Để tạo danh sách phát, bạn có thể thêm nhiều tệp âm thanh vào câu trả lời. Khi bản nhạc đầu tiên phát xong, bản nhạc tiếp theo sẽ tự động phát và quá trình này sẽ tiếp tục cho đến khi phát xong từng bản nhạc. Người dùng cũng có thể nhấn nút Tiếp theo trên màn hình hoặc nói "Tiếp theo" hoặc nói điều gì đó tương tự để chuyển sang bản nhạc tiếp theo.
Nút Tiếp theo bị tắt đối với bản nhạc cuối cùng của danh sách phát. Tuy nhiên, nếu bạn bật chế độ lặp lại, danh sách phát sẽ bắt đầu lại từ bản nhạc đầu tiên. Để tìm hiểu thêm về chế độ lặp lại, hãy xem bài viết Triển khai chế độ lặp lại.
Để tạo một danh sách phát, hãy đưa nhiều MediaObject vào mảng media_objects. Đoạn mã sau đây cho thấy một lời nhắc trả về danh sách phát gồm 3 bản nhạc:
{
"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
}
}
}
],
}
}
}
]
}
Triển khai chế độ lặp lại
Chế độ lặp lại cho phép bạn cung cấp phản hồi âm thanh tự động lặp lại. Bạn có thể sử dụng chế độ này để phát lặp lại một bản nhạc hoặc phát lặp lại theo một danh sách phát. Nếu người dùng nói "Tiếp theo" hoặc nói tương tự như một bản nhạc lặp lại, thì bài hát sẽ bắt đầu lại. Đối với danh sách phát lặp, người dùng nói "Tiếp theo" sẽ bắt đầu bản nhạc tiếp theo trong danh sách phát.
Để triển khai chế độ lặp lại, hãy thêm trường repeat_mode vào câu lệnh của bạn và đặt giá trị của trường đó thành ALL. Việc thêm vào này cho phép phản hồi nội dung đa phương tiện của bạn lặp lại với điểm bắt đầu của đối tượng nội dung đa phương tiện đầu tiên khi đến điểm kết thúc của đối tượng nội dung đa phương tiện cuối cùng.
Đoạn mã sau đây cho thấy một lời nhắc trả về một bản nhạc lặp lại:
{
"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"
}
}
}
]
}