Media Session API'si ile medya bildirimlerini ve oynatma kontrollerini özelleştirme

Donanım medya tuşlarıyla entegrasyon, medya bildirimlerini özelleştirme ve daha fazlası.

Kullanıcıların tarayıcılarında o anda ne oynattığını bilmelerini ve tarayıcıyı başlatan sayfaya dönmeden bunu kontrol etmelerini sağlamak için Media Session API kullanıma sunuldu. Bu çözüm web geliştiricilerinin, özel medya bildirimlerindeki meta veriler ve oynatma, duraklatma, arama, değişiklikleri izleme gibi medya etkinlikleri ve mikrofonu kapatma/açma, kamerayı açma/kapatma ve telefonu kapatma gibi video konferans etkinlikleri aracılığıyla bu deneyimi özelleştirmelerine olanak tanır. Bu özelleştirmeler çeşitli bağlamlarda kullanılabilir. Örneğin, masaüstü medya hub'ları, mobil cihazlardaki medya bildirimleri ve hatta giyilebilir cihazlar. Söz konusu özelleştirmeleri bu makalede açıklayacağım.

Media Session API'si hakkında

Medya oturumu API'sı çeşitli avantajlar ve yetenekler sağlar:

• Donanım medya anahtarları desteklenir.
• Medya bildirimleri mobil cihazlarda, masaüstünde ve eşlenmiş giyilebilir cihazda özelleştirilir.
• Medya merkezi masaüstünde kullanılabilir.
• Kilit ekranı medya denetimleri ChromeOS ve mobil cihazlarda kullanılabilir.
• Pencere içinde pencere kontrolleri; ses çalma, video konferans ve sunum slaytları için kullanılabilir.
• Mobil cihazlarda Asistan entegrasyonu kullanılabilir.

Bu noktaların bazılarını birkaç örnekle açıklayacağız.

1. Örnek: Kullanıcılar klavyelerinin "sonraki parça" medya tuşuna basarsa web geliştiricileri, tarayıcının ön veya arka planda olmasına bakılmaksızın bu kullanıcı işlemini gerçekleştirebilir.

2. Örnek: Kullanıcılar cihaz ekranı kilitliyken web'de bir podcast dinlerlerse bile kilit ekranındaki medya denetimlerindeki "geriye sar" simgesine dokunabilirler. Böylece web geliştiricileri, oynatma süresini birkaç saniye geriye alabilir.

3. Örnek: Kullanıcıların ses çalan sekmeleri varsa masaüstündeki medya merkezinden oynatmayı kolayca durdurabilirler. Böylece web geliştiricilerine durumlarını temizleme şansı elde ederler.

4. Örnek: Kullanıcılar bir video görüşmesindeyse, web sitesinin mikrofon verilerini almasını durdurmak için Pencere İçinde Pencere penceresinde "mikrofonu aç/kapat" denetimine basabilir.

Bu işlemlerin tamamı iki farklı arayüz üzerinden gerçekleştirilir: MediaSession arayüzü ve MediaMetadata arayüzü. Birincisi, kullanıcıların oynatılan içeriği kontrol etmesine olanak tanır. İkincisi, MediaSession adlı CSS'ye neyin kontrol edilmesi gerektiğini nasıl bildirdiğinizdir.

Aşağıdaki resimde, bu arayüzlerin belirli medya denetimleriyle (bu örnekte mobil cihazlardaki medya bildirimi) ilişkisi gösterilmektedir.

Ne çaldığını kullanıcılara bildirin

Bir web sitesinde ses veya video oynatıldığında, kullanıcılar medya bildirimlerini mobil cihazlardaki bildirim tepsisinde veya masaüstündeki medya merkezinde otomatik olarak alır. Tarayıcı, dokümanın başlığını ve bulabildiği en büyük simge resmini kullanarak uygun bilgileri göstermek için elinden geleni yapar. Media Session API'si sayesinde medya bildirimini, aşağıda gösterildiği gibi başlık, sanatçı adı, albüm adı ve poster gibi bazı zengin medya meta verileriyle özelleştirebilirsiniz.

Chrome, yalnızca medya süresi en az 5 saniye olduğunda medya bildirimlerini göstermek için "tam" ses odağı ister. Bu şekilde, zil sesi gibi arızi seslerin bildirim gösterilmemesi sağlanır.

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

