TTMusic/openspec/specs/audio-pcm-bridge/spec.md

ADDED Requirements

Requirement: PCM 环形缓冲区捕获

系统 SHALL 在原生音频输出回调 AudioRendererOnWriteData 中，于均衡器处理完成后，将 PCM 数据拷贝到一个固定大小的环形缓冲区中。缓冲区 SHALL 使用单写单读无锁模式，写端为音频线程，读端为 NAPI 调用线程。

Scenario: 正常播放时捕获 PCM 数据

• WHEN 音频正在播放，均衡器处理完成后
• THEN 系统将当前帧的 PCM 数据（int16 格式）写入环形缓冲区，并更新写入位置标记和 has_data 标志为 true

Scenario: 播放暂停时停止捕获

• WHEN 音频处于暂停状态（pause_on == true）
• THEN AudioRendererOnWriteData 直接返回，不向缓冲区写入任何数据

Scenario: 缓冲区写满时覆盖旧数据

• WHEN 环形缓冲区写满
• THEN 系统 SHALL 从头覆盖旧数据，保证缓冲区始终包含最近的 PCM 数据

Requirement: 缓冲区记录音频元信息

环形缓冲区 SHALL 同时记录当前音频的采样率（sample_rate）和声道数（channels），供 ArkTS 侧读取时使用。

Scenario: 音频初始化时设置元信息

• WHEN 音频渲染器通过 AoutOpenAudio 初始化成功
• THEN 系统 SHALL 将 desired->freq（采样率）和 desired->channels（声道数）写入缓冲区的元信息字段

Requirement: NAPI 接口获取频谱数据

系统 SHALL 提供名为 _getSpectrumData 的 NAPI 函数，ArkTS 侧可通过此函数同步获取当前环形缓冲区中的 PCM 数据快照。

Scenario: 播放中调用获取数据

• WHEN ArkTS 侧在音频播放中调用 _getSpectrumData(id)
• THEN 系统 SHALL 返回一个包含 PCM 样本数据的 number[] 数组（1024 个样本，单声道），以及当前采样率

Scenario: 无可用数据时返回空

• WHEN ArkTS 侧调用 _getSpectrumData(id) 但缓冲区 has_data 为 false（未开始播放或已停止）
• THEN 系统 SHALL 返回空数组 []

Scenario: 立体声转单声道

• WHEN 音频为立体声（channels == 2）
• THEN NAPI 函数 SHALL 将左右声道取平均值合并为单声道后返回

Requirement: ArkTS 层接口声明

IjkMediaPlayer 类 SHALL 新增 getSpectrumData(): number[] 公开方法，封装对原生 _getSpectrumData NAPI 的调用。

Scenario: ArkTS 调用频谱数据接口

• WHEN 外部组件调用 IjkMediaPlayer.getInstance().getSpectrumData()
• THEN 系统 SHALL 返回当前 PCM 样本数组，格式为 number[]，长度为 1024 或 0（无数据时）