Se usó la API de Cloud Translation para traducir esta página.

Personaliza las notificaciones multimedia y los controles de reproducción con la API de Media Session

Cómo realizar la integración con teclas multimedia de hardware, personalizar las notificaciones multimedia y mucho más

François Beaufort

Para permitir que los usuarios sepan qué se está reproduciendo actualmente en su navegador y que lo controlen sin regresar a la página que la inició, la API de Media Session se que se presentaron. Permite que los desarrolladores web personalicen esta experiencia a través de metadatos en notificaciones multimedia personalizadas, eventos multimedia como reproducir, pausar, búsqueda, cambio de seguimiento y eventos de videoconferencia, como silenciar/dejar de silenciar micrófono, activar o desactivar la cámara y colgar. Estas personalizaciones son disponible en varios contextos, como concentradores multimedia de escritorio, notificaciones multimedia en dispositivos móviles e incluso en wearables. Describiré estas personalizaciones en este artículo.

Capturas de pantalla de contextos de sesiones multimedia. — Centro multimedia en computadoras, notificaciones multimedia en dispositivos móviles y dispositivos wearable.

Información acerca de la API de Media Session

La API de Media Session proporciona varios beneficios y capacidades:

Se admiten las teclas multimedia de hardware.
Las notificaciones multimedia se personalizan en dispositivos móviles, computadoras y dispositivos wearable vinculados.
El centro de contenido multimedia está disponible en computadoras.
Los controles multimedia de la pantalla de bloqueo están disponibles en ChromeOS y dispositivos móviles.
Los controles de ventana de pantalla en pantalla están disponibles para la reproducción de audio, videoconferencias y presentación de diapositivas.
Ya está disponible la integración del Asistente en dispositivos móviles.

Navegadores compatibles

Origen

Algunos ejemplos ilustrarán algunos de estos puntos.

Ejemplo 1: Si los usuarios presionan "siguiente pista". teclas multimedia del teclado, los desarrolladores web pueden controlar esta acción del usuario aunque el navegador esté en primer plano o en segundo plano.

Ejemplo 2: Si los usuarios escuchan un podcast en la Web mientras utilizan su dispositivo pantalla bloqueada, puede seleccionar la opción "Buscar hacia atrás" ícono de la cerradura controles multimedia de pantalla para que los desarrolladores web retrocedan el tiempo de reproducción unos pocos segundos.

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

Ejemplo 4: Si los usuarios están en una videollamada, pueden presionar el botón de micrófono" de la ventana de pantalla en pantalla para evitar que el sitio web recibiendo datos del micrófono.

Todo esto se logra mediante dos interfaces diferentes: la interfaz MediaSession y la interfaz MediaMetadata. El primero permite a los usuarios controlar en reproducción. La segunda es cómo le indicas a MediaSession lo que debe controlarse.

A modo de ejemplo, la imagen a continuación muestra cómo estas interfaces se relacionan con controles multimedia, en este caso, una notificación multimedia en un dispositivo móvil.

Ilustración de las interfaces de sesión multimedia — Anatomía de una notificación multimedia en un dispositivo móvil.

Permite que los usuarios sepan qué se está reproduciendo

Cuando un sitio web reproduce audio o video, los usuarios obtienen contenido multimedia automáticamente notificaciones en la bandeja de notificaciones del dispositivo móvil o en el concentrador multimedia una computadora de escritorio. El navegador se esfuerza por mostrar la información adecuada utilizando el título del documento y la imagen de ícono más grande que encuentre. Con la sesión multimedia API, es posible personalizar las notificaciones multimedia metadatos, como el título, el nombre del artista, el nombre del álbum y el material gráfico, como se muestra a continuación.

Chrome solicita información "completa" el foco de audio para mostrar notificaciones multimedia solo cuando que la duración del contenido multimedia sea de al menos 5 segundos. Esto garantiza que los sonidos como dingos, no muestran notificaciones.

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

