בעזרת ה-Media Session API, אפשר להתאים אישית את ההתראות של המדיה ואת פקדי ההפעלה

איך לשלב עם מקשי מדיה פיזיים, להתאים אישית התראות מדיה ועוד.

פרנסואה בופורט

GitHub

כדי לאפשר למשתמשים לדעת מה מופעל כרגע בדפדפן ולשלוט בו, מבלי לחזור לדף שבו הוא הופעל, השקנו את Media Session API. הוא מאפשר למפתחי אינטרנט להתאים אישית את החוויה הזו באמצעות מטא-נתונים בהתראות מדיה מותאמות אישית, אירועי מדיה כמו הפעלה, השהיה, חיפוש, שינוי מסלול ואירועים של שיחות ועידה בווידאו כמו השתקה/ביטול השתקה של המיקרופון, הפעלה/כיבוי של המצלמה וניתוק. ההתאמות האישיות האלה זמינות בכמה הקשרים, כולל רכזות מדיה במחשב, התראות מדיה בנייד ואפילו במכשירים לבישים. במאמר הזה נתאר את ההתאמות האישיות האלה.

מרכז המדיה במחשב, התראות מדיה בנייד ובמכשיר לביש.

מידע על ה-Media Session API

ל-Media session API יש מספר יתרונות ויכולות:

• יש תמיכה במקשי מדיה של חומרה.
• התראות מדיה מותאמות אישית בנייד, במחשב ובמכשירים לבישים מותאמים.
• מרכז המדיה זמין במחשב.
• בקרי מדיה של מסך הנעילה זמינים ב-ChromeOS ובנייד.
• אפשר להשתמש באמצעי הבקרה על החלון במצב 'תמונה בתוך תמונה' להפעלת אודיו, לשיחות ועידה בווידאו ולהצגת שקפים.
• השילוב עם Assistant בנייד זמין.

תמיכה בדפדפן

• 73
• 79
• 82
• 15

מקור

הנה כמה דוגמאות להמחשת חלק מהנקודות האלה.

דוגמה 1: אם המשתמשים לוחצים על מקש המדיה "next Track" במקלדת, מפתחי אתרים יכולים לטפל בפעולת המשתמש הזו גם אם הדפדפן נמצא בחזית וגם ברקע.

דוגמה 2: אם משתמשים מאזינים לפודקאסט באינטרנט כשמסך המכשיר נעול, הם עדיין יכולים ללחוץ על סמל הדילוג לאחור בפקדי המדיה במסך הנעילה, כדי שמפתחי האינטרנט יזיזו את זמן ההפעלה אחורה בכמה שניות.

דוגמה 3: אם למשתמשים יש כרטיסיות שמשמיעות אודיו, הם יכולים בקלות להפסיק את ההפעלה ממרכז המדיה במחשב, כדי שמפתחי אינטרנט יוכלו לתקן את המצב.

דוגמה 4:אם המשתמשים בשיחת וידאו, הם יכולים ללחוץ על לחצן החלפת המצב של המיקרופון בחלון 'תמונה בתוך תמונה' כדי למנוע מהאתר לקבל את נתוני המיקרופון.

כל זה מתבצע דרך שני ממשקים שונים: הממשק MediaSession והממשק MediaMetadata. הראשונה מאפשרת למשתמשים לשלוט במה שמופעל. השיטה השנייה מאפשרת לך להגיד לMediaSession מה צריך לשלוט.

לצורך המחשה, התמונה הבאה ממחישה את הקשר בין הממשקים האלה לאמצעי בקרה ספציפיים של מדיה, במקרה הזה, התראת מדיה בנייד.

המבנה של התראת מדיה בנייד.

ליידע את המשתמשים מה מופעל

כשאתר מפעיל אודיו או וידאו, המשתמשים מקבלים התראות מדיה באופן אוטומטי במגש ההתראות בנייד או במרכז המדיה במחשב. הדפדפן עושה כמיטב יכולתו כדי להציג את המידע המתאים באמצעות כותרת המסמך ותמונת הסמל הגדולה ביותר שהוא יכול למצוא. באמצעות ה-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 של blob ובכתובות URL של נתונים.
• אם לא הוגדרה גרפיקה ומופיעה תמונת סמל (שצוין באמצעות <link rel=icon>) בגודל הרצוי, המערכת תשתמש בה לקבלת התראות מדיה.
• גודל היעד לגרפיקה של התראות ב-Chrome ל-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>

המשתמשים יכולים לשלוט במה שמופעל

