Dostosuj powiadomienia o multimediach i elementy sterujące odtwarzaniem za pomocą interfejsu Media Session API

Jak integrować się z kluczami sprzętowymi do multimediów, dostosowywać powiadomienia multimedialne i wykonywać inne czynności.

François Beaufort

Dlatego wprowadziliśmy interfejs Media Session API, aby użytkownicy wiedzieli, co jest obecnie odtwarzane w przeglądarce i mogli nim kontrolować. Umożliwia deweloperom stron internetowych dostosowanie tej funkcji za pomocą metadanych w niestandardowych powiadomieniach multimedialnych, zdarzeń multimedialnych, takich jak odtwarzanie, wstrzymywanie, przeskakiwanie, zmiana utworu, oraz zdarzeń konferencji wideo, takich jak wyciszenie/wyciszanie mikrofonu, włączanie/wyłączanie kamery i rozłączanie. Te dostosowania są dostępne w kilku kontekstach, w tym w centrach multimedialnych na komputerach, w powiadomieniach o multimediach na urządzeniach mobilnych, a nawet na urządzeniach do noszenia. W tym artykule opiszę te opcje.

Informacje o interfejsie Media Session API

Interfejs Media Session API ma kilka korzyści i możliwości:

• Obsługiwane są klucze sprzętowe.
• Powiadomienia o multimediach są dostosowywane na urządzeniu mobilnym, komputerze i sparowanym urządzeniu do noszenia.
• Centrum multimediów jest dostępne na komputerach.
• Opcje sterowania multimediami na ekranie blokady są dostępne na urządzeniach z ChromeOS i urządzeniach mobilnych.
• Elementy sterujące oknem obrazu w obrazie są dostępne w przypadku odtwarzania dźwięku, wideokonferencji i prezentacji slajdów.
• Integracja z Asystentem jest dostępna na urządzeniach mobilnych.

Poniżej przedstawiamy kilka przykładów ilustrujących niektóre z tych kwestii.

Przykład 1: jeśli użytkownicy nacisną klawisz multimedialny „następny utwór” na klawiaturze, deweloperzy internetowi mogą obsłużyć to działanie niezależnie od tego, czy przeglądarka jest na pierwszym czy drugim planie.

Przykład 2. Jeśli użytkownicy słuchają podcastu w internecie, gdy ekran urządzenia jest zablokowany, nadal mogą kliknąć ikonę „przewiń do tyłu” w elementach sterujących multimediów na ekranie blokady, aby deweloperzy internetowi przesunęli czas odtwarzania o kilka sekund do tyłu.

Przykład 3. Jeśli użytkownicy mają karty z odtwarzanym dźwiękiem, mogą łatwo zatrzymać odtwarzanie z poziomu panelu multimediów na komputerze. Dzięki temu deweloperzy stron internetowych mogą wyczyścić stan.

Przykład 4. Jeśli użytkownicy prowadzą rozmowę wideo, mogą w oknie Picture-in-Picture kliknąć przełącznik mikrofonu, aby strona internetowa przestała otrzymywać dane z mikrofonu.

Wszystko to można zrobić w 2 interfejsach: MediaSession i MediaMetadata. Pierwszy pozwala użytkownikom kontrolować to, co jest odtwarzane. Druga kwestia to sposób, w jaki MediaSession określa, co ma być kontrolowane.

Na ilustracji poniżej widać, jak te interfejsy są powiązane z konkretnymi elementami sterującymi multimediami, w tym przypadku z powiadomieniami o multimediach na urządzeniu mobilnym.

Informuj użytkowników o utworach

Gdy strona odtwarza dźwięk lub obraz, użytkownicy automatycznie otrzymują powiadomienia o multimediach na pasku powiadomień na urządzeniu mobilnym lub w centrum multimediów na komputerze. Przeglądarka stara się wyświetlać odpowiednie informacje, korzystając z tytułu dokumentu i największego znalezionego obrazu ikony. Dzięki interfejsowi API sesji multimedialnej można dostosować powiadomienie multimedialne, korzystając z bardziej rozbudowanych metadanych multimediów, takich jak tytuł, nazwa wykonawcy, nazwa albumu i grafika, jak pokazano poniżej.

Chrome prosi o „pełne” skupienie na dźwięku, aby wyświetlać powiadomienia o multimediach tylko wtedy, gdy czas trwania multimediów wynosi co najmniej 5 sekund. Dzięki temu przypadkowe dźwięki, takie jak dźwięki dzwonka, nie będą wyświetlać powiadomień.

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

