背景音频播放器UTS插件（安卓、IOS、鸿蒙等） - 更新日志

1.2.42（2026-06-06）

iOS 媒体卡按键最终收口：initPlayerByIos() 原生初始化入口直接强制 autoRegisterRemoteCommand = true，不再根据 options.autoRegisterRemoteCommand 推导全局开关，避免 HBuilderX 5.07 生成层把可选 boolean 再次落成 false 后跳过 MPRemoteCommandCenter target 注册。
iOS 媒体卡诊断增强：新增常开 traceIosMediaCard()，并补充 媒体卡 wrapper 默认注册已强制开启、媒体卡原生初始化强制注册、媒体卡 target 注册开始/完成 等日志；真机初始化后应看到 autoRegister=true 和 target token 状态。
iOS 云打包兼容：clearRemoteCommandTargets() 通过 Swift helper 使用 let allTargets: Any? = nil 清理旧 target；iOS OptionsImpl 构造器不再使用默认 = null，内部兜底调用显式传入带上下文的 null，避免云端 Swift 生成裸 nil。
iOS 媒体卡 token 保活：强引用保存 MPRemoteCommand.addTarget(handler:) 返回的 remotePlayTarget / remotePauseTarget / remoteStopTarget / remoteTogglePlayPauseTarget / remoteNextTarget / remotePrevTarget / remoteSeekTarget token，避免 handler 被释放后状态栏播放、暂停、上一首、下一首点击无效。
iOS 媒体卡按键二次修复：MPRemoteCommandCenter.addTarget(handler:) 返回的是 iOS 原生 token，不一定是 UTSCallback，注册前不再依赖 instanceof UTSCallback 才移除旧 target。
iOS 远程命令注册增强：每次初始化/重新注册媒体卡命令前，通过 Swift helper 对 play / pause / stop / playPause / next / prev / seek 对应的系统命令统一执行 removeTarget(nil)，清理差量编译或重复初始化残留的旧 handler，避免旧 handler 先返回 success 后导致状态栏媒体卡点击无效。
iOS 媒体卡执行链路保持原生优先：播放、暂停、停止、上一首、下一首和 playPause 仍由 iOS 平台层先直接消费命令，再上报 remoteCommand 且标记 handled=true，页面只作为日志和业务观察方。
发布日志与诊断标记同步：示例页和插件内置完整示例构建标记更新为 2026-06-06-bg-audio-1.2.42-native-force-remote-register，iOS 原生 trace 标记更新为 lizhao-bg-audio/1.2.42-ios-native-force-remote-register@2026-06-06。
package.json、uni_modules.json 和 README 当前版本统一升级为 1.2.42；发布 iOS 包时请重新云打包或重新制作/安装包含本轮 iOS UTS 生成物的自定义基座。

1.2.41（2026-06-06）

iOS 发布确认版：针对初始化成功后页面按钮不再触发 success / fail / complete、点击 skipToIndexOne 闪退的问题，固定发布到 1.2.41，便于客户区分 1.2.40 诊断包与本次可发布包。
iOS typed bridge 回调链路收口：play / pause / resume / stop / seek / setTrack / setPlaylist / appendTrack / skipToIndex / getPlayerState / getCapabilities 等入口继续保留强类型桥接字段优先读取，确保页面按文档传入回调时能真实触发。
iOS skipToIndex 稳定性确认：目标曲加载完成后先返回 success / complete，再延迟一拍自动播放，避免同一原生命令栈内嵌套播放导致闪退。
发布日志与诊断标记同步：示例页和插件内置完整示例构建标记更新为 2026-06-06-bg-audio-1.2.41-release，iOS 原生 trace 标记更新为 lizhao-bg-audio/1.2.41-ios-typed-callback-release@2026-06-06。
package.json、uni_modules.json 和 README 当前版本统一升级为 1.2.41；发布 iOS 包时请重新云打包或重新制作/安装包含本轮 iOS UTS 生成物的自定义基座。

1.2.39（2026-06-04）

合并 Android 歌单加载最终修复：重新制作 Android 自定义基座后，用户已确认点击【初始化】->【加载歌单】流程正常，不再出现 9012002 tracks 为必填项。
Android SetPlaylistBridgeOptions.tracks 保持 Array<any>，并保留 tracksPayloadJson 普通 JSON 快照兜底，避免 HBuilderX 5.07 ByJs 对对象数组字段预包装或读取不稳定时丢失歌单。
Android setPlaylist({ tracks, tracksPayloadJson, success, fail }) 恢复强类型回调桥接，稳定生成 success/fail/complete callback wrapper；页面侧现在可收到 setPlaylist success，返回当前下标与队列长度。
Android setPlaylist() 增加首曲装载成功回调兜底：内部 setTrack 已完成但未回传 success 时，短延迟确认队列已设置并主动返回 currentIndex / queueLength。
Android 错误详情补充 hasTracksField 与 tracksPayloadJsonLength，用于区分页面未传参、JS 资源未更新、原生基座未更新或桥接字段丢失。
iOS 同步支持 tracksPayloadJson，并保持逐项归一化入队，避免公共桥接类型放宽后影响 iOS 编译和运行稳定性。
示例页“加载歌单”输出 setPlaylist 参数确认 日志，包含曲目数量、曲目 id 与 JSON 快照长度；构建标记统一为 2026-06-04-bg-audio-1.2.39-android-release。
插件 example/backgroundAudio.vue 新增完整演示页，客户下载插件后可直接复制到 pages/backgroundAudio/backgroundAudio.vue 使用；README 同步补充页面注册与自定义基座说明。
更新 Android 队列守卫、回调桥接守卫与版本守卫，锁定对象数组兜底、强类型回调桥接和 1.2.39 发布版本，防止后续回退。
package.json 与 uni_modules.json 版本号统一为 1.2.39；发布 Android 包时请使用包含本轮 Android 原生 UTS 生成物的新自定义基座。

1.2.38（2026-06-04）

