تخصيص إشعارات الوسائط وعناصر التحكّم في التشغيل باستخدام واجهة برمجة التطبيقات Media session API

كيفية الدمج مع مفاتيح الوسائط الخارجية وتخصيص إشعارات الوسائط وغير ذلك

François Beaufort

السماح للمستخدمين بمعرفة المحتوى الذي يتم تشغيله حاليًا في المتصفّح والتحكّم فيه بدون الرجوع إلى الصفحة التي أطلقتها، فقد تم إطلاق Media Session API المقدمة. وهي تتيح لمطوّري الويب تخصيص هذه التجربة من خلال البيانات الوصفية في إشعارات الوسائط المخصصة، وأحداث الوسائط مثل التشغيل، والإيقاف المؤقت، التقديم والترجيع وتتبّع التغيير وعقد اجتماعات الفيديو مثل كتم الصوت أو إعادة الصوت والميكروفون وتشغيل/إيقاف الكاميرا وإنهاء المكالمة. وتتميز هذه التخصيصات متوفرة في عدة سياقات، بما في ذلك مراكز وسائط الكمبيوتر المكتبي وإشعارات الوسائط وعلى الهاتف المحمول، وحتى على الأجهزة القابلة للارتداء. سأصف هذه التخصيصات في هذه المقالة.

لمحة عن واجهة برمجة التطبيقات لجلسات الوسائط

توفّر واجهة برمجة التطبيقات لجلسات الوسائط العديد من المزايا والإمكانات:

• تتوفّر مفاتيح الوسائط على الجهاز.
• يتم تخصيص إشعارات الوسائط على الأجهزة الجوّالة وأجهزة الكمبيوتر المكتبي والأجهزة القابلة للارتداء المقترنة.
• يتوفّر مركز الوسائط على أجهزة الكمبيوتر المكتبي.
• تتوفّر عناصر التحكّم في الوسائط على شاشة القفل على ChromeOS والأجهزة الجوّالة.
• تتوفّر عناصر التحكّم في نافذة "نافذة ضمن النافذة" لتشغيل الصوت، ومؤتمرات الفيديو وتقديم الشرائح.
• وتتوفّر إمكانية الدمج مع "مساعد Google" على الأجهزة الجوّالة.

ستوضح بعض الأمثلة بعض هذه النقاط.

المثال 1: إذا ضغط المستخدمون على "المقطع الصوتي التالي" ومفتاح الوسائط للوحة المفاتيح، يمكن لمطوّري البرامج على الويب معالجة إجراء المستخدم هذا سواء كان المتصفّح يعمل في المقدّمة. أو الخلفية.

المثال 2: إذا كان المستخدمون يستمعون إلى بودكاست على الويب أثناء استخدام أجهزتهم الشاشة مقفلة، فلا يزال بإمكانهم ضرب "الترجيع" رمز القفل عناصر التحكم في وسائط الشاشة حتى يتمكن مطورو الويب من إرجاع وقت التشغيل إلى الخلف بمقدار قليل ثوانٍ.

المثال 3: إذا كان لدى المستخدمين علامات تبويب لتشغيل الصوت، يمكنهم بسهولة إيقافها التشغيل من مركز الوسائط على سطح المكتب حتى يحصل مطورو الويب على فرصة مسح حالتهم.

مثال 4: إذا كان المستخدمون يجرون مكالمة فيديو، يمكنهم الضغط على "تبديل" ميكروفون عنصر التحكم في نافذة "نافذة ضمن النافذة" لمنع موقع الويب من تلقّي بيانات الميكروفون

يتم ذلك من خلال واجهتَين مختلفتَين: واجهة MediaSession وواجهة MediaMetadata. الأولى تتيح للمستخدمين التحكم في كل اللعب. والطريقة الثانية هي كيفية إخبار MediaSession بما يجب التحكّم فيه.

لتوضيح ذلك، توضح الصورة التالية كيفية ارتباط هذه الواجهات بواجهات برمجة تطبيقات محددة عناصر التحكم في الوسائط، وهي في هذه الحالة إشعار بالوسائط على الهاتف المحمول.

