Media Session API: controles e intención

Media Session API permite describir el contenido activo y recibir controles mediados por el navegador, como reproducir, pausar, buscar y cambiar de pista. Son señales útiles de interacción, pero no prueban autorización, una tarjeta en la pantalla bloqueada ni una decisión humana. BotBrowser puede repetir un fixture sintético autorizado y revisar estados propios de la página; no puede fabricar una tecla de auriculares ni garantizar una notificación del sistema operativo. El contrato debe unir una tarea de medios declarada, sus controles y una alternativa visible.

La especificación Media Session de W3C define metadatos, manejadores, estado de reproducción y posición. La referencia Media Session API de MDN y la guía de Chrome muestran patrones de integración, no una promesa de soporte uniforme.

TL;DR

• Inicia una sesión solo para una tarea de medios visible y propia de la página.
• Trata navigator.mediaSession.metadata, playbackState, los manejadores y el estado de posición como campos separados.
• Registra solo acciones que el reproductor pueda completar, elimina manejadores al terminar y conserva botones dentro de la página.
• Valida duration, position y playbackRate antes de setPositionState().
• Registra resultados reducidos como pause-requested o unsupported, nunca identidad, URLs privadas o datos de cuenta.

Contenido

• Definir la tarea y los metadatos
• Registrar manejadores alrededor de la intención
• Mantener estados veraces
• Limpiar controles y conservar alternativas
• Registrar un fixture mínimo
• Leer resultados sin exagerar
• Conclusión práctica

Definir la tarea y los metadatos

Crea la sesión para una tarea concreta: un episodio, una vista previa o una lista aprobada. Debe existir un título visible, un control de reproducción y una forma clara de detener o cambiar antes de escribir metadatos. navigator.mediaSession.metadata es presentación, no un registro de identidad. Usa solo title, artist, album, albumArtist y artwork necesarios; no incluyas correos, tokens, URLs firmadas ni etiquetas ocultas.

El componente dueño del elemento multimedia debe controlar la pista, la revisión de metadatos y mediaSession.playbackState. Una respuesta tardía debe ignorarse si trackId ya cambió. Define estados pequeños como idle, intent-recorded, playing, paused, ended, action-rejected, unsupported y stale. playing significa que el elemento inició reproducción, no que una persona escuchó.

La guía de Web Audio API trata grafos y micrófono; Media Session describe una tarea de reproducción. No conviertas una acción en permiso de micrófono.

Registrar manejadores alrededor de la intención

setActionHandler() conecta comandos mediados por el navegador con funciones propias. Acciones habituales son play, pause, seekbackward, seekforward, previoustrack y nexttrack; el soporte varía. Registra solo acciones implementadas. Verifica trackId dentro de cada callback y elimina manejadores con navigator.mediaSession.setActionHandler(action, null) cuando termine la tarea.

El callback es una solicitud, no una autorización. Ejecuta media.play() o media.pause() según la política, captura promesas rechazadas y actualiza la interfaz solo después del evento real. No marques playing porque el callback se ejecutó. La guía de intención del usuario para Clipboard API aplica el mismo límite a una solicitud mediada por el navegador.

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

El fixture usa media-17 y episode-04, no envía audio ni datos de cuenta. Para buscar, limita el desplazamiento al intervalo válido y registra unsupported si la acción no existe.

Mantener estados veraces

playbackState acepta none, paused o playing. Actualízalo desde eventos reales. setPositionState({ duration, position, playbackRate }) requiere duración finita mayor que 0, posición entre 0 y duration y velocidad finita mayor que 0; omite la llamada para una transmisión sin duración. La API no prueba búfer, reloj ni que alguien oyera cada cuadro.

Actualiza en timeupdate, al terminar una búsqueda y al cambiar de pista, usando una positionRevision para descartar muestras tardías. La tabla separa observación del navegador y resultado de producto:

Observación	Estado propio	Respuesta segura
Falta mediaSession	unsupported	Mantener botones de la página
play resuelve	play-complete	Establecer playbackState: 'playing'
play rechaza	play-rejected	Mantener pausado y permitir reintento
pause tras el final	stale	No iniciar la siguiente pista
Posición inválida	position-skipped	Omitir hasta la próxima muestra válida

La tabla no afirma que un sistema operativo mostró un botón ni que alguien actuó. La guía de Web Share API aplica la misma separación.

Limpiar controles y conservar alternativas

En ended, cambio de ruta, cierre de sesión o parada explícita, pausa el elemento, limpia metadata, asigna none, elimina manejadores y libera referencias. La limpieza debe ser idempotente. Conserva botones etiquetados para reproducir, pausar, anterior, siguiente y buscar, además de un estado vivo como paused, playing, ended o play-rejected.

No uses una acción para eludir consentimiento, autoplay, pago o comprobaciones de cuenta. Registra intent-recorded tras un clic visible y luego instala metadatos. Si cambia la ruta mientras una promesa está pendiente, marca stale y evita que una resolución tardía cambie la nueva ruta.

Registrar un fixture mínimo

Permite solo fixtureId, action, state, positionState, fallback, browserVersion y context. Conserva positionState como valid, skipped o not-applicable, no una línea temporal completa. Repite el fixture con API disponible, ausente, play() rechazado y limpieza durante una acción pendiente.

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

El registro excluye título, artista, artwork, cuenta y URL completa. Una fila reducida muestra la rama sin convertirse en historial de escucha.

Leer resultados sin exagerar

BotBrowser puede repetir el fixture autorizado, inspeccionar estado visible y comparar manejadores. No puede crear un evento físico de auriculares, forzar una tarjeta de bloqueo, garantizar una notificación ni probar que alguien escuchó. Si falta mediaSession, verifica la alternativa. Si el estado dice playing mientras el elemento está pausado, corrige la propiedad antes de revisar la plataforma.

Los metadatos pueden revelar intereses fuera de la página. Usa etiquetas aprobadas para vistas sensibles, evita artwork con texto privado y no combines Media Session con fuentes, dispositivos o permisos para puntuar a una persona.

Sources

• Media Session, W3C
• Media Session API, MDN
• MediaSession.setActionHandler(), MDN
• MediaSession.setPositionState(), MDN
• Media Session, Chrome for Developers
• BotBrowser automation consistency

Conclusión práctica

Vincula metadatos y controles a una tarea de medios visible y propia. Registra solo acciones implementadas, valida estados, limpia durante el desmontaje y conserva controles accesibles dentro de la página. Guarda resultados acotados, no historial de escucha. BotBrowser puede repetir la interacción sintética; la intención humana y la presentación del sistema quedan fuera de la prueba.