Android 修复示例页 loadPlaylist() 加载 3 首歌后只能切到第 2 首的问题：非 iOS 平台改为直接调用 setPlaylist({ tracks, startIndex: 0 }) 一次性下发完整队列，不再依赖 appendTrack success 递归追加尾曲。
Android 演示页新增歌单队列诊断日志，加载和切歌后输出队列长度与曲目 ID，便于通过 logcat 判断 queueLength 是否为完整歌单。
保留 iOS 旧 setTrack + appendTrack 兼容路径，避免影响旧 iOS 自定义基座的桥接稳定性。
更新 Android 队列守卫脚本，锁定非 iOS 示例页必须使用 setPlaylist 加载完整歌单，防止回退为回调链式追加。
已在雷电模拟器验证：加载 3 首歌返回 queueLength=3，连续点击两次下一首不再出现 9012004 没有下一首曲目；第 3 首若使用网易云临时地址可能因音源过期单独返回 9012005 播放失败，发布示例建议替换稳定音源。
package.json 与 uni_modules.json 版本号升级到 1.2.38，用于发布 Android 歌单下一首边界修复版。

1.2.37（2026-06-03）

Android 修复 initPlayer() 使用 success / fail / complete 时不回调的问题：公开入口改用显式 InitPlayerBridgeOptions type，避免 HBuilderX App 端代理生成时丢失页面回调。
Android 修复 setPlaylist() 成功回调不触发，以及随后 play() 不播放且无回调的问题：setPlaylist / play 公开入口改用 SetPlaylistBridgeOptions / PlayBridgeOptions，内部再转换为原播放参数执行。
根入口与 iOS 同名 wrapper 同步使用桥接参数类型，避免 App 端共用 JS 代理被旧签名拖回 interface extends BackgroundAudioCallbacks 的不稳定生成形态。
README “先看最小接入”示例改为页面生命周期内注册事件、方法内初始化和箭头函数回调写法，避免客户在 <script> 顶层直接调用初始化导致回调时机不稳定。
新增回调桥接守卫脚本，锁定 initPlayer / setPlaylist / play 在 Android 生成物中必须生成带 UTSCallback 字段的 *BridgeOptionsJSONObject。
已在 Android 模拟器验证：initPlayer、setPlaylist、play 均触发成功回调，播放器进入播放态并持续上报进度。
package.json 与 uni_modules.json 版本号升级到 1.2.37，用于发布 Android App 回调桥接修复版；发布后建议继续回归 iOS 同名入口回调。

1.2.36（2026-05-27）

新增智能下一曲预加载：initPlayer({ preloadNext, preloadNextTime, nextTrackTimeout }) 可在队列末尾临近结束时触发 preloadNext，方便业务提前请求下一曲接口。
新增 waitingNext 状态和 waitingNext / nextTrackTimeout 事件；当前曲播完但下一曲接口尚未返回时，插件会等待业务调用 appendTrack()。
appendTrack() 在 waitingNext 状态下追加到下一曲后会自动续播，并在成功回调中返回 autoPlay: true。
Harmony 补齐平台入口自己的智能下一曲预加载状态机，解决鸿蒙真机直接走 utssdk/app-harmony/index.uts 时只在根入口实现预加载、页面收不到 preloadNext 的问题。
Harmony 新增显式 HarmonyNextTrackPayload 事件负载类，修复 ArkTS 严格模式 arkts-no-untyped-obj-literals 编译错误，确保鸿蒙运行包可正常制作。
示例页“加载单曲预加载测试”改为唯一 id 和唯一 url 的 setTrack() 单曲队列，并自动播放、自动跳到预加载触发点，便于真机确认 preloadNext -> appendTrack -> 自动续播 全流程。
README 补充智能下一曲预加载完整示例、触发条件、队列末尾限制、Harmony 真机测试建议和“跳到预加载触发点”注意事项，避免误认为点击播放一定触发预加载回调。
已在 Harmony 真机 nova 14 Pro 验证：剩余约 18 秒触发 preloadNext，3 秒后模拟接口 appendTrack 成功，原曲结束后自动切到追加曲继续播放。
package.json 与 uni_modules.json 版本号升级到 1.2.36，用于发布智能下一曲预加载与 Harmony 真机补修版。

1.2.35（2026-05-27）

新增 initPlayer({ debug }) 配置项，默认 false，用于控制插件内部 console.log / console.warn 调试输出。
Android / iOS / Harmony / 根入口日志统一收口到 debug 开关；getDebugTrace() 诊断链路继续保留，方便正式包默认安静、排查时显式开启日志。
README 补充 debug 参数说明和示例，package.json 与 uni_modules.json 版本号升级到 1.2.35。

1.2.34（2026-05-27）

Harmony 按上架检测建议优化短音、瞬态音播放场景的音频焦点策略：AVPlayer 创建后、首次 prepare() / play() 前激活 AudioSessionManager 的 CONCURRENCY_MIX_WITH_OTHERS 并发策略，并显式设置 audioInterruptMode = SHARE_MODE，避免被系统按 stop 独占焦点策略识别。
Harmony AVPlayer 同步设置 audioRendererInfo.usage = STREAM_USAGE_MUSIC 与 rendererFlags = 0，让后台音乐可按系统策略并发播放或短暂暂停后自动恢复。
Harmony 新增 audioSession.concurrency.mix 与 avPlayer.audioFocus.share 中文诊断日志，方便真机确认发布包已包含音频焦点策略下发。
新增 check-bg-audio-harmony-audio-focus.js，锁定 CONCURRENCY_MIX_WITH_OTHERS、SHARE_MODE、rendererInfo 以及配置调用必须早于首次 prepare() / play()。
package.json 和 uni_modules.json 版本号升级到 1.2.34，用于发布 Harmony 上架短音焦点策略优化版。

1.2.33（2026-05-26）

Android 修复页面调用 BgAudio.seek({ position, success, fail }) 后实际已经跳转、但 success / complete 回调不触发的问题：根入口和 Android 平台入口统一改为强类型 SeekOptions | null，让 HBuilderX ByJs 生成层把页面 callback id 还原为可调用回调。
Android 保留 position 动态字段兜底和超过真实时长时 clamp 到末尾的旧逻辑，避免修复回调桥接时回退 1.1.23 已修复的 9012006 跳转位置非法 问题。
更新 check-bg-audio-android-seek-position.js，锁定根入口和 Android 平台入口不能再使用 any | null，防止后续重新引入 seek success 回调丢失。
已复验 Android seek、iOS action 回调、Android 静态告警、调试桥接、通知状态和倍速运行时回归脚本，并完成 Android 平台 lsp lint 语法校验。
package.json 和 uni_modules.json 版本号升级到 1.2.33，用于发布 Android seek 成功回调桥接修复版。