السماح للمستخدمين بمعرفة ما يتم تشغيله

عندما يشغّل موقع إلكتروني الصوت أو الفيديو، يحصل المستخدمون على الوسائط تلقائيًا. الإشعارات إما في علبة الإشعارات على الهاتف الجوّال أو في مركز الوسائط على سطح المكتب. يبذل المتصفح قصارى جهده لعرض المعلومات المناسبة باستخدام عنوان المستند وأكبر صورة رمز يمكن العثور عليها. مع جلسة الوسائط من الممكن تخصيص إشعار الوسائط باستخدام بعض الوسائط الغنية البيانات الوصفية مثل العنوان واسم الفنان واسم الألبوم والعمل الفني، كما هو موضّح أدناه.

يطلب Chrome تفعيل "الخيار الكامل" التركيز الصوتي لعرض إشعارات الوسائط فقط عند مدة الوسائط لا تقل عن 5 ثوانٍ. يضمن ذلك رصد الأصوات العرضية مثل الإشعارات لا تعرض الإشعارات.

// After media (video or audio) starts playing
await document.querySelector("video").play();

if ("mediaSession" in navigator) {
  navigator.mediaSession.metadata = new MediaMetadata({
    title: 'Never Gonna Give You Up',
    artist: 'Rick Astley',
    album: 'Whenever You Need Somebody',
    artwork: [
      { src: 'https://via.placeholder.com/96',   sizes: '96x96',   type: 'image/png' },
      { src: 'https://via.placeholder.com/128', sizes: '128x128', type: 'image/png' },
      { src: 'https://via.placeholder.com/192', sizes: '192x192', type: 'image/png' },
      { src: 'https://via.placeholder.com/256', sizes: '256x256', type: 'image/png' },
      { src: 'https://via.placeholder.com/384', sizes: '384x384', type: 'image/png' },
      { src: 'https://via.placeholder.com/512', sizes: '512x512', type: 'image/png' },
    ]
  });

  // TODO: Update playback state.
}

عند انتهاء التشغيل، لا داعي "للإصدار" جلسة الوسائط على أنها سيختفي تلقائيًا. ضع في اعتبارك أن سيتم استخدام navigator.mediaSession.metadata عند بدء عملية التشغيل التالية. رغم ذلك. ولهذا السبب من المهم تعديلها عند استخدام مصدر تشغيل الوسائط التغييرات للتأكد من عرض المعلومات ذات الصلة في إشعار الوسائط.

هناك بعض النقاط التي يجب مراعاتها حول بيانات التعريف للوسائط.

• تتوافق مصفوفة العمل الفني للإشعارات مع عناوين URL لملفات الكائن الثنائي الكبير (blob) وعناوين URL للبيانات.
• إذا لم يتم تحديد أي عمل فني وكانت هناك صورة رمز (تم تحديدها باستخدام <link rel=icon>) بالحجم المطلوب، ستستخدمها إشعارات الوسائط.
• حجم العمل الفني المستهدف للإشعار في Chrome لنظام Android هو 512x512. بالنسبة الأجهزة المنخفضة المواصفات، هو 256x256.
• يتم استخدام السمة title لعنصر HTML للوسائط في عمود "يجري الآن تشغيل". تطبيق macOS المصغّر.
• إذا كان مورد الوسائط مضمّنًا (على سبيل المثال في إطار iframe)، فإن واجهة برمجة التطبيقات لجلسات الوسائط يجب تعيين المعلومات من السياق المضمن. اطّلِع على المقتطف أدناه.

<iframe id="iframe">
  <video>...</video>
</iframe>
<script>
  iframe.contentWindow.navigator.mediaSession.metadata = new MediaMetadata({
    title: 'Never Gonna Give You Up',
    ...
  });
</script>

يمكنك أيضًا إضافة معلومات عن فصول فردية، مثل عنوان القسم وطابعه الزمني وصورة لقطة شاشة إلى البيانات الوصفية للوسائط. يسمح هذا للمستخدمين بالتنقل عبر محتوى الوسائط.

