Customize media notifications and playback controls with the Media Session API

Cómo integrarse con teclas de medios de hardware, personalizar notificaciones de medios y más.

6 de marzo de 2020
Updated 13 de agosto de 2020

Para que los usuarios sepan lo que se está reproduciendo actualmente en su browser y lo controlen sin volver a la página que lo inició, se ha introducido la API de sesión multimedia. Permite a los desarrolladores Web personalizar esta experiencia a través de metadata en notificaciones multimedia personalizadas y eventos multimedia como reproducción, pausa e incluso búsqueda y cambio de seguimiento. Estas personalizaciones están disponibles en varios contextos, incluidos centros de medios de escritorio, notificaciones de medios en dispositivos móviles e incluso en dispositivos portátiles. Describiré estas personalizaciones en este artículo.

Compatibilidad con varios browsers

En el momento de redactar este artículo, Chrome es el único navegador que admite la API de sesión multimedia tanto en computadoras de escritorio como en dispositivos móviles. Firefox tiene soporte parcial para la API Media Session en el escritorio detrás de una bandera, y Samsung Internet también tiene soporte parcial. Ver Browser compatibility
para obtener información actualizada.

La API de sesión de medios ofrece varios beneficios y capacidades:

• Se admiten claves de medios de hardware.
• Las notificaciones de medios se personalizan en dispositivos móviles, Chrome OS y dispositivos portátiles emparejados.
• the centro de medios está disponible en el escritorio.
• Los controles multimedia de la pantalla de bloqueo están disponibles en Sistema operativo Chrome y móvil.
• Están disponibles los controles de la ventana Picture-in-Picture.
• La integración del asistente en el móvil está disponible.

Algunos ejemplos ilustrarán algunos de estos puntos.

Ejemplo 1: Si los usuarios presionan la tecla multimedia «siguiente pista» de su teclado, los desarrolladores web pueden manejar esta acción del Username, already be que Chrome esté en primer plano o en segundo plano.

Ejemplo 2: Si los usuarios escuchan un podcast en la web mientras la pantalla de su dispositivo está bloqueada, aún pueden presionar el ícono «buscar hacia atrás» en los controles de medios de la pantalla de bloqueo para que los desarrolladores web muevan el tiempo de reproducción hacia atrás unos segundos.

Ejemplo 3: Si los usuarios tienen pestañas que reproducen audio, pueden detener fácilmente la reproducción desde el centro de medios en el escritorio para que los desarrolladores web tengan la oportunidad de borrar su estado.

Todo esto se hace a través de dos interfaces diferentes: MediaSession interfaz y el MediaMetadata interfaz. El primero permite a los usuarios controlar lo que esté jugando. El segundo es como dices MediaSession lo que necesita ser controlado.

A modo de ilustración, la siguiente imagen muestra cómo estas interfaces se relacionan con controles de medios específicos, en este caso, una notificación de medios en el móvil.

Deja que los usuarios sepan lo que suena

Cuando un sitio web reproduce audio o video, los usuarios reciben automáticamente notificaciones de medios, ya sea en la bandeja de notificaciones del dispositivo móvil o en el centro de medios del escritorio. Chrome hace todo lo posible para mostrar la información adecuada utilizando el título del documento y la imagen de icono más grande que puede encontrar. Con la API de sesión de medios, es posible personalizar la notificación de medios con algunos metadatos de medios más ricos, como el título, el nombre del artista, el nombre del álbum y las ilustraciones, como se muestra a continuación.

Chrome solicita el enfoque de audio «completo» para mostrar notificaciones de medios solo cuando la duración del medio es al menos 5 segundos. Esto asegura que los sonidos incidentales como los dings no muestren notificaciones.

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://dummyimage.com/96x96',   sizes: '96x96',   type: 'image/png' },
{ src: 'https://dummyimage.com/128x128', sizes: '128x128', type: 'image/png' },
{ src: 'https://dummyimage.com/192x192', sizes: '192x192', type: 'image/png' },
{ src: 'https://dummyimage.com/256x256', sizes: '256x256', type: 'image/png' },
{ src: 'https://dummyimage.com/384x384', sizes: '384x384', type: 'image/png' },
{ src: 'https://dummyimage.com/512x512', sizes: '512x512', type: 'image/png' },
]
});

}

