更新记录

1.2.53（2026-10-08）

• 修复 iOS 在未初始化、无可播放曲目等失败分支中，将强类型 fail 回调转换为通用函数时可能闪退的问题；保留原 success / fail / complete 参数和调用方式。
• 补齐 iOS 播放时补载曲目、设置歌单及按索引切歌的装载失败回调，确保依次触发 fail / complete，兼容只传 complete，成功时不会重复完成回调。
• 本次包含 iOS 原生代码更新，升级后必须重新制作并安装 iOS 自定义基座或正式 IPA；仅更新页面资源或 WGT 不会更新原生修复。Android 原生实现未变更，本次升级无需重打 Android 自定义基座。

1.2.52（2026-10-04）

• 新增 subscribe / unsubscribe 独立事件订阅，多个页面或组件可分别持有 token 并只取消自己的回调，不影响旧 on / off 用法。
• 新增 uni-app 与 uni-app x 独立订阅示例；完整播放示例增加一键复制事件日志，便于定位播放和订阅状态。
• 修复 Android Vapor 页面切换或子页面销毁时误清理模块事件桥，导致父页面及后续页面收不到 progress / stateChange 等回调的问题。
• Android 原生实现已在匹配的新自定义基座完成播放、后台媒体控制、独立订阅、10 次页面往返和冷启动验收；升级后需重新制作并安装 Android 自定义基座或正式包。
• iOS 新订阅实现已完成打包，本版本发布前未进行 iOS 真机验收。

1.2.51（2026-09-21）

• 修复 Android 初始化、播放控制、状态与能力查询、跳转、倍速、音量、循环、曲目追加和移除等 API 已执行但 success / fail / complete 不回调的问题。
• 修复完整示例把初始化参数中的 fail 回调字段误显示为红色错误的问题；只有真实失败、异常或错误日志才固定显示在首屏。
• 修复完整示例第三首测试曲目的曲名与歌手字段写反，媒体通知现在按“月光下的传说 / 李钊”展示。
• 修复 Web 切换曲目时成功和完成回调重复触发，以及移除曲目后播放列表位置与实际音源不一致的问题。
• 修复 Web 播放被浏览器拒绝时仍返回成功的问题，现在通过失败回调和错误事件说明原因。
• 修复简单示例重复初始化时叠加进度监听、退出页面后仍保留监听的问题。
• 按功能模块重整使用说明，补齐各项能力的接入示例和平台差异；示例页面采用紧凑布局，状态与日志可展开查看。
• 升级后无需修改现有调用代码；Android 原生 UTS 生成物已变化，必须重新制作并安装匹配的 Android 自定义基座或正式包。iOS 无需因本次 Android 修复重新制作基座。

平台兼容性

uni-app(4.84)

uni-app x(4.84)

其他

lizhao-bg-audio

介绍

lizhao-bg-audio 为 uni-app / uni-app x 提供背景音频播放能力，用同一套 API 管理单曲、歌单、播放进度和系统媒体控制，适合音乐、有声书与课程音频。

功能特色

各平台的后台、音量、倍速和动态下一曲能力有差异，详细范围见后文“支持平台”。

适合哪些场景

下载与导入

1. 从插件市场选择“使用 HBuilderX 导入插件”，导入自己的 uni-app 或 uni-app x 项目。
2. 保留完整的 uni_modules/lizhao-bg-audio 目录；页面只从 @/uni_modules/lizhao-bg-audio 导入。
3. 先运行下面的最小示例，再按业务需要增加歌单、进度或系统控制。

插件提供了可复制的完整页面：

复制示例到自己的页面目录后，在 pages.json 注册对应页面。插件提供播放 API，播放器外观可以按业务自行编写。

5 分钟跑通：播放一首音频

调用顺序是：先监听事件 → 初始化成功 → 设置曲目成功 → 开始播放。下面使用公开演示音频，接入时换成自己的可访问地址。不要在 <script> 顶层直接执行 initPlayer()，应从按钮、页面生命周期或应用音频管理方法调用。

uni-app：放进一个已注册的 .vue 页面

<template>
  <view>
    <button @click="initAndPlay">初始化并播放</button>
    <button @click="stopPlayback">停止播放</button>
  </view>
</template>

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

// 保存监听函数，退出页面时使用同一个引用取消订阅。
const  = (event) => console.log('音频播放结束', event.payload)
const onError = (event) => console.log('音频运行错误', event.payload)

