پاسخ های رسانه ها

پاسخ‌های رسانه‌ای به Actions شما اجازه می‌دهد محتوای صوتی را با مدت زمان پخش بیشتر از حد ۲۴۰ ثانیه SSML پخش کند. پاسخ‌های رسانه‌ای هم روی دستگاه‌های فقط صوتی و هم در دستگاه‌هایی که می‌توانند محتوای بصری را نمایش دهند، کار می‌کنند. در یک نمایشگر، پاسخ های رسانه ای با یک جزء بصری با کنترل های رسانه و (اختیاری) یک تصویر ثابت همراه است.

هنگام تعریف یک پاسخ رسانه، از نامزدی با قابلیت‌های سطح RICH_RESPONSE و LONG_FORM_AUDIO استفاده کنید تا «دستیار Google» فقط در دستگاه‌های پشتیبانی‌شده پاسخ غنی را برگرداند. شما فقط می توانید از یک پاسخ غنی برای هر شیء content در یک درخواست استفاده کنید.

صدا برای پخش باید در یک فایل MP3 با فرمت صحیح باشد. فایل‌های MP3 باید روی سرور وب میزبانی شوند و از طریق یک URL HTTPS در دسترس عموم قرار گیرند. پخش زنده فقط برای فرمت MP3 پشتیبانی می شود.

نمونه ای از پاسخ رسانه در صفحه نمایش هوشمند
شکل 1. نمونه ای از پاسخ رسانه ای در صفحه نمایش هوشمند

رفتار

نمونه ای از پاسخ رسانه ای در گوشی هوشمند
شکل 2. نمونه ای از پاسخ رسانه ای در گوشی هوشمند

مؤلفه اصلی پاسخ رسانه ای کارت تک تراک است. کارت به کاربر این امکان را می دهد که کارهای زیر را انجام دهد:

  • 10 ثانیه آخر را دوباره پخش کنید
  • 30 ثانیه به جلو پرش کنید
  • طول کل محتوای رسانه را مشاهده کنید
  • یک نشانگر پیشرفت برای پخش رسانه مشاهده کنید
  • زمان پخش سپری شده را مشاهده کنید

پاسخ‌های رسانه‌ای از کنترل‌های صوتی زیر برای تعاملات صوتی پشتیبانی می‌کنند، که همه آن‌ها توسط Google Assistant مدیریت می‌شوند:

  • "Ok Google, play."
  • "Ok Google, Pause."
  • "Ok Google, stop."
  • "Ok Google، از اول شروع کن."

کاربران همچنین می‌توانند با گفتن عباراتی مانند «Hey Google، صدا را افزایش بده» صدا را کنترل کنند. یا «Hey Google، میزان صدا را روی 50 درصد تنظیم کن». اگر عبارات آموزشی مشابهی داشته باشند، مقاصد در Action شما اولویت دارند. اجازه دهید «دستیار» به این درخواست‌های کاربر رسیدگی کند، مگر اینکه Action شما دلیل خاصی برای آن داشته باشد.

رفتار در گوشی های اندرویدی

در گوشی‌های اندرویدی، کنترل‌های رسانه در زمانی که گوشی قفل است نیز در دسترس هستند. کنترل‌های رسانه نیز در ناحیه اعلان ظاهر می‌شوند و کاربران می‌توانند در صورت رعایت هر یک از شرایط زیر، پاسخ‌های رسانه را ببینند:

  • Google Assistant در پیش زمینه است و صفحه نمایش تلفن روشن است.
  • کاربر هنگام پخش صدا، دستیار Google را ترک می کند و ظرف 10 دقیقه پس از اتمام پخش، به دستیار Google باز می گردد. در بازگشت به Google Assistant، کاربر کارت رسانه و تراشه‌های پیشنهاد را می‌بیند.

خواص

پاسخ های رسانه ای دارای ویژگی های زیر هستند:

