Personnalisez les notifications multimédias et les commandes de lecture avec l'API Media Session

Comment intégrer les touches multimédias matérielles, personnaliser les notifications multimédias, et plus encore.

François Beaufort

Pour indiquer aux utilisateurs le contenu en cours de lecture dans leur navigateur et le contrôler sans revenir à la page qui l'a lancée, l'API Media Session présenté. Il permet aux développeurs Web de personnaliser cette expérience via les métadonnées dans les notifications multimédias personnalisées, les événements multimédias tels que la lecture, la mise en pause, rechercher, suivre les modifications et les événements de visioconférence (activation/désactivation du son, par exemple) ; allumer/éteindre la caméra et raccrocher. Ces personnalisations sont disponibles dans plusieurs contextes, y compris les hubs multimédias de bureau, les notifications multimédias sur mobile et même sur les accessoires connectés. Je vais décrire ces personnalisations dans cet article.

</ph>

À propos de l'API Media Session

L'API Media Session offre plusieurs avantages et fonctionnalités:

• Les touches multimédias matérielles sont compatibles.
• Les notifications multimédias sont personnalisées sur les appareils mobiles, les ordinateurs et les accessoires connectés associés.
• Le hub multimédia est disponible sur ordinateur.
• Les commandes multimédias de l'écran de verrouillage sont disponibles sur ChromeOS et sur mobile.
• Les commandes de fenêtre Picture-in-picture sont disponibles pour la lecture audio, visioconférence et présentation de diapositives.
• L'intégration de l'Assistant est disponible sur mobile.

Quelques exemples illustrent certains de ces points.

Exemple 1:Si l'utilisateur appuie sur le titre suivant touche multimédia de son clavier, les développeurs Web peuvent gérer cette action de l'utilisateur, que le navigateur soit au premier plan ; ou l'arrière-plan.

Exemple 2:Si les utilisateurs écoutent un podcast sur le Web avec leur appareil l'écran est verrouillé, il peut toujours appuyer sur la touche de retour arrière icône en forme de cadenas des commandes multimédias à l'écran pour permettre aux développeurs Web de reculer de quelques secondes secondes.

Exemple 3:Si les utilisateurs ont des onglets qui lisent du contenu audio, ils peuvent facilement arrêter à partir du hub multimédia sur un ordinateur de bureau, afin que les développeurs Web puissent effacer son état.

Exemple 4:Si les utilisateurs sont en communication vidéo, ils peuvent appuyer sur le bouton micro" dans la fenêtre Picture-in-picture pour empêcher le site Web recevoir les données du micro.

Tout cela s'effectue via deux interfaces différentes: l'interface MediaSession et l'interface MediaMetadata. Le premier permet aux utilisateurs de contrôler en cours de lecture. La seconde permet d'indiquer à MediaSession ce qui doit être contrôlé.

À titre d'illustration, l'image ci-dessous montre la relation entre ces interfaces et certaines des commandes multimédias, dans ce cas une notification multimédia sur mobile.

</ph>

Indiquez aux utilisateurs le contenu en cours de lecture

Lorsqu'un site Web lit du contenu audio ou vidéo, les utilisateurs obtiennent automatiquement des contenus multimédias soit dans la barre de notification de votre appareil mobile, soit dans le Media Hub sur ordinateur. Le navigateur s'efforce d'afficher les informations appropriées en utilisant les le titre du document et la plus grande image d'icône qu'il peut trouver. Avec la session multimédia il est possible de personnaliser la notification multimédia en y ajoutant des éléments multimédias comme le titre, le nom de l'artiste, le nom de l'album et la pochette, comme indiqué ci-dessous.

Chrome demande l'état "complet" sélection audio pour n'afficher les notifications multimédias la durée du contenu multimédia est d'au moins cinq secondes. Cela garantit que les sons accessoires comme les alertes, n'affichent pas de notifications.

// 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.
}