Cuando finaliza la reproducción, no es necesario “liberar” de la sesión multimedia la notificación desaparecerá automáticamente. Ten en cuenta que Se usará navigator.mediaSession.metadata cuando comience la próxima reproducción sin embargo. Por eso, es importante actualizarla cuando la fuente de reproducción de contenido multimedia cambios para garantizar que se muestre información relevante en la notificación multimedia.

Debes tener en cuenta algunos aspectos sobre los metadatos de contenido multimedia.

El array de material gráfico de notificaciones admite URLs de BLOB y URLs de datos.
Si no se define ningún material gráfico y hay una imagen de ícono (especificada usando <link rel=icon>) con el tamaño deseado, se usará para las notificaciones multimedia.
El tamaño objetivo del material gráfico de la notificación en Chrome para Android es 512x512. Para de baja gama, es 256x256.
El atributo title del elemento HTML multimedia se usa en el campo "Está sonando" Widget de macOS.
Si el recurso multimedia está incorporado (por ejemplo, en un iframe), la API de Media Session la información se debe establecer a partir del contexto incorporado. Consulta el siguiente fragmento.

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

También puedes agregar información de capítulos individuales, como el título de la sección, la marca de tiempo y una imagen de captura de pantalla a los metadatos multimedia. Esto permite a los usuarios navegar por el contenido de los medios.

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

Información del capítulo que se muestra en una notificación multimedia de ChromeOS. — Notificación multimedia con capítulos en ChromeOS.

Permite que los usuarios controlen lo que se reproduce

Una acción de la sesión multimedia es una acción (por ejemplo, "reproducir" o "pausar") que un sitio web puede para los usuarios cuando interactúan con la reproducción de contenido multimedia actual. Las acciones son son análogos y funcionan de la misma forma que los eventos. Al igual que los eventos, las acciones implementando mediante la configuración de los controladores en un objeto adecuado, una instancia de MediaSession, en este caso. Algunas acciones se activan cuando los usuarios presionan botones de auriculares, otro dispositivo remoto, un teclado, o interactuar con un notificación multimedia.

Captura de pantalla de una notificación multimedia en Windows 10. — Notificación multimedia personalizada en Windows 10.

Debido a que es posible que algunas acciones de las sesiones multimedia no sean compatibles, se recomienda usa un bloque try…catch cuando las configures.

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