export default {
  onLoad() {
    // 先监听，避免错过起播后的事件。
    BgAudio.on('ended', )
    BgAudio.on('error', onError)
  },
  onUnload() {
    // 页面离开只解除页面监听，背景音频可以继续播放。
    BgAudio.off('ended', )
    BgAudio.off('error', onError)
  },
  methods: {
    initAndPlay() {
      BgAudio.initPlayer({
        success: () => {
          BgAudio.setTrack({
            track: {
              id: 'demo-1',
              url: 'https://www.soundhelix.com/examples/mp3/SoundHelix-Song-1.mp3',
              title: '演示音频',
              singer: 'SoundHelix'
            },
            success: () => {
              // 设置曲目后显式播放；0 表示从头开始。
              BgAudio.play({
                startPosition: 0,
                fail: (err) => console.log('播放失败', err.errCode, err.errMsg)
              })
            },
            fail: (err) => console.log('设置曲目失败', err.errCode, err.errMsg)
          })
        },
        fail: (err) => console.log('初始化失败', err.errCode, err.errMsg)
      })
    },
    stopPlayback() {
      // 由使用者主动结束播放。
      BgAudio.stop({
        fail: (err) => console.log('停止失败', err.errCode, err.errMsg)
      })
    }
  }
}
</script>

uni-app x：放进一个已注册的 .uvue 页面

<template>
  <view>
    <button @click="initAndPlay">初始化并播放</button>
    <button @click="stopPlayback">停止播放</button>
  </view>
</template>

<script setup lang="uts">
import * as BgAudio from '@/uni_modules/lizhao-bg-audio'
import { type BackgroundAudioEvent, type BackgroundAudioFail } from '@/uni_modules/lizhao-bg-audio'

// UTS 为事件和失败参数声明类型。
const  = (event: BackgroundAudioEvent): void => {
  console.log('音频播放结束', event.payload)
}
const onError = (event: BackgroundAudioEvent): void => {
  console.log('音频运行错误', event.payload)
}
function showFail(err: BackgroundAudioFail): void {
  console.log('音频操作失败', err.errCode, err.errMsg)
}

onLoad(() => {
  BgAudio.on('ended', )
  BgAudio.on('error', onError)
})
onUnload(() => {
  // 解除本页面监听，不自动停止全局背景音频。
  BgAudio.off('ended', )
  BgAudio.off('error', onError)
})

function initAndPlay(): void {
  BgAudio.initPlayer({
    success: (_res: any) => {
      BgAudio.setTrack({
        track: {
          id: 'demo-1',
          url: 'https://www.soundhelix.com/examples/mp3/SoundHelix-Song-1.mp3',
          title: '演示音频',
          singer: 'SoundHelix'
        },
        success: (_trackResult: any) => {
          // 设置曲目成功后，再发起播放。
          BgAudio.play({
            startPosition: 0,
            fail: (err: BackgroundAudioFail) => showFail(err)
          })
        },
        fail: (err: BackgroundAudioFail) => showFail(err)
      })
    },
    fail: (err: BackgroundAudioFail) => showFail(err)
  })
}

function stopPlayback(): void {
  // 仅在使用者点击停止时结束播放。
  BgAudio.stop({ fail: (err: BackgroundAudioFail) => showFail(err) })
}
</script>

最小示例用于一个播放页面。多个页面共同控制背景音频时，建议在应用级统一管理播放器和事件，页面只负责展示；具体订阅边界见后文“事件与回调”。

从基础到进阶：按业务模块使用

以下片段沿用基础示例的 BgAudio 导入。除初始化与监听外，其余操作均在初始化成功后，从按钮或业务方法中调用；各片段按需选择，不要顺序执行所有控制操作。

模块一：暂停、继续与结束播放

解决什么问题： 区分临时暂停与主动结束。什么时候使用： 播放按钮、暂停按钮、关闭播放器或退出收听业务时。

// 分别绑定到对应按钮，不要一次依次执行。
function pauseAudio() {
  BgAudio.pause({ fail: (err) => console.log('暂停失败', err.errMsg) })
}
function resumeAudio() {
  BgAudio.resume({ fail: (err) => console.log('继续播放失败', err.errMsg) })
}
function stopAudio() {
  BgAudio.stop({ fail: (err) => console.log('停止失败', err.errMsg) })
}