1.2.32（2026-05-25）

Harmony 修复息屏播放到当前曲完成后不自动播放下一首、媒体卡手动控制可能卡住的问题：自然完成事件由平台层先判断队列并直接续播，loopMode=off 现在按列表顺序播放到末尾。
Harmony 新增自然完成事件消费保护，避免 AVPlayer completed 与 BackgroundAudioManager 重复上报导致根入口二次切歌或 AVSession 进入 completed 后难以恢复。
Harmony 工程配置补齐 harmony-configs/entry/src/main/module.json5，EntryAbility 增加 backgroundModes: ["audioPlayback"]，并声明 ohos.permission.INTERNET 与 ohos.permission.KEEP_BACKGROUND_RUNNING，用于息屏后台音频连续任务。
readme 补充 Harmony 后台音频 module.json5 配置示例，明确发布或真机验证前必须重新打鸿蒙自定义基座或运行包。
新增 check-bg-audio-harmony-ended-autoplay.js 与 check-bg-audio-harmony-background-config.js，锁定息屏续播和后台配置，防止发布前误删。
package.json 和 uni_modules.json 版本号升级到 1.2.32，用于发布 Harmony 息屏后台播放与媒体卡续播修复版。

1.2.31（2026-05-25）

Harmony 播放入口新增后台音频连续任务申请，使用当前 Ability 的 bundleName / abilityName 创建 WantAgent，避免发布包继续依赖测试包名。
Harmony 停止播放时释放后台音频连续任务，停止后不再继续占用后台运行名额。
Harmony 后台音频保活新增请求序号保护，停止后晚到的启动结果会记录为“后台音频保活开启结果已过期”，不再误改运行状态。
Harmony 后台保活日志统一走 getDebugTrace() 诊断链路，日志保持中文且精简，便于发布包真机排查。
package.json 和 uni_modules.json 版本号升级到 1.2.31，用于发布 Harmony 后台音频保活和日志规范修复版。

1.2.30（2026-05-24）

Harmony 修复 App 重启后媒体卡下一首标题短暂闪回首次加载音频标题的问题：平台队列只有旧当前项时，媒体卡下一首/上一首命令改为派发 deferToPage=true，交给页面业务歌单加载目标曲目，不再由平台层抢先 skipToNext(null)。
Harmony / 根入口队列匹配改为 URL 优先、ID 兜底，避免多集课程共用同一个业务 track.id 时，把第二首、第三首误认为第一次加载的队列项。
Harmony setTrack 命中同 ID 旧项时会替换队列缓存内容，确保 AVSession 队列项里的 title/url 跟当前真实音频一致。
Harmony 补充 remote.next.defer、queue.sameIdDifferentUrl、setTrack.replaceCached 等真机诊断日志，便于确认媒体卡命令是否已交给页面歌单，以及旧标题缓存是否被替换。
更新 check-bg-audio-harmony-avsession.js 与 check-bg-audio-harmony-remote-autoplay.js，锁定 activeItemId + metadata 同步顺序、URL 优先匹配和旧一项队列 defer 行为。
Android 修复 SeekOptions? 传入 BackgroundAudioCallbacks? 导致云打包 Kotlin 编译失败：新增 failSeekOptions / successSeekOptions，seekByAndroid 不再把独立 SeekOptions type 直接传给通用回调 helper。
更新 check-bg-audio-android-seek-position.js，锁定 Android seek 链路必须使用 SeekOptions 专用回调 helper，防止后续回退为 fail(..., options) / success(options, ...)。
版本号升级到 1.2.30，用于发布已通过鸿蒙真机验证和 Android 云打包验证的媒体卡标题闪回与 Android seek 类型适配修复版。

1.2.29（2026-05-24）

Harmony 修复 App 重启后媒体卡下一首标题短暂闪回首次加载音频标题的问题：平台队列只有旧当前项时，媒体卡下一首/上一首命令改为派发 deferToPage=true，交给页面业务歌单加载目标曲目，不再由平台层抢先 skipToNext(null)。
Harmony / 根入口队列匹配改为 URL 优先、ID 兜底，避免多集课程共用同一个业务 track.id 时，把第二首、第三首误认为第一次加载的队列项。
Harmony setTrack 命中同 ID 旧项时会替换队列缓存内容，确保 AVSession 队列项里的 title/url 跟当前真实音频一致。
Harmony 补充 remote.next.defer、queue.sameIdDifferentUrl、setTrack.replaceCached 等真机诊断日志，便于确认媒体卡命令是否已交给页面歌单，以及旧标题缓存是否被替换。
更新 check-bg-audio-harmony-avsession.js 与 check-bg-audio-harmony-remote-autoplay.js，锁定 activeItemId + metadata 同步顺序、URL 优先匹配和旧一项队列 defer 行为。
版本号升级到 1.2.29，用于发布已通过鸿蒙真机验证的媒体卡标题闪回修复版。

1.2.28（2026-05-23）

