Come eseguire l'integrazione con chiavi multimediali hardware, personalizzare le notifiche multimediali e altro ancora.
Per consentire agli utenti di sapere cosa è attualmente in riproduzione nel 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 riproduzione, messa in pausa, ricerca, 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 la possibilità di riagganciare. Queste personalizzazioni sono disponibili in diversi contesti, tra cui hub multimediali per computer, notifiche multimediali su dispositivi mobili e persino su dispositivi indossabili. Descriverò queste personalizzazioni in questo articolo.
Informazioni sull'API Media Session
L'API Media session offre diversi vantaggi e funzionalità:
- Sono supportati i tasti multimediali hardware.
- Le notifiche multimediali sono personalizzate su dispositivo mobile, computer e dispositivo indossabile accoppiato.
- 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 slide.
- È disponibile l'integrazione con l'assistente sui dispositivi mobili.
Alcuni esempi illustreranno alcuni di questi punti.
Esempio 1: se gli utenti premeno il tasto multimediale "Traccia successiva" della tastiera, gli sviluppatori web possono gestire l'azione dell'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 per consentire agli sviluppatori web di retrocedere di qualche secondo il tempo di riproduzione.
Esempio 3. Se gli utenti hanno schede che riproducono audio, possono facilmente interrompere la riproduzione dall'hub multimediale sul computer per consentire agli sviluppatori web di cancellare il loro stato.
Esempio 4. Se gli utenti partecipano a una videochiamata, possono premere il controllo "Attiva/disattiva il microfono" nella finestra Picture in picture per impedire al sito web di ricevere i dati del microfono.
Tutto questo tramite due diverse interfacce: l'interfaccia di MediaSession e l'interfaccia di MediaMetadata. Il primo consente agli utenti di controllare
i contenuti in riproduzione. Il secondo è il modo per indicare a MediaSession cosa deve essere controllato.
Per spiegarci meglio, la seguente immagine mostra la correlazione tra queste interfacce e controlli multimediali specifici, in questo caso una notifica relativa ai contenuti multimediali su dispositivo mobile.
Fai sapere agli utenti cosa è in riproduzione
Quando un sito web riproduce audio o video, gli utenti ricevono automaticamente le notifiche multimediali nella barra delle notifiche dei dispositivi mobili o nell'hub multimediale sui 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 dei contenuti multimediali con alcuni metadati multimediali più avanzati, come il titolo, il nome dell'artista, il nome dell'album e l'artwork, come mostrato di seguito.
Chrome richiede lo stato attivo dell'audio "completo" per mostrare le notifiche multimediali solo quando la durata dei contenuti multimediali è almeno 5 secondi. In questo modo, i suoni accidentali come i rumori non vengono mostrati.
// 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 scomparirà automaticamente. Tieni presente che, però, verrà utilizzato l'attributo navigator.mediaSession.metadata all'avvio della riproduzione successiva. Per questo motivo è importante aggiornarlo quando la fonte di riproduzione dei contenuti multimediali cambia, al fine di garantire che nella notifica dei contenuti multimediali vengano mostrate informazioni pertinenti.
Occorre tenere presente alcuni aspetti relativi ai metadati dei contenuti multimediali.
- L'array di artwork delle notifiche supporta URL BLOB e URL di dati.
- Se non viene definito un artwork e esiste un'immagine dell'icona (specificata utilizzando
<link rel=icon>) di dimensioni adeguate, verrà utilizzata dalle notifiche multimediali. - La dimensione target dell'artwork delle notifiche in Chrome per Android è
512x512. Per i dispositivi di fascia bassa è256x256. - L'attributo
titledell'elemento HTML multimediale viene utilizzato nel widget di macOS "Ora 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>
Puoi aggiungere anche informazioni sui singoli capitoli, ad esempio il titolo, il timestamp e un'immagine screenshot ai metadati dei contenuti multimediali. Ciò consente agli utenti di esplorare i contenuti dei 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 i contenuti in riproduzione
Un'azione della sessione multimediale è un'azione (ad esempio, "riproduci" o "pausa") che un sito web è in grado di gestire per gli utenti quando interagiscono con la riproduzione in corso dei contenuti multimediali. Le azioni sono analoghe e funzionano allo stesso modo degli 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 da un paio di cuffie, di un altro dispositivo remoto, una tastiera o interagiscono con una notifica di contenuti multimediali.
Poiché alcune azioni delle 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.`);
}
}
Disattivare un gestore delle azioni per le sessioni multimediali è semplice quanto l'impostazione 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 disponibili durante le riproduzioni di contenuti multimediali. È simile al pattern del listener di eventi, ad eccezione del fatto che la gestione di un evento significa che il browser smette di eseguire qualsiasi comportamento predefinito e lo utilizza come indicatore che il sito web supporti l'azione multimediale. Di conseguenza, i controlli delle azioni multimediali non verranno mostrati a meno che non sia impostato il gestore delle azioni appropriato.
Riprodurre / mettere in pausa
L'azione "play" indica che l'utente vuole riprendere la riproduzione dei contenuti multimediali
mentre "pause" indica l'intenzione di 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 di riproduzione e pausa multimediali come mostrato di seguito.
Ad esempio, il browser potrebbe considerare un sito web come non riprodurre 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 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 multimediale corrente dall'inizio se la riproduzione multimediale ha un'idea di inizio oppure passare all'elemento precedente nella playlist se la riproduzione dei contenuti multimediali ha una nozione 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 della playlist se la riproduzione multimediale include la 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
cancellare lo stato, se opportuno.
navigator.mediaSession.setActionHandler('stop', () => {
// Stop playback and clear state if appropriate.
});
Vai avanti / indietro
L'azione "seekbackward" indica che l'utente vuole spostare indietro di un breve periodo il tempo di riproduzione dei contenuti multimediali, mentre "seekforward" indica di voler avanzare di un breve periodo il tempo di riproduzione dei contenuti multimediali. In entrambi i casi, un breve
periodo di tempo significa pochi secondi.
Il valore seekOffset fornito nel gestore delle azioni indica il tempo in secondi per
spostare il tempo di riproduzione dei contenuti multimediali. Se non viene indicato (ad esempio undefined), devi 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 il tempo di riproduzione
dei contenuti multimediali a un orario specifico.
Il valore seekTime fornito nel gestore delle azioni indica il tempo in secondi per 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 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 la posizione di riproduzione dei contenuti multimediali in una notifica basta 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 tempo attuale.
La durata deve essere specificata ed 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 è 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, il browser potrebbe visualizzare i controlli per il microfono e la videocamera e per riagganciare. Quando l'utente fa clic su queste azioni, il sito web le gestisce tramite le azioni di videoconferenza riportate di seguito. Per un esempio, vedi la sezione Videoconferenze di esempio.
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 accendere
o spegnere 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 sulle slide
Quando l'utente inserisce la propria presentazione in una finestra Picture in picture, il browser può visualizzare i controlli per scorrere le slide. Quando l'utente fa clic su questi elementi, il sito web li gestisce tramite l'API Media Session. Per un esempio, vedi l'esempio di presentazione di Presentazioni.
Diapositiva precedente
L'azione "previousslide" indica che l'utente vuole tornare alla
slide precedente durante la presentazione delle slide.
navigator.mediaSession.setActionHandler('previousslide', () => {
// Show previous slide.
});
Supporto dei browser
- 111
- 111
- x
- x
Diapositiva successiva
L'azione "nextslide" indica che l'utente vuole passare alla slide successiva
durante la presentazione delle slide.
navigator.mediaSession.setActionHandler('nextslide', () => {
// Show next slide.
});
Supporto dei browser
- 111
- 111
- x
- x
Campioni
Dai un'occhiata ad alcuni esempi di Media Session che presentano Blender Foundation e il lavoro di Jan Morgenstern.
Risorse
- Specifiche della sessione multimediale: wicg.github.io/mediasession
- Problemi relativi alle specifiche: github.com/WICG/mediasession/issues
- Bug di Chrome: crbug.com