pause 保留播放位置，resume 从当前位置继续，stop 停止并重置进度。需要从指定位置开始时使用 play({ startPosition: 秒数 })。普通页面切换和应用退到后台，不应自动调用 stop。当前没有公开 destroyPlayer 方法。

模块二：加载歌单与切换章节

解决什么问题： 一次传入完整歌单，并从指定章节开始。什么时候使用： 课程目录、专辑或有声书章节列表。

uni-app 在初始化成功后执行：

// 设置完整队列；startIndex 从 0 开始，设置成功后再播放。
BgAudio.setPlaylist({
  tracks: [
    {
      id: 'chapter-1',
      url: 'https://www.soundhelix.com/examples/mp3/SoundHelix-Song-1.mp3',
      title: '第一章'
    },
    {
      id: 'chapter-2',
      url: 'https://www.soundhelix.com/examples/mp3/SoundHelix-Song-2.mp3',
      title: '第二章'
    }
  ],
  startIndex: 0,
  success: () => {
    BgAudio.play({ fail: (err) => console.log('歌单播放失败', err.errMsg) })
  },
  fail: (err) => console.log('加载歌单失败', err.errMsg)
})

uni-app x 使用公开的 SetPlaylistBridgeOptions 类型，以下函数放入 <script setup lang="uts">，初始化成功后调用 loadPlaylist()：

import { type SetPlaylistBridgeOptions } from '@/uni_modules/lizhao-bg-audio'

function loadPlaylist(): void {
  // tracks 使用该公开参数类型要求的数组类型。
  const tracks: Array<any> = [
    {
      id: 'chapter-1',
      url: 'https://www.soundhelix.com/examples/mp3/SoundHelix-Song-1.mp3',
      title: '第一章'
    },
    {
      id: 'chapter-2',
      url: 'https://www.soundhelix.com/examples/mp3/SoundHelix-Song-2.mp3',
      title: '第二章'
    }
  ]
  const options: SetPlaylistBridgeOptions = {
    tracks: tracks,
    startIndex: 0,
    success: (_res: any) => {
      BgAudio.play({
        fail: (err: BackgroundAudioFail) => console.log('歌单播放失败', err.errMsg)
      })
    },
    fail: (err: BackgroundAudioFail) => console.log('加载歌单失败', err.errMsg)
  }
  BgAudio.setPlaylist(options)
}

已有队列后，把下面操作分别放到切歌按钮中：

// 上一首、下一首或选中第二项；目标曲目下标从 0 开始。
function previousChapter() {
  BgAudio.skipToPrev({ fail: (err) => console.log('上一首失败', err.errMsg) })
}
function nextChapter() {
  BgAudio.skipToNext({ fail: (err) => console.log('下一首失败', err.errMsg) })
}
function selectSecondChapter() {
  BgAudio.skipToIndex({
    index: 1,
    fail: (err) => console.log('切换章节失败', err.errMsg)
  })
}

目标下标必须在列表范围内。setPlaylist 用于替换完整列表，setTrack 用于设置当前曲目；不要把 setTrack 当作清空旧歌单的方法。

模块三：追加与移除曲目

解决什么问题： 播放中修改待播列表。什么时候使用： “加入播放列表”、删除章节或取得下一集地址后。

// 追加一首待播音频；id 应在业务列表中保持唯一。
function addChapter() {
  BgAudio.appendTrack({
    track: {
      id: 'chapter-3',
      url: 'https://www.soundhelix.com/examples/mp3/SoundHelix-Song-3.mp3',
      title: '第三章'
    },
    success: () => console.log('已加入播放列表'),
    fail: (err) => console.log('追加失败', err.errMsg)
  })
}
function removeChapter() {
  BgAudio.removeTrack({
    trackId: 'chapter-3',
    success: () => console.log('列表已更新'),
    fail: (err) => console.log('移除失败', err.errMsg)
  })
}

普通追加用于更新队列；处于 waitingNext 时追加下一曲才会触发等待续播。删除当前播放项后，建议查询播放器和队列状态再刷新页面。

模块四：跳转进度与断点续听

解决什么问题： 拖动进度条或从上次位置开始。什么时候使用： 已加载曲目，需要定位到具体内容时。

// 所有时间单位均为秒；分别用于拖动进度和断点起播。
function seekToThirtySeconds() {
  BgAudio.seek({
    position: 30,
    fail: (err) => console.log('进度跳转失败', err.errMsg)
  })
}
function playFromSavedPosition() {
  BgAudio.play({
    startPosition: 90,
    fail: (err) => console.log('断点播放失败', err.errMsg)
  })
}