Harmony 修复点击播放、以及暂停后再次点击播放时页面先收到 stateChange=paused、随后才收到 playing 的问题：播放入口到 AVPlayer 确认 playing 期间增加短保护，过滤 manager / AVPlayer 启动瞬间的过渡 paused。
Harmony 新增 avPlayerPlayStartingByHarmony 与 shouldSuppressTransientPausedByHarmony，仅在播放启动、等待 initialized、等待 prepared 或 manager canplay 自动续播阶段屏蔽过渡暂停。
根入口新增 rootPlayStarting 兜底保护，play / resume 启动窗口内如果平台桥仍上报旧 paused，会在根事件桥拦截并输出中文日志，避免页面收到假暂停。
Harmony pauseByHarmony / stopByHarmony 主动控制命令会立即清理播放启动保护，避免真实用户暂停或停止被误吞。
新增 check-bg-audio-harmony-play-transient-paused.js 与 check-bg-audio-root-play-paused-guard.js，锁定播放启动中不能再把过渡 paused 派发到页面。
iOS 修复 BgAudio.seek({ position, success }) 已经完成跳转和进度更新，但页面 success / complete 回调不触发的问题：SeekOptions 改为对象 type 并显式声明 position / success / fail / complete，让 HBuilderX 生成 SeekOptionsJSONObject，把页面 callback id 还原为可调用闭包。
iOS seek 平台入口改为强类型 SeekOptions | null，新增 failSeekOptions / successSeekOptions / ensureRuntimeBySeekOptions，避免把 SeekOptions 结构化传给通用 BackgroundAudioCallbacks helper 后在 Swift/云打包层出现类型不匹配。
iOS seekByIos 成功后补充中文诊断日志 跳转命令成功回调已触发 与 seekByIos.success.callback trace，方便真机确认当前基座是否包含本次修复。
Android 同步移除 SeekOptionsImpl implements SeekOptions，改用 createSeekOptionsByAndroid() 对象字面量工厂，避免共享 SeekOptions 从 interface 改为对象 type 后后续 Android 编译触发 class implements 问题。
更新 check-bg-audio-ios-action-callbacks.js 和 check-bg-audio-android-seek-position.js，锁定 iOS seekByJs(_ options: SeekOptionsJSONObject?)、app-service UTSSDKModulesLizhaoBgAudioSeekOptionsJSONObject 参数类型，以及 Android 不再使用 SeekOptionsImpl。
iOS trace 标记同步更新为 lizhao-bg-audio/1.2.28-ios-seek-success-callback@2026-05-23，用于发布包和真机日志确认版本。
iOS trace 标记同步更新为 lizhao-bg-audio/1.2.28-ios-stop-success-callback@2026-05-22，方便发布包和真机日志确认版本。
版本号保持 1.2.28，用于合并发布 Harmony 过渡暂停过滤与 iOS seek success 回调修复补丁。

1.2.27（2026-05-22）

Harmony 真机验证通过后发布补丁版：保留 1.2.26 的 Android 倍速 9012002 最终补修和 Harmony 控制命令 ArkTS 编译补修。
Harmony 控制命令继续使用 ActionOptions 专用适配层，暂停、恢复、停止、上一首、下一首不再把 ActionOptions 结构化传给 BackgroundAudioCallbacks helper。
iOS trace 标记同步更新为 lizhao-bg-audio/1.2.27-ios-stop-success-callback@2026-05-22，方便发布包和真机日志确认版本。
版本号升级到 1.2.27，用于发布已通过鸿蒙真机验证的稳定版。

1.2.26（2026-05-22）

Android 补修 1.2.25 后真机点击倍速仍返回 9012002 参数不合法 的问题：Android 平台导出入口 setPlaybackRate 改为接收原始 any，避免生成层先把页面参数转成 SetPlaybackRateOptions? 时丢失 playbackRate。
Android 新增 normalizeSetPlaybackRateOptionsByAndroid，统一从原始桥接对象恢复 playbackRate / success / fail / complete，再构造 SetPlaybackRateOptionsImpl 交给原生 PlaybackParams.setSpeed()。
Android 回归脚本继续锁定根入口动态字段兜底、平台入口先归一化、生成 Kotlin setPlaybackRateByJs(options: Any?)，防止后续重新退回强类型入口导致倍速失效。
iOS trace 标记同步更新为 lizhao-bg-audio/1.2.26-ios-stop-success-callback@2026-05-22，方便发布包和真机日志确认版本。
版本号升级到 1.2.26，用于发布 Android 倍速 9012002 最终补修版。

1.2.25（2026-05-22）

Android 修复 Android 13+ / targetSdk 33+ 系统媒体卡显示旧版 android.R.drawable.ic_media_* 控制图标导致视觉发虚的问题：新系统不再向通知添加 legacy Notification.Action 图标，改由系统按 PlaybackState 生成上一首、播放/暂停、下一首控件。
Android 12 及更低版本、或旧 targetSdk 基座仍保留 MediaStyle + Notification.Action 兜底，保证旧系统通知栏按钮继续可点。
iOS 修复 BgAudio.stop({ success }) 已执行停止逻辑并派发 stateChange=stopped，但页面 success / complete 回调没有触发的问题：stop 入口改为强类型 ActionOptions，让 HBuilderX 生成层输出 ActionOptionsJSONObject 并把页面 callback id 还原为可调用闭包。
iOS ActionOptions 改为对象 type 并显式声明 success / fail / complete，内部控制参数统一使用对象字面量 as ActionOptions，避免 Swift 生成 ActionOptionsImpl : NSObject, ActionOptions 多继承错误。
iOS 新增 failActionOptions / successActionOptions / ensureRuntimeByActionOptions，控制类命令不再把 ActionOptions 传入 BackgroundAudioCallbacks helper，修复云打包 ActionOptions does not conform to BackgroundAudioCallbacks。
iOS 停止命令补充中文诊断日志 停止命令入口回调检查、停止命令成功回调已触发 与 stopByIos.success.callback trace，方便真机确认 stop 命令回调链路。
更新 Android 16 媒体通知回归脚本，锁定新旧系统分流逻辑，避免后续重新把旧图标无条件添加到系统媒体卡。
更新 iOS action 回调回归脚本，锁定 stopByJs(_ options: ActionOptionsJSONObject?)、JS proxy 的 UTSSDKModulesLizhaoBgAudioActionOptionsJSONObject 参数类型，以及 Swift 产物不能再出现 ActionOptionsImpl : NSObject, ActionOptions 或 ActionOptions 传入 BackgroundAudioCallbacks helper。
版本号升级到 1.2.25，用于发布 Android 系统媒体卡图标清晰度、iOS stop 成功回调桥接和 iOS 云打包兼容修复。

1.1.24（2026-05-20）