اموال تایپ کنید مورد نیاز توضیحات
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 عدد صحیح اختیاری شاخص مبتنی بر 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 می‌تواند رویدادهای وضعیت رسانه را ایجاد کند تا Action شما را از پیشرفت پخش مطلع کند. این رویدادهای وضعیت را در کد وب هوک خود مدیریت کنید تا کاربران را هنگام توقف، توقف یا پایان پخش رسانه به طور مناسب مسیریابی کنید.

Google Assistant یک رویداد وضعیت را از لیست زیر بر اساس پیشرفت پخش رسانه و درخواست‌های کاربر برمی‌گرداند:

  • FINISHED : پخش رسانه توسط کاربر (یا پرش به قطعه بعدی رسانه) و انتقال به خروجی مکالمه انجام نشده است. این وضعیت همچنین با هدف سیستم MEDIA_STATUS_FINISHED نگاشت می شود.
  • PAUSED : کاربر پخش رسانه را متوقف کرد. برای دریافت این رویداد وضعیت با ویژگی optional_media_controls شرکت کنید. این وضعیت همچنین با هدف سیستم MEDIA_STATUS_PAUSED نگاشت می شود.
  • STOPPED : کاربر پخش رسانه را متوقف کرده یا از آن خارج شد. برای دریافت این رویداد وضعیت با ویژگی optional_media_controls شرکت کنید. این وضعیت همچنین با هدف سیستم MEDIA_STATUS_STOPPED نگاشت می شود.
  • FAILED : پخش رسانه انجام نشد. این وضعیت همچنین با هدف سیستم MEDIA_STATUS_FAILED نگاشت می شود.

در حین پخش رسانه، کاربر ممکن است درخواستی ارائه دهد که می تواند به عنوان یک رویداد توقف و توقف رسانه تفسیر شود (مانند "توقف"، "لغو" یا "خروج"). در این شرایط، Assistant قصد سیستم actions.intent.CANCEL را برای Action شما فراهم می‌کند، یک رویداد وضعیت رسانه با مقدار وضعیت "STOPPED" ایجاد می‌کند و از Action شما به طور کامل خارج می‌شود.

وقتی دستیار یک رویداد وضعیت رسانه با مقدار وضعیت PAUSED یا STOPPED ایجاد می‌کند، با یک پاسخ رسانه‌ای که فقط حاوی یک تأیید است (از نوع MEDIA_STATUS_ACK ) پاسخ دهید.

پیشرفت رسانه ها

پیشرفت فعلی پخش رسانه در قسمت context.media.progress برای درخواست های webhook موجود است. می توانید از پیشرفت رسانه به عنوان زمان شروع برای ازسرگیری پخش در نقطه ای که پخش رسانه پایان یافته است استفاده کنید. برای اعمال افست زمان شروع به پاسخ رسانه ای، از ویژگی 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" یا چیزی شبیه به آن را بگویند.

دکمه Next در آخرین آهنگ لیست پخش غیرفعال است. با این حال، اگر حالت حلقه را فعال کنید، لیست پخش دوباره از اولین آهنگ شروع می شود. برای کسب اطلاعات بیشتر در مورد حالت حلقه، به پیاده سازی حالت حلقه مراجعه کنید.

برای ایجاد یک لیست پخش، بیش از یک 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
                }
              }
            }
          ],
        }
      }
    }
  ]
}

اجرای حالت حلقه

حالت حلقه به شما امکان می دهد یک پاسخ صوتی ارائه دهید که به طور خودکار تکرار می شود. می توانید از این حالت برای تکرار یک آهنگ واحد یا حلقه زدن در لیست پخش استفاده کنید. اگر کاربر برای یک آهنگ تک حلقه‌ای «بعدی» یا چیزی مشابه بگوید، آهنگ دوباره شروع می‌شود. برای لیست‌های پخش حلقه‌ای، کاربر با گفتن «بعدی» آهنگ بعدی را در فهرست پخش شروع می‌کند.

برای پیاده سازی حالت حلقه، فیلد 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"
        }
      }
    }
  ]
}