Ta strona została przetłumaczona przez Cloud Translation API.

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

Integracja ze sprzętowymi klawiszami multimedialnymi, dostosowywanie powiadomień o multimediach i inne funkcje.

François Beaufort

GitHub

Interfejs Media Session API został wdrożony, aby umożliwić użytkownikom sprawdzanie, co jest aktualnie odtwarzane w przeglądarce, oraz kontrolowanie ich bez konieczności powrotu na stronę, na której została ona uruchomiona. Umożliwia ona dostosowanie tego interfejsu za pomocą metadanych w niestandardowych powiadomieniach multimedialnych, zdarzeń multimedialnych takich jak odtwarzanie, wstrzymywanie, przeszukiwanie, zmienianie ścieżki oraz zdarzenia dotyczące rozmów wideo (np. wyciszanie/wyłączanie wyciszenia mikrofonu, włączanie/wyłączanie kamery i rozłączanie). Te dostosowania są dostępne w kilku kontekstach, m.in. w centrach multimediów na komputerze, w powiadomieniach o multimediach na urządzeniach mobilnych, a nawet na urządzeniach do noszenia. W tym artykule omówię te dostosowania.

Zrzuty ekranu przedstawiające konteksty sesji z mediami. — Media Hub na komputerze, powiadomienia o multimediach na urządzeniach mobilnych i urządzenia do noszenia.

Informacje o interfejsie Media Session API

Interfejs Media session API ma kilka zalet i możliwości:

Sprzętowe klawisze multimedialne są obsługiwane.
Powiadomienia o multimediach są dostosowywane na urządzeniach mobilnych, komputerach i sparowanych urządzeniach do noszenia.
Centrum multimediów jest dostępne na komputerze.
Opcje sterowania multimediami na ekranie blokady są dostępne na urządzeniach z ChromeOS i urządzeniami mobilnymi.
Elementy sterujące oknem obrazu w obrazie są dostępne podczas odtwarzania dźwięku, rozmów wideo i prezentowania slajdów.
Dostępna jest integracja z Asystentem na urządzeniach mobilnych.

Obsługa przeglądarek

Źródło

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

Przykład 1: jeśli użytkownik naciśnie klawisz multimedialny „Następna ścieżka” na klawiaturze, deweloperzy stron internetowych mogą wykonać to działanie niezależnie od tego, 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ą kliknąć ikonę przewijania do tyłu na ekranie blokady, aby deweloperzy mogli przesunąć czas odtwarzania o kilka sekund wstecz.

Przykład 3: jeśli użytkownicy mają karty, które odtwarzają dźwięk, mogą łatwo zatrzymać odtwarzanie w centrum multimediów na komputerze, aby deweloperzy stron internetowych mogli wyczyścić swoje ustawienia.

Przykład 4: jeśli użytkownicy uczestniczą w rozmowie wideo, mogą nacisnąć przełącznik „przełącz mikrofon” w oknie obrazu w obrazie, by witryna nie odbierała danych z mikrofonu.

Wszystko to odbywa się za pomocą 2 interfejsów: MediaSession i MediaMetadata. Pierwszy pozwala użytkownikowi kontrolować odtwarzane treści. Po drugie, wskazujesz, co MediaSession ma kontrolować.

Poniższy przykład pokazuje, jak te interfejsy odnoszą się do określonych opcji sterowania multimediami, w tym przypadku z powiadomieniem na urządzeniu mobilnym.

Ilustracja przedstawiająca interfejsy sesji z multimediami — Struktura powiadomień o multimediach na urządzeniach mobilnych.

Informuj użytkowników, co jest odtwarzane

Gdy witryna odtwarza dźwięk lub obraz, użytkownicy automatycznie otrzymują powiadomienia o multimediach na pasku powiadomień na urządzeniach mobilnych lub w centrum multimediów na komputerach. Przeglądarka robi wszystko, co w pełni możliwości, by pokazać odpowiednie informacje, używając tytułu dokumentu i największego możliwego obrazu ikony. Interfejs Media Session API umożliwia dostosowanie powiadomień multimedialnych przez dodanie bardziej multimedialnych metadanych, takich jak tytuł, nazwa wykonawcy, nazwa albumu i grafika, jak pokazano poniżej.

Chrome prosi o „pełne” zaznaczenie 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ą sygnalizowane przypadkowymi dźwiękami, np. dźwiękami.

// 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, że po rozpoczęciu następnego odtwarzania zostanie użyta wartość navigator.mediaSession.metadata. Dlatego ważne jest zaktualizowanie go, gdy źródło odtwarzania multimediów ulegnie zmianie, aby mieć pewność, że powiadomienie o multimediach zawiera istotne informacje.

Należy pamiętać o kilku kwestiach dotyczących metadanych multimediów.

Tablica grafiki powiadomień obsługuje adresy URL obiektów blob i danych.
Jeśli nie zdefiniowano żadnej grafiki, a obraz ikony (określony przy użyciu <link rel=icon>) ma odpowiedni rozmiar, będzie używany w powiadomieniach o multimediach.
Rozmiar docelowy grafiki powiadomień w Chrome na Androida to 512x512. W przypadku mniej zaawansowanych urządzeń jest to 256x256.
Atrybut title elementu HTML multimediów jest używany w widżecie „Now odtwarzany” w systemie macOS.
Jeśli zasób multimedialny jest umieszczony (na przykład w elemencie iframe), informacje z interfejsu Media Session API muszą być ustawione na podstawie tego 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>