navigator.mediaSession.metadata = new MediaMetadata({
  // title, artist, album, artwork, ...
  chapterInfo: [{
    title: 'Chapter 1',
    startTime: 0,
    artwork: [
      { src: 'https://via.placeholder.com/128', sizes: '128x128', type: 'image/png' },
      { src: 'https://via.placeholder.com/512', sizes: '512x512', type: 'image/png' },
    ]
  }, {
    title: 'Chapter 2',
    startTime: 42,
    artwork: [
      { src: 'https://via.placeholder.com/128', sizes: '128x128', type: 'image/png' },
      { src: 'https://via.placeholder.com/512', sizes: '512x512', type: 'image/png' },
    ]
  }]
});

السماح للمستخدمين بالتحكّم في المحتوى الذي يتم تشغيله

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

وبما أنّ بعض إجراءات جلسات الوسائط قد تكون غير متاحة، نقترح عليك سيتم استخدام حظر "try…catch" عند ضبطها.

const actionHandlers = [
  ['play',          () => { /* ... */ }],
  ['pause',         () => { /* ... */ }],
  ['previoustrack', () => { /* ... */ }],
  ['nexttrack',     () => { /* ... */ }],
  ['stop',          () => { /* ... */ }],
  ['seekbackward',  (details) => { /* ... */ }],
  ['seekforward',   (details) => { /* ... */ }],
  ['seekto',        (details) => { /* ... */ }],
  /* Video conferencing actions */
  ['togglemicrophone', () => { /* ... */ }],
  ['togglecamera',     () => { /* ... */ }],
  ['hangup',           () => { /* ... */ }],
  /* Presenting slides actions */
  ['previousslide', () => { /* ... */ }],
  ['nextslide',     () => { /* ... */ }],
];

for (const [action, handler] of actionHandlers) {
  try {
    navigator.mediaSession.setActionHandler(action, handler);
  } catch (error) {
    console.log(`The media session action "${action}" is not supported yet.`);
  }
}

إلغاء ضبط معالِج إجراء جلسة الوسائط أمر سهل مثل ضبطه على null.

try {
  // Unset the "nexttrack" action handler at the end of a playlist.
  navigator.mediaSession.setActionHandler('nexttrack', null);
} catch (error) {
  console.log(`The media session action "nexttrack" is not supported yet.`);
}

وبعد ضبط الإعدادات، ستستمر معالِجات إجراءات جلسة الوسائط خلال عمليات تشغيل الوسائط. يشبه ذلك نمط أداة معالجة الحدث باستثناء أنّ معالجة حدث معيَّن أن المتصفح يتوقف عن تنفيذ أي سلوك افتراضي ويستخدمه إلى أن الموقع الإلكتروني يدعم الإجراء الإعلامي. وبالتالي، تسمح عناصر التحكّم في الإجراءات على الوسائط ما لم يتم ضبط معالج الإجراء المناسب.

تشغيل / إيقاف مؤقت

يشير الإجراء "play" إلى أنّ المستخدم يريد استئناف تشغيل الوسائط. بينما يشير "pause" إلى الرغبة في إيقافه مؤقتًا.

"تشغيل/إيقاف مؤقت" الرمز دائمًا في إشعار الوسائط وما شابه يتم التعامل مع أحداث الوسائط تلقائيًا بواسطة المتصفح. لتجاوز الإعداد التلقائي سلوك، التعامل مع "تشغيل" و"إيقاف مؤقت" الوسائط كما هو موضح أدناه.

قد يعتبر المتصفح أنّ أحد المواقع الإلكترونية لا يشغّل الوسائط عند التقديم/الترجيع. التحميل على سبيل المثال. وفي هذه الحالة، يمكنك إلغاء هذا السلوك من خلال ضبط navigator.mediaSession.playbackState إلى "playing" أو "paused" للتأكد تظل واجهة مستخدم موقع الويب متزامنة مع عناصر التحكم في إشعارات الوسائط.

const video = document.querySelector('video');

navigator.mediaSession.setActionHandler('play', async () => {
  // Resume playback
  await video.play();
});

navigator.mediaSession.setActionHandler('pause', () => {
  // Pause active playback
  video.pause();
});

