Media Session API로 미디어 알림 및 재생 컨트롤 맞춤설정

하드웨어 미디어 키와 통합하고 미디어 알림을 맞춤설정하는 방법 등을 알아봅니다.

François Beaufort
François Beaufort
GitHub

사용자에게 현재 브라우저에서 재생 중인 콘텐츠를 알리고 제어할 수 있도록 하기 위해 Media Session API가 을 도입하였습니다. 이를 통해 웹 개발자는 사용자 지정 미디어 알림의 메타데이터, 재생, 일시중지, 탐색, 변경 추적, 화상 회의 일정(예: 음소거/음소거 해제) 마이크, 켜기/끄기, 전화를 끊을 수 있습니다. 이러한 맞춤설정은 데스크톱 미디어 허브, 미디어 알림, 미디어 알림 등 모바일, 심지어 웨어러블 기기에서도 사용할 수 있습니다. 이러한 맞춤설정에 대해서는 이 도움말을 참고하세요.

<ph type="x-smartling-placeholder">
</ph> 미디어 세션 컨텍스트의 스크린샷
데스크톱의 미디어 허브, 모바일, 웨어러블 기기의 미디어 알림

Media Session API 정보

Media Session API는 다음과 같은 여러 이점과 기능을 제공합니다.

  • 하드웨어 미디어 키가 지원됩니다.
  • 미디어 알림은 모바일, 데스크톱 및 페어링된 웨어러블 기기에서 맞춤설정됩니다.
  • 미디어 허브는 데스크톱에서 사용할 수 있습니다.
  • 잠금 화면 미디어 컨트롤은 ChromeOS 및 휴대기기에서 사용할 수 있습니다.
  • PIP 모드 창 컨트롤은 오디오 재생에 사용할 수 있습니다. 화상 회의, 슬라이드 발표 등입니다.
  • 휴대기기에서 어시스턴트 통합을 사용할 수 있습니다.

브라우저 지원

  • Chrome: 73 <ph type="x-smartling-placeholder">
  • Edge: 79. <ph type="x-smartling-placeholder">
  • Firefox: 82. <ph type="x-smartling-placeholder">
  • Safari: 15. <ph type="x-smartling-placeholder">

소스

몇 가지 예를 통해 이러한 내용을 설명합니다.

예 1: 사용자가 '다음 트랙'을 누르는 경우 키보드의 미디어 키 웹 개발자는 브라우저가 포그라운드에 있든 상관없이 이 사용자 작업을 처리할 수 있습니다. 만들 수 있습니다.

예 2: 사용자가 기기를 사용하는 동안 웹에서 팟캐스트를 듣는 경우 화면이 잠겨 있어도 '뒤로 탐색' 버튼을 자물쇠 아이콘 웹 개발자가 재생 시간을 몇 배 뒤로 늦출 수 있도록 초입니다.

예 3: 사용자가 오디오를 재생하는 탭이 있는 경우 쉽게 중지할 수 있습니다. 데스크톱의 미디어 허브에서 재생할 수 있도록 하여 웹 개발자가 상태를 삭제할 수 있습니다

예 4: 사용자가 영상 통화 중인 경우 '전환 버튼 마이크" 컨트롤을 사용하여 웹사이트를 더 이상 사용하지 않도록 수신 중입니다.

이 작업은 모두 두 가지 인터페이스, 즉 MediaSession 인터페이스를 통해 실행됩니다. MediaMetadata 인터페이스를 지원합니다. 첫 번째는 사용자가 직접 제어해야 하는 있습니다. 두 번째는 제어해야 할 대상을 MediaSession에 알리는 방법입니다.

아래 이미지는 이러한 인터페이스가 특정 애플리케이션, 미디어 컨트롤(이 경우 모바일의 미디어 알림)

<ph type="x-smartling-placeholder">
</ph> 미디어 세션 인터페이스 그림
모바일의 미디어 알림 분석

사용자에게 재생 중인 음악 알리기

웹사이트에서 오디오 또는 동영상을 재생할 때 사용자에게 자동으로 미디어가 재생됩니다. 휴대기기의 알림 트레이나 기기의 미디어 허브에서 알림을 확인할 수 있습니다. 있습니다. 브라우저는 찾을 수 있는 가장 큰 아이콘 이미지여야 합니다. 미디어 세션 사용 API를 사용하면 좀 더 풍부한 미디어로 미디어 알림을 맞춤설정할 수 있습니다. 메타데이터(예: 제목, 아티스트 이름, 앨범 이름, 아트워크)를 생성할 수 있습니다.

Chrome에서 'full'을 요청함 오디오 포커스는 미디어 길이가 5초 이상이어야 합니다. 이를 통해 부수적인 소리가 나는 알림이 표시되지 않습니다.

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

