Personalizza le notifiche multimediali e i controlli di riproduzione con l'API Media Session

Come integrarli con i tasti multimediali hardware, personalizzare le notifiche multimediali e altro ancora.

Per consentire agli utenti di sapere cosa è attualmente in riproduzione nel loro browser e controllarlo senza tornare alla pagina che l'ha avviato, è stata introdotta l'API Media Session. Consente agli sviluppatori web di personalizzare questa esperienza tramite metadati nelle notifiche multimediali personalizzate, eventi multimediali come la riproduzione, la messa in pausa, la ricerca, il cambio di traccia ed eventi di videoconferenza, come l'attivazione e la disattivazione dell'audio del microfono, l'accensione e lo spegnimento della videocamera e riaggancia. Queste personalizzazioni sono disponibili in diversi contesti, tra cui hub multimediali per computer, notifiche multimediali su dispositivi mobili e persino su dispositivi indossabili. In questo articolo illustrerò queste personalizzazioni.

Informazioni sull'API Media Session

L'API Media session offre diversi vantaggi e funzionalità:

• Sono supportati i tasti multimediali hardware.
• Le notifiche relative ai contenuti multimediali sono personalizzate su dispositivi mobili, desktop e indossabili accoppiati.
• L'hub multimediale è disponibile su computer.
• I controlli multimediali della schermata di blocco sono disponibili su ChromeOS e sui dispositivi mobili.
• I controlli della finestra Picture in picture sono disponibili per la riproduzione audio, le videoconferenze e la presentazione di diapositive.
• L'integrazione con l'assistente sui dispositivi mobili è disponibile.

Alcuni esempi illustrano alcuni di questi punti.

Esempio 1: se gli utenti premeno il tasto multimediale "Traccia successiva" della tastiera, gli sviluppatori web possono gestire questa azione utente indipendentemente dal fatto che il browser sia in primo piano o in background.

Esempio 2: se gli utenti ascoltano un podcast sul Web mentre lo schermo del dispositivo è bloccato, possono comunque premere l'icona "Vai indietro" dai controlli multimediali della schermata di blocco in modo che gli sviluppatori web spostino il tempo di riproduzione indietro di alcuni secondi.

Esempio 3: se gli utenti hanno schede che riproducono audio, possono facilmente interrompere la riproduzione dal media hub sul computer per consentire agli sviluppatori web di cancellare il proprio stato.

Esempio 4: se gli utenti stanno partecipando a una videochiamata, possono premere il controllo "attiva/disattiva microfono" nella finestra Picture in picture per interrompere la ricezione dei dati del microfono sul sito web.

Tutto questo avviene tramite due interfacce diverse: l'interfaccia MediaSession e l'interfaccia MediaMetadata. La prima consente agli utenti di controllare ciò che viene riprodotto. Il secondo consiste nel modo in cui indichi a MediaSession cosa deve essere controllato.

L'immagine seguente mostra come queste interfacce siano correlate a controlli multimediali specifici, in questo caso una notifica multimediale su dispositivo mobile.

Fai sapere agli utenti cosa sono in riproduzione

Quando un sito web è in riproduzione audio o video, gli utenti ricevono automaticamente le notifiche multimediali nella barra delle notifiche sui dispositivi mobili o nell'hub multimediale sul computer. Il browser fa del suo meglio per mostrare le informazioni appropriate utilizzando il titolo del documento e l'immagine dell'icona più grande che riesce a trovare. Con l'API Media Session, è possibile personalizzare la notifica relativa ai contenuti multimediali con alcuni metadati multimediali più completi, come il titolo, il nome dell'artista, il nome dell'album e l'artwork, come mostrato di seguito.

Chrome richiede lo stato attivo audio "completo" per mostrare le notifiche multimediali solo quando la durata dei contenuti multimediali è almeno 5 secondi. In questo modo, le notifiche non verranno visualizzate per suoni accidentali, come i suoni di un campanello.

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