iOS 修复最低支持 iOS 12.0 时云打包报 'playbackState' is only available in iOS 13.0 or newer：UTS 层不再直接访问 MPNowPlayingInfoCenter.playbackState，改由 Swift helper 使用 #available(iOS 13.0, *) 保护。
iOS 12 继续通过 nowPlayingInfo 的 elapsed/duration/rate 同步控制中心进度；iOS 13+ 额外同步 playbackState，保持媒体卡播放态一致。
新增 NowPlaying iOS 12 兼容静态回归检查，防止后续再次在 UTS 入口直接引用 iOS 13+ 的 playbackState。
Harmony 强制改为 AVPlayer + AVSession 原生链路：AVPlayer 负责真实播放、跳转和 setSpeed() 倍速，AVSession 负责系统媒体卡、上一首/下一首、播放暂停、seek 和 setSpeed 命令。
Harmony 不再写入 BackgroundAudioManager.playbackRate，避免真机点击倍速触发 9012005 播放失败；能力矩阵在原生链路可用时返回 playbackRate=true、sessionLevel=native。
Harmony 保留 BackgroundAudioManager 作为环境探测和旧状态栏命令兜底，同时新增 check-bg-audio-harmony-avplayer-engine.js、check-bg-audio-harmony-avsession.js，锁定倍速、跳转和系统媒体卡桥接。
Harmony 修复真机首次点击播放需要点两次的问题：AVPlayer 写入 url 后如果仍处于 idle，现在会等待 stateChange=initialized 后再执行 prepare()，避免首次播放触发 9012005 Harmony AVPlayer 准备播放失败。
Harmony 优化播放状态机打断逻辑：暂停、停止会同步清理等待 initialized 的播放意图，避免用户打断后被异步初始化回调重新拉起播放。
Harmony 修复 AVSession 严格 ArkTS 编译问题：媒体卡播放、暂停、停止命令不再向非空 ActionOptions 传 null，队列项改为显式类实例，规避 arkts-no-untyped-obj-literals 和 UTSJSONObject is not assignable to AVQueueItem。
新增 Harmony AVPlayer 首次播放回归检查和问题复盘，锁定 idle -> initialized -> prepared -> playing 的真机状态机顺序，避免后续回退到立即 prepare()。
版本号保持 1.1.24，用于发布 iOS 12 兼容和 Harmony 倍速、跳转、媒体卡、首次播放稳定性修复。

1.1.23（2026-05-18）

Android 对齐 iOS 事件回调链路：on(eventName, callback) 保存 BackgroundAudioEventCallback 后由 emitRuntimeEvent() 直接调用页面 callback，确保 stateChange / progress / buffer / remoteCommand / interruption 等事件统一传回当前页面。
Android 事件订阅、派发、页面回调调用和取消订阅补充中文诊断 trace，便于真机通过 getDebugTrace() 判断事件是否已从插件传到页面。
Android off() 改为与 iOS 一致的按事件名清空订阅，并补充 @UTSJS.keepAlive，避免跨端函数引用比较语义不一致。
Android 修复页面点击“跳转 30s”返回 9012006 跳转位置非法：seek 入口增加动态 position 兜底读取，public seek 超过真实时长时与通知栏 seek、iOS seek 一致跳到末尾。
iOS / Android / 根入口均已移除事件 callback 闭包引用比较，统一采用事件名清理订阅表，减少云打包和跨端桥接差异风险。
版本号升级到 1.1.23，用于发布 Android / iOS 事件回调行为统一修复。

1.1.22（2026-05-18）

iOS 修复 BgAudio.on(name, callback) 已注册但页面收不到 stateChange / progress / buffer / remoteCommand 等事件回调的问题：平台事件表改为保存 BackgroundAudioEventCallback 强类型回调，事件派发时直接调用页面 callback，不再把页面函数当成非 UTSCallback 跳过。
iOS 修复云打包 Swift 编译失败：移除 off() 中对事件回调闭包的 == 比较，改为按事件名清空订阅，避免 type '(BackgroundAudioEvent) -> ()' cannot conform to 'Equatable'。
根入口同步移除闭包引用比较，避免 iOS 编译到统一入口时再次触发闭包不可比较问题。
演示页和 iOS 平台补充事件订阅、事件派发、页面回调调用链路中文日志，便于真机确认事件是否从插件传到当前页面。
演示页诊断标记更新为 2026-05-18-ios-event-callback-direct-1，iOS 原生 trace 标记更新为 lizhao-bg-audio/ios-event-callback-direct@2026-05-18-1，便于确认自定义基座包含本次修复。
版本号升级到 1.1.22，用于发布 iOS 事件回调传递与云打包闭包比较修复。

1.1.21（2026-05-18）

iOS 修复页面按钮调用 seek({ position: 30 }) 时只刷新 NowPlaying 到 30 秒、音频仅短暂停顿但实际不跳转播放的问题：public seek 现在使用 lastStatus/lastTickIsPlaying/AVPlayer.rate 判断 seek 前逻辑播放态，不再只依赖 AVPlayer.timeControlStatus 的瞬时值。
iOS public seek / 远程 seek 的恢复播放时机从“提交 seek 后立即恢复”改为“completion 校验落点后恢复”，避免 play() 抢在 seek 落地前触发而继续旧位置播放。
iOS seekInternal() 现在会记录 seek 前位置、提交序号和 completion 实际落点，便于判断播放器是否真的跳到目标秒数。
iOS seek completion 若发现 actual 与目标秒数偏差超过 1 秒，会输出 seekInternal.retry 并自动重试一次；最终 NowPlaying 使用 AVPlayer 实际落点刷新。
更新 scripts/check-bg-audio-ios-remote-seek-nowplaying.js，锁定 iOS seek 必须保留逻辑播放态、在 completion 后恢复播放并刷新 NowPlaying，避免后续退回“媒体卡显示跳转但播放器没跳”的假成功。
演示页诊断标记更新为 2026-05-18-ios-public-seek-actual-retry-1，iOS 原生 trace 标记更新为 lizhao-bg-audio/ios-public-seek-actual-retry@2026-05-18-1，便于确认真机基座包含本次修复。
版本号升级到 1.1.21，用于发布 iOS 页面点击跳转 30s、实际落点校验与重试修复。

1.1.20（2026-05-16）

