更新记录

1.0.8（2026-04-22）

• Android 补齐通知栏媒体控制：新增上一首/播放暂停/下一首/停止动作，支持在后台从通知栏直接发起媒体命令。
• Android 补齐前台服务保活：新增 BackgroundAudioForegroundService，播放期常驻媒体通知，降低后台被系统回收风险。
• Android 新增通知通道与媒体通知同步：曲目标题、歌手/专辑信息与播放状态会随 MediaSession 状态联动刷新。
• Android Manifest 新增前台服务声明（foregroundServiceType=mediaPlayback）。
• iOS 升级回原生媒体链路：AVPlayer + AVAudioSession + MPRemoteCommandCenter + MPNowPlayingInfoCenter（含远程命令桥接与播放信息同步）。
• Harmony 移除 stub 占位实现，补齐为 BackgroundAudioManager + InnerAudioContext 双引擎可用实现（含能力探测、事件回调、错误码路径）。
• 文档同步更新 Android/iOS/Harmony 实现能力，版本号升级到 1.0.8。

平台兼容性

uni-app(4.84)

uni-app x(4.84)

lizhao-bg-audio

lizhao-bg-audio 是纯 UTS 背景音频播放器 API 插件，提供统一的播放控制、队列管理、远程控制事件与错误码体系。

支持平台

技术实现说明

会话层级说明

安装说明

import * as LizhaoBackgroundAudio from '@/uni_modules/lizhao-bg-audio'

目录结构说明

uni_modules/
└─ lizhao-bg-audio/
   ├─ package.json
   ├─ readme.md
   ├─ changelog.md
   ├─ example/
   └─ utssdk/
      ├─ interface.uts
      ├─ unierror.uts
      ├─ index.uts
      ├─ app-android/
      │  └─ index.uts
      ├─ app-ios/
      │  └─ index.uts
      ├─ app-harmony/
      │  └─ index.uts
      ├─ web/
      │  └─ index.uts
      ├─ mp-weixin/
      │  └─ index.uts
      └─ mp-alipay/
         └─ index.uts

API 列表

• initPlayer(options)
• setTrack(options)
• play(options)
• pause(options)
• resume(options)
• stop(options)
• seek(options)
• setPlaybackRate(options)
• setVolume(options)
• setLoopMode(options)
• setPlaylist(options)
• appendTrack(options)
• removeTrack(options)
• skipToNext(options)
• skipToPrev(options)
• skipToIndex(options)
• getPlayerState(options)
• getQueueState(options)
• getCapabilities(options)
• on(eventName, callback)
• off(eventName, callback)

initPlayer(options)

说明
初始化播放器运行时并返回平台能力矩阵。

支持平台
Android / iOS / Harmony / Web / 微信小程序 / 支付宝小程序

参数

setTrack(options)

说明
设置当前播放曲目与媒体元数据。

参数

play(options) / pause(options) / resume(options) / stop(options)

说明
控制播放状态。

参数

seek(options) / setPlaybackRate(options) / setVolume(options) / setLoopMode(options)

说明
设置播放进度、倍速、音量、循环模式。

参数

setPlaylist(options) / appendTrack(options) / removeTrack(options) / skipToNext(options) / skipToPrev(options) / skipToIndex(options)

说明
管理播放队列与切歌控制。

参数

getPlayerState(options) / getQueueState(options) / getCapabilities(options)

说明
获取播放器状态、队列状态与能力矩阵。

参数

on(eventName, callback) / off(eventName, callback)

说明
订阅/取消订阅播放器事件。

返回值说明

BackgroundAudioTrack

BackgroundAudioPlayerState

BackgroundAudioCapabilities

错误码说明

权限说明

自定义基座说明

• 当前版本未接入三方原生 SDK，但 Android 已新增前台服务与媒体通知声明。
• Android/iOS 已接入系统媒体会话能力，建议使用自定义基座或云打包以确保原生配置完整生效。
• 若新增原生依赖或服务声明，必须同步维护：
  • Android：utssdk/app-android/config.json、AndroidManifest.xml
  • iOS：utssdk/app-ios/Info.plist、UTS.entitlements、PrivacyInfo.xcprivacy

示例（uni-app）

import * as BgAudio from '@/uni_modules/lizhao-bg-audio'

BgAudio.initPlayer({
  success(res) {
    console.log('init success', res)
  }
})

BgAudio.setPlaylist({
  tracks: [
    {
      id: 'track-1',
      url: 'https://www.soundhelix.com/examples/mp3/SoundHelix-Song-1.mp3',
      title: 'SoundHelix Song 1',
      singer: 'Singer A',
      cover: ''
    },
    {
      id: 'track-2',
      url: 'https://www.learningcontainer.com/wp-content/uploads/2020/02/Kalimba.mp3',
      title: 'Kalimba',
      singer: 'Singer B'
    }
  ],
  startIndex: 0,
  success() {
    BgAudio.play({})
  }
})

BgAudio.on('remoteCommand', (event) => {
  console.log('remote command', event.payload)
})

示例（uni-app x）

import * as BgAudio from '@/uni_modules/lizhao-bg-audio'

BgAudio.initPlayer({
  success() {
    BgAudio.setTrack({
      track: {
        id: 'single-1',
        url: 'https://download.samplelib.com/mp3/sample-3s.mp3',
        title: 'Sample 3s'
      },
      success() {
        BgAudio.play({ startPosition: 0 })
      }
    })
  }
})

BgAudio.on('progress', (event) => {
  console.log('progress', event.payload)
})

注意事项

1. 非 App 平台按“能力探测 + 明确降级/报错”执行，不伪造成功返回。
2. setVolume 在部分小程序平台可能不支持，将返回 9012007。
3. Android 已支持系统级会话回调，建议重点回归锁屏/通知栏/耳机线控场景。
4. iOS 已启用 MPRemoteCommandCenter 远程控制桥接与 MPNowPlayingInfoCenter 元数据同步。
5. Harmony 当前仍为 BackgroundAudioManager + InnerAudioContext 双引擎策略，后续可继续演进到更原生的 AVSession 链路。