Al termine della riproduzione, non è necessario "rilasciare" la sessione multimediale, perché la notifica scompare automaticamente. Tieni presente che verrà utilizzato navigator.mediaSession.metadata all'avvio della riproduzione successiva. Ecco perché è importante aggiornarlo quando la sorgente di riproduzione di contenuti multimediali cambia per assicurarti che nella notifica dei contenuti multimediali vengano mostrate informazioni pertinenti.

Ci sono alcuni aspetti da considerare in merito ai metadati dei contenuti multimediali.

• L'array di artwork delle notifiche supporta URL blob e URL di dati.
• Se non viene definito alcun artwork ed è presente un'immagine icona (specificata utilizzando <link rel=icon>) di dimensioni desiderabili, verrà utilizzata dalle notifiche multimediali.
• La dimensione target dell'artwork delle notifiche in Chrome per Android è pari a 512x512. Per i dispositivi di fascia bassa, il prezzo è 256x256.
• L'attributo title dell'elemento HTML multimediale viene utilizzato nel widget MacOS "In riproduzione".
• Se la risorsa multimediale è incorporata (ad esempio in un iframe), le informazioni dell'API Media Session devono essere impostate dal contesto incorporato. Vedi lo snippet di seguito.

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

Consenti agli utenti di controllare i contenuti in riproduzione

Un'azione relativa a una sessione multimediale è un'azione (ad esempio, "riproduci" o "pausa") che un sito web può gestire per gli utenti quando interagiscono con la riproduzione attuale dei contenuti multimediali. Le azioni sono analoghe e funzionano in modo molto simile agli eventi. Come gli eventi, le azioni vengono implementate impostando i gestori su un oggetto appropriato, un'istanza di MediaSession, in questo caso. Alcune azioni vengono attivate quando gli utenti premono pulsanti dalle cuffie, da un altro dispositivo remoto o da una tastiera oppure quando interagiscono con una notifica multimediale.

Poiché alcune azioni per le sessioni multimediali potrebbero non essere supportate, ti consigliamo di utilizzare un blocco try…catch durante l'impostazione.

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

Per annullare l'impostazione di un gestore delle azioni per le sessioni multimediali, basta impostarlo su 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 volta impostati, i gestori delle azioni delle sessioni multimediali continueranno a essere visualizzati durante le riproduzioni dei contenuti multimediali. Si tratta di un pattern simile al listener di eventi, ma la gestione di un evento implica che il browser smette di eseguire qualsiasi comportamento predefinito e lo utilizza per indicare che il sito web supporta l'azione multimediale. Di conseguenza, i controlli delle azioni multimediali non verranno mostrati a meno che non sia impostato il gestore delle azioni corretto.

Riproduci / metti in pausa

L'azione "play" indica che l'utente vuole riprendere la riproduzione di contenuti multimediali mentre "pause" indica che vuole interromperla temporaneamente.

L'icona "riproduci/metti in pausa" viene sempre mostrata in una notifica di contenuti multimediali e i relativi eventi multimediali vengono gestiti automaticamente dal browser. Per eseguire l'override del comportamento predefinito, gestisci le azioni multimediali "riproduci" e "metti in pausa" come mostrato di seguito.

Ad esempio, il browser potrebbe considerare che un sito web non riproduce contenuti multimediali durante la ricerca o il caricamento. In questo caso, sostituisci questo comportamento impostando navigator.mediaSession.playbackState su "playing" o "paused" per assicurarti che l'interfaccia utente del sito web rimanga sincronizzata con i controlli delle notifiche multimediali.

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

Traccia precedente

L'azione "previoustrack" indica che l'utente vuole avviare la riproduzione di contenuti multimediali corrente dall'inizio se la riproduzione di contenuti multimediali ha un'idea di inizio oppure vuole passare all'elemento precedente nella playlist se la riproduzione di contenuti multimediali ha un'idea di playlist.

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

Passare alla traccia successiva