Harmony 兼容 HBuilderX 4.87 ArkTS 编译：移除平台文件中对全局 BackgroundAudioManager 类型名的依赖，改为本地 HarmonyBackgroundAudioManager 结构类型，避免 4.87 报 找不到名称“BackgroundAudioManager” 和 arkts-no-any-unknown。
Harmony 补齐 ensureManagerByHarmony() 调用点的显式局部变量类型，并移除平台事件载荷入口里的 any，保持 uni.getBackgroundAudioManager() 真实播放链路和通知栏控制不变。
更新 Harmony ArkTS 严格模式与播放链路回归脚本，锁定 4.87 兼容类型写法。
版本号升级到 1.1.20，用于发布 Harmony HBuilderX 4.87 编译兼容修复。

1.1.19（2026-05-15）

iOS 修复锁屏/控制中心媒体卡封面不显示：cover 现在会解析为 MPMediaItemArtwork 写入 MPNowPlayingInfoCenter，支持 HTTPS、本地文件路径与 data URI，并缓存封面对象避免进度刷新重复下载。
iOS 修复锁屏/控制中心媒体卡进度条拖拽不生效、拖拽后仍从头播放、以及音乐已跳到目标位置但系统进度条回到 00:00 重新走的问题。
iOS 远程 seek 现在由 Swift helper 直接读取 MPChangePlaybackPositionCommandEvent.positionTime，避免 UTS 动态字段读取原生事件失败后退回当前播放秒数。
iOS 远程 seek 会直接执行原生 seek 并通过 handled: true 避免桥接层重复消费同一次命令；拖拽后会按拖拽前播放状态恢复播放并保持倍速。
iOS seekInternal() 改为使用 CMTimeMakeWithSeconds 构造目标时间，请求零容差精确 seek，并在执行前取消旧 seek，降低连续拖拽时旧任务干扰。
iOS 增加最新 seek 序号保护，忽略已取消或被后续拖拽覆盖的旧 completion；最新 completion 会用 AVPlayer 实际落点再次刷新 MPNowPlayingInfoCenter 的 elapsed/duration/rate，避免旧进度锚点覆盖媒体卡 UI。
iOS NowPlaying 写入改由 Swift 原生 helper 使用 MPMediaItemPropertyTitle、MPNowPlayingInfoPropertyElapsedPlaybackTime、MPNowPlayingInfoPropertyPlaybackRate、MPMediaItemPropertyPlaybackDuration 等 MediaPlayer 常量键完成，确保系统媒体卡识别进度信息。
iOS 修复云打包 Swift 编译失败：cancelPendingSeeks() 改为在 AVPlayerItem 上调用，避免 value of type 'AVPlayer' has no member 'cancelPendingSeeks'。
iOS 修复云打包 Swift 编译失败：NowPlaying Swift helper 接收 String? 并在原生层归一化，避免 UTS 生成的可选字符串传入非可选 String 参数时报 value of optional type 'String?' must be unwrapped。
Android 媒体通知默认按钮从五键改为三键 prev / playPause / next，适配 Android 16 更紧凑的系统媒体卡；仍可通过 notificationActions 自定义按钮顺序。
新增 scripts/check-bg-audio-ios-remote-seek-nowplaying.js 回归检查，锁定远程 seek 必须传入播放状态、completion 后刷新 NowPlaying、Swift helper 必须使用 MediaPlayer 原生常量键并兼容可选字符串入参。
演示页补充两首 demo 曲目的封面地址，并将诊断 build 标记更新为 2026-05-15-ios-media-card-seek-release-1，便于发布包确认。
版本号升级到 1.1.19，用于发布 iOS 媒体卡封面展示、进度拖拽、进度条同步、iOS 云打包编译修复，以及 Android 三键媒体卡默认按钮调整。

1.1.18（2026-05-15）

iOS 修复中文或已百分号编码中文音频 URL 无法播放的问题：URL 归一化改为先 decodeURI 再 encodeURI，避免 %E6... 被二次编码成 %25E6... 后请求 404。
iOS 修复状态栏媒体卡上一曲/下一曲无法切换的问题：加载歌单时改为单次 setTrack 携带完整队列，插件内部同步 queueTracksByJs/queueIndexByJs，避免页面连续 appendTrack 触发旧桥接闪退。
iOS 修复内部 skipToIndex -> setTrack 切歌路径：内部 SetTrackOptionsImpl 直通原生设置曲目，保留内部成功回调，确保媒体卡切歌后可继续自动播放。
演示页 iOS 加载歌单路径减少额外桥接调用，状态刷新不再调用空参数 getPlayerState({})，降低旧自定义基座桥接异常风险。
版本号升级到 1.1.18，用于发布 iOS 中文音频播放、状态栏媒体卡切歌和加载歌单稳定性修复。

1.1.17（2026-05-14）

iOS 修复云打包 Swift 编译失败：InitPlayerOptionsImpl 补齐 notificationActions 协议字段，避免 type 'InitPlayerOptionsImpl' does not conform to protocol 'InitPlayerOptions'。
iOS 端该字段仅用于对齐 interface.uts 协议完整性，不改变 iOS 播放、远程控制和中断恢复逻辑。
版本号升级到 1.1.17，用于发布已通过 iOS 云打包验证的协议字段补齐修复。

1.1.16（2026-05-14）

Android 修复 initPlayer({ notificationActions: ['prev','playPause','next'] }) 后状态栏仍显示五键的问题：初始化链路补充通知按钮配置诊断，通知构建时按实际 notificationActions 重建 action 列表，便于确认三键媒体卡是否生效。
演示页新增“初始化三键媒体卡”测试按钮，初始化前会先停止旧会话和旧通知，避免历史五键前台服务通知残留影响三键按钮验证。
Android 调试轨迹补充 notification actions 与 build notification actions count，客户现场可通过页面日志或 USB logcat 直接判断配置是否进入插件层、通知是否按三键构建。
版本号升级到 1.1.16，用于发布 Android 通知按钮三键媒体卡配置生效与诊断增强修复。

1.1.15（2026-05-14）

