الردود على الوسائط

تسمح ردود الوسائط لـ "الإجراءات" بتشغيل محتوى صوتي بمدة تشغيل أطول من 240 ثانية وهي SSML. تعمل ردود الوسائط على كل من الأجهزة الصوتية فقط والأجهزة التي يمكنها عرض المحتوى المرئي. على شاشة العرض، تكون ردود الوسائط مصحوبةً بمكوِّن مرئي مزود بعناصر تحكم في الوسائط و(اختياريًا) صورة ثابتة.

عند تحديد استجابة على مستوى الوسائط، يمكنك استخدام مرشح يتضمّن قدرات RICH_RESPONSE وLONG_FORM_AUDIO السطح حتى لا يعرض "مساعد Google" الردود المنسّقة إلا على الأجهزة المتوافقة. لا يمكن استخدام سوى استجابة منسّقة واحدة لكل عنصر content في الطلب.

يجب أن يكون ملف الصوت للتشغيل بتنسيق MP3 بشكل صحيح. يجب استضافة ملفات MP3 على خادم ويب وأن تكون متاحة للجمهور من خلال عنوان URL يستخدم 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" أثناء تشغيل الصوت ثم يعود إلى "مساعد 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"
        }
      }
    }
  ]
}