保存位置时同时保存曲目 id，恢复时先加载相同曲目。时长未知或音源不支持定位时，应处理失败并保留从头播放入口。

模块五：倍速、音量与循环

解决什么问题： 按收听习惯调整播放方式。什么时候使用： 音频已经加载后，用户修改播放设置时。

// 各设置分别由对应按钮调用；先查询能力再显示不确定的平台选项。
function useNormalCourseSpeed() {
  BgAudio.setPlaybackRate({
    playbackRate: 1.5,
    fail: (err) => console.log('倍速设置失败', err.errMsg)
  })
}
function useComfortableVolume() {
  BgAudio.setVolume({
    volume: 0.8,
    fail: (err) => console.log('音量设置失败', err.errMsg)
  })
}
function repeatPlaylist() {
  BgAudio.setLoopMode({
    loopMode: 'all',
    fail: (err) => console.log('循环设置失败', err.errMsg)
  })
}

倍速参数为大于 0 的数值，但实际可播范围由平台决定。包含 Harmony 的应用，建议使用 0.5 / 0.75 / 1 / 1.25 / 1.5 / 1.75 / 2 档；传入更大数值不代表能够播放到该倍速。volume 为 0～1，Harmony 当前不支持通过此 API 调整音量。

循环模式为 off（关闭循环）、single（单曲循环）、all（列表循环）。模式名称相同不代表各端循环流程完全一致，iOS、Web 和小程序的范围见“支持平台”。

模块六：用事件更新播放界面

解决什么问题： 让进度条和播放按钮跟随真实状态更新。什么时候使用： 页面展示播放器时；注册一次，退出时解除。

// 在页面 onLoad 中调用 bindPlayerView，在 onUnload 中调用返回的清理函数。
function bindPlayerView() {
  const  = (event) => console.log('当前播放进度', event.payload)
  const onState = (event) => console.log('播放状态变化', event.payload)
  const onError = (event) => console.log('播放运行错误', event.payload)
  BgAudio.on('progress', )
  BgAudio.on('stateChange', onState)
  BgAudio.on('error', onError)
  return () => {
    // 使用注册时的同一函数引用。
    BgAudio.off('progress', )
    BgAudio.off('stateChange', onState)
    BgAudio.off('error', onError)
  }
}

不要在每次 play 时重复注册事件。progress 更新较频繁，页面可以节流显示；数据库或网络保存应另设合理间隔。

多个页面分别接收和取消进度

解决什么问题： 播放页、迷你播放器等页面各自接收进度，退出一个页面不会取消其他页面的订阅。什么时候使用： 多个页面或组件共享背景音频，需要分别管理同名事件时。

下面是 uni-app 页面的脚本示例。每个页面保存自己的 token，重复调用不会多次注册，退出时只取消自己持有的订阅。

import { subscribe, unsubscribe } from '@/uni_modules/lizhao-bg-audio'

// 每个页面保存自己的 token，退出时只取消本页订阅。
export default {
  data() {
    return { progressToken: '' }
  },
  onLoad() {
    this.subscribeProgress()
  },
  onUnload() {
    if (this.progressToken === '') return
    try {
      unsubscribe(this.progressToken)
      this.progressToken = ''
    } catch (error) {
      console.error('取消进度订阅失败', error)
    }
  },
  methods: {
    subscribeProgress() {
      if (this.progressToken !== '') return
      try {
        const token = subscribe('progress', (event) => {
          console.log('本页面收到进度', event.payload)
        })
        if (token === '') {
          console.error('注册失败，请检查事件的平台支持及插件是否可用')
          return
        }
        this.progressToken = token
      } catch (error) {
        console.error('注册进度订阅失败', error)
      }
    }
  }
}

subscribe 可以在播放器初始化前调用，成功后只接收新事件；需要立即恢复界面时，另用 getPlayerState 查询当前状态。unsubscribe(token) 只取消该 token，不停止播放，也不影响其他 token 或旧 on 监听。

可复制的 uni-app 示例 与 uni-app x 示例 在同一页展示 A、B 两个独立订阅者，可分别取消、恢复并比较次数。先在完整播放示例开始播放，再通过 navigateTo 保留播放页并进入订阅页；复制后按前文方式注册页面。uni-app x 回调使用公开的 BackgroundAudioSubscriptionEvent 类型。

