MediaSession: метод setActionHandler()

Метод setActionHandler() интерфейса MediaSession устанавливает обработчик для действия сессии воспроизведения. Эти действия позволяют веб-приложению получать уведомления, когда пользователь взаимодействует с встроенными физическими или экранными средствами управления медиа устройства, такими как кнопки воспроизведения, остановки или перемотки.

type

Строка, представляющая тип действия, на который следует подписаться. Она будет одним из следующих:

hangup

Завершение вызова.

nextslide

Переход к следующему слайду при представлении презентации.

nexttrack

Переход к следующему треку.

pause

Приостановка воспроизведения медиа.

play

Начало (или возобновление) воспроизведения медиа.

previousslide

Переход к предыдущему слайду при представлении презентации.

previoustrack

Возврат к предыдущему треку.

seekbackward

Перемотка назад от текущей позиции медиа. Свойство seekOffset, переданное в обратный вызов, определяет количество времени для перемотки назад.

seekforward

Перемотка вперёд от текущей позиции медиа. Свойство seekOffset, переданное в обратный вызов, определяет количество времени для перемотки вперёд.

seekto

Перемещение позиции воспроизведения до указанного момента времени в медиа. Время перехода указано в свойстве seekTime обратного вызова. Если вы намерены выполнить несколько операций seekto последовательно, вы также можете указать свойство fastSeek обратного вызова со значением true. Это сообщает браузеру, что он может предпринять шаги для оптимизации повторяющихся операций, что, вероятно, приведет к улучшению производительности.

skipad

Пропуск текущей рекламы или рекламного блока. Это действие может быть доступно или недоступно в зависимости от платформы и агента пользователя, или может быть отключено из-за уровня подписки или других обстоятельств.

stop

Полная остановка воспроизведения.

togglecamera

Включение или выключение активной камеры пользователя.

togglemicrophone

Включение или выключение микрофона пользователя.

callback

Функция, вызываемая, когда вызывается указанный тип действия. Обратный вызов не должен возвращать значение. Обратный вызов получает словарь, содержащий следующие свойства:

action

Строка, представляющая тип действия. Это свойство позволяет одному обратному вызову обрабатывать несколько типов действий.

fastSeek Необязательно

Действие seekto может включать это свойство, которое представляет собой булево значение, указывающее, следует ли выполнять "быструю" перемотку. Быстрая перемотка — это перемотка, выполняемая в быстрой последовательности, например, при быстрой перемотке вперёд или назад через медиа, быстро пропуская его. Это свойство может использоваться для указания того, что вы должны использовать кратчайший возможный метод перемотки медиа. fastSeek не включено в конечное действие в последовательности перемотки в этой ситуации.

seekOffset Необязательно

Если action равно либо seekforward, либо seekbackward, и это свойство присутствует, это число с плавающей запятой, указывающее количество секунд для перемещения позиции воспроизведения вперёд или назад. Если это свойство отсутствует, эти действия должны выбрать разумное значение для пропуска вперед или назад (например, 7 или 10 секунд).

seekTime Необязательно

Если action равно seekto, это свойство должно быть присутствовать и должно быть числом с плавающей запятой, обозначающим абсолютное время в медиа, до которого нужно переместить позицию воспроизведения, где 0 означает начало медиа. Это свойство отсутствует для других типов действий.

None (undefined).

Чтобы удалить ранее установленный обработчик действия, снова вызовите setActionHandler(), указав null в качестве callback.

Обработчик действия получает на вход один параметр: объект, который предоставляет как тип действия (чтобы одна функция могла обрабатывать несколько типов действий), так и данные, необходимые для выполнения действия.

В этом примере создается новая сессия медиа и назначаются обработчики действий (которые ничего не делают).