video.addEventListener('play', () => {
  navigator.mediaSession.playbackState = 'playing';
});

video.addEventListener('pause', () => {
  navigator.mediaSession.playbackState = 'paused';
});

المقطع الصوتي السابق

يشير الإجراء "previoustrack" إلى أنّ المستخدم يريد بدء عملية تشغيل الوسائط الحالية من البداية إذا كان تشغيل الوسائط يتضمن أو الانتقال إلى العنصر السابق في قائمة التشغيل إذا كان تشغيل الوسائط يتضمن مفهومًا لقائمة التشغيل.

navigator.mediaSession.setActionHandler('previoustrack', () => {
  // Play previous track.
});

المقطع الصوتي التالي

يشير الإجراء "nexttrack" إلى أنّ المستخدم يريد نقل تشغيل الوسائط إلى العنصر التالي في قائمة التشغيل إذا كان تشغيل الوسائط يتضمن مفهومًا لقائمة تشغيل.

navigator.mediaSession.setActionHandler('nexttrack', () => {
  // Play next track.
});

إيقاف

يشير الإجراء "stop" إلى أنّ المستخدم يريد إيقاف تشغيل الوسائط ومحو الحالة إذا لزم الأمر.

navigator.mediaSession.setActionHandler('stop', () => {
  // Stop playback and clear state if appropriate.
});

الترجيع / الأمام

يشير الإجراء "seekbackward" إلى أنّ المستخدم يريد نقل الوسائط. يتأخر وقت التشغيل بمقدار فترة قصيرة بينما يشير "seekforward" إلى الرغبة في لتقديم وقت تشغيل الوسائط لفترة قصيرة. في كلتا الحالتين، الفترة القصيرة يعني بضع ثوانٍ.

قيمة seekOffset المقدمة في معالج الإجراء هي الوقت بالثواني نقل وقت تشغيل الوسائط بواسطة. وإذا لم يتم توفيرها (على سبيل المثال، undefined)، يجب عندها يجب استخدام وقت معقول (على سبيل المثال، 10 إلى 30 ثانية).

const video = document.querySelector('video');
const defaultSkipTime = 10; /* Time to skip in seconds by default */

navigator.mediaSession.setActionHandler('seekbackward', (details) => {
  const skipTime = details.seekOffset || defaultSkipTime;
  video.currentTime = Math.max(video.currentTime - skipTime, 0);
  // TODO: Update playback state.
});

navigator.mediaSession.setActionHandler('seekforward', (details) => {
  const skipTime = details.seekOffset || defaultSkipTime;
  video.currentTime = Math.min(video.currentTime + skipTime, video.duration);
  // TODO: Update playback state.
});

التقديم إلى وقت محدّد

يشير الإجراء "seekto" إلى أنّ المستخدم يريد نقل ملف تشغيل الوسائط. الوقت إلى وقت محدد.

قيمة seekTime المقدمة في معالج الإجراء هي الوقت بالثواني نقل وقت تشغيل الوسائط إليه.

تكون القيمة المنطقية fastSeek المقدّمة في معالج الإجراء صحيحة إذا كان الإجراء يتم استدعاؤه عدة مرات كجزء من التسلسل، وهذا ليس آخر استدعاء بهذا التسلسل.

const video = document.querySelector('video');

navigator.mediaSession.setActionHandler('seekto', (details) => {
  if (details.fastSeek && 'fastSeek' in video) {
    // Only use fast seek if supported.
    video.fastSeek(details.seekTime);
    return;
  }
  video.currentTime = details.seekTime;
  // TODO: Update playback state.
});

ضبط موضع التشغيل

عرض موضع تشغيل الوسائط بدقة في الإشعار هو أمر بمنتهى البساطة كإعداد حالة الموضع في الوقت المناسب كما هو موضح أدناه. تشير رسالة الأشكال البيانية حالة الموضع هي مزيج من معدل تشغيل الوسائط والمدة الوقت الحالي.

يجب توفير المدة وأن تكون موجبة. يجب أن يكون الموضع إيجابيًا أقل من المدة. يجب أن يكون معدل التشغيل أكبر من 0.

const video = document.querySelector('video');

