Media Session API : contrôles et intention utilisateur

Media Session API permet à une page de décrire un média actif et de recevoir des commandes médiées par le navigateur, comme lire, mettre en pause, avancer ou changer de piste. Ces commandes signalent une interaction, mais ne prouvent ni l’autorisation d’une personne, ni l’affichage d’une carte de verrouillage, ni l’acceptation d’une transaction distante. BotBrowser peut rejouer un fixture synthétique autorisé et inspecter les états de la page; il ne peut pas fabriquer une touche de casque ni garantir une notification du système. Ce guide relie les contrôles, l’état de lecture, la position et les replis à une tâche déclarée.

La spécification Media Session du W3C définit métadonnées, gestionnaires d’action, état et position. La référence MDN décrit les objets du navigateur et le guide Chrome montre des intégrations. Il s’agit d’un contrat d’interface, pas d’une promesse d’un comportement identique sur chaque plateforme.

Résumé

• Démarrez une session pour une tâche multimédia visible et possédée par la page.
• Séparez metadata, playbackState, les gestionnaires et l’état de position.
• N’enregistrez que les actions réalisables et retirez les gestionnaires obsolètes.
• Validez duration, position et playbackRate avant setPositionState().
• Conservez des résultats comme pause-requested ou unsupported, jamais les données privées de l’auditeur.

Sommaire

• Définir la tâche et les métadonnées
• Enregistrer les actions autour de l’intention
• Garder l’état et la position véridiques
• Retirer les contrôles et préserver les replis
• Enregistrer un fixture minimal
• Lire les résultats sans extrapoler
• Conclusion pratique

Définir La Tâche Et Les Métadonnées

Définissez une tâche concrète: lire un épisode, prévisualiser un cours ou écouter une liste approuvée. Un titre visible, un bouton de lecture et un arrêt clair doivent exister avant l’écriture des métadonnées. Un script au chargement qui affiche une pochette peut faire croire à une activité jamais demandée.

Utilisez navigator.mediaSession.metadata comme présentation, non comme identité. MediaMetadata peut contenir title, artist, album, albumArtist et artwork; gardez le minimum utile. N’insérez ni courriel, ni jeton, ni URL signée. Une URL d’image est aussi une donnée de page: choisissez une ressource approuvée ou omettez-la.

Le composant propriétaire de l’élément multimédia doit posséder la piste, la révision et playbackState. Ignorez une réponse réseau tardive si trackId a changé. L’article Web Audio et flux audio traite le graphe et le microphone; Media Session décrit la lecture et ne donne aucun accès au microphone.

Employez idle, intent-recorded, metadata-set, playing, paused, ended, action-rejected, unsupported et stale. playing signifie que l’élément a signalé le démarrage; il ne signifie pas qu’une personne a écouté.

Enregistrer Les Actions Autour De L’intention

setActionHandler() relie une commande du navigateur à une fonction de la page. Les actions courantes sont play, pause, seekbackward, seekforward, previoustrack et nexttrack. Enregistrez une action seulement si le lecteur sait la terminer. Une avance de file payante demande une règle produit explicite.

Créez un ensemble pour chaque tâche. Lors d’un changement de piste, vérifiez trackId; à la fin, retirez les gestionnaires avec navigator.mediaSession.setActionHandler(action, null) lorsque c’est accepté, effacez les métadonnées et placez playbackState à none. Un callback ancien ne doit pas piloter un nouvel élément.

Le callback est une demande et non une autorisation. Appelez media.play() ou media.pause(), capturez le rejet, puis mettez à jour le contrôle après l’état réel. Ne marquez pas la lecture simplement parce qu’une action est arrivée. Le guide Clipboard API sur l’intention utilisateur applique la même limite aux requêtes médiées par le navigateur.

