اعلان‌های رسانه و کنترل‌های پخش را با Media Session API سفارشی کنید

نحوه ادغام با کلیدهای رسانه سخت افزاری، سفارشی کردن اعلان های رسانه و موارد دیگر.

François Beaufort

برای اینکه کاربران بدانند چه چیزی در حال حاضر در مرورگر آنها در حال پخش است و کنترل آن بدون بازگشت به صفحه ای که آن را راه اندازی کرده است، Media Session API معرفی شده است. این به توسعه دهندگان وب اجازه می دهد تا این تجربه را از طریق ابرداده در اعلان های رسانه سفارشی، رویدادهای رسانه ای مانند پخش، مکث، جستجو، تغییر ردیابی و رویدادهای کنفرانس ویدیویی مانند قطع/لغو صدای میکروفون، روشن/خاموش کردن دوربین، و قطع تماس سفارشی کنند. این سفارشی‌سازی‌ها در زمینه‌های مختلفی از جمله مرکز رسانه دسک‌تاپ، اعلان‌های رسانه در تلفن همراه و حتی در دستگاه‌های پوشیدنی در دسترس هستند. من این سفارشی سازی ها را در این مقاله شرح خواهم داد.

درباره Media Session API

Media session API چندین مزیت و قابلیت را ارائه می دهد:

• کلیدهای رسانه ای سخت افزاری پشتیبانی می شوند.
• اعلان‌های رسانه در تلفن همراه، دسک‌تاپ و دستگاه‌های پوشیدنی جفت شده سفارشی می‌شوند.
• مرکز رسانه روی دسکتاپ در دسترس است.
• کنترل‌های رسانه قفل صفحه در ChromeOS و تلفن همراه در دسترس هستند.
• کنترل‌های پنجره تصویر در تصویر برای پخش صدا ، کنفرانس ویدیویی و ارائه اسلاید در دسترس هستند.
• ادغام دستیار در تلفن همراه در دسترس است.

چند مثال برخی از این نکات را نشان خواهد داد.

مثال 1: اگر کاربران کلید رسانه "تراک بعدی" صفحه کلید خود را فشار دهند، توسعه دهندگان وب می توانند این عملکرد کاربر را چه مرورگر در پیش زمینه یا در پس زمینه باشد، انجام دهند.

مثال 2: اگر کاربران در حالی که صفحه دستگاهشان قفل است به یک پادکست در وب گوش دهند، همچنان می توانند نماد "جستجوی عقب" را از کنترل رسانه های صفحه قفل بزنند تا توسعه دهندگان وب زمان پخش را چند ثانیه به عقب برگردانند.

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

مثال 4: اگر کاربران در حال تماس ویدیویی هستند، می توانند کنترل "ضامن کردن میکروفون" را در پنجره تصویر در تصویر فشار دهند تا وب سایت از دریافت داده های میکروفون جلوگیری کند.

این همه از طریق دو رابط مختلف انجام می شود: رابط MediaSession و رابط MediaMetadata . اولین مورد به کاربران اجازه می دهد هر چیزی را که در حال پخش است کنترل کنند. دوم این است که چگونه به MediaSession بگویید چه چیزی باید کنترل شود.

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

به کاربران اطلاع دهید که چه چیزی در حال پخش است

هنگامی که یک وب‌سایت در حال پخش صدا یا تصویر است، کاربران به‌طور خودکار اعلان‌های رسانه را در سینی اعلان‌ها در تلفن همراه یا مرکز رسانه روی دسک‌تاپ دریافت می‌کنند. مرورگر تمام تلاش خود را می کند تا با استفاده از عنوان سند و بزرگترین تصویر نمادی که می تواند پیدا کند، اطلاعات مناسب را نشان دهد. با Media Session API، می‌توانید اعلان رسانه را با برخی فراداده‌های رسانه غنی‌تر مانند عنوان، نام هنرمند، نام آلبوم و آثار هنری مطابق شکل زیر سفارشی کنید.

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های حباب و URLهای داده پشتیبانی می کند.
• اگر هیچ اثر هنری تعریف نشده باشد و یک تصویر نماد (که با استفاده از <link rel=icon> مشخص شده است) در اندازه دلخواه وجود داشته باشد، اعلان‌های رسانه از آن استفاده خواهند کرد.
• اندازه هدف اثر هنری اعلان در Chrome for Android 512x512 است. برای دستگاه های ارزان قیمت، 256x256 است.
• ویژگی title عنصر HTML رسانه در ویجت macOS "در حال پخش" استفاده می شود.
• اگر منبع رسانه جاسازی شده باشد (مثلاً در یک iframe)، اطلاعات Media Session API باید از زمینه تعبیه شده تنظیم شود. قطعه زیر را ببینید.

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

به کاربران اجازه دهید آنچه را که در حال پخش است کنترل کنند

کنش جلسه رسانه کنشی است (به عنوان مثال "پخش" یا "مکث") که یک وب سایت می تواند برای کاربران در هنگام تعامل با پخش رسانه فعلی انجام دهد. کنش‌ها مشابه رویدادها هستند و تقریباً مانند رویدادها عمل می‌کنند. مانند رویدادها، اقدامات با تنظیم کننده ها بر روی یک شی مناسب، نمونه ای از 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.
});

ارائه اقدامات اسلاید

هنگامی که کاربر نمایش اسلایدهای خود را در یک پنجره تصویر در تصویر قرار می دهد، مرورگر ممکن است کنترل هایی را برای پیمایش در میان اسلایدها نمایش دهد. هنگامی که کاربر روی آنها کلیک می کند، وب سایت آنها را از طریق Media Session API مدیریت می کند. برای مثال، نمونه ارائه اسلایدها را ببینید.

اسلاید قبلی

عمل "previousslide" نشان می دهد که کاربر می خواهد هنگام ارائه اسلایدها به اسلاید قبلی برگردد.

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

اسلاید بعدی

عمل "nextslide" نشان می دهد که کاربر هنگام ارائه اسلایدها می خواهد به اسلاید بعدی برود.

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

نمونه ها

برخی از نمونه‌های Media Session را که شامل کارهای Blender Foundation و Jan Morgenstern است، بررسی کنید.

منابع

• مشخصات جلسه رسانه: wicg.github.io/mediasession
• مشکلات مشخصات: github.com/WICG/mediasession/issues
• اشکالات کروم: crbug.com