Desactivar un controlador de acción de sesión multimedia es tan fácil como configurarlo en 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.`);
}

Una vez configurados, los controladores de acciones de la sesión multimedia se conservarán durante las reproducciones de contenido multimedia. Esto es similar al patrón del objeto de escucha de eventos, con la excepción de que controlar un evento significa que el navegador deja de realizar cualquier comportamiento predeterminado y lo usa como para indicar que el sitio web respalda la acción. Por lo tanto, los controles de acciones multimedia no se mostrará a menos que se configure el controlador de acciones adecuado.

Captura de pantalla del widget de Está sonando en macOS Big Sur. — Widget de Está sonando en macOS Big Sur

Reproducir / pausar

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

La función de "reproducir y pausar" el ícono siempre se muestra en una notificación multimedia y las notificaciones el navegador controla automáticamente los eventos multimedia. Para anular el valor predeterminado “reproducir” y "pausar" acciones multimedia como se muestra a continuación.

El navegador puede considerar que un sitio web no reproduce contenido multimedia al buscar o cargando por ejemplo. En este caso, anula este comportamiento estableciendo navigator.mediaSession.playbackState a "playing" o "paused" para asegurarte la IU del sitio web se mantiene sincronizada con los controles de notificaciones multimedia.

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

Pista anterior

La acción "previoustrack" indica que el usuario desea iniciar la reproducción de contenido multimedia actual desde el principio si la reproducción de contenido multimedia tiene la idea de al principio o al elemento anterior de la playlist si el contenido multimedia tiene una noción de playlist.

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

Pista siguiente

La acción "nexttrack" indica que el usuario quiere mover la reproducción de contenido multimedia a el siguiente elemento de la lista de reproducción si la reproducción de contenido multimedia tiene una noción de lista de reproducción.

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

Detener

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

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

Adelantar / retroceder

La acción "seekbackward" indica que el usuario quiere mover el contenido multimedia. el tiempo de reproducción hacia atrás por un período corto, mientras que "seekforward" indica un deseo para adelantar el tiempo de reproducción del contenido multimedia por un período breve. En ambos casos, un un período corto significa unos segundos.

El valor seekOffset proporcionado en el controlador de acciones es el tiempo en segundos que mover el tiempo de reproducción de contenido multimedia. Si no se proporciona (por ejemplo, undefined), debes usar un tiempo razonable (por ejemplo, de 10 a 30 segundos).

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

Ir a un horario específico

La acción "seekto" indica que el usuario quiere mover la reproducción de contenido multimedia. de una hora a una hora específica.

El valor seekTime proporcionado en el controlador de acciones es el tiempo en segundos que cambiar el tiempo de reproducción de contenido multimedia

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

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

Establece la posición de reproducción

Mostrar con precisión la posición de reproducción de contenido multimedia en una notificación es muy simple como configurar el estado de posición en un momento adecuado, como se muestra a continuación. El es una combinación de la velocidad de reproducción del contenido multimedia, la duración y hora actual.

Captura de pantalla de los controles multimedia de la pantalla de bloqueo en ChromeOS. — Controles multimedia de la pantalla de bloqueo en ChromeOS.

Se debe proporcionar la duración, que debe ser positiva. La posición debe ser positiva y inferior a la duración. La velocidad de reproducción debe ser superior a 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();
});

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

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

Acciones de videoconferencia

Cuando el usuario inicia la videollamada en una ventana de pantalla en pantalla, el navegador puede mostrar controles para el micrófono y la cámara, y para colgar. Cuando el usuario hace clic en ellos, el sitio web los administra a través del video. las siguientes acciones de conferencia. Para ver un ejemplo, consulta el ejemplo de videoconferencias.

Captura de pantalla de los controles de videoconferencia en la ventana Pantalla en pantalla. — Controles de videoconferencia en una ventana de pantalla en pantalla.

Activar o desactivar micrófono

La acción "togglemicrophone" indica que el usuario desea silenciar o activar el sonido. el micrófono. El método setMicrophoneActive(isActive) le indica al navegador si el sitio web considera que el micrófono está activo.

let isMicrophoneActive = false;

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

Alternar cámaras

La acción "togglecamera" indica que el usuario quiere activar el modo cámara. El método setCameraActive(isActive) indica si navegador considera que el sitio web está activo.

let isCameraActive = false;

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

Cuelga.

La acción "hangup" indica que el usuario desea finalizar una llamada.

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

Presentación de acciones en diapositivas

Cuando el usuario coloca su presentación de diapositivas en una ventana de pantalla en pantalla, el navegador puede mostrar controles para navegar por las diapositivas. Cuando el usuario el sitio web los administra a través de la API de Media Session. Para un consulta el ejemplo de Cómo presentar diapositivas.

Diapositiva anterior

La acción "previousslide" indica que el usuario quiere volver a la la diapositiva anterior cuando las presentaste.

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

Navegadores compatibles

Siguiente diapositiva

La acción "nextslide" indica que el usuario quiere ir a la siguiente diapositiva. cuando presentes las diapositivas.

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

Navegadores compatibles

Ejemplos

Consulta algunas muestras de sesiones multimedia en las que se muestran Combinaer Foundation y Obra de Jan Morgenstern.

Una presentación en pantalla que ilustra la API de Media Session.

Recursos

Especificaciones de la sesión multimedia: wicg.github.io/mediasession
Problemas de especificaciones: github.com/WICG/mediasession/issues
Errores de Chrome: crbug.com