function updatePositionState() {
  if ('setPositionState' in navigator.mediaSession) {
    navigator.mediaSession.setPositionState({
      duration: video.duration,
      playbackRate: video.playbackRate,
      position: video.currentTime,
    });
  }
}

// When video starts playing, update duration.
await video.play();
updatePositionState();

// When user wants to seek backward, update position.
navigator.mediaSession.setActionHandler('seekbackward', (details) => {
  /* ... */
  updatePositionState();
});

// When user wants to seek forward, update position.
navigator.mediaSession.setActionHandler('seekforward', (details) => {
  /* ... */
  updatePositionState();
});

// When user wants to seek to a specific time, update position.
navigator.mediaSession.setActionHandler('seekto', (details) => {
  /* ... */
  updatePositionState();
});

// When video playback rate changes, update position state.
video.addEventListener('ratechange', (event) => {
  updatePositionState();
});

عملية إعادة ضبط حالة الموضع سهلة تمامًا مثل ضبطها على null.

// Reset position state when media is reset.
navigator.mediaSession.setPositionState(null);

إجراءات مؤتمرات الفيديو

عندما يضع المستخدم مكالمة الفيديو في نافذة "نافذة ضمن النافذة"، قد يعرض المتصفح عناصر تحكم في الميكروفون والكاميرا ولإنهاء الاتصال. وعندما ينقر المستخدم على تلك المقاطع، يتعامل معها الموقع الإلكتروني عبر الفيديو. لمكالمات الفيديو أدناه. على سبيل المثال، يُرجى الاطّلاع على نموذج لاجتماع فيديو.

تفعيل/إيقاف الميكروفون

يشير الإجراء "togglemicrophone" إلى أنّ المستخدم يريد كتم الصوت أو إعادته. الميكروفون. تُعلم الطريقة setMicrophoneActive(isActive) المتصفّح. ما إذا كان موقع الويب يعتبر أن الميكروفون نشطًا أم لا.

let isMicrophoneActive = false;

navigator.mediaSession.setActionHandler('togglemicrophone', () => {
  if (isMicrophoneActive) {
    // Mute the microphone.
  } else {
    // Unmute the microphone.
  }
  isMicrophoneActive = !isMicrophoneActive;
  navigator.mediaSession.setMicrophoneActive(isMicrophoneActive);
});

تبديل اتجاه الكاميرا

يشير الإجراء "togglecamera" إلى أنّ المستخدم يريد تفعيل الإجراء. الكاميرا أو إيقافها. تشير الطريقة setCameraActive(isActive) إلى ما إذا كان في المتصفح يعتبر الموقع الإلكتروني نشطًا.

let isCameraActive = false;

navigator.mediaSession.setActionHandler('togglecamera', () => {
  if (isCameraActive) {
    // Disable the camera.
  } else {
    // Enable the camera.
  }
  isCameraActive = !isCameraActive;
  navigator.mediaSession.setCameraActive(isCameraActive);
});

قطع الاتصال

يشير الإجراء "hangup" إلى أنّ المستخدم يريد إنهاء المكالمة.

navigator.mediaSession.setActionHandler('hangup', () => {
  // End the call.
});

إجراءات مشاركة العروض التقديمية

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

الشريحة السابقة

يشير الإجراء "previousslide" إلى أنّ المستخدم يريد الرجوع إلى الشريحة السابقة عند تقديم الشرائح.

navigator.mediaSession.setActionHandler('previousslide', () => {
  // Show previous slide.
});

الشريحة التالية

يشير الإجراء "nextslide" إلى أنّ المستخدِم يريد الانتقال إلى الشريحة التالية. عند تقديم الشرائح.

navigator.mediaSession.setActionHandler('nextslide', () => {
  // Show next slide.
});

نماذج

يمكنك الاطّلاع على بعض نماذج جلسات الوسائط التي تضمّ Blender Foundation. من أعمال "جان مورغنسترن"

الموارد

• مواصفات جلسة الوسائط: wicg.github.io/mediasession
• مشاكل في المواصفات: github.com/WICG/mediasession/issues
• أخطاء Chrome: crbug.com