模块七：系统媒体卡与音频中断

解决什么问题： 让锁屏、通知栏和耳机控制与应用内状态一致。什么时候使用： App 后台收听与系统控制联动。

基础示例中的 title、singer 会用于媒体信息；需要封面时补充曲目的 cover。播放控制由插件和系统协作处理，页面监听事件以刷新界面。

// 初始化前注册；业务结束时调用返回的清理函数。
function bindSystemAudioEvents() {
  const onRemote = (event) => {
    // 已处理的系统命令不要再次执行，以免一次点击切换两首。
    console.log('收到系统媒体控制', event.payload)
  }
  const onInterruption = (event) => {
    console.log('收到音频中断或恢复通知', event.payload)
    BgAudio.getPlayerState({
      success: (state) => console.log('中断后的播放状态', state),
      fail: (err) => console.log('读取状态失败', err.errMsg)
    })
  }
  BgAudio.on('remoteCommand', onRemote)
  BgAudio.on('interruption', onInterruption)
  return () => {
    BgAudio.off('remoteCommand', onRemote)
    BgAudio.off('interruption', onInterruption)
  }
}

Android 可在初始化时通过 notificationActions 选择按钮，默认上一首、播放/暂停、下一首；最终外观和可见按钮仍由系统决定。iOS 的 autoRecover 控制系统允许恢复时是否自动续播，不能保证每次中断都会自动恢复。

模块八：动态获取下一集、等待与超时

解决什么问题： 下一集地址需要先请求业务接口，当前曲结束前无法一次拿到整个列表。什么时候使用： Android / Harmony 的动态课程、临时鉴权音频或推荐列表。

“智能下一曲”会提前通知业务补充队列，不会替业务下载或缓存下一曲。先在基础示例的初始化参数中加入：

// 合入业务的初始化流程，成功后仍需设置曲目或歌单并播放。
BgAudio.initPlayer({
  preloadNext: true,
  preloadNextTime: 20,
  nextTrackTimeout: 15000,
  success: () => console.log('动态下一曲已开启'),
  fail: (err) => console.log('初始化失败', err.errMsg)
})

播放前注册以下监听。此例用固定演示曲目表示“业务已取得下一曲”，实际接入时在自己的接口成功回调中调用 appendTrack，并处理接口失败。

// 在音频业务初始化时调用一次；结束该业务后调用返回的清理函数。
function bindSmartNext() {
  let appended = false
  const onPreloadNext = (_event) => {
    // 本例只补充一首；实际业务按章节 id 去重，并忽略已切换曲目的过期请求。
    if (appended) return
    appended = true
    BgAudio.appendTrack({
      track: {
        id: 'next-demo',
        url: 'https://www.soundhelix.com/examples/mp3/SoundHelix-Song-2.mp3',
        title: '下一集演示'
      },
      success: () => console.log('下一集已加入队列'),
      fail: (err) => {
        appended = false
        console.log('追加下一集失败', err.errMsg)
      }
    })
  }
  const Next = (event) => console.log('正在等待下一集', event.payload)
  const onNextTimeout = (event) => console.log('等待超时，可提示手动重试', event.payload)
  BgAudio.on('preloadNext', onPreloadNext)
  BgAudio.on('waitingNext', Next)
  BgAudio.on('nextTrackTimeout', onNextTimeout)
  return () => {
    BgAudio.off('preloadNext', onPreloadNext)
    BgAudio.off('waitingNext', Next)
    BgAudio.off('nextTrackTimeout', onNextTimeout)
  }
}

触发条件是：已开启 preloadNext、loopMode='off'、当前曲目处于队列末尾，而且还没有下一曲。提前触发还要求能取得有效时长；同一次曲目播放过程只请求一次。已经加载了完整歌单时，不会为了已有的下一曲重复触发请求。

当前曲结束仍未补齐下一曲时进入 waitingNext；等待期间成功追加会自动续播。nextTrackTimeout=0 表示不自动超时；超时后会通知 nextTrackTimeout，此后补充曲目需要业务明确发起播放。主动停止、切歌或重新设置歌单会结束原来的等待任务。

需要离开页面后继续获取下一集时，应把这组业务监听放在应用级音频管理中。iOS、Web 和小程序目前不承诺上述三个事件及等待自动续播完整可用。

模块九：查询状态、队列与可用能力