Android 修复客户 Android 16 机型“播放正常但状态栏没有媒体控制”的问题：媒体通知首次发布改为启动 BackgroundAudioForegroundService，由服务调用 startForeground 发布 MediaStyle + MediaSession 通知，后续刷新再走 NotificationManager.notify。
Android 补齐 FOREGROUND_SERVICE_MEDIA_PLAYBACK 权限声明，适配 Android 14+ 对 foregroundServiceType="mediaPlayback" 的清单要求。
Android 补齐 getDebugTrace/getCrashReports 诊断 API 平台导出，修复页面启动时 IndexKt-getDebugTraceByJs method not found。
Android 增强 OPPO Android 14 远程音频加载失败诊断：MediaPlayer.onError 现在会返回 reason/url/trackId/title/what/extra，并写入调试轨迹，便于区分网络/DNS 不可达与解码失败。
Android 修复 vivo Android 16 旧 targetSdkVersion 基座初始化失败：POST_NOTIFICATIONS 仅在 targetSdk 33+ 时主动请求，权限 API 异常只记录诊断，不再中断 initPlayer。
Android 修复 vivo Android 16 点击“加载歌单”后闪退：补充 Manifest 历史服务名 uts.lizhaobackgroundaudio.BackgroundAudioForegroundService 的 Kotlin 兼容入口，并保留 UTS 生成服务名兜底，避免系统创建媒体播放前台服务时 ClassNotFoundException。
Android 修复重新打自定义基座后点击“初始化”失败：通知栏控制按钮改为通过前台媒体服务分发，不再动态注册自定义广播接收器，规避 Android 16 要求 RECEIVER_NOT_EXPORTED/RECEIVER_EXPORTED 的安全异常。
Android 修复 vivo Android 16 前台服务和 MediaSession 已激活但状态栏仍不显示媒体卡：媒体通知 when 改用 System.currentTimeMillis()，避免 SystemClock.elapsedRealtime() 被系统判定为超旧通知并丢弃。
新增 check-bg-audio-android-foreground-media-service.js、check-bg-audio-android-foreground-service-component.js 回归脚本，锁定前台服务、媒体通知、组件类名兼容与停止清理链路。
新增 check-bg-audio-android16-notification-actions-service.js 回归脚本，锁定通知按钮不再走动态广播、媒体通知时间使用墙钟时间，避免 Android 16 初始化与状态栏回归。
版本号升级到 1.1.15，用于发布 Android 前台服务媒体通知、Android 16 初始化与状态栏媒体卡、诊断 API、远程音频错误诊断和旧 targetSdk 初始化兼容修复。

1.1.14（2026-05-14）

Harmony 修复系统状态栏播放中点击下一曲后“曲目信息已切换、进度条在走但无声音”的问题：播放中换源前先内部暂停释放旧音频管线，再延迟装载新曲并播放。
Harmony 修复上述场景下状态栏暂停按钮不生效的问题：内部切歌暂停事件会被短时保护吞掉，不污染页面状态；用户后续真正点击暂停时可同步到插件和页面状态。
Harmony 保留 onCanplay 后补发播放命令，降低 BackgroundAudioManager 过早调用 play() 被系统忽略导致停在 ready 的风险。
Harmony 状态栏上一首/下一首命令继续由平台层消费，并通过 handled: true 避免根入口重复切歌。
演示页调试日志继续降噪：进度事件按约 3 秒采样，启动时历史 trace 只回放最近 30 行，便于定位状态栏控制链路。
新增/更新 Harmony 状态栏切歌回归检查，覆盖远程下一曲、平台队列同步、播放中换源前暂停保护和 ready 后续播逻辑。
版本号升级到 1.1.14，用于发布 Harmony 状态栏切歌无声与暂停失效修复。

1.1.13（2026-05-13）

Harmony 修复纯血鸿蒙运行时报错：平台入口补齐 initPlayer/setTrack/getCapabilities/on/off 等公开 API，避免 lizhaoBgAudio_utsProxy.xxx is not a function。
Harmony 端保持明确降级策略：能力矩阵返回 supported=false，播放能力通过 fail/complete 返回 9012008，不伪造后台播放成功。
Harmony 增加轻量队列缓存、事件订阅、状态查询和诊断轨迹，保证演示页初始化、加载歌单、能力探测等流程可预测返回。
Harmony 修复 ArkTS 严格模式编译错误：事件桥空 payload 不再使用 {} as any，改为显式 HarmonyEmptyPayload 类实例，规避 arkts-no-untyped-obj-literals。
Harmony 修复平台入口缺少 SetPlaylistOptions 导入导致的 找不到名称“SetPlaylistOptions”。
Harmony 恢复真实播放链路：接入 HBuilderX 4.87 官方 uni.getBackgroundAudioManager()，支持 setTrack/play/pause/resume/stop/seek/skipToNext/skipToPrev/skipToIndex。
Harmony 能力矩阵改为运行时探测，背景音频管理器可用时返回 supported=true、sessionLevel=manager、backgroundAudio=true、mediaSession=true。
Harmony 通知栏上一首/下一首事件接入插件队列切歌逻辑，并继续保留 on/off/getDebugTrace/getCrashReports 诊断能力。
Android 修复演示页启动读取插件诊断轨迹时报错：平台入口补齐 getDebugTrace/clearDebugTrace/getCrashReports/clearCrashReports 导出，避免生成桥接缺少 getDebugTraceByJs 导致 method not found。
Android 增加轻量运行时轨迹与最近错误报告缓存，便于客户现场通过页面日志确认初始化、播放、暂停、队列控制等关键调用链路。
Android 清理 UTS 静态分析 warning：移除 BackgroundAudioTrack.title、SetTrackOptions.track/url、SeekOptions.position、SetPlaybackRateOptions.playbackRate、SetVolumeOptions.volume、SetLoopModeOptions.loopMode 等必填字段上的恒定空值判断。
Android 保留实际业务校验：空字符串、非法进度、非法倍速、非法音量仍会通过 fail/complete 返回错误。
Android 修复 13+ 通知权限请求：初始化、设置曲目、播放和通知刷新时主动申请 POST_NOTIFICATIONS，兼容小米等 Android 13/14/16 机型通知栏不展示媒体通知的问题。
Android 修复通知栏播放/暂停图标不同步问题：媒体通知操作按钮跟随插件实际播放状态刷新。
Android 修复通知栏上一首/下一首不生效：统一页面按钮与通知栏切歌链路，补齐队列索引恢复、真实 handled 诊断和平台队列同步。
Android 修复 setTrack + appendTrack 加载歌单时通知栏队列只剩首曲的问题：平台层优先按 JS 动态命令对象还原曲目，并在演示页 setTrack 同步返回后立即追加尾曲，避免命令 success 回调丢失导致下一曲不存在。
新增 check-bg-audio-harmony-playback-engine.js、check-bg-audio-harmony-arkts-strict.js、check-bg-audio-android-static-warnings.js、check-bg-audio-android-notification-permission.js、check-bg-audio-android-notification-state.js、check-bg-audio-android-notification-skip-queue.js 等回归脚本，覆盖 Harmony 播放链路、ArkTS 严格模式、Android 通知权限、通知状态与队列切歌。
版本号升级到 1.1.13，用于客户侧重新发布并刷新云端构建缓存。

