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

Integracja ze sprzętowymi klawiszami multimedialnymi, dostosowywanie powiadomień dotyczących multimediów itp.

Aby informować użytkowników o tym, co aktualnie jest odtwarzane w przeglądarce, oraz sterować nią bez konieczności powrotu na stronę, na której można ją uruchomić, wprowadziliśmy interfejs Media Session API. Umożliwia on programistom stron internetowych dostosowywanie tego interfejsu przez metadane w niestandardowych powiadomieniach o multimediach, zdarzeniach związanych z multimediami (odtwarzanie, wstrzymywanie, przewijanie, śledzenie zmian) oraz podczas rozmów wideo (np. wyciszanie/wyłączanie wyciszenia mikrofonu, włączanie/wyłączanie kamery czy rozłączanie się). Te dostosowania są dostępne w kilku kontekstach, m.in. w centrach multimediów na komputery, w powiadomieniach o multimediach na urządzeniach mobilnych, a nawet na urządzeniach do noszenia. W tym artykule omówię te dostosowania.

Informacje o interfejsie Media Session API

Interfejs Media session API ma kilka zalet:

• Sprzętowe klawisze multimedialne są obsługiwane.
• Powiadomienia o multimediach są dostosowywane na urządzeniach mobilnych, komputerach i sparowanych urządzeniach do noszenia.
• Media Hub jest dostępne na komputerach.
• Opcje sterowania multimediami na ekranie blokady są dostępne w systemie ChromeOS i urządzeniach mobilnych.
• Elementy sterujące oknami obrazu w obrazie umożliwiają odtwarzanie dźwięku, rozmowy wideo i prezentowanie slajdów.
• Dostępna jest integracja z Asystentem na urządzeniach mobilnych.

Kilka przykładów ilustruje niektóre z tych punktów.

Przykład 1. Jeśli użytkownik naciśnie klawisz multimedialny „Następna ścieżka” na klawiaturze, programiści mogą wykonać to działanie bez względu na to, czy przeglądarka działa na pierwszym planie, czy w tle.

Przykład 2: jeśli użytkownicy słuchają podcastu w internecie, gdy ekran urządzenia jest zablokowany, mogą nadal kliknąć ikonę przewijania do tyłu przy elementach sterujących multimediami na ekranie blokady. Dzięki temu deweloperzy stron internetowych mogą przesunąć czas odtwarzania do tyłu o kilka sekund.

Przykład 3: jeśli użytkownicy mają karty odtwarzające dźwięk, mogą łatwo zatrzymać odtwarzanie w centrum multimediów na komputerze, aby deweloperzy stron internetowych mieli szansę sprawdzić swój stan.

Przykład 4. Jeśli użytkownicy uczestniczą w rozmowie wideo, mogą nacisnąć przełącznik „Przełącz mikrofon” w oknie obrazu w obrazie, aby wyłączyć odbieranie danych z mikrofonu przez witrynę.

Wszystko to odbywa się za pomocą 2 różnych interfejsów: MediaSession i MediaMetadata. Pierwszy pozwala użytkownikom kontrolować odtwarzanie. Po drugie, informujesz MediaSession, co musi kontrolować.

Na ilustracji poniżej widać, jak te interfejsy są powiązane z określonymi opcjami sterowania multimediami, w tym przypadku z powiadomieniem o multimediach na urządzeniu mobilnym.

Poinformuj użytkowników, co jest odtwarzane

Gdy strona odtwarza dźwięk lub film, użytkownicy automatycznie otrzymują powiadomienia o multimediach na pasku powiadomień na urządzeniu mobilnym lub w centrum multimediów na komputerze. Przeglądarka dokłada wszelkich starań, aby wyświetlić odpowiednie informacje, używając tytułu dokumentu i największego dostępnego obrazu ikony. Za pomocą interfejsu Media Session API możesz dostosować powiadomienia multimedialne, dodając do nich metadane multimedialne, np. tytuł, nazwę wykonawcy, nazwę albumu i grafikę, jak pokazano poniżej.

