BackgroundAudio
Играет одну аудиозапись, которая продолжает звучать, пока приложение в фоне и экран заблокирован, —
аудиогид, подкаст, урок, — из плагина background-audio. Система показывает запись с её названием и
кнопкой play / pause (экран блокировки, уведомление); на кнопку гарнитуры, входящий звонок и
выдернутые наушники она реагирует без кода приложения. Для звука экрана, который останавливается
вместе с приложением, бери AudioPlayer (Медиа), для игровых звуков —
audio (Игровое аудио).
- аудиогид продолжает играть при заблокированном экране
- проигрывать звук в фоне, пока приложение свёрнуто
- показать название трека и кнопку паузы на экране блокировки
- показывать спиннер загрузки, пока звук не начался, и ошибку, если он не может играть
- показать позицию воспроизведения и полосу перемотки
- продолжить с того места, где слушатель остановился
- откатиться на
AudioPlayerтам, где фоновое аудио недоступно (BackgroundAudio.supported)
Платформы: iOS и Android в приложении-вьюере le.codes, веб и веб-плеер (что играет скрытая
вкладка, решает браузер); нет на десктопе и в headless-тестах и пока нет в iOS- или
Android-приложении, собранном через lecodes app. Проверяй BackgroundAudio.supported.
Обзор
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 он есть, что бы ни было в списке):
{ "plugins": { "background-audio": "*" } }- Именно плагин объявляет системе фоновое воспроизведение в собственной сборке приложения: фоновый режим
audioв iOS Info.plist, сервис воспроизведения медиа и его разрешения в Android-манифесте. Подключай его только в приложении, которое играет в фоне: App Store отклоняет приложение, которое объявило режим и не использует его, а Google Play спрашивает, зачем нужен сервис. - Без плагина
BackgroundAudio.supportedравенfalse, а вызов отклоняется.
Воспроизведение записи: play, pause, resume, stop
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
BackgroundAudio.on('state', ({ value }) => …) // 'idle' | 'loading' | 'playing' | 'paused' | 'ended' | 'failed'
BackgroundAudio.off('state', listener)- Состояние меняется и от вызовов приложения, и без них: кнопка на экране блокировки, гарнитура, звонок, прервавший запись, её конец. Рисуй кнопку play по событию, а не по последнему вызову приложения.
'loading'приходит и посреди записи, когда сеть не успевает.
Длительность и позиция: события duration и position
BackgroundAudio.on('duration', ({ value }) => …) // секунды: раз на запись, когда известна её длина
BackgroundAudio.on('position', ({ value }) => …) // секунды: примерно дважды в секунду, пока играет
BackgroundAudio.seek(seconds): Promise<void>positionшлётся, только пока у него есть слушатель: хост не дёргает приложение ради позиции, которую никто не показывает. Добавляй слушателя, когда плеер на экране, и снимай (off), когда нет. Первое значение приходит сразу, и ещё по одному — после всего, что сдвигает запись: перемотки, паузы, её конца.seekограничивается границами записи; пока длина неизвестна, он задаёт, откуда запись начнётся.
Возвращение из фона: status
BackgroundAudio.status(): Promise<{ state: BackgroundAudioState, duration: number, position: number }>Код приложения в фоне не выполняется, и position туда не шлётся. Когда приложение возвращается
(Жизненный цикл приложения, событие resume), прочитай всё разом:
app.addEventListener('resume', () => {
BackgroundAudio.status().then(({ state, position, duration }) => { /* перерисовать плеер */ })
})Не ставь запись на паузу по событию приложения pause: это ровно тот момент, когда она должна
играть дальше.
Там, где фонового аудио нет: supported
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()Смотрите также
- Медиа —
AudioPlayer: звук, который живёт вместе с экраном - Игровое аудио — игровое аудио
- Жизненный цикл приложения — события
pause/resume