Po zakończeniu odtwarzania nie musisz „zwalniać” sesji multimediów, ponieważ powiadomienie zniknie automatycznie. Pamiętaj jednak, że podczas następnego odtwarzania będzie używany adres navigator.mediaSession.metadata. Dlatego ważne jest, aby zaktualizować go, gdy zmieni się źródło odtwarzania multimediów, aby mieć pewność, że w powiadomieniu o multimediach będą wyświetlane odpowiednie informacje.

Pamiętaj o kilku kwestiach dotyczących metadanych multimediów.

• Tablica elementów graficznych powiadomienia obsługuje adresy URL typu blob: i data:.
• Jeśli nie zdefiniujesz grafiki, a obraz ikony (określony za pomocą <link rel=icon>) ma odpowiedni rozmiar, będzie on używany w powiadomieniach multimedialnych.
• Rozmiar docelowy grafiki powiadomienia w Chrome na Androida to 512x512. W przypadku urządzeń niskiej klasy jest to 256x256.
• Atrybut title elementu HTML multimediów jest używany w widżecie „Co jest grane” w systemie macOS.
• Jeśli zasób multimedialny jest umieszczony (na przykład w elemencie iframe), informacje o interfejsie Media Session API muszą pochodzić z umieszczonego kontekstu. Zobacz fragment poniżej.

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

Do metadanych multimediów możesz też dodać informacje o poszczególnych rozdziałach, takie jak tytuł, sygnatura czasowa i obraz zrzutu ekranu. Dzięki temu użytkownicy mogą poruszać się po treściach multimediów.

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

Pozwól użytkownikom sterować odtwarzaniem

Działanie sesji multimediów to działanie (np. „odtwórz” lub „zatrzymaj”), które witryna może wykonać dla użytkowników, gdy ci wchodzą w interakcję z bieżącym odtwarzaniem multimediów. Działania są podobne do zdarzeń i działają w podobny sposób. Podobnie jak zdarzenia, działania są implementowane przez ustawienie modułów obsługi w odpowiednim obiekcie, w tym przypadku instancji klasy MediaSession. Niektóre działania są wywoływane, gdy użytkownicy nacisną przyciski w słuchawkach, innym urządzeniu zdalnym lub na klawiaturze albo wejdą w interakcję z powiadomieniem multimedialnym.

Niektóre działania w ramach sesji multimedialnych mogą nie być obsługiwane, dlatego podczas ich konfigurowania zalecamy użycie bloku try…catch.

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