재생이 끝나면 손을 떼지 않아도 됩니다. 미디어 세션을 알림이 자동으로 사라집니다. 다음 사항을 명심하세요 다음 재생이 시작되면 navigator.mediaSession.metadata이(가) 사용됩니다. 하지만 따라서 미디어 재생 소스가 시작 또는 종료되었을 때 미디어 알림에 관련 정보가 표시되도록 변경합니다.

미디어 메타데이터에 관해 알아야 할 몇 가지 사항이 있습니다.

  • 알림 아트워크 배열은 blob URL과 데이터 URL을 지원합니다.
  • 아트워크가 정의되어 있지 않고 원하는 크기의 아이콘 이미지 (<link rel=icon>를 사용하여 지정됨)가 있는 경우 미디어 알림에서 이 아트워크를 사용합니다.
  • Android용 Chrome의 알림 아트워크 대상 크기는 512x512입니다. 대상 256x256입니다.
  • 미디어 HTML 요소의 title 속성은 '지금 재생 중'에서 사용됩니다. macOS 위젯입니다.
  • 미디어 리소스가 삽입된 경우 (예: iframe에), Media Session API가 정보는 삽입된 컨텍스트에서 설정해야 합니다. 아래 스니펫을 참조하세요.
<iframe id="iframe">
  <video>...</video>
</iframe>
<script>
  iframe.contentWindow.navigator.mediaSession.metadata = new MediaMetadata({
    title: 'Never Gonna Give You Up',
    ...
  });
</script>

섹션 제목, 타임스탬프, 스크린샷 이미지와 같은 개별 챕터 정보를 미디어 메타데이터에 추가할 수도 있습니다. 이를 통해 사용자는 미디어 콘텐츠를 탐색할 수 있습니다.

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' },
    ]
  }]
});
드림 <ph type="x-smartling-placeholder">
</ph> ChromeOS 미디어 알림에 표시되는 챕터 정보입니다.
ChromeOS의 챕터가 포함된 미디어 알림
를 통해 개인정보처리방침을 정의할 수 있습니다.

사용자가 재생 중인 콘텐츠를 제어하도록 허용

미디어 세션 작업은 웹사이트에서 수행할 수 있는 작업 (예: '재생' 또는 '일시중지')입니다. 사용자가 현재 미디어 재생과 상호 작용할 때 핸들에 놓입니다. 액션은 이벤트와 유사하며 이벤트와 거의 동일하게 작동합니다. 이벤트와 마찬가지로 액션도 적절한 객체, 즉 Kubernetes 클러스터의 인스턴스인 여기서는 MediaSession입니다. 사용자가 키를 누르면 일부 작업이 트리거됩니다. 헤드셋, 다른 원격 기기, 키보드의 버튼이나 조작하려는 미디어 알림

<ph type="x-smartling-placeholder">
</ph> Windows 10의 미디어 알림 스크린샷.
Windows 10의 맞춤설정된 미디어 알림

일부 미디어 세션 작업이 지원되지 않을 수 있으므로 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.`);
  }
}

미디어 세션 작업 핸들러를 설정 해제하려면 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.`);
}

설정되면 미디어 세션 작업 핸들러는 미디어 재생 중에도 유지됩니다. 이는 이벤트 처리와 비슷하다는 점을 제외하면 이벤트 리스너 패턴과 유사합니다. 브라우저가 기본 동작을 중단하고 이것을 기본 동작으로 신호를 보냅니다. 따라서 미디어 작업 제어는 적절한 작업 핸들러가 설정되지 않으면 표시되지 않습니다.

<ph type="x-smartling-placeholder">
</ph> macOS Big Sur의 Now Playing 위젯 스크린샷
macOS Big Sur의 Now Playing 위젯

재생 / 일시중지

"play" 작업은 사용자가 미디어 재생을 재개하려고 함을 나타냅니다. "pause"는 일시적으로 중지하려는 의향을 나타냅니다.

'재생/일시중지' 아이콘이 항상 미디어 알림과 관련 미디어 이벤트는 브라우저에서 자동으로 처리됩니다. 기본값을 재정의하려면 다음 단계를 따르세요. '재생'을 처리합니다. 및 '일시중지' 미디어 작업을 실행합니다.

브라우저에서는 미디어를 탐색할 때 웹사이트에서 미디어를 재생하지 않는 것으로 간주하거나 예로 들 수 있습니다 이 경우 다음과 같이 설정하여 이 동작을 재정의합니다. navigator.mediaSession.playbackState에서 "playing" 또는 "paused"로 변경하여 웹사이트 UI가 미디어 알림 컨트롤과 동기화 상태를 유지합니다.

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

이전 트랙

"previoustrack" 작업은 사용자가 미디어 재생에 미디어가 재생 중인 경우 재생목록의 이전 항목으로 이동합니다. 재생목록의 개념이 있습니다.

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

다음 트랙

"nexttrack" 작업은 사용자가 미디어 재생을 이동하려고 함을 나타냅니다. 미디어 재생에 재생목록이라는 개념이 있는 경우 재생목록의 다음 항목을 반환합니다.

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