解决什么问题： 返回页面时恢复播放器 UI，或按运行环境隐藏不可用操作。什么时候使用： 页面显示、设置功能入口之前、队列修改之后。

// 三种查询按业务需要独立调用，返回数据通过 success 读取。
BgAudio.getPlayerState({
  success: (state) => console.log('播放器状态', state),
  fail: (err) => console.log('读取播放器状态失败', err.errMsg)
})
BgAudio.getQueueState({
  success: (queue) => console.log('播放队列', queue),
  fail: (err) => console.log('读取队列失败', err.errMsg)
})
BgAudio.getCapabilities({
  success: (caps) => console.log('当前平台能力', caps),
  fail: (err) => console.log('读取能力失败', err.errMsg)
})

能力查询用于判断接口是否可用；它不代表某个音源一定可以播放，也不表示系统允许应用无限期后台运行。调用后仍需处理 fail 和 error。

模块十：收集播放问题信息

解决什么问题： 遇到初始化或播放异常时，取得有用的反馈信息。什么时候使用： 用户主动反馈问题或开发联调时。

// 绑定到“查看播放诊断”按钮；先保存记录，需要重现问题时再清空。
function readAudioDiagnostics() {
  try {
    console.log('播放诊断记录', BgAudio.getDebugTrace())
    console.log('异常记录', BgAudio.getCrashReports())
  } catch (error) {
    console.log('读取诊断失败', error)
  }
}
function clearAudioDiagnostics() {
  try {
    BgAudio.clearDebugTrace()
    BgAudio.clearCrashReports()
    console.log('诊断记录已清空')
  } catch (error) {
    console.log('清空诊断失败', error)
  }
}

需要控制台日志时，在业务初始化中打开 debug：

// 用于开发联调；合入原有初始化流程，日常使用保持默认关闭。
BgAudio.initPlayer({
  debug: true,
  success: () => console.log('调试日志已开启'),
  fail: (err) => console.log('初始化失败', err.errMsg)
})

Android / iOS 可保留部分初始化诊断；Harmony / Web 提供运行期间的记录；微信小程序返回空数组。异常记录的覆盖范围因平台而异，空数组不能作为“从未发生错误”的依据。

API 用途速查

部分平台还保留无参数兼容入口 initPlayerNoOptions()；新接入统一使用有失败回调的 initPlayer(options)。

常用参数查询

初始化参数

曲目信息 BackgroundAudioTrack

播放与队列参数

已有项目使用 setTrack({ track, tracks, tracksPayloadJson, ... }) 的兼容调用可以保留；新列表使用 setPlaylist。tracksPayloadJson 是可选曲目数据快照，格式为 JSON.stringify({ tracks })，通常不需要手工填写；它不能替代必要的曲目信息。

通用回调

业务操作与查询使用这些回调；on/off、subscribe/unsubscribe 和四个诊断方法不使用 options 回调。建议使用 success: (res) => {}、fail: (err) => {} 字段写法。播放命令的成功回调不等于音频已经播完，后续网络或解码异常仍可能通过 error 返回。

返回值说明

initPlayer 的成功结果包含 initialized 与 capabilities。其他控制操作的成功结果可能随平台不同；需要完整状态时使用对应查询 API。

播放器状态 getPlayerState

队列状态 getQueueState

平台能力 getCapabilities

事件与回调

on(eventName, callback) 注册事件，off(eventName, callback) 取消订阅。事件对象包含 name、payload 与毫秒时间戳 timestamp。payload 的字段依事件和平台不同，使用前检查是否存在。

subscribe(eventName, callback) 返回独立的字符串 token，其回调收到 BackgroundAudioSubscriptionEvent：包含 subscriptionId（本次 token）、name、payload（可为 null）和毫秒时间戳 timestamp。旧 on 回调结构保持不变。

每次成功注册都会取得新的 token，即使传入同一个回调也不合并。未知事件、当前平台未实现的事件或无效回调返回空字符串，不建立订阅。unsubscribe(token) 首次取消有效订阅返回 true；空、未知或已取消的 token 返回 false。token 仅用于当前插件实例，不保存到本地或跨应用重启复用；调用异常应由业务捕获并显示失败。

循环和自动续播过程可能在平台内部处理完成事件，不能把 ended 当作所有平台每首必到的计数器。remoteCommand 的具体命令依系统而定；存在 handled=true 时表示已经处理，deferToPage=true 时才需要业务根据自己的列表决定后续行为。

