Comment intégrer les touches multimédias matérielles, personnaliser les notifications multimédias, et plus encore.
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 type="x-smartling-placeholder">![Captures d'écran des contextes de sessions multimédias](https://web.dev/static/articles/media-session/image/screenshots-media-sessio-f4629fe9ea633.jpg?authuser=19&hl=fr)
À 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.
Navigateurs pris en charge
-
<ph type="x-smartling-placeholder">
-
<ph type="x-smartling-placeholder">
-
<ph type="x-smartling-placeholder">
-
<ph type="x-smartling-placeholder">
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 type="x-smartling-placeholder">![Illustration des interfaces de sessions multimédias.](https://web.dev/static/articles/media-session/image/media-session-interfaces-c7bc0962a921c.jpg?authuser=19&hl=fr)
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 de256x256
. - 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' },
]
}]
});
![Informations sur les chapitres affichées dans une notification multimédia ChromeOS.](https://web.dev/static/articles/media-session/image/screenshot-notification-chapter.jpg?authuser=19&hl=fr)
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.
![Capture d'écran d'une notification multimédia sous Windows 10.](https://web.dev/static/articles/media-session/image/screenshot-a-media-notif-0b640cbe50bb1.jpg?authuser=19&hl=fr)
É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 type="x-smartling-placeholder">![Capture d'écran du widget En écoute dans macOS Big Sur.](https://web.dev/static/articles/media-session/image/screenshot-the-playing-178373d8aea09.jpg?authuser=19&hl=fr)
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 type="x-smartling-placeholder">![Capture d'écran des commandes multimédias de l'écran de verrouillage dans ChromeOS.](https://web.dev/static/articles/media-session/image/screenshot-lock-screen-m-e71582de5ca3d.jpg?authuser=19&hl=fr)
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 type="x-smartling-placeholder">![Capture d'écran des commandes de visioconférence dans une fenêtre Picture-in-picture.](https://web.dev/static/articles/media-session/image/screenshot-video-confere-7e82acef00cdb.jpg?authuser=19&hl=fr)
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.
});
Navigateurs pris en charge
-
<ph type="x-smartling-placeholder">
-
<ph type="x-smartling-placeholder">
-
<ph type="x-smartling-placeholder">
-
<ph type="x-smartling-placeholder">
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.
});
Navigateurs pris en charge
-
<ph type="x-smartling-placeholder">
-
<ph type="x-smartling-placeholder">
-
<ph type="x-smartling-placeholder">
-
<ph type="x-smartling-placeholder">
Exemples
Consultez des exemples de sessions multimédias sur Blender Foundation et Œuvres de Jan Morgenstern.
<ph type="x-smartling-placeholder">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