À la fin de la lecture, il n'est pas nécessaire de "relâcher" la session multimédia en tant que par défaut disparaîtra automatiquement. Gardez à l'esprit que navigator.mediaSession.metadata sera utilisé lorsque la prochaine lecture commencera par contre. C'est pourquoi il est important de le mettre à jour lorsque la source de lecture les modifications pour que les informations pertinentes s'affichent dans la notification multimédia.

Quelques points à noter concernant les métadonnées des contenus multimédias.

• Le tableau des illustrations de notification prend en charge les URL de blob et les URL de données.
• Si aucune illustration n'est définie et qu'il existe une image d'icône (spécifiée à l'aide de <link rel=icon>) de la taille souhaitée, les notifications multimédias l'utilisent.
• La taille cible de l'illustration de notification dans Chrome pour Android est de 512x512. Pour sur les appareils d'entrée de gamme, elle est de 256x256.
• L'attribut title de l'élément HTML multimédia est utilisé dans la commande "En écoute". Widget macOS.
• Si la ressource multimédia est intégrée (dans un iFrame, par exemple), l'API Media Session les informations doivent être définies à partir du contexte intégré. Voir l'extrait ci-dessous.

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

Vous pouvez également ajouter des informations sur chaque chapitre, comme le titre de la section, son code temporel et une capture d'écran aux métadonnées multimédias. Cela permet aux utilisateurs de parcourir le contenu du média.

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' },
    ]
  }]
});

</ph>

Permettez aux utilisateurs de contrôler la lecture

Une action de session multimédia est une action (par exemple, "lire" ou "mettre en pause") qu'un site Web peut pour les utilisateurs lorsqu'ils interagissent avec la lecture multimédia en cours. Les actions sont sont analogues et fonctionnent à peu près de la même manière que les événements. Comme les événements, les actions implémentés en définissant des gestionnaires sur un objet approprié, une instance de MediaSession, dans ce cas. Certaines actions sont déclenchées lorsque l'utilisateur appuie sur les boutons d'un casque, d'un autre appareil distant ou d'un clavier, ou d'interagir avec notification multimédia.

</ph>

Étant donné que certaines actions de session multimédia peuvent ne pas être prises en charge, nous vous recommandons de utilisez un bloc try…catch lorsque vous les configurez.

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

Pour désactiver un gestionnaire d'actions de session multimédia, il suffit de le définir sur 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.`);
}

Une fois définis, les gestionnaires d'actions de session multimédia sont conservés pendant les lectures de contenus multimédias. Ce modèle est semblable au modèle de l'écouteur d'événements, à la différence près que le traitement d'un événement le navigateur cesse de fonctionner par défaut et l'utilise comme une indiquent que le site Web accepte l'action multimédia. D'où les commandes des actions multimédias ne s'affiche que si le gestionnaire d'actions approprié est défini.

</ph>

Lecture / Pause

L'action "play" indique que l'utilisateur souhaite reprendre la lecture du contenu multimédia. tandis que "pause" indique que vous souhaitez l'interrompre temporairement.

Les options de lecture/pause s'affiche toujours dans une notification multimédia et les les événements multimédias sont gérés automatiquement par le navigateur. Pour remplacer les valeurs par défaut et le comportement de lecture, et "pause" actions multimédias, comme indiqué ci-dessous.

Le navigateur peut considérer qu'un site Web ne lit pas de contenu multimédia lorsqu'il recherche ou en cours de chargement. Dans ce cas, vous pouvez ignorer ce comportement en définissant navigator.mediaSession.playbackState à "playing" ou "paused" pour vous en assurer l'UI du site web reste synchronisée avec les commandes de notification multimédia.

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

Titre précédent

L'action "previoustrack" indique que l'utilisateur souhaite démarrer l'activité la lecture du contenu multimédia en cours depuis le début si la notion de commencer, ou passer à l'élément précédent de la playlist si la lecture comporte la notion de playlist.

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

Titre suivant