Cuando finaliza la reproducción, no es necesario «liberar» la sesión multimedia, ya que la notificación desaparecerá automáticamente. Manten eso en mente
navigator.mediaSession.metadata se utilizará cuando comience la siguiente reproducción. Por eso es importante actualizarlo cuando cambie la fuente de reproducción de medios para asegurarse de que se muestre información relevante en la notificación de medios.

Hay algunas cosas a tener en cuenta sobre los metadatos multimedia.

• La matriz de material gráfico de notificación admite Url de blobs y URL de datos.
• Si no se define ninguna ilustración y hay una imagen de icono (especificada mediante <link rel=icon>) en un tamaño deseable, las notificaciones de medios lo usarán.
• El tamaño de destino del material gráfico de notificación en Chrome para Android es 512x512. Para dispositivos de gama baja, es 256x256.
• the title The attribute del elemento HTML multimedia se utiliza en el widget macOS «Reproduciendo ahora».
• Si el recurso de medios está incrustado (por ejemplo, en un iframe), la información de la API de sesión de medios debe establecerse desde el contexto incrustado. Vea el fragmento a continuación.

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

Permita que los usuarios controlen lo que se está reproduciendo

Una acción de sesión multimedia es una acción (por ejemplo, «reproducir» o «pausar») que un sitio web puede manejar para los usuarios cuando interactúan con la reproducción multimedia actual. Las acciones son análogas a los eventos y funcionan de la misma manera. Al igual que los eventos, las acciones se implementan estableciendo controladores en un objeto apropiado, una instancia de
MediaSession, en este caso. Algunas acciones se activan cuando los usuarios presionan los botones de un auricular, otro dispositivo remoto, un teclado o interactúan con una notificación de medios.

Debido a que algunas acciones de la sesión de medios pueden no ser compatibles, se recomienda utilizar un try… catch bloquear al configurarlos.

