تسمح ردود الوسائط لـ "الإجراءات" بتشغيل محتوى صوتي بمدة تشغيل أطول من 240 ثانية وهي SSML. تعمل ردود الوسائط على كل من الأجهزة الصوتية فقط والأجهزة التي يمكنها عرض المحتوى المرئي. على شاشة العرض، تكون ردود الوسائط مصحوبةً بمكوِّن مرئي مزود بعناصر تحكم في الوسائط و(اختياريًا) صورة ثابتة.
عند تحديد استجابة على مستوى الوسائط، يمكنك استخدام مرشح يتضمّن قدرات RICH_RESPONSE
وLONG_FORM_AUDIO
السطح حتى لا يعرض "مساعد Google" الردود المنسّقة إلا على الأجهزة المتوافقة. لا يمكن استخدام سوى
استجابة منسّقة واحدة لكل عنصر content
في الطلب.
يجب أن يكون ملف الصوت للتشغيل بتنسيق MP3 بشكل صحيح. يجب استضافة ملفات MP3 على خادم ويب وأن تكون متاحة للجمهور من خلال عنوان URL يستخدم HTTPS. لا يتوفّر البث المباشر إلا بتنسيق MP3.
السلوك
المكوّن الأساسي لاستجابة الوسائط هو البطاقة ذات المسار الفردي. تسمح البطاقة للمستخدم بالقيام بما يلي:
- إعادة تشغيل آخر 10 ثوانٍ
- تخطي 30 ثانية إلى الأمام
- عرض إجمالي مدة محتوى الوسائط
- عرض مؤشر مستوى تقدُّم تشغيل الوسائط
- الاطّلاع على وقت التشغيل المنقضي
تتيح الردود على الوسائط عناصر التحكّم التالية في الصوت للتفاعلات الصوتية، ويتعامل "مساعد Google" مع كل هذه العناصر:
- "Ok Google، تشغيل"
- "Ok Google، أريد إيقاف التشغيل مؤقتًا"
- "Ok Google، إيقاف"
- "Ok Google، البدء من جديد"
ويمكن للمستخدمين أيضًا التحكّم في مستوى الصوت من خلال قول عبارات مثل "Ok Google، أريد رفع مستوى الصوت" أو "Ok Google، أريد ضبط مستوى الصوت على 50 في المئة". تكون للأهداف في الإجراء الخاص بك الأولوية إذا كانت تتعامل مع عبارات تدريب مماثلة. يمكنك السماح لخدمة "مساعد Google" بمعالجة طلبات المستخدمين هذه ما لم يكن الإجراء الخاص بك سببًا محددًا لذلك.
السلوك على هواتف Android
على هواتف Android، تتوفّر أيضًا عناصر التحكّم في الوسائط عندما يكون الهاتف مقفلاً. تظهر عناصر التحكم في الوسائط أيضًا في منطقة الإشعارات، ويمكن للمستخدمين الاطّلاع على الردود بشأن الوسائط عند استيفاء أي من الشروط التالية:
- يتم عرض "مساعد Google" في المقدّمة وشاشة الهاتف قيد التشغيل.
- يغادر المستخدم "مساعد Google" أثناء تشغيل الصوت ثم يعود إلى "مساعد Google" في غضون 10 دقائق من اكتمال التشغيل. عند العودة إلى "مساعد Google"، سيرى المستخدم بطاقة الوسائط وشرائح الاقتراحات.
أماكن إقامة
تتضمَّن الردود على الوسائط السمات التالية:
الموقع | Type | المتطلب | الوصف |
---|---|---|---|
media_type |
MediaType |
مطلوبة | نوع الوسائط للرد المقدّم. اعرض الرمز MEDIA_STATUS_ACK
عند الاعتراف بحالة الوسائط. |
start_offset |
سلسلة | إجراء اختياري | البحث عن موضع لبدء أول مسار وسائط أدخِل القيمة بالثواني، مع التعبير عن ثواني كسرية بأكثر من تسع خانات عشرية، ويجب أن تنتهي في اللاحقة "s". على سبيل المثال، يتم التعبير عن 3 ثوانٍ ونانو ثانية واحدة على النحو التالي: "3.000000001s". |
optional_media_controls |
مصفوفة OptionalMediaControls |
إجراء اختياري | تفعيل الموقع الإلكتروني لتلقّي استدعاءات عندما يغيّر المستخدم حالة تشغيل الوسائط (مثلاً عن طريق إيقاف تشغيل الوسائط مؤقتًا أو إيقافه) |
media_objects |
مصفوفة MediaObject |
مطلوبة | يمثل عناصر الوسائط التي سيتم تضمينها في الطلب. عند
الإقرار بحالة وسائط باستخدام MEDIA_STATUS_ACK ، لا
تقدّم كائنات وسائط. |
first_media_object_index |
عدد صحيح | إجراء اختياري | فهرس مستند إلى 0 لأول MediaObject في media_objects يتم تشغيله. إذا لم يتم تحديد السياسة أو كانت صفرًا أو خارج الحدود،
يبدأ التشغيل عند أول 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" إنشاء أحداث حالة الوسائط لإبلاغ الإجراء الخاص بتقدّم التشغيل. يمكنك معالجة أحداث الحالة هذه في رمز الرد التلقائي على الويب لتوجيه المستخدمين بشكلٍ مناسب عند إيقاف تشغيل الوسائط مؤقتًا أو إيقافها أو إنهائها.
يعرض "مساعد 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
للإجراء الخاص بك، وينشئ حدثًا لحالة الوسائط يتضمّن قيمة الحالة "متوقّفة"، ثم
يُخرج الإجراء الخاص بك تمامًا.
عندما ينشئ "مساعد Google" حدث حالة وسائط يتضمّن قيمة الحالة PAUSED
أو STOPPED
،
يمكنك الاستجابة باستخدام استجابة وسائط تتضمّن
الإقرار فقط (من النوع MEDIA_STATUS_ACK
).
تقدّم الوسائط
يتوفّر التقدّم الحالي في تشغيل الوسائط في الحقل
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.'); } });
إرجاع قائمة تشغيل
يمكنك إضافة أكثر من ملف صوتي واحد في ردّك لإنشاء قائمة تشغيل. عند الانتهاء من تشغيل المقطع الصوتي الأول، يتم تشغيل المسار التالي تلقائيًا، ويستمر ذلك إلى أن يتم تشغيل كل مقطع صوتي. يمكن للمستخدمين أيضًا الضغط على زر التالي على الشاشة أو قول "التالي" أو شيئًا مشابهًا للتخطي إلى المقطع الصوتي التالي.
يكون الزر التالي غير مفعّل في المقطع الصوتي الأخير من قائمة التشغيل. مع ذلك، إذا فعّلت وضع التكرار، تبدأ قائمة التشغيل مجددًا من المقطع الصوتي الأول. لمزيد من المعلومات حول وضع التكرار، راجِع تنفيذ وضع التكرار.
لإنشاء قائمة تشغيل، يجب تضمين أكثر من علامة MediaObject
واحدة في المصفوفة media_objects
. يُظهر مقتطف الرمز التالي مطالبة تعرض قائمة تشغيل مكونة من ثلاثة مقاطع صوتية:
{ "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" } } } ] }