1.1.12（2026-05-13）

Android 修复系统通知栏媒体卡播放/暂停图标不同步问题：通知图标只跟随插件自身 MediaPlayer / MediaSession 状态，不再使用可能滞后的 AudioManager.isMusicActive() 判定。
Android 通知栏播放/暂停按钮触发后会先登记本次传输命令，避免部分 ROM 随后补发 MediaSession.onPlay/onPause 时把暂停/播放状态反向切回去。
版本号升级到 1.1.12，用于客户侧重新发布并刷新云端构建缓存。

1.1.8（2026-05-13）

Android 云打包修复 removeTrackByJs 可空桥接参数导致的 Kotlin 编译错误：规避 Argument type mismatch: actual type is 'Any?', but 'Any' was expected.。
removeTrack 根入口与 Android 平台入口统一改为动态参数接入，再内部归一化 RemoveTrackOptions / trackId / success / fail / complete，保持页面端调用方式不变。
同步 package.json 与 uni_modules.json 版本号到 1.1.8，用于发布并刷新云端插件构建缓存。

1.1.6（2026-05-12）

iOS 修复 MPNowPlayingInfoCenter 元数据未同步问题，补齐标题/歌手/专辑/时长/进度/速率更新链路。
iOS 修复锁屏 seek 目标时间解析，优先读取远程命令事件中的 positionTime（并保留 seekTime 兜底）。
iOS 修复远程命令 target 清理缺失，初始化重入时改为显式 removeTarget，降低重复回调风险。
根入口 initPlayer 增强 autoRecover/autoRegisterRemoteCommand 参数透传与注释，统一跨端入口行为说明。
readme 补充调试 API 文档：getDebugTrace/clearDebugTrace/getCrashReports/clearCrashReports，并新增初始化参数生效边界说明。

1.1.5（2026-04-29）

修复 iOS 端以下控制功能无效问题
优化背景音频演示页控制链路稳定性（初始化后执行与状态刷新体验）。
同步更新插件功能描述文案，版本升级到 1.1.5。

1.0.9（2026-04-23）

Android 修复媒体卡控制“点了无效”根因：移除对未合并 Service 的命令派发依赖，通知动作改为 PendingIntent.getBroadcast + 动态 BroadcastReceiver 直达播放器控制链路。
Android 修复系统媒体键路由冲突：取消 setMediaButtonReceiver 的错误兜底路径，统一走 MediaSession.Callback 处理系统媒体卡播放/暂停/上下曲命令。
Android 修复系统媒体卡按钮偶发失效：通知栏与 MediaSession 远程命令改为原生优先执行，避免后台 JS 挂起导致的播放/暂停/切歌不响应。
Android 补齐媒体键事件回调：新增 MediaSession.Callback.onMediaButtonEvent 与 FLAG_HANDLES_MEDIA_BUTTONS，兼容 ROM 仅下发媒体按键事件的控制面板。
Android 修复 KEYCODE_MEDIA_PLAY_PAUSE 语义：系统媒体卡中心键改为播放/暂停切换，不再固定触发播放。
Android 修复媒体卡状态判定：播放/暂停按钮改为 lastSessionStatus + player.isPlaying 双重判定，规避部分 ROM isPlaying() 读值延迟导致的“暂停键无效”。
Android 增强 ROM 兼容：MediaSession.onPlay 改为切换语义，并引入 AudioManager.isMusicActive() 作为播放态兜底判定。
Android 新增媒体键重复回调去重：当同一次系统点击同时触发 onMediaButtonEvent + onPlay/onPause 时，自动跳过重复回调，避免“按了无效（实际被双重切换）”。
Android 新增播放命令防抖：针对部分 ROM 连续触发 onPause -> onPlay（或反向）的连发问题，500ms 内自动拦截冲突回调。
Android 新增通知封面缓存升级：网络封面支持内存 + 磁盘双层缓存，首次下载后重启 App 可直接命中本地封面。
Android 修复根入口 remoteCommand 重复执行：当原生层已标记 handled=true 时，JS 层不再二次调用 play/pause/next/prev，解决系统媒体卡点击后被反向覆盖的问题。
Android 强化媒体卡播放态判定：play/pause 切换改为仅基于当前播放器会话状态（不再依赖 AudioManager.isMusicActive），并将 toggle -> play/pause 去重窗口扩展到 1800ms，兼容部分 ROM 延迟回调。
Android 增加媒体键兜底通道：为 MediaSession 显式设置 MediaButtonReceiver(PendingIntent -> BackgroundAudioForegroundService)，并在 Service 内解析 ACTION_MEDIA_BUTTON，兼容部分 ROM 不回调 MediaSession.Callback.onPlay/onPause 的场景。
Android 修复媒体服务路由兼容性：PendingIntent.getService 改为 action + package 路由，并在 Service 增加完整 intent-filter，规避部分机型/基座上的 Service 类路径解析不一致导致的 “service not found”。
Android 增加非标准系统命令兜底：MediaSession.Callback 新增 onCommand/onCustomAction 解析，将 play/pause/toggle/next/prev/stop 类命令统一映射回媒体键处理链，兼容 MIUI 等 ROM 的自定义控制路径。

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。