Pozwól użytkownikom kontrolować, co jest odtwarzane

Akcja sesji multimediów to działanie (np. „odtworzenie” lub „wstrzymanie”), które witryna może wykonać, gdy użytkownik wejdzie 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 w odpowiednim obiekcie, w instancji MediaSession. Niektóre działania są wykonywane, gdy użytkownik naciśnie przyciski na zestawie słuchawkowym, na innym urządzeniu zdalnym lub na klawiaturze albo gdy wejdzie w interakcję z powiadomieniem multimedialnym.

Zrzut ekranu z powiadomieniem o multimediach w systemie Windows 10. — Niestandardowe powiadomienia o multimediach w systemie Windows 10.

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

Aby wyłączyć moduł obsługi sesji multimediów, wystarczy zmienić jego ustawienie 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 skonfigurowaniu moduły obsługi działań w ramach sesji multimediów będą odtwarzane podczas odtwarzania multimediów. Działa to podobnie do wzorca odbiornika, ale obsługa zdarzenia oznacza, że przeglądarka przestaje wykonywać domyślne działanie i używa go jako sygnału, że witryna obsługuje działanie związane z multimediami. Elementy sterujące działań związanych z multimediami nie będą więc widoczne, jeśli nie zostanie skonfigurowany odpowiedni moduł obsługi działań.

Zrzut ekranu widżetu Co jest grane w systemie macOS Big Sur. — Widżet Co jest grane w systemie macOS Big Sur.

Odtwarzanie / wstrzymywanie

Czynność "play" wskazuje, że użytkownik chce wznowić odtwarzanie multimediów, a "pause" wskazuje na potrzebę tymczasowego wstrzymania odtwarzania.

Ikona odtwarzania/wstrzymywania jest zawsze widoczna w powiadomieniu o multimediach, a powiązane z nimi zdarzenia multimedialne są obsługiwane automatycznie przez przeglądarkę. Aby zastąpić domyślne działanie, skonfiguruj działania związane z multimediami „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 zachowanie, ustawiając dla zasady navigator.mediaSession.playbackState wartość "playing" lub "paused", aby interfejs witryny był zsynchronizowany z ustawieniami powiadomień multimedialnych.

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

Poprzednia ścieżka

Czynność "previoustrack" wskazuje, że użytkownik chce rozpocząć odtwarzanie multimediów od początku, jeśli ma pojęcie „rozpoczynania”, lub przejść do poprzedniego elementu na playliście, jeśli jest powiązana z playlistą.

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

Następna ścieżka

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

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

Zatrzymaj

Czynność "stop" wskazuje, że użytkownik chce zatrzymać odtwarzanie multimediów i w razie potrzeby wyczyścić stan.

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

Przewiń do tyłu lub do przodu

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

Wartość seekOffset podana w module obsługi działań to czas (w sekundach), o który przesuwa się czas odtwarzania multimediów. Jeśli go nie podasz (np. undefined), użyj 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

Czynność "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), o który ma być przesuwany czas odtwarzania multimediów.

Wartość logiczna fastSeek podana w module obsługi działań 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 dokładnie wyświetlić pozycję odtwarzania multimediów w powiadomieniu, wystarczy ustawić stan pozycji w odpowiednim momencie, jak pokazano poniżej. Stan pozycji to połączenie szybkości odtwarzania multimediów, czasu trwania i bieżącego czasu.

Zrzut ekranu przedstawiający opcje sterowania multimediami na ekranie blokady w ChromeOS. — Sterowanie multimediami na ekranie blokady w ChromeOS.

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 znajdzie rozmowę wideo w oknie obrazu w obrazie, przeglądarka może wyświetlić elementy sterujące mikrofonem i kamerą oraz zakończyć rozłączanie. Gdy użytkownik je kliknie, strona obsługuje je, wykonując opisane poniżej czynności dotyczące rozmów wideo. Przykład znajdziesz w przykładzie rozmowy wideo.

Zrzut ekranu przedstawiający elementy sterujące rozmową wideo w oknie obrazu w obrazie. — Elementy sterujące rozmową wideo w oknie obrazu w obrazie.

Włącz lub wyłącz mikrofon

Czynność "togglemicrophone" wskazuje, że użytkownik chce wyciszyć mikrofon lub wyłączyć jego wyciszenie. Metoda setMicrophoneActive(isActive) informuje przeglądarkę, czy witryna obecnie uważa 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

Czynność "hangup" wskazuje, ż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. Po kliknięciu przez użytkownika witryna obsługuje je przez interfejs Media Session API. Przykład znajdziesz w tym artykule.

Poprzedni slajd

Czynność "previousslide" wskazuje, że podczas prezentacji użytkownik chce wrócić do poprzedniego slajdu.

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

Obsługa przeglądarek

Następny slajd

Czynność "nextslide" wskazuje, że użytkownik chce przejść do następnego slajdu podczas prezentacji.

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

Obsługa przeglądarek

Sample

Obejrzyj przykłady sesji medialnych, w których wykorzystano Blender Foundation i dzieło Jana Morgensterna.

Screencast ilustrujący interfejs Media Session API.

Zasoby

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