Bildirim otomatik olarak kaybolacağı için oynatma sona erdiğinde medya oturumunu "bırakmanıza" gerek yoktur. Yine de bir sonraki oynatma başladığında navigator.mediaSession.metadata öğesinin kullanılacağını unutmayın. Bu nedenle, medya bildiriminde ilgili bilgilerin gösterildiğinden emin olmak için medya oynatma kaynağı değiştiğinde kaynağınızın güncellenmesi önemlidir.

Medya meta verileri ile ilgili göz önüne alınması gereken birkaç nokta vardır.

• Bildirim posteri dizisi, blob URL'lerini ve veri URL'lerini destekler.
• Herhangi bir poster tanımlanmamışsa ve istediğiniz boyutta bir simge resmi (<link rel=icon> kullanılarak belirtilir) varsa medya bildirimleri bunu kullanır.
• Android için Chrome'da bildirim posterinin hedef boyutu: 512x512. Düşük teknolojili cihazlar için bu değer 256x256.
• Medya HTML öğesinin title özelliği, "Şimdi oynatılıyor" macOS widget'ında kullanılır.
• Medya kaynağı yerleştirilmişse (örneğin bir iframe içine) Media Session API bilgileri yerleştirilmiş bağlamdan ayarlanmalıdır. Aşağıdaki snippet'i inceleyin.

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

Kullanıcıların oynatılan içeriği kontrol etmesine izin verme

Medya oturumu işlemi, bir web sitesinin mevcut medya oynatmayla etkileşimde bulunduğunda kullanıcılar için işleyebileceği bir işlemdir (örneğin "oynat" veya "duraklat"). Eylemler olaylara benzer ve işleyiş şekilleriyle hemen hemen aynıdır. Etkinliklerde olduğu gibi, işlemler de uygun bir nesnede (bu örnekte MediaSession örneği) işleyiciler ayarlanarak uygulanır. Kullanıcılar mikrofonlu kulaklıktaki, başka bir uzak cihazdaki veya klavyedeki düğmelere bastığında ya da bir medya bildirimiyle etkileşimde bulunduğunda bazı işlemler tetiklenir.

Bazı medya oturumu işlemleri desteklenmeyebileceği için, bunları ayarlarken bir try…catch engellemesi kullanmanız önerilir.

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

Medya oturumu işlem işleyicisini ayarlamak, null değerine ayarlamak kadar kolaydır.

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

Ayarlandıktan sonra medya oturumu işlem işleyicileri, medya oynatmaları boyunca kullanılmaya devam eder. Bu, etkinlik işleyici kalıbına benzerdir. Tek fark, bir etkinliğin işlenmesi tarayıcının herhangi bir varsayılan davranışı yapmayı durdurması ve bunu, web sitesinin medya işlemini desteklediğine dair bir sinyal olarak kullanması anlamına gelir. Bu nedenle, uygun işlem işleyici ayarlanmadığı sürece medya işlemi kontrolleri gösterilmez.

Oynat / duraklat

"play" işlemi kullanıcının medya oynatmayı devam ettirmek istediğini belirtirken "pause" işlemi geçici olarak durdurmak istediğini belirtir.

"Oynat/duraklat" simgesi her zaman medya bildiriminde gösterilir ve ilgili medya etkinlikleri tarayıcı tarafından otomatik olarak işlenir. Varsayılan davranışını geçersiz kılmak için "oynat" ve "duraklat" medya işlemlerini aşağıda gösterildiği gibi gerçekleştirin.

Örneğin, tarayıcı bir web sitesinin arama veya yükleme yaparken medya oynatmadığını düşünebilir. Bu durumda, web sitesi kullanıcı arayüzünün medya bildirimi kontrolleriyle senkronize kalmasını sağlamak için navigator.mediaSession.playbackState değerini "playing" veya "paused" olarak ayarlayarak bu davranışı geçersiz kılın.

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

Önceki parça

"previoustrack" işlemi, medya oynatmanın başlangıç kavramı varsa kullanıcının geçerli medya oynatmayı baştan başlatmak veya medya oynatmada oynatma listesi fikri varsa oynatma listesindeki bir önceki öğeye geçmek istediğini belirtir.

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

Sonraki parça