const actionHandlers = [
['play',          () => {  }],
['pause',         () => {  }],
['previoustrack', () => {  }],
['nexttrack',     () => {  }],
['stop',          () => {  }],
['seekbackward',  (details) => {  }],
['seekforward',   (details) => {  }],
['seekto',        (details) => {  }],
];
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.`);
}
}

Desconfigurar un controlador de acciones de sesión de medios es tan fácil como configurarlo en null.

try {
navigator.mediaSession.setActionHandler("nexttrack", null);
} catch (error) {
console.log(`The media session action "nexttrack" is not supported yet.`);
}

Una vez configurados, los controladores de acciones de la sesión multimedia persistirán durante las reproducciones multimedia. Esto es similar al patrón de escucha de eventos, excepto que manejar un event significa que el navegador deja de realizar cualquier comportamiento predeterminado y lo usa como una señal de que el sitio web admite la acción de los medios. Por lo tanto, los controles de acción de los medios no se mostrarán a menos que se establezca el controlador de acción adecuado.

Reproducir pausar

the "play" acción indica que el usuario desea reanudar la reproducción multimedia mientras "pause" indica un deseo de detenerlo temporalmente.

El icono «reproducir / pausar» siempre se muestra en una notificación de medios y el navegador gestiona automáticamente los eventos de medios relacionados. Para anular su comportamiento predeterminado, maneje las acciones de medios «reproducir» y «pausar» como se muestra a continuación.

El navegador puede considerar que un sitio web no está reproduciendo medios al buscar o cargar, por ejemplo. En este caso, anule este comportamiento configurando
navigator.mediaSession.playbackState to "playing" or "paused" para asegurarse de que la user interface del sitio web se mantenga sincronizada con los controles de notificación de medios.

navigator.mediaSession.setActionHandler("play", async () => {
await document.querySelector("video").play();
navigator.mediaSession.playbackState = "playing";
});
navigator.mediaSession.setActionHandler("pause", () => {
document.querySelector("video").pause();
navigator.mediaSession.playbackState = "paused";
});

Pista anterior

the "previoustrack" La acción indica que el usuario desea iniciar la reproducción multimedia actual desde el principio si la reproducción multimedia tiene una noción de comienzo, o pasar al elemento anterior en la lista de reproducción si la reproducción multimedia tiene una noción de lista de reproducción.

navigator.mediaSession.setActionHandler("previoustrack", () => {
});

Siguiente pista

the "nexttrack" La acción indica que el usuario desea mover la reproducción de medios al siguiente elemento de la lista de reproducción si la reproducción de medios tiene una noción de lista de reproducción.

navigator.mediaSession.setActionHandler("nexttrack", () => {
});

Stop

the "stop" La acción indica que el usuario desea detener la reproducción de medios y borrar el estado si corresponde.

navigator.mediaSession.setActionHandler("stop", () => {
});

Buscar hacia atrás / adelante

the "seekbackward" La acción indica que el usuario quiere hacer retroceder el tiempo de reproducción de medios por un período corto mientras "seekforward" indica el deseo de adelantar un período breve el tiempo de reproducción de medios. En ambos casos, un período corto significa unos segundos.

the seekOffset El valor proporcionado en el controlador de acciones es el tiempo en segundos para pasar el tiempo de reproducción de medios. Si no se proporciona (por ejemplo undefined), entonces debería utilizar un tiempo razonable (por ejemplo, 10-30 segundos).

const video = document.querySelector('video');
const defaultSkipTime = 10; 
navigator.mediaSession.setActionHandler("seekbackward", (details) => {
const skipTime = details.seekOffset || defaultSkipTime;
video.currentTime = Math.max(video.currentTime - skipTime, 0);
});
navigator.mediaSession.setActionHandler("seekforward", (details) => {
const skipTime = details.seekOffset || defaultSkipTime;
video.currentTime = Math.min(video.currentTime + skipTime, video.duration);
});

Busca un momento específico

the "seekto" action indica que el usuario desea mover el tiempo de reproducción de medios a un tiempo específico.

the seekTime El valor proporcionado en el controlador de acciones es el tiempo en segundos para mover el tiempo de reproducción de medios a.

the fastSeek El valor booleano proporcionado en el controlador de acciones es verdadero si la acción se llama varias veces como parte de una secuencia y esta no es la última llamada de esa secuencia.

const video = document.querySelector('video');
navigator.mediaSession.setActionHandler("seekto",(details) => {
if (details.fastSeek && "fastSeek" in video) {
video.fastSeek(details.seekTime);
return;
}
video.currentTime = details.seekTime;
});

Establecer la posición de reproducción

Mostrar con precisión la posición de reproducción de medios en una notificación es tan simple como configurar el estado de la posición en el momento apropiado como se muestra a continuación. El estado de posición es una combinación de la velocidad de reproducción de medios, la duración y la hora actual.

const video = document.querySelector("video");
function updatePositionState() {
if ("setPositionState" in navigator.mediaSession) {
navigator.mediaSession.setPositionState({
duration: video.duration,
playbackRate: video.playbackRate,
position: video.currentTime
});
}
}

await video.play();
updatePositionState();

navigator.mediaSession.setActionHandler("seekbackward", details => {
updatePositionState();
});

navigator.mediaSession.setActionHandler("seekforward", details => {
updatePositionState();
});

navigator.mediaSession.setActionHandler("seekto", details => {
updatePositionState();
});

video.addEventListener("ratechange", event => {
updatePositionState();
});

Restablecer el estado de posición es tan fácil como configurarlo en null.

navigator.mediaSession.setPositionState(null);

Muestras

Mira algunos Muestras de sesiones de medios presentando Fundación Blender and
El trabajo de Jan Morgenstern.

Means