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

Come eseguire l'integrazione con i tasti multimediali hardware, personalizzare le notifiche multimediali e altro ancora.

François Beaufort

Per consentire agli utenti di sapere cosa è attualmente in riproduzione nel browser e di controllarlo senza tornare alla pagina che l'ha avviata, l'API Media Session è stata sono state introdotte. Consente agli sviluppatori web di personalizzare questa esperienza tramite in notifiche multimediali personalizzate, eventi multimediali come riproduzione, messa in pausa ricerca, modifica delle tracce e eventi di videoconferenza, come l'attivazione/disattivazione dell'audio microfono, accendere/spegnere la videocamera e riagganciare. Queste personalizzazioni sono disponibile in diversi contesti, tra cui hub multimediali desktop, notifiche multimediali su dispositivi mobili e persino su dispositivi indossabili. Descrivi queste personalizzazioni in questo articolo.

Informazioni sull'API Media Session

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

• I tasti multimediali hardware sono supportati.
• Le notifiche relative ai contenuti multimediali sono personalizzate su dispositivo mobile, computer e dispositivo indossabile accoppiato.
• L'hub multimediale è disponibile su computer.
• I controlli multimediali nella schermata di blocco sono disponibili su ChromeOS e dispositivi mobili.
• I controlli della finestra Picture in picture sono disponibili per la riproduzione audio, videoconferenze e presentazione di slide.
• È disponibile l'integrazione con l'assistente sui dispositivi mobili.

Alcuni esempi illustreranno alcuni di questi punti.

Esempio 1: se gli utenti selezionano la "traccia successiva" tasto multimediale della tastiera, gli sviluppatori web possono gestire questa azione dell'utente se il browser è in primo piano o lo sfondo.

Esempio 2:se gli utenti ascoltano un podcast sul web mentre usano il dispositivo schermo è bloccato, possono comunque premere il pulsante icona dalla serratura filtrare i controlli multimediali in modo che gli sviluppatori web spostino il tempo di riproduzione indietro di qualche secondi.

Esempio 3: se gli utenti hanno schede che riproducono audio, possono interrompere facilmente la riproduzione dall'hub multimediale sul desktop per consentire agli sviluppatori web di cancellarne lo stato.

Esempio 4: se gli utenti partecipano a una videochiamata, possono premere il pulsante di attivazione/disattivazione microfono" nella finestra Picture in picture per impedire al sito web ricezione dati del microfono.

Il tutto attraverso due diverse interfacce: l'interfaccia MediaSession e l'interfaccia MediaMetadata. La prima consente agli utenti di controllare che giocano. Il secondo è come indicare a MediaSession cosa deve essere controllato.

Per spiegarci meglio, l'immagine di seguito mostra come queste interfacce si relazionano a specifiche controlli multimediali, in questo caso una notifica multimediale su dispositivo mobile.

Fai sapere agli utenti cosa c'è in riproduzione

Quando un sito web riproduce contenuti audio o video, gli utenti ricevono automaticamente i contenuti multimediali notifiche nella barra delle notifiche sul dispositivo mobile o nell'hub multimediale desktop. Il browser fa del suo meglio per mostrare le informazioni appropriate utilizzando titolo del documento e l'immagine icona più grande che riesce a trovare. Con la sessione multimediale API, è possibile personalizzare le notifiche multimediali con metadati come titolo, nome dell'artista, nome dell'album e artwork, come mostrato di seguito.

Chrome richiede "completa" la messa a fuoco audio per mostrare le notifiche dei contenuti multimediali solo quando la durata dei contenuti multimediali è almeno 5 secondi. In questo modo i suoni accidentali ad esempio, non vengono mostrate notifiche.

// 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 c'è bisogno di "rilasciare" la sessione multimediale come la notifica scomparirà automaticamente. Tieni presente che L'app navigator.mediaSession.metadata verrà usata all'avvio della prossima riproduzione però. Questo è il motivo per cui è importante aggiornarlo quando l'origine di riproduzione dei contenuti multimediali modifiche per garantire che le informazioni pertinenti vengano mostrate nella notifica dei contenuti multimediali.

Ci sono alcuni aspetti da considerare in merito ai metadati 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 auspicabili, verrà utilizzata dalle notifiche relative ai contenuti multimediali.
• La dimensione target dell'artwork della notifica in Chrome per Android è 512x512. Per dispositivi di fascia bassa, è 256x256.
• L'attributo title dell'elemento multimediale HTML viene utilizzato nella playlist "Now Playing" Widget macOS.
• Se la risorsa multimediale è incorporata (ad esempio in un iframe), l'API Media Session le informazioni 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>

Puoi aggiungere anche informazioni sui singoli capitoli, ad esempio il titolo della sezione, il relativo timestamp e un'immagine screenshot ai metadati multimediali. In questo modo gli utenti possono navigare tra i contenuti multimediali.

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