중지

"stop" 작업은 사용자가 미디어 재생을 중지하고 상태를 삭제할 수도 있습니다.

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

뒤로 / 앞으로 탐색

"seekbackward" 작업은 사용자가 미디어를 이동하려고 함을 나타냅니다. 재생 시간을 짧은 시간 뒤로 뒤로 하고 "seekforward"은 미디어 재생 시간을 조금 앞당겨야 합니다. 두 경우 모두 짧은 기간은 몇 초를 의미합니다.

작업 핸들러에 제공된 seekOffset 값은 조정할 수 있습니다. 제공되지 않으면 (예: undefined) 적절한 시간 (예: 10~30초)을 사용해야 합니다.

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

특정 시간 탐색

"seekto" 작업은 사용자가 미디어 재생을 이동하려고 함을 나타냅니다. 특정 시간으로 설정할 수 있습니다

작업 핸들러에 제공된 seekTime 값은 미디어 재생 시간을 이동합니다

작업이 다음과 같은 경우 작업 핸들러에 제공된 fastSeek 부울은 true입니다. 시퀀스의 일부로 여러 번 호출되며 마지막 호출이 아님 삽입해야 합니다.

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

재생 위치 설정

알림에 미디어 재생 위치를 정확하게 표시하는 것은 매우 간단합니다. 위치 상태를 아래와 같이 적절한 시점에 설정할 수 있습니다. 이 위치 상태는 미디어 재생 속도, 재생 시간 및 확인할 수 있습니다.

<ph type="x-smartling-placeholder">
</ph> ChromeOS의 잠금 화면 미디어 컨트롤 스크린샷
ChromeOS의 잠금 화면 미디어 컨트롤.

기간은 양수로 입력해야 합니다. 위치는 양수여야 하며 재생 시간보다 짧아야 합니다. 재생 속도는 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();
});

위치 상태를 재설정하는 것은 null로 설정하는 것만큼 쉽습니다.

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

화상 회의 작업

사용자가 영상 통화를 PIP 모드 창에 넣으면 브라우저에 마이크 및 카메라 및 전화를 끊는 컨트롤이 표시될 수 있습니다. 사용자가 클릭하면 웹사이트에서 동영상을 처리합니다. 아래에 설명된 회의 작업을 확인하세요. 예를 보려면 화상 회의 샘플을 참고하세요.

<ph type="x-smartling-placeholder">
</ph> PIP 모드 창에 표시된 화상 회의 컨트롤 스크린샷
PIP 모드의 화상 회의 제어 기능
를 통해 개인정보처리방침을 정의할 수 있습니다.

마이크 전환

"togglemicrophone" 작업은 사용자가 음소거 또는 음소거 해제를 원함을 나타냅니다. 있습니다. setMicrophoneActive(isActive) 메서드는 브라우저에 웹사이트에서 현재 마이크가 활성으로 간주되고 있는지 여부

let isMicrophoneActive = false;

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

카메라 전환

"togglecamera" 작업은 사용자가 활성 상태로 전환하려고 함을 나타냅니다. 선택할 수 있습니다. setCameraActive(isActive) 메서드는 브라우저가 웹사이트를 활성 상태로 간주합니다.

let isCameraActive = false;

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

전화 끊기

"hangup" 작업은 사용자가 통화를 종료하려고 함을 나타냅니다.

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

슬라이드 작업 표시

사용자가 슬라이드 프레젠테이션을 PIP 모드 창에 넣으면 브라우저에 슬라이드 탐색 컨트롤이 표시될 수 있습니다. 사용자가 클릭하면 웹사이트가 Media Session API를 통해 처리합니다. 프레젠테이션 발표 샘플을 참고하세요.

이전 슬라이드

"previousslide" 작업은 사용자가 이전 슬라이드에 대해 설명하겠습니다.

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

브라우저 지원

  • Chrome: 111 <ph type="x-smartling-placeholder">
  • Edge: 111. <ph type="x-smartling-placeholder">
  • Firefox: 지원되지 않음 <ph type="x-smartling-placeholder">
  • Safari: 지원되지 않음 <ph type="x-smartling-placeholder">

다음 슬라이드

"nextslide" 작업은 사용자가 다음 슬라이드로 이동하려고 함을 나타냅니다. 할 수 있습니다.

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

브라우저 지원

  • Chrome: 111 <ph type="x-smartling-placeholder">
  • Edge: 111. <ph type="x-smartling-placeholder">
  • Firefox: 지원되지 않음 <ph type="x-smartling-placeholder">
  • Safari: 지원되지 않음 <ph type="x-smartling-placeholder">

샘플

Blender Foundation을 소개하는 미디어 세션 샘플을 확인하고 얀 모겐스턴의 작품

<ph type="x-smartling-placeholder">
</ph> <ph type="x-smartling-placeholder">
Media Session API를 보여주는 스크린캐스트

리소스