BackgroundAudio

Играет одну аудиозапись, которая продолжает звучать, пока приложение в фоне и экран заблокирован, — аудиогид, подкаст, урок, — из плагина background-audio. Система показывает запись с её названием и кнопкой play / pause (экран блокировки, уведомление); на кнопку гарнитуры, входящий звонок и выдернутые наушники она реагирует без кода приложения. Для звука экрана, который останавливается вместе с приложением, бери AudioPlayer (Медиа), для игровых звуков — audio (Игровое аудио).

  • аудиогид продолжает играть при заблокированном экране
  • проигрывать звук в фоне, пока приложение свёрнуто
  • показать название трека и кнопку паузы на экране блокировки
  • показывать спиннер загрузки, пока звук не начался, и ошибку, если он не может играть
  • показать позицию воспроизведения и полосу перемотки
  • продолжить с того места, где слушатель остановился
  • откатиться на AudioPlayer там, где фоновое аудио недоступно (BackgroundAudio.supported)

Платформы: iOS и Android в приложении-вьюере le.codes, веб и веб-плеер (что играет скрытая вкладка, решает браузер); нет на десктопе и в headless-тестах и пока нет в iOS- или Android-приложении, собранном через lecodes app. Проверяй BackgroundAudio.supported.

Обзор

TypeScript
const state = signal<BackgroundAudioState>('idle')
const position = signal(0)
const length = signal(0)

BackgroundAudio.on('state', ({ value }) => { state.value = value })        // loading, playing, paused, ended, failed
BackgroundAudio.on('duration', ({ value }) => { length.value = value })    // секунды, как только запись известна
BackgroundAudio.on('position', ({ value }) => { position.value = value })  // секунды, дважды в секунду, пока играет

const toggle = () => {
  if (state.value === 'idle') BackgroundAudio.play({ src: 'https://example.com/guide.mp3', title: 'The old bridge', artist: 'City guide' })
  else if (state.value === 'playing' || state.value === 'loading') BackgroundAudio.pause()
  else BackgroundAudio.resume()      // после 'ended' — с начала; после 'failed' — запись запрашивается заново
}

UIScreen(
  UIButton(UIText(() => state.value === 'playing' ? 'Pause' : state.value === 'loading' ? '…' : 'Play')).onClick(toggle),
  UIText(() => `${Math.floor(position.value)} / ${Math.floor(length.value)} s`),
  UIButton(UIText('Stop')).onClick(() => { BackgroundAudio.stop() }),
).style({ pt: 'safe-top', p: 20, gap: 12 }).open()

Подключение фонового аудио: plugins в app.json

BackgroundAudio нужен плагин background-audio, перечисленный в app.json приложения (один список на все платформы; в приложении-вьюере le.codes он есть, что бы ни было в списке):

JSON
{ "plugins": { "background-audio": "*" } }
  • Именно плагин объявляет системе фоновое воспроизведение в собственной сборке приложения: фоновый режим audio в iOS Info.plist, сервис воспроизведения медиа и его разрешения в Android-манифесте. Подключай его только в приложении, которое играет в фоне: App Store отклоняет приложение, которое объявило режим и не использует его, а Google Play спрашивает, зачем нужен сервис.
  • Без плагина BackgroundAudio.supported равен false, а вызов отклоняется.

Воспроизведение записи: play, pause, resume, stop

TypeScript
BackgroundAudio.play(track: { src: string, title: string, artist?: string, position?: number }): Promise<void>
BackgroundAudio.pause(): Promise<void>
BackgroundAudio.resume(): Promise<void>
BackgroundAudio.stop(): Promise<void>
  • Одна запись за раз: play отпускает ту, что играла. src — http / https url; title и artist — то, что показывает система; position — откуда начать, в секундах.
  • play резолвится, как только хост принял запись, — что с ней стало, сообщает событие state: 'loading', потом 'playing' или 'failed'.
  • resume продолжает после паузы, начинает с начала после 'ended' и запрашивает запись заново после 'failed'.
  • stop отпускает запись: системный плеер исчезает, состояние — 'idle'.
  • Запись играет, пока её не остановят, — закрытие экрана её не останавливает. Останавливай её там, где у приложения больше нет способа её показать.

Что делает плеер: событие state

TypeScript
BackgroundAudio.on('state', ({ value }) => …)   // 'idle' | 'loading' | 'playing' | 'paused' | 'ended' | 'failed'
BackgroundAudio.off('state', listener)
  • Состояние меняется и от вызовов приложения, и без них: кнопка на экране блокировки, гарнитура, звонок, прервавший запись, её конец. Рисуй кнопку play по событию, а не по последнему вызову приложения.
  • 'loading' приходит и посреди записи, когда сеть не успевает.

Длительность и позиция: события duration и position

TypeScript
BackgroundAudio.on('duration', ({ value }) => …)   // секунды: раз на запись, когда известна её длина
BackgroundAudio.on('position', ({ value }) => …)   // секунды: примерно дважды в секунду, пока играет
BackgroundAudio.seek(seconds): Promise<void>
  • position шлётся, только пока у него есть слушатель: хост не дёргает приложение ради позиции, которую никто не показывает. Добавляй слушателя, когда плеер на экране, и снимай (off), когда нет. Первое значение приходит сразу, и ещё по одному — после всего, что сдвигает запись: перемотки, паузы, её конца.
  • seek ограничивается границами записи; пока длина неизвестна, он задаёт, откуда запись начнётся.

Возвращение из фона: status

TypeScript
BackgroundAudio.status(): Promise<{ state: BackgroundAudioState, duration: number, position: number }>

Код приложения в фоне не выполняется, и position туда не шлётся. Когда приложение возвращается (Жизненный цикл приложения, событие resume), прочитай всё разом:

TypeScript
app.addEventListener('resume', () => {
  BackgroundAudio.status().then(({ state, position, duration }) => { /* перерисовать плеер */ })
})

Не ставь запись на паузу по событию приложения pause: это ровно тот момент, когда она должна играть дальше.

Там, где фонового аудио нет: supported

TypeScript
const main = () => {
  const src = 'https://example.com/guide.mp3'
  if (BackgroundAudio.supported) BackgroundAudio.play({ src, title: 'The old bridge' })
  else new AudioPlayer(src).play()      // десктоп: играет, пока приложение открыто
}
main()

Смотрите также