Chrome wysyła żądanie „pełnego” dźwięku, aby wyświetlać powiadomienia o multimediach tylko wtedy, gdy czas trwania multimediów wynosi co najmniej 5 sekund. Dzięki temu powiadomienia nie będą pojawiać się w przypadkowych dźwiękach takich jak dzwonienie.

// 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 automatycznie zniknie. Pamiętaj, że pole navigator.mediaSession.metadata zostanie użyte, gdy rozpocznie się kolejne odtwarzanie. Dlatego tak ważne jest zaktualizowanie go po zmianie źródła odtwarzania multimediów, aby mieć pewność, że w powiadomieniu o multimediach widoczne są istotne informacje.

W związku z metadanymi multimediów trzeba pamiętać o kilku kwestiach.

• Tablica grafiki powiadomień obsługuje adresy URL obiektów blob i danych.
• Jeśli nie zdefiniowano żadnej grafiki i istnieje obraz ikony (określony przy użyciu <link rel=icon>) w pożądanym rozmiarze, będzie on używany w powiadomieniach o multimediach.
• Docelowy rozmiar grafiki powiadomień w Chrome na Androida to 512x512. W przypadku mniej zaawansowanych urządzeń jest to 256x256.
• Atrybut title elementu Media HTML jest używany w widżecie „Now odtwarzany” w widżecie macOS.
• Jeśli zasób multimedialny jest umieszczony (na przykład w elemencie iframe), informacje z interfejsu Media Session API muszą być ustawiane na podstawie tego kontekstu. Zobacz fragment kodu 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, np. tytuł, sygnaturę czasową czy obraz zrzutu ekranu. Umożliwia to użytkownikom poruszanie się po materiałach multimedialnych.

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 kontrolować odtwarzanie

Akcja sesji multimediów to działanie (np. „odtwórz” lub „wstrzymaj”), które może wykonać witryna użytkownika, gdy wchodzą w interakcję z odtwarzanym aktualnie odtwarzanym multimediam. Działania są podobne do zdarzeń i działają tak samo. Podobnie jak w przypadku zdarzeń, działania są wdrażane przez ustawienie modułów obsługi odpowiedniego obiektu, w tym przypadku wystąpienia MediaSession. Niektóre działania są wywoływane, gdy użytkownik naciśnie przyciski na zestawie słuchawkowym, innym urządzeniu zdalnym lub klawiaturze albo wejdzie w interakcję z powiadomieniem o multimediach.

