Media Session API: управление и намерение пользователя

API медиасессии позволяет странице описывать активный медиаматериал и получать переданные браузером команды: воспроизведение, пауза, перемотка и смена трека. Такие команды показывают ветку взаимодействия, но не доказывают, что человек разрешил воспроизведение, увидел карточку на экране блокировки или принял удалённую транзакцию. BotBrowser может повторить разрешённый синтетический fixture и проверить состояние страницы; он не создаёт нажатие гарнитуры и не гарантирует системное уведомление. Ниже описано, как связать управление, состояние и откат с одной объявленной задачей.

Спецификация медиасессии W3C определяет метаданные, обработчики, состояние воспроизведения и позицию. Справочник MDN описывает объекты браузера, а руководство Chrome показывает интеграцию. Это контракт интерфейса, а не гарантия одинаковых функций на всех платформах.

Кратко

• Запускайте сессию только для видимой задачи, которой владеет страница.
• Разделяйте metadata, playbackState, обработчики и состояние позиции.
• Регистрируйте только выполнимые действия и удаляйте устаревшие обработчики.
• Проверяйте duration, position и playbackRate перед setPositionState().
• Храните ограниченные результаты вроде pause-requested или unsupported, а не личные данные слушателя.

Содержание руководства

• Определите задачу и метаданные
• Регистрируйте обработчики вокруг намерения
• Сохраняйте правдивыми состояние и позицию
• Удаляйте управление и оставляйте откат
• Запишите минимальный fixture
• Читайте результаты без преувеличений
• Итоги

Определите задачу и метаданные

Задайте конкретную задачу: воспроизвести эпизод, показать фрагмент курса или включить утверждённый список. До записи метаданных должны быть видны название, кнопка запуска и понятная остановка. Скрипт, который показывает обложку при загрузке, может объявить активность, которой никто не просил.

Используйте navigator.mediaSession.metadata как представление, а не идентификатор. MediaMetadata содержит title, artist, album, albumArtist и artwork; оставляйте только необходимое. Не помещайте email, токены, подписанные URL или скрытые метки эксперимента. URL изображения также является данными страницы: применяйте утверждённый ресурс или не указывайте его.

Компонент, владеющий медиаэлементом, должен владеть треком, ревизией и playbackState. Запоздалый ответ сети нужно отбросить, если trackId изменился. Статья о Web Audio и аудиопроцессах описывает граф и микрофон; медиасессия сообщает о воспроизведении и не выдаёт доступ к микрофону.

Используйте состояния idle, intent-recorded, metadata-set, playing, paused, ended, action-rejected, unsupported и stale. playing означает, что элемент сообщил о запуске; это не доказательство того, что человек слушает.

Регистрируйте обработчики вокруг намерения

setActionHandler() связывает команду браузера с функцией страницы. Частые действия: play, pause, seekbackward, seekforward, previoustrack и nexttrack. Регистрируйте действие только при наличии безопасной реализации. Переход к следующему платному треку требует отдельной политики.

Создавайте набор обработчиков для каждой задачи. При смене трека проверяйте trackId; при завершении удаляйте обработчики через navigator.mediaSession.setActionHandler(action, null), очищайте метаданные и ставьте playbackState в none, если это поддерживается. Старый callback не должен управлять новым элементом.

Callback - это запрос, а не результат авторизации. Вызовите media.play() или media.pause(), обработайте отказ и обновите видимую кнопку после фактического состояния. Сам приход действия не означает playing. Руководство по намерению пользователя в API буфера обмена проводит ту же границу для запросов браузера.

const task = { fixtureId: 'media-17', trackId: 'episode-04', state: 'intent-recorded' };
const media = document.querySelector('#player');
function record(next) {
  task.state = next;
  document.querySelector('#status').textContent = next;
}
media.addEventListener('playing', () => {
  navigator.mediaSession.playbackState = 'playing';
  record('play-complete');
});
media.addEventListener('pause', () => {
  navigator.mediaSession.playbackState = 'paused';
  record('pause-complete');
});
media.addEventListener('error', () => record('play-rejected'));
navigator.mediaSession.metadata = new MediaMetadata({ title: 'Episode 04', artist: 'Fixture', album: 'Bounded test' });
navigator.mediaSession.setActionHandler('play', async () => {
  try {
    await media.play();
  } catch {
    record('play-rejected');
  }
});
navigator.mediaSession.setActionHandler('pause', () => {
  media.pause();
});

Сохраняйте правдивыми состояние и позицию

playbackState принимает none, paused и playing; синхронизируйте его с событиями элемента. Отклонённый play() не должен становиться playing. Для setPositionState({ duration, position, playbackRate }) нужна конечная длительность больше 0, позиция внутри диапазона и конечная скорость больше 0. Для потока без длительности вызов пропускается.

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

Наблюдение	Состояние	Ответ
Нет mediaSession	unsupported	Оставить кнопки страницы.
play завершён	play-complete	Установить playbackState: 'playing'.
play отклонён	play-rejected	Оставить паузу и видимую повторную попытку.
pause после конца	stale	Не запускать следующий трек автоматически.
Неверная позиция	position-skipped	Ждать следующего корректного значения.

Статьи о границах Web Share и намерении пользователя при работе с буфером обмена показывают тот же принцип: callback или разрешённый запрос сами по себе не доказывают согласие или передачу данных.

Удаляйте управление и оставляйте откат

При завершении, переходе, выходе или остановке поставьте паузу, очистите metadata, установите playbackState в none, удалите обработчики и освободите ссылки. Очистка должна быть идемпотентной. Оставляйте доступные клавиатурные кнопки воспроизведения, паузы, следующего трека и перемотки со статусами paused, playing, ended или play-rejected.

Не используйте действие для обхода autoplay, согласия, оплаты или проверки аккаунта. Если нужен клик «Запустить», сначала запишите intent-recorded, затем установите метаданные. При навигации во время play() пометьте попытку stale и не позволяйте позднему результату изменить новый маршрут.

Запишите минимальный fixture

Полезная строка содержит fixtureId, action, state, positionState, fallback, browserVersion и context. Исключите чувствительные названия, байты обложки, аккаунты, полные URL и целые исключения. Повторите тест при отсутствии API, отклонённом promise и очистке во время ожидающего действия.

{
  "fixtureId": "media-17",
  "action": "pause",
  "state": "pause-complete",
  "positionState": "valid",
  "fallback": "in-page-controls",
  "browserVersion": "156.0",
  "fixtureRevision": 3
}

Читайте результаты без преувеличений

BotBrowser может повторить fixture в разрешённом контексте, сравнить видимые состояния и сохранить объявленные параметры. Он не создаёт физическое событие гарнитуры, системное нажатие или карточку блокировки и не доказывает прослушивание. Если mediaSession отсутствует, проверяйте откат; если действие не меняет экран, проверяйте promise элемента и ревизию владельца.

Метаданные могут отображаться за пределами страницы. Используйте утверждённые подписи для чувствительных предпросмотров и не объединяйте названия, шрифты или разрешения для оценки человека либо устройства.

Источники

• Медиасессия, W3C
• API медиасессии, MDN
• MediaSession.setActionHandler(), MDN
• MediaSession.setPositionState(), MDN
• Медиасессия, Chrome
• Границы автоматизации BotBrowser

Итоги

Связывайте метаданные и управление с видимой задачей страницы. Проверяйте состояние и позицию, удаляйте обработчики при очистке и сохраняйте доступные кнопки. Храните ограниченные результаты, а не историю прослушивания. BotBrowser повторяет синтетическое взаимодействие; намерение, системная презентация и реальное слушание остаются вне доказательства.