"nexttrack" işlemi, medya oynatmada oynatma listesi fikri varsa kullanıcının medya oynatmayı oynatma listesindeki bir sonraki öğeye taşımak istediğini belirtir.

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

Durdur

"stop" işlemi, kullanıcının medya oynatmayı durdurmak ve uygunsa durumu temizlemek istediğini belirtir.

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

Geri / ileri sar

"seekbackward" işlemi, kullanıcının medya oynatma süresini kısa bir süre geri taşımak istediğini belirtirken "seekforward" işlemi, medya oynatma süresini kısa bir süre ileri taşımak istediğini belirtir. Kısa bir süre her iki durumda da birkaç saniye anlamına gelir.

İşlem işleyicide sağlanan seekOffset değeri, medya oynatma süresini saniye cinsinden taşıyan süredir. Sağlanmamışsa (örneğin, undefined) makul bir süre (ör. 10-30 saniye) kullanmanız gerekir.

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

Belirli bir zamana git

"seekto" işlemi, kullanıcının medya oynatma süresini belirli bir zamana taşımak istediğini belirtir.

İşlem işleyicide sağlanan seekTime değeri, medya oynatma süresinin saniye cinsinden taşınma süresidir.

İşlem bir dizinin parçası olarak birden fazla kez çağrılıyorsa ve bu, söz konusu dizideki son çağrı değilse işlem işleyicide sağlanan fastSeek boole değeri doğrudur.

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

Oynatma konumunu ayarla

Bir bildirimde medya oynatma konumunu doğru şekilde görüntülemek aşağıda gösterildiği gibi konum durumunu uygun bir zamana ayarlamak kadar basittir. Konum durumu; medya oynatma hızı, süre ve geçerli sürenin birleşimidir.

Süre sağlanmalı ve pozitif olmalıdır. Konum pozitif ve süreden küçük olmalıdır. Oynatma hızı 0'dan büyük olmalıdır.

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

Konum durumunu sıfırlamak, null olarak ayarlamak kadar kolaydır.

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

Video konferans işlemleri

Kullanıcı, video görüşmesini Pencere İçinde Pencere penceresine koyduğunda tarayıcı; mikrofon, kamera ve görüşmeyi sonlandırma denetimlerini görüntüleyebilir. Kullanıcı bunları tıkladığında web sitesi bunları aşağıdaki video konferans işlemleri aracılığıyla işler. Örnek için Video Konferans örneğini inceleyin.

Mikrofonu aç/kapat

"togglemicrophone" işlemi, kullanıcının mikrofonun sesini kapatmak veya açmak istediğini belirtir. setMicrophoneActive(isActive) yöntemi, tarayıcıya, web sitesinin mikrofonun etkin olarak kabul edip etmediğini bildirir.

let isMicrophoneActive = false;

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

Kameralar arasında geçiş yap

"togglecamera" işlemi, kullanıcının etkin kamerayı açmak veya kapatmak istediğini belirtir. setCameraActive(isActive) yöntemi, tarayıcının web sitesini etkin olarak kabul edip etmediğini belirtir.

let isCameraActive = false;

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

Görüşmeyi bitir

"hangup" işlemi, kullanıcının bir aramayı sonlandırmak istediğini gösterir.

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

Slaytları sunma işlemleri

Kullanıcı slayt sunularını pencere içinde pencereye yerleştirdiğinde, tarayıcı slaytlar arasında gezinmeye ilişkin denetimler görüntüleyebilir. Kullanıcı bu tıklamaları tıkladığında web sitesi bunları Media Session API üzerinden işler. Örnek için Slaytlar'ı gösterme örneğine göz atın.

Önceki slayt

"previousslide" işlemi, kullanıcının slaytları sunarken önceki slayta dönmek istediğini belirtir.

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

Sonraki slayt

"nextslide" işlemi, kullanıcının slaytları sunarken sonraki slayta geçmek istediğini gösterir.

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

Sana Özel

Blender Foundation ve Jan Morgenstern'ın çalışmalarının yer aldığı bazı Medya Oturumu örneklerine göz atın.

Kaynaklar

• Medya Oturumu Özellikleri: wicg.github.io/mediasession
• Teknik Özellikler ile İlgili Sorunlar: github.com/WICG/mediasession/issues
• Chrome Hataları: crbug.com