TTMusic/openspec/changes/archive/2026-02-07-add-audio-spectrum-animation/design.md

Context

当前 ijkplayer 的音频管线流程为：FFmpeg 解码 → AudioRendererOnWriteData 回调 → PCM 填充 → 均衡器处理 → OH_AudioRenderer 输出。PCM 数据在原生层产生和消费，ArkTS 层完全无法访问。播放界面 (LocalMusic.ets) 使用 Swiper 容器承载封面和歌词两个页面，已有 Canvas 使用经验（ScanFilePage.ets 中用于 Lottie 动画渲染）。

关键约束：

• PCM 数据仅存在于 C 层 AudioRendererOnWriteData 回调中，生命周期极短
• 音频回调运行在独立线程，与 JS 线程不同
• ArkTS 禁止使用 unknown/any 类型，禁止解构赋值
• 需控制跨线程数据拷贝和 FFT 计算的性能开销

Goals / Non-Goals

Goals:

• 在原生层零拷贝方式捕获 PCM 数据到环形缓冲区
• 通过 NAPI 接口将 PCM 数据高效传递给 ArkTS 层
• 在 ArkTS 侧实现轻量 FFT，生成频谱数据
• 提供 4 种可切换的 Canvas 频谱动画特效
• 所有动效参数（颜色、亮度、大小、速度）完全由频谱数据实时驱动
• 集成到播放界面 Swiper 中，用户可自由滑动切换

Non-Goals:

• 不实现录音或音频采集功能（仅读取播放中的 PCM）
• 不在 C 层做 FFT（避免增加原生层复杂度，ArkTS 侧 FFT 性能已足够）
• 不支持自定义特效插件系统（初版提供内置 4 种）
• 不修改音频播放逻辑或影响播放质量

Decisions

决策 1：PCM 数据捕获方案 — 原生环形缓冲区

选择：在 SDL_Aout_Opaque 结构体中新增环形缓冲区，在 AudioRendererOnWriteData 均衡器处理之后直接 memcpy 到缓冲区。

备选方案：

• A) 使用 OpenHarmony AudioCapturer API 从系统层采集 — 需要额外权限，延迟高，且无法获取 app 内部播放的精确 PCM
• B) 在 FFmpeg 解码层拦截 — 太早，未经均衡器处理，且与解码线程耦合
• C) 通过 MessageCallback 推送数据 — libuv 回调开销大，不适合高频音频数据

理由：直接在 AudioRendererOnWriteData 末尾拷贝，代码侵入最小（仅加几行），数据是均衡器处理后的最终 PCM，与用户听到的一致。

环形缓冲区设计：

// 新增到 SDL_Aout_Opaque
#define SPECTRUM_BUFFER_SIZE 4096  // 2048 samples * 2 channels * sizeof(int16_t)
typedef struct SpectrumBuffer {
    int16_t data[SPECTRUM_BUFFER_SIZE / sizeof(int16_t)];
    volatile int write_pos;
    volatile bool has_data;
    int sample_rate;
    int channels;
} SpectrumBuffer;

决策 2：NAPI 桥接方案 — 同步拉取模式

选择：新增 _getSpectrumData(id) NAPI 函数，ArkTS 侧按帧主动调用获取当前缓冲区快照，返回 number[] 数组。

备选方案：

• A) 推送模式（原生层定时通过 libuv 回调推送） — 每秒 30-60 次 uv_queue_work 调用会产生大量 GC 压力
• B) SharedArrayBuffer 共享内存 — OpenHarmony NAPI 对 SharedArrayBuffer 支持有限且复杂

理由：拉取模式让 ArkTS 侧控制采样频率，与 Canvas 绑帧渲染天然同步，实现简单。每次调用仅拷贝一个窗口大小的数据（2048 个样本），开销可控。

决策 3：FFT 实现方案 — ArkTS 纯计算

选择：在 ArkTS 侧实现 Cooley-Tukey 基 2 FFT 算法（1024 点），输出 512 个频率 bin 的幅值。

备选方案：