פעולה של ביקור במדיה היא פעולה (לדוגמה, 'הפעלה' או 'השהיה') שאתר יכול לטפל בה עבור משתמשים כשהם מקיימים אינטראקציה עם הפעלת המדיה הנוכחית. הפעולות דומות לאירועים ופועלות באותו אופן. בדומה לאירועים, כדי להטמיע פעולות, צריך להגדיר רכיבי handler לאובייקט מתאים – במקרה הזה, מופע של MediaSession. חלק מהפעולות מתבצעות כשמשתמשים לוחצים על לחצנים באוזניות, במכשיר מרוחק אחר, במקלדת או אינטראקציה עם התראת מדיה.

התראה על מדיה בהתאמה אישית ב-Windows 10.

יכול להיות שחלק מהפעולות בסשן מדיה לא נתמכות, לכן מומלץ להשתמש בבלוק 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.`);
  }
}

קל מאוד לבטל את ההגדרה של handler לפעולות של סשן מדיה, כמו להגדיר אותו לערך 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.`);
}

לאחר ההגדרה, רכיבי ה-handler של הפעולות בסשן המדיה ימשיכו לפעול בכל הפעלות של מדיה. הדבר דומה לדפוס event listener, למעט העובדה שהטיפול באירוע פירושו שהדפדפן מפסיק לבצע התנהגות ברירת מחדל ומשתמש בה כאות לכך שהאתר תומך בפעולה במדיה. לכן, פקדי פעולות במדיה לא יוצגו, אלא אם יוגדר ה-handler המתאים לפעולות.

הווידג'ט 'מה שומעים עכשיו?' ב-macOS Big Sur.

הפעלה / השהיה

הפעולה "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 שסופק ב-handler של הפעולות הוא הזמן בשניות שצריך להעביר את זמן ההפעלה של המדיה. אם הוא לא צוין (לדוגמה, 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 שסופק ב-handler של הפעולות הוא הזמן בשניות להעברת זמן ההפעלה של המדיה.

הערך הבוליאני fastSeek שסופק ב-handler של הפעולות הוא TRUE אם הפעולה מופעלת מספר פעמים כחלק מרצף, וזו לא הקריאה האחרונה ברצף הזה.

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.
});

הגדרת מיקום ההפעלה

הצגה מדויקת של מיקום ההפעלה של המדיה בהתראה היא פשוטה כמו הגדרת מצב המיקום בזמן המתאים, כפי שמתואר בהמשך. מצב המיקום הוא שילוב של קצב ההפעלה של המדיה, משך הזמן והזמן הנוכחי.

בקרות מדיה של מסך הנעילה ב-ChromeOS.

יש לציין משך זמן חיובי. המיקום צריך להיות חיובי וקצר ממשך הזמן. קצב ההפעלה חייב להיות גדול מ-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);

פעולות בשיחות ועידה בווידאו

כשהמשתמש מעביר את שיחת הווידאו לחלון של תמונה בתוך תמונה, הדפדפן עשוי להציג פקדים לשליטה במיקרופון ובמצלמה ולניתוק. כשהמשתמש לוחץ על הלחצנים האלה, האתר מטפל בהם בפעולות של שיחת הוועידה בווידאו שמפורטות בהמשך. לדוגמה, אפשר לעיין בדוגמה של שיחת ועידה בווידאו.

הפקדים של שיחת הוועידה בווידאו בחלון 'תמונה בתוך תמונה'.

שימו לב: בזמן הכתיבה, הפעולות של שיחת הוועידה בווידאו זמינות רק ב-Chrome 92 במחשב.

החלפת מצב המיקרופון

הפעולה "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.
});

הצגת פעולות ב-Slides

כשהמשתמש מעביר את מצגת השקפים לחלון תמונה בתוך תמונה, ייתכן שהדפדפן יציג פקדים לניווט בשקפים. כשהמשתמש לוחץ עליהם, האתר מטפל בהם דרך ה-Media Session API. לדוגמה, ראו הצגת הדוגמה של Slides.

לכרטיס הקודם

הפעולה "previousslide" מציינת שהמשתמש רוצה לחזור לשקף הקודם במהלך הצגת השקפים.

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

תמיכה בדפדפן

• 111
• 111
• x
• x

לכרטיס הבא

הפעולה "nextslide" מציינת שהמשתמש רוצה לעבור לשקף הבא במהלך הצגת השקפים.

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

תמיכה בדפדפן

• 111
• 111
• x
• x

טעימות

אתם מוזמנים להיעזר בדוגמאות של סשנים של מדיה בהשתתפות Blender Foundation ועבודה של יאן מורגנסטרן.

הקלטת מסך שממחישה את ה-Media Session API.

משאבים

• מפרט של סשן מדיה: wicg.github.io/mediasession
• בעיות במפרט: github.com/WICG/mediasession/issues
• באגים של Chrome : crbug.com