## 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(无数据时)