Consenti agli utenti di controllare la riproduzione

Un'azione della sessione multimediale è un'azione (ad esempio "riproduci" o "metti in pausa") che un sito web può per gli utenti quando interagiscono con l'attuale riproduzione dei contenuti multimediali. Le azioni sono sono analoghi e funzionano in modo analogo agli eventi. Come gli eventi, le azioni implementato impostando gestori su un oggetto appropriato, un'istanza MediaSession, in questo caso. Alcune azioni vengono attivate quando gli utenti premeno di tasti di cuffie, di un altro dispositivo remoto, di una tastiera notifica multimediale.

Poiché alcune azioni relative alle sessioni multimediali potrebbero non essere supportate, ti consigliamo di usa 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 un gestore di azioni della sessione multimediale, è sufficiente 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 verranno mantenuti durante le riproduzioni multimediali. È simile al pattern listener di eventi, tranne che per la gestione di un evento significa che il browser smette di eseguire qualsiasi comportamento predefinito e lo utilizza come un indica che il sito web supporta l'azione multimediale. Di conseguenza, i controlli delle azioni multimediali non verranno mostrati se non viene impostato il gestore di azioni appropriato.

Riprodurre / mettere in pausa

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

L'opzione "Riproduci/Pausa" viene sempre mostrata in una notifica di contenuti multimediali e i relativi sono gestiti automaticamente dal browser. Per eseguire l'override delle impostazioni predefinite comportamento, gestire la riproduzione e "metti in pausa" azioni multimediali come mostrato di seguito.

Il browser potrebbe considerare che un sito web non stia riproducendo contenuti multimediali quando cerca o ad esempio durante il caricamento. In questo caso, sostituisci questo comportamento impostando navigator.mediaSession.playbackState a "playing" o "paused" per assicurarti la UI del sito web rimane sincronizzata con i controlli di notifica dei contenuti 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 ha una nozione di all'inizio o passa all'elemento precedente nella playlist se i contenuti multimediali vengono riprodotti ha una nozione di playlist.

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

Traccia successiva

L'azione "nexttrack" indica che l'utente vuole spostare la riproduzione dei contenuti multimediali in all'elemento successivo nella playlist, se la riproduzione multimediale ha una nozione di playlist.

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

Interrompi

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

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

Va indietro / avanti

L'azione "seekbackward" indica che l'utente vuole spostare i contenuti multimediali. il tempo di riproduzione torna indietro di un breve periodo mentre "seekforward" indica un desiderio per mandare avanti di un breve periodo il tempo di riproduzione dei contenuti multimediali. In entrambi i casi, per un periodo di tempo breve si intende pochi secondi.

Il valore seekOffset fornito nel gestore di azioni corrisponde al tempo in secondi per sposta il tempo di riproduzione dei contenuti multimediali. Se non viene specificato (ad esempio undefined), dovresti utilizzare un tempo ragionevole (ad es. 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 orario specifico

L'azione "seekto" indica che l'utente vuole spostare la riproduzione dei contenuti multimediali a un orario specifico.

Il valore seekTime fornito nel gestore di azioni corrisponde al tempo in secondi per sposta il tempo di riproduzione dei contenuti multimediali.

Il valore booleano fastSeek fornito nel gestore di azioni è true se l'azione è essere chiamato più volte come parte di una sequenza e questa non è l'ultima 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

Mostrare con precisione il punto di riproduzione dei contenuti multimediali in una notifica è semplicissimo come impostare lo stato della posizione al momento giusto, come mostrato di seguito. La stato posizione è una combinazione di velocità di riproduzione multimediale, durata e ora attuale.

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

Il ripristino dello stato di posizione è semplice quanto l'impostazione 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, browser potrebbe visualizzare i controlli per il microfono e la videocamera e per la chiusura. Quando l'utente fa clic su questi elementi, il sito web li gestisce tramite il video azioni di videoconferenza riportate di seguito. Per un esempio, guarda l'esempio di videoconferenze.

Attiva/disattiva microfono

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

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 l'opzione videocamera accesa o spenta. Il metodo setCameraActive(isActive) indica se il parametro 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);
});

Riagganciare

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

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

Presentazione delle azioni delle slide

Quando l'utente inserisce la presentazione in una finestra Picture in picture, il browser potrebbe visualizzare i controlli per navigare tra le slide. Quando l'utente fa clic su questi, il sito web li gestisce tramite l'API Media Session. Per un vedi l'esempio di presentazione di slide.

Diapositiva precedente

L'azione "previousslide" indica che l'utente vuole tornare all'app slide precedente quando si presentano slide.

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

Diapositiva successiva

L'azione "nextslide" indica che l'utente vuole passare alla slide successiva durante la presentazione di slide.

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

Esempi

Dai un'occhiata ad alcuni esempi di sessioni multimediali con mister Foundation e Il lavoro di Jan Morgenstern.

Risorse

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