if ("mediaSession" in navigator) {
  navigator.mediaSession.metadata = new MediaMetadata({
    title: "Unforgettable",
    artist: "Nat King Cole",
    album: "The Ultimate Collection (Remastered)",
    artwork: [
      {
        src: "https://dummyimage.com/96x96",
        sizes: "96x96",
        type: "image/png",
      },
      {
        src: "https://dummyimage.com/128x128",
        sizes: "128x128",
        type: "image/png",
      },
      {
        src: "https://dummyimage.com/192x192",
        sizes: "192x192",
        type: "image/png",
      },
      {
        src: "https://dummyimage.com/256x256",
        sizes: "256x256",
        type: "image/png",
      },
      {
        src: "https://dummyimage.com/384x384",
        sizes: "384x384",
        type: "image/png",
      },
      {
        src: "https://dummyimage.com/512x512",
        sizes: "512x512",
        type: "image/png",
      },
    ],
  });

  navigator.mediaSession.setActionHandler("play", () => {
    /* Code excerpted. */
  });
  navigator.mediaSession.setActionHandler("pause", () => {
    /* Code excerpted. */
  });
  navigator.mediaSession.setActionHandler("stop", () => {
    /* Code excerpted. */
  });
  navigator.mediaSession.setActionHandler("seekbackward", () => {
    /* Code excerpted. */
  });
  navigator.mediaSession.setActionHandler("seekforward", () => {
    /* Code excerpted. */
  });
  navigator.mediaSession.setActionHandler("seekto", () => {
    /* Code excerpted. */
  });
  navigator.mediaSession.setActionHandler("previoustrack", () => {
    /* Code excerpted. */
  });
  navigator.mediaSession.setActionHandler("nexttrack", () => {
    /* Code excerpted. */
  });
  navigator.mediaSession.setActionHandler("skipad", () => {
    /* Code excerpted. */
  });
  navigator.mediaSession.setActionHandler("togglecamera", () => {
    /* Code excerpted. */
  });
  navigator.mediaSession.setActionHandler("togglemicrophone", () => {
    /* Code excerpted. */
  });
  navigator.mediaSession.setActionHandler("hangup", () => {
    /* Code excerpted. */
  });
}

Следующий пример настраивает две функции для воспроизведения и паузы, а затем использует их в качестве обратных вызовов с соответствующими обработчиками действий.

const actionHandlers = [
  // play
  [
    "play",
    async () => {
      // play our audio
      await audioEl.play();
      // set playback state
      navigator.mediaSession.playbackState = "playing";
      // update our status element
      updateStatus(allMeta[index], "Action: play  |  Track is playing…");
    },
  ],
  [
    "pause",
    () => {
      // pause out audio
      audioEl.pause();
      // set playback state
      navigator.mediaSession.playbackState = "paused";
      // update our status element
      updateStatus(allMeta[index], "Action: pause  |  Track has been paused…");
    },
  ],
];

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

В этом примере используются соответствующие обработчики действий для возможности перемотки вперед и назад через воспроизводимое медиа.

navigator.mediaSession.setActionHandler("seekbackward", (evt) => {
  // User clicked "Seek Backward" media notification icon.
  let skipTime = evt.seekOffset || 10; // Time to skip in seconds
  audio.currentTime = Math.max(audio.currentTime - skipTime, 0);
});

navigator.mediaSession.setActionHandler("seekforward", (evt) => {
  // User clicked "Seek Forward" media notification icon.
  let skipTime = evt.seekOffset || 10; // Time to skip in seconds
  audio.currentTime = Math.min(audio.currentTime + skipTime, audio.duration);
});

Чтобы удалить обработчик действия медиа, присвойте ему значение null.

navigator.mediaSession.setActionHandler("nexttrack", null);

Также можно, если вы предпочитаете, использовать одну функцию для обработки нескольких типов действий, проверив значение свойства action:

let skipTime = 7;

navigator.mediaSession.setActionHandler("seekforward", handleSeek);
navigator.mediaSession.setActionHandler("seekbackward", handleSeek);

function handleSeek(details) {
  switch (details.action) {
    case "seekforward":
      audio.currentTime = Math.min(
        audio.currentTime + skipTime,
        audio.duration,
      );
      break;
    case "seekbackward":
      audio.currentTime = Math.max(audio.currentTime - skipTime, 0);
      break;
  }
}

Здесь функция handleSeek() обрабатывает как действия seekbackward , так и seekforward.

Обработчики действий "previousslide" и "nextslide" могут использоваться для обработки переходов вперед и назад по презентации слайдов, например, когда пользователь переводит презентацию в окно картинка-в-картинке и нажимает на предоставляемые браузером средства навигации по слайдам.

try {
  navigator.mediaSession.setActionHandler("previousslide", () => {
    log('> User clicked "Previous Slide" icon.');
    if (slideNumber > 1) slideNumber--;
    updateSlide();
  });
} catch (error) {
  log('Warning! The "previousslide" media session action is not supported.');
}

try {
  navigator.mediaSession.setActionHandler("nextslide", () => {
    log('> User clicked "Next Slide" icon.');
    slideNumber++;
    updateSlide();
  });
} catch (error) {
  log('Warning! The "nextslide" media session action is not supported.');
}

См. Пример презентации слайдов/сессии медиа для рабочего примера.