订阅边界： 当前 Android、iOS、微信小程序以及公共入口的 off 会清空指定事件的订阅组；Harmony 和 Web 可以按传入函数取消。请始终保存并传入同一函数引用，跨页面共享播放器时统一管理订阅，避免页面卸载影响另一个页面的同名事件。

使用独立订阅时，保存 token 并用 unsubscribe 取消；旧 off 不会清理 subscribe 创建的订阅，unsubscribe 也不会清理旧 on 监听。两套接口混用时不依赖它们之间的回调先后顺序。

subscribe 的事件支持范围如下；注册成功表示已接收订阅，具体事件仍需满足对应的播放或系统条件：

支持平台

需要按平台处理的差异

• 倍速： Android、iOS 和 Web 的可播范围受系统、浏览器、编码格式影响；小程序依运行环境提供的能力。Harmony 会把正数映射到最近的 0.5 / 0.75 / 1 / 1.25 / 1.5 / 1.75 / 2 档，状态中的请求值不能证明实际已按更高倍速播放。
• 音量： Android / iOS / Web 可调用；Harmony 不支持。小程序后台音频通常不能通过插件设置音量，普通音频降级模式可能可用，先查看 volume 能力。
• 系统控制： App 提供媒体卡接入；Android 13 及以上可能按系统规则决定按钮位置。Web 需要浏览器支持媒体控制；微信依后台管理器能力。
• 循环： iOS 当前提供多曲列表循环；单曲循环和仅一项列表循环尚未实现自动重播。Web 可使用单曲循环，列表自动循环不能仅凭设置成功认定已支持；小程序同样需要按平台处理自动续播业务。
• 动态下一曲： Android / Harmony 提供提前通知、等待与超时处理；iOS、Web、小程序不应依赖这组三个事件及等待期间的自动续播。
• 中断恢复： iOS 按 autoRecover 与系统是否允许恢复共同决定；Android 等平台的焦点恢复通知不等于自动恢复播放，业务应根据真实状态更新 UI。
• 音源与封面： HTTPS 地址最便于多端复用；本地文件、请求头、封面 data URI 和特殊编码格式不能按统一参数类型推定全平台支持。使用需要鉴权的地址前，先验证目标平台的实际播放请求。

错误码说明

失败对象通常包含 errSubject='lizhao-bg-audio'、errCode、errMsg 和可选的 details。定位问题时同时保留错误码、信息及当前操作，不要只记录“播放失败”。

注意事项

• 首次在 App 使用时，安装包含本插件的自定义基座或正式包；原生逻辑或平台配置变化后需重新制作对应平台安装包，iOS 原生修复不能仅通过页面资源或 WGT 更新生效。只改页面和文档通常无需重打 Android 自定义基座。
• Android 网络音频需要网络访问能力，媒体通知受系统通知与后台策略影响；iOS 后台收听需要启用 UIBackgroundModes: audio。使用标准基座出现插件不可用时，先改用包含本插件的安装包。
• Harmony 后台收听需要在应用 EntryAbility 声明 backgroundModes: ["audioPlayback"]，并声明 ohos.permission.INTERNET 和 ohos.permission.KEEP_BACKGROUND_RUNNING；修改配置后重新打包。
• 微信后台音频需按平台要求配置 requiredBackgroundModes: ["audio"]。浏览器通常要求由用户点击发起首次播放。
• 系统省电、强制关闭应用、断网、音源失效与其他应用争用音频，都可能影响后台播放；不要把能力查询中的 backgroundAudio=true 当作持续播放保证。
• 播放器供应用共享，不为每个页面创建独立实例。普通页面卸载时解除页面事件，主动结束收听业务时再 stop；应用级下一曲业务监听应随收听业务管理。
• setPlaylist、setTrack 或播放控制的成功，表示本次命令已处理；真实可听状态应结合 stateChange、progress 和错误事件判断。
• 不要在每次进度更新时保存数据库、弹 Toast 或发起网络请求。音频地址和日志可能含鉴权参数，反馈前请去掉账号、口令、Token 等敏感内容。

联系方式

信-微：l-z-1-8-7-1512-5421（去掉短横线）

作者系列 UTS 插件

以下为已在 DCloud 插件市场上架的作者系列 UTS 插件，可按业务场景组合使用。未列出的插件表示当前未确认公开市场页，后续上架后再补充。