Niektóre działania w ramach sesji multimedialnych mogą nie być obsługiwane, dlatego zalecamy ich konfigurowanie z blokadą 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.`);
  }
}

Aby wyłączyć moduł obsługi sesji multimedialnych, wystarczy ustawić 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 skonfigurowaniu moduły obsługi działań sesji multimedialnej będą zapamiętywane podczas odtwarzania multimediów. Ta funkcja jest podobna do wzorca detektora zdarzeń, z tą różnicą, że obsługa zdarzenia oznacza, że przeglądarka przestaje wykonywać domyślne działania i wykorzystuje je jako sygnał, że witryna obsługuje akcję multimedialną. Ustawienia akcji związanych z multimediami nie będą widoczne, jeśli nie zostanie ustawiony odpowiedni moduł obsługi działań.

Odtwarzanie / wstrzymywanie

Działanie "play" oznacza, że użytkownik chce wznowić odtwarzanie multimediów, a "pause" wskazuje, że chce tymczasowo je zatrzymać.

Ikona odtwarzania/wstrzymania jest zawsze widoczna w powiadomieniu o multimediach, a powiązane z nimi zdarzenia multimedialne są obsługiwane automatycznie przez przeglądarkę. Aby zastąpić ich domyślne działanie, obsługiwaj działania multimedialne „odtwórz” i „wstrzymaj”, jak pokazano poniżej.

Na przykład podczas wyszukiwania lub wczytywania przeglądarka może uznać, że witryna nie odtwarza multimediów. W takim przypadku zastąp to działanie, ustawiając dla zasady navigator.mediaSession.playbackState wartość "playing" lub "paused", aby zapewnić synchronizację interfejsu witryny z ustawieniami powiadomień o multimediach.

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" oznacza, że użytkownik chce rozpocząć odtwarzanie multimediów od początku, jeśli podczas odtwarzania multimediów określono, że się ono zaczyna, albo przejść do poprzedniego elementu na playliście, jeśli odtwarzanie multimediów jest powiązane z playlistą.

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

Następny utwór

Działanie "nexttrack" oznacza, że użytkownik chce przenieść odtwarzanie multimediów do następnego elementu na playliście, jeśli odtwarzanie multimediów jest powiązane z playlistą.

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

Zatrzymaj

Działanie "stop" oznacza, że użytkownik chce zatrzymać odtwarzanie multimediów i w razie potrzeby wyczyścić jego stan.

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

Przewijanie do tyłu lub do przodu

Działanie "seekbackward" oznacza, że użytkownik chce o krótki czas przesunąć czas odtwarzania multimediów do tyłu, a "seekforward" oznacza chęć przesunięcia czasu odtwarzania multimediów do przodu. W obu przypadkach krótki przedział czasu to kilka sekund.

Wartość seekOffset podana w module obsługi działań to czas (w sekundach), o jaki ma przesuwać się czas odtwarzania multimediów. Jeśli nie zostanie podany (np. undefined), należy użyć rozsądnego czasu (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.
});

Przewiń do określonego momentu

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

Wartość seekTime podana w module obsługi działań to czas (w sekundach), na który ma nastąpić zmiana czasu odtwarzania multimediów.

Wartość logiczna fastSeek podana w module obsługi działania ma wartość prawda, jeśli działanie jest wywoływane wiele razy 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.
});

Ustaw pozycję odtwarzania

Aby precyzyjnie określić pozycję odtwarzania multimediów w powiadomieniu, wystarczy ustawić stan pozycji we właściwym momencie, jak pokazano poniżej. Stan pozycji to wartość szybkości odtwarzania multimediów, czasu trwania i bieżącego czasu.

Czas trwania musi być wartością 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();
});

Aby zresetować stan pozycji, wystarczy zmienić jego ustawienie na null.

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

Działania związane z rozmowami wideo

Gdy użytkownik łączy rozmowę wideo w oknie obrazu w obrazie, przeglądarka może wyświetlić elementy sterujące mikrofonem i kamerą oraz się rozłączyć. Gdy użytkownik je kliknie, witryna przeprowadzi je w ramach poniższych działań wideokonferencyjnych. Przykładowe informacje znajdziesz w tym przykładzie.

Włącz lub wyłącz mikrofon

Działanie "togglemicrophone" oznacza, że użytkownik chce wyciszyć mikrofon lub wyłączyć jego wyciszenie. Metoda setMicrophoneActive(isActive) informuje przeglądarkę, czy witryna uznaje obecnie mikrofon za 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 kamerę

Czynność "togglecamera" wskazuje, że użytkownik chce włączyć lub wyłączyć aktywną kamerę. Metoda setCameraActive(isActive) wskazuje, czy przeglądarka uznaje witrynę za aktywną.

let isCameraActive = false;

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

Rozłącz

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

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

Działania związane z prezentowaniem slajdów

Gdy użytkownik umieści prezentację w oknie obrazu w obrazie, przeglądarka może wyświetlić elementy sterujące do poruszania się między slajdami. Witryna obsługuje te kliknięcia za pomocą interfejsu Media Session API. Przykład znajdziesz w artykule Przykładowe Prezentacje.

Poprzedni slajd

Działanie "previousslide" oznacza, że użytkownik chce wrócić do poprzedniego slajdu podczas prezentacji slajdów.

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

Następny slajd

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

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

Próbki

Obejrzyj przykłady sesji medialnych, które przedstawiają Blender Foundation i pracę 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