L'action "nexttrack" indique que l'utilisateur souhaite déplacer la lecture du contenu multimédia vers l'élément suivant de la playlist si la lecture du contenu multimédia comporte la notion de playlist.

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

Arrêter

L'action "stop" indique que l'utilisateur souhaite arrêter la lecture du contenu multimédia et supprimer l'état, le cas échéant.

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

Avancer / rembobiner

L'action "seekbackward" indique que l'utilisateur souhaite déplacer le contenu multimédia. le temps de lecture en arrière de courte période, tandis que "seekforward" indique que vous souhaitez pour avancer brièvement la lecture des contenus multimédias. Dans les deux cas, une courte période signifie quelques secondes.

La valeur seekOffset fournie dans le gestionnaire d'actions correspond au temps nécessaire (en secondes) pour le temps de lecture des contenus multimédias. Si elle n'est pas fournie (par exemple, undefined), alors Choisissez un intervalle de temps raisonnable (par exemple, 10 à 30 secondes).

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

Rechercher une heure spécifique

L'action "seekto" indique que l'utilisateur souhaite déplacer la lecture du contenu multimédia à une heure précise.

La valeur seekTime fournie dans le gestionnaire d'actions correspond au temps nécessaire (en secondes) pour déplacer la durée de lecture des contenus multimédias.

La valeur booléenne fastSeek fournie dans le gestionnaire d'actions est "true" si l'action est plusieurs fois dans le cadre d'une séquence, alors que ce n'est pas le dernier appel dans cette séquence.

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

Définir la position de lecture

Pour afficher avec précision la position de lecture d'un contenu multimédia dans une notification, rien de plus simple : comme définir l'état de la position à un moment approprié, comme indiqué ci-dessous. La l'état de la position combine la vitesse de lecture d'un contenu multimédia, sa durée l'heure actuelle.

</ph>

La durée doit être une valeur positive. La position doit être positive et inférieure à la durée. La vitesse de lecture doit être supérieure à 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();
});

Pour réinitialiser l'état de la position, il vous suffit de le définir sur null.

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

Actions de visioconférence

Lorsque l'utilisateur passe son appel vidéo dans une fenêtre Picture-in-picture, le navigateur peut afficher les commandes du micro et de la caméra, et de raccrocher. Lorsque l'utilisateur clique dessus, le site Web les gère tout au long de la vidéo les actions de conférence ci-dessous. Pour obtenir un exemple, consultez l'exemple de visioconférence.

</ph>

Activer/Désactiver le micro

L'action "togglemicrophone" indique que l'utilisateur souhaite couper ou réactiver le son le microphone. La méthode setMicrophoneActive(isActive) indique au navigateur si le site Web considère actuellement le micro comme actif.

let isMicrophoneActive = false;

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

Activer/Désactiver la caméra

L'action "togglecamera" indique que l'utilisateur souhaite activer la caméra. La méthode setCameraActive(isActive) indique si le navigateur considère le site Web comme actif.

let isCameraActive = false;

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

Raccrocher

L'action "hangup" indique que l'utilisateur souhaite mettre fin à un appel.

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

Actions de présentation de diapositives

Lorsque l'utilisateur place sa présentation de diapositives dans une fenêtre Picture-in-picture, le navigateur peut afficher des commandes de navigation dans les diapositives. Lorsque l'utilisateur clique dessus, le site Web les gère via l'API Media Session. Pour une consultez l'exemple de présentation Slides.

Diapositive précédente

L'action "previousslide" indique que l'utilisateur souhaite revenir à la diapositive précédente lors de la présentation.

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

Diapositive suivante

L'action "nextslide" indique que l'utilisateur souhaite passer à la diapositive suivante. lors de la présentation de diapositives.

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

Exemples

Consultez des exemples de sessions multimédias sur Blender Foundation et Œuvres de Jan Morgenstern.

Ressources

• Spécification de la session multimédia: wicg.github.io/mediasession
• Problèmes de spécifications: github.com/WICG/mediasession/issues
• Bugs Chrome: crbug.com