• A) 在 C 层用 FFmpeg 的 libavutil/tx.h 做 FFT — 减少一次数据传递，但增加原生层复杂度，FFT 结果传到 JS 层也需要拷贝
• B) 引入第三方 FFT 库 — 增加外部依赖，与项目"无新依赖"原则不符

理由：1024 点 FFT 计算量极小（约 5000 次乘加），现代处理器在 ArkTS 中也能在 1ms 内完成。放在 ArkTS 侧便于调试和迭代，避免频繁修改原生代码重新编译。

处理流程：

PCM int16[] → 取单声道 → 加窗(Hann) → FFT → 取幅值 → 对数映射 → 分频段 → 平滑

频段划分（对数分布，映射到 32-64 个可视化柱）：

• 低频 (32-250Hz)：约 8 柱，覆盖鼓点/贝斯
• 中频 (250-4000Hz)：约 16 柱，覆盖人声/乐器
• 高频 (4000-16000Hz)：约 8 柱，覆盖镲片/泛音

决策 4：频谱可视化架构 — 策略模式 + Canvas 统一渲染

选择：定义 SpectrumRenderer 接口，每种特效实现该接口的 render(ctx, spectrumData, canvasWidth, canvasHeight) 方法。主组件持有 Canvas 和定时器，按当前选择的渲染策略绘制。

理由：策略模式使新增特效只需实现一个类，不影响其他特效和主逻辑。Canvas 是 ArkUI 内置能力，无需额外依赖。

四种特效实现要点：

特效	渲染方式	数据驱动参数
柱状频谱	fillRect 绘制等间距矩形条	高度=幅值，颜色=频段映射渐变
波形频谱	bezierCurveTo 绘制平滑曲线	Y轴=幅值，线宽=能量强度
圆形频谱	极坐标变换后 lineTo 绘制放射线	半径=幅值，颜色=角度映射
粒子频谱	粒子池 + arc 绘制圆点	速度/大小/透明度=幅值，颜色=频段

决策 5：UI 集成方案 — Swiper 第二页

选择：在 LocalMusic.ets 的 Swiper 中，在封面和歌词之间插入频谱页面，顺序变为：封面 → 频谱 → 歌词。频谱页面上方显示小型特效切换按钮。

备选方案：

• A) 作为封面页面的背景叠加显示 — 与旋转唱片视觉冲突，遮挡封面信息
• B) 放在底部播放栏 — 空间太小，无法展现频谱细节

理由：独立 Swiper 页面提供最大渲染空间，不干扰现有封面和歌词体验。用户可以根据需要滑动查看。

决策 6：性能控制策略

• 渲染帧率：Canvas 绑帧 30fps（使用 setInterval 33ms），不追求 60fps 以省电
• FFT 窗口：1024 点，每次渲染前计算一次，复用上一帧数据避免重复计算
• 平滑算法：指数移动平均 current = current * 0.7 + previous * 0.3，避免跳变
• 生命周期：仅在频谱页面可见且播放中时才启动定时器和 NAPI 调用，页面切走或暂停时立即停止
• 内存：粒子池预分配固定数量（200 个），复用而不是创建/销毁

Risks / Trade-offs

• [PCM 数据延迟] → 环形缓冲区引入约 1 帧（~23ms@44100Hz）延迟，对视觉频谱影响可忽略
• [线程安全] → 环形缓冲区使用 volatile 标记 + 单写单读模式，避免加锁开销。写端为音频线程，读端为 NAPI 调用线程，天然无竞争
• [FFT 精度] → 1024 点 FFT 频率分辨率约 43Hz（@44100Hz），低频区分辨率较粗，通过对数频率映射缓解
• [不同采样率] → 缓冲区记录 sample_rate，FFT 分析器动态适配。主流音频均为 44100/48000Hz
• [性能下降] → 粒子特效较重，在低端设备上可能卡顿。兜底方案：检测帧率下降时自动降级到柱状频谱
• [原生层修改风险] → 仅在 AudioRendererOnWriteData 末尾加 memcpy，不影响播放逻辑。环形缓冲区独立于播放状态，写满自动覆盖旧数据

Open Questions

• 是否需要支持频谱特效偏好的持久化存储（记住用户上次选择的特效）？
• 粒子特效的粒子数量是否需要根据设备性能动态调整？