const task = { fixtureId: 'media-17', trackId: 'episode-04', state: 'intent-recorded' };
const media = document.querySelector('#player');
function record(next) {
  task.state = next;
  document.querySelector('#status').textContent = next;
}
media.addEventListener('playing', () => {
  navigator.mediaSession.playbackState = 'playing';
  record('play-complete');
});
media.addEventListener('pause', () => {
  navigator.mediaSession.playbackState = 'paused';
  record('pause-complete');
});
media.addEventListener('error', () => record('play-rejected'));
navigator.mediaSession.metadata = new MediaMetadata({ title: 'Episode 04', artist: 'Fixture', album: 'Bounded test' });
navigator.mediaSession.setActionHandler('play', async () => {
  try {
    await media.play();
  } catch {
    record('play-rejected');
  }
});
navigator.mediaSession.setActionHandler('pause', () => {
  media.pause();
});

Garder L’état Et La Position Véridiques

playbackState accepte none, paused et playing; synchronisez-le avec les événements réels. Un rejet de play() ne doit jamais devenir playing. setPositionState({ duration, position, playbackRate }) demande une durée finie supérieure à 0, une position dans l’intervalle et une vitesse finie supérieure à 0. Pour un flux sans durée finie, omettez l’appel.

Mettez à jour lors de timeupdate, d’une recherche terminée ou d’un changement de piste, plutôt qu’à chaque image. Un positionRevision empêche une réponse retardée d’écraser la piste courante. La matrice sépare observation et décision:

Observation	État	Réponse
mediaSession absent	unsupported	Garder les boutons de page.
play aboutit	play-complete	Fixer playbackState: 'playing'.
play est rejeté	play-rejected	Garder la pause et le nouvel essai visible.
pause arrive après la fin	stale	Ne pas lancer automatiquement une autre piste.
Position invalide	position-skipped	Attendre un échantillon valide.

Le guide des limites de Web Share applique la même règle: un callback ne prouve ni consentement ni livraison.

Retirer Les Contrôles Et Préserver Les Replis

À la fin, au changement de route, à la déconnexion ou à l’arrêt, mettez en pause, effacez metadata, fixez playbackState à none, retirez les gestionnaires et libérez les références. Le nettoyage doit être idempotent. Conservez des boutons accessibles de lecture, pause, piste suivante et recherche, utilisables au clavier avec un statut paused, playing, ended ou play-rejected.

N’utilisez pas une action pour contourner autoplay, consentement, paiement ou contrôle de compte. Si un clic «Démarrer» est requis, enregistrez intent-recorded avant les métadonnées. Lors d’une navigation pendant play(), marquez l’essai stale et empêchez sa résolution de modifier la nouvelle route.

Enregistrer Un Fixture Minimal

Une ligne utile contient fixtureId, action, state, positionState, fallback, browserVersion et context. Excluez noms sensibles, octets d’image, comptes, URL complètes et exceptions entières. Répétez avec API absente, promesse rejetée et nettoyage pendant une action en attente.

{
  "fixtureId": "media-17",
  "action": "pause",
  "state": "pause-complete",
  "positionState": "valid",
  "fallback": "in-page-controls",
  "browserVersion": "156.0",
  "fixtureRevision": 3
}

Lire Les Résultats Sans Extrapoler

BotBrowser peut rejouer le fixture dans un contexte autorisé, comparer les états visibles et conserver les paramètres déclarés. Il ne peut pas créer une touche de casque, presser une touche système, forcer une carte de verrouillage ni prouver une écoute. Si mediaSession manque, vérifiez le repli; si une action n’actualise pas l’écran, inspectez la promesse et la révision du propriétaire. Cette capacité de répétition et cette limite de contrôle système sont propres à ce scénario Media Session.

Les métadonnées peuvent sortir de la page. Utilisez des libellés approuvés pour les aperçus sensibles et ne combinez pas titres, polices ou permissions pour noter une personne ou un appareil.

Sources

• Media Session, W3C
• Media Session API, MDN
• MediaSession.setActionHandler(), MDN
• MediaSession.setPositionState(), MDN
• Media Session, Chrome
• Cohérence d’automatisation BotBrowser

Conclusion pratique

Reliez les métadonnées et contrôles à une tâche visible et possédée par la page. Validez état et position, retirez les contrôles au nettoyage et gardez les boutons accessibles. Conservez des résultats bornés, pas un historique d’écoute. BotBrowser répète l’interaction synthétique; l’intention, l’affichage système et l’écoute réelle restent hors preuve.