L'azione "nexttrack" indica che l'utente vuole spostare la riproduzione di contenuti multimediali all'elemento successivo nella playlist se la riproduzione di contenuti multimediali ha il concetto di playlist.

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

Interrompi

L'azione "stop" indica che l'utente vuole interrompere la riproduzione di contenuti multimediali e cancellare lo stato, se opportuno.

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

Vai indietro / avanti

L'azione "seekbackward" indica che l'utente vuole spostare indietro il tempo di riproduzione dei contenuti multimediali di un breve periodo, mentre "seekforward" indica che vuole avanzare il tempo di riproduzione dei contenuti multimediali di un breve periodo. In entrambi i casi, un breve periodo significa pochi secondi.

Il valore seekOffset fornito nel gestore delle azioni è il tempo in secondi per spostare il tempo di riproduzione dei contenuti multimediali. Se non è disponibile (ad esempio undefined), dovresti impiegare un tempo ragionevole (ad esempio 10-30 secondi).

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

Vai a un'ora specifica

L'azione "seekto" indica che l'utente vuole spostare il tempo di riproduzione dei contenuti multimediali a un'ora specifica.

Il valore seekTime fornito nel gestore delle azioni indica il tempo in secondi in cui spostare il tempo di riproduzione dei contenuti multimediali.

Il valore booleano fastSeek fornito nel gestore delle azioni è true se l'azione viene chiamata più volte in una sequenza e questa non è l'ultima chiamata in quella sequenza.

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

Imposta la posizione di riproduzione

Per visualizzare in modo preciso il punto di riproduzione dei contenuti multimediali in una notifica è sufficiente impostare lo stato della posizione al momento opportuno, come mostrato di seguito. Lo stato della posizione è una combinazione di velocità di riproduzione dei contenuti multimediali, durata e ora corrente.

La durata deve essere specificata e deve essere positiva. La posizione deve essere positiva e inferiore alla durata. La velocità di riproduzione deve essere maggiore di 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();
});

Ripristinare lo stato della posizione è facile quanto impostarlo su null.

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

Azioni di videoconferenza

Quando l'utente inserisce la videochiamata in una finestra Picture in picture, nel browser potrebbero essere visualizzati i controlli del microfono, della videocamera e per riagganciare. Quando l'utente fa clic su queste opzioni, il sito web le gestisce tramite le azioni di videoconferenza riportate di seguito. Per un esempio, consulta l'Esempio di videoconferenze.

Attiva/disattiva microfono

L'azione "togglemicrophone" indica che l'utente vuole disattivare o riattivare l'audio del microfono. Il metodo setMicrophoneActive(isActive) indica al browser se il sito web considera attualmente il microfono attivo.

let isMicrophoneActive = false;

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

Cambia fotocamera

L'azione "togglecamera" indica che l'utente vuole attivare o disattivare la videocamera attiva. Il metodo setCameraActive(isActive) indica se il browser considera attivo il sito web.

let isCameraActive = false;

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

Riaggancia

L'azione "hangup" indica che l'utente vuole terminare una chiamata.

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

Presentazione delle azioni delle diapositive

Quando l'utente inserisce la propria presentazione in una finestra Picture in picture, il browser può visualizzare i controlli per spostarsi tra le diapositive. Quando l'utente fa clic su questi elementi, il sito web le gestisce tramite l'API Media Session. Per un esempio, vedi l'esempio di presentazione di diapositive.

Diapositiva precedente

L'azione "previousslide" indica che l'utente vuole tornare alla diapositiva precedente durante la presentazione delle diapositive.

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

Diapositiva successiva

L'azione "nextslide" indica che l'utente vuole passare alla diapositiva successiva durante la presentazione delle diapositive.

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

Samples

Dai un'occhiata ad alcuni esempi di Media Session, che mostrano Blender Foundation e le opere di Jan Morgenstern.

Risorse

• Specifiche della sessione multimediale: wicg.github.io/mediasession
• Problemi di specifiche: github.com/WICG/mediasession/issues
• Bug di Chrome: crbug.com