Wyłączenie modułu obsługi działania sesji multimedialnej jest tak proste jak ustawienie go na 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.`);
}

Po ustawieniu moduły obsługi czynności sesji multimediów będą działać podczas odtwarzania multimediów. Jest to podobne do wzorca detektora zdarzeń, z tym że obsługa zdarzenia oznacza, że przeglądarka przestanie działać domyślne i wykorzystuje to jako sygnał, że witryna obsługuje działanie związane z multimediami. Dlatego elementy sterujące działaniem multimediów nie będą widoczne, dopóki nie ustawisz odpowiedniego modułu obsługi.

Odtwarzanie / wstrzymywanie

Działanie "play" wskazuje, że użytkownik chce wznowić odtwarzanie multimediów, a "pause" wskazuje na chęć tymczasowego zatrzymania odtwarzania.

Ikona „odtwórz/wstrzymaj” jest zawsze wyświetlana w powiadomieniu o multimediach, a powiązane z nim zdarzenia multimedialne są obsługiwane automatycznie przez przeglądarkę. Aby zastąpić domyślne działanie, obsłuż akcje „odtwórz” i „wstrzymaj” w mediach, jak pokazano poniżej.

Podczas przewijania lub wczytywania przeglądarka może uznać, że strona internetowa nie odtwarza multimediów. W tym przypadku możesz zmienić to zachowanie, ustawiając wartość navigator.mediaSession.playbackState na "playing" lub "paused", aby interfejs witryny był zsynchronizowany z ustawieniami powiadomień o mediach.

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

Poprzedni utwór

Działanie "previoustrack" wskazuje, że użytkownik chce rozpocząć odtwarzanie bieżącego multimediów od początku, jeśli odtwarzanie ma charakter początkowy, lub przejść do poprzedniego elementu na playliście, jeśli odtwarzanie ma charakter playlisty.

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

Następny utwór

Działanie "nexttrack" wskazuje, że użytkownik chce przenieść odtwarzanie multimediów do następnego elementu na playliście, jeśli odtwarzanie multimediów ma pojęcie playlisty.

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

Zatrzymaj

Działanie "stop" wskazuje, że użytkownik chce zatrzymać odtwarzanie multimediów i w odpowiednim przypadku wyczyścić stan.

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

Przewijanie do tyłu/do przodu

Działanie "seekbackward" wskazuje, że użytkownik chce przesunąć czas odtwarzania multimediów o krótki okres w tył, a działanie "seekforward" wskazuje, że chce przesunąć czas odtwarzania multimediów o krótki okres do przodu. W obu przypadkach krótki okres oznacza kilka sekund.

Wartość seekOffset podana w module obsługi działań to czas (w sekundach) przesuwany w czasie odtwarzania multimediów. Jeśli nie jest podany (np. undefined), wybierz odpowiedni czas (np. 10–30 sekund).

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

Przewijanie do konkretnego momentu

Działanie "seekto" wskazuje, że użytkownik chce przesunąć czas odtwarzania multimediów do określonego momentu.

Wartość seekTime podana w obiekcie obsługi działania to czas w sekundach, o który przesunąć odtwarzanie multimediów.

Argument typu boolean fastSeek podany w obiekcie obsługującym działanie ma wartość true, jeśli działanie jest wywoływane wielokrotnie w ramach sekwencji i nie jest to ostatnie wywołanie w tej sekwencji.

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

Ustawianie pozycji odtwarzania

Dokładne wyświetlenie w powiadomieniu pozycji odtwarzania sprowadza się do ustawienia stanu pozycji w odpowiednim momencie, jak pokazano poniżej. Stan pozycji to kombinacja szybkości odtwarzania multimediów, czasu trwania i bieżącego czasu.

Czas trwania musi być podany i dodatni. Pozycja musi być dodatnia i mniejsza niż czas trwania. Szybkość odtwarzania musi być większa niż 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();
});

Resetowanie stanu pozycji jest bardzo proste. Wystarczy ustawić wartość null.

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

Czynności związane z rozmowami wideo

Gdy użytkownik otwiera rozmowę wideo w oknie obrazu w obrazie, przeglądarka może wyświetlać opcje mikrofonu i kamery oraz możliwość rozłączania się. Gdy użytkownik kliknie te opcje, witryna przeprowadzi go do działań związanych z wideokonferencjami opisanych poniżej. Przykładem jest rozmowa wideo.

Włącz lub wyłącz mikrofon

Działanie "togglemicrophone" wskazuje, że użytkownik chce wyciszyć lub włączyć mikrofon. Metoda setMicrophoneActive(isActive) informuje przeglądarkę, czy w danym momencie witryna uważa, że mikrofon jest aktywny.

let isMicrophoneActive = false;

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

Przełącz aparat

Działanie "togglecamera" wskazuje, że użytkownik chce włączyć lub wyłączyć aktywną kamerę. Metoda setCameraActive(isActive) wskazuje, czy przeglądarka uważa, że strona jest aktywna.

let isCameraActive = false;

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

rozłączyć połączenie,

Działanie "hangup" wskazuje, że użytkownik chce zakończyć połączenie.

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

Działanie podczas wyświetlania slajdów

Gdy użytkownik umieści prezentację slajdów w oknie obrazu w obrazie, przeglądarka może wyświetlić elementy sterujące do poruszania się po slajdach. Gdy użytkownik kliknie te linki, witryna przekieruje go do nich za pomocą interfejsu Media Session API. Przykład znajdziesz w przykładzie prezentacji.

Poprzedni slajd

Działanie "previousslide" wskazuje, że użytkownik chce wrócić do poprzedniej slajdu podczas prezentacji.

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

Następny slajd

Działanie "nextslide" wskazuje, że użytkownik chce przejść do następnego slajdu podczas prezentacji slajdów.

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

Przykłady

Zapoznaj się z przykładami sesji medialnej, w których występuje Blender Foundation i prace Jana Morgensterna.

Zasoby

• Specyfikacja sesji multimediów: wicg.github.io/mediasession
• Problemy ze specyfikacją: github.com/WICG/mediasession/issues
• Błędy w Chrome: crbug.com