Thinker 按键录音降噪对比示例
==============================

功能说明
--------

本示例在 ``arcs_evb`` 的 ARCS AP Core 上运行完整音频降噪链路。按下开发板
``KEY1`` 后，设备录制 3 秒 48 kHz 单声道 PCM16 音频，逐个 480 点帧提取
42 维音频特征并调用 Thinker 量化模型生成 22 个频带增益，随后依次播放原始
录音和降噪结果，便于直接试听比较。

模型输入为 ``int8 [1, 42]``，输入量化采用
``floor(feature * 4 + 0.5)``；模型输出为 ``int8 [1, 22]``，按 ``16``
反量化后执行 Sigmoid。两项 scale 均来自当前模型资源，不能替换为其他模型的
固定值。

硬件连接
--------

本示例仅支持 ``arcs_evb``，需要连接以下板载资源：

- ``KEY1``：``GPIOB_06``，通过 ``ADC_CH4`` 检测按键电压；
- 麦克风：使用 ``MIC0`` 差分输入；
- 扬声器：连接开发板扬声器接口；
- 烧录和日志：连接开发板烧录 Type-C 接口。

``GPIOB_06`` 的 ADC 复用使用 AON 功能索引 3。按键判定阈值为 600 mV，
软件连续采样 3 次进行消抖。

处理流程
--------

1. 初始化 LISA Audio、LISA ADC、Luna、Thinker 和模型运行内存。
2. 等待 ``KEY1`` 按下，录制 3 秒 48 kHz 单声道 PCM16 音频。
3. 将录音按 480 点（10 ms）分帧，执行特征提取、Thinker 推理和频谱增益处理。
4. 播放原始录音。
5. 间隔 500 ms 后播放降噪录音。
6. 等待按键释放并重新进入可触发状态。

资源布局
--------

应用和模型资源需要分别烧录：

.. list-table::
   :header-rows: 1

   * - 资源
     - Flash 偏移
     - 默认 XIP 地址
     - 大小
   * - ``lnn_thinker_audio_denoise.bin``
     - ``0x000000``
     - ``0x30000000``
     - 不超过 1 MiB
   * - ``denoise_arcs.bin``
     - ``0x100000``
     - ``0x30100000``
     - ``0x14750`` （83,792 字节）

编译
----

.. include:: /sample_build.rst

烧录
----

构建时 CMake 会把模型复制到构建目录。使用以下命令同时烧录应用和模型：

.. code-block:: bash

   ./tools/burn/cskburn -C arcs -s /dev/ttyACM0 -b 3000000 \
     0x0 build/lnn_thinker_audio_denoise.bin \
     0x100000 build/denoise_arcs.bin

烧录完成后设备自动复位，日志串口波特率为 921600。

操作方法
--------

1. 确认麦克风和扬声器已连接，扬声器音量处于安全范围。
2. 启动设备并等待 ``ready; press KEY1`` 日志。
3. 按下 ``KEY1`` 后对麦克风说话，录音持续 3 秒。
4. 等待降噪进度完成，先试听原始录音，再试听降噪录音。
5. 释放并再次按下 ``KEY1`` 可重复完整链路。

预期输出
--------

.. code-block:: text

   [I][denoise_model] model ready: input=int8[1,42] output=int8[1,22]
   [I][audio_denoise] ready; press KEY1 (PB06) to record 3 seconds
   [I][audio_denoise] KEY1 pressed: ... mV
   [I][audio_denoise] step 1/4: recording 3 seconds at 48000 Hz
   [I][audio_denoise] recording complete: samples=...
   [I][audio_denoise] step 2/4: denoising ... frames
   [I][audio_denoise] denoise progress: .../... frames
   [I][audio_denoise] step 3/4: original audio
   [I][audio_denoise] original audio playback complete
   [I][audio_denoise] step 4/4: denoised audio
   [I][audio_denoise] denoised audio playback complete
   [I][audio_denoise] comparison complete; press KEY1 to run again

核心 API
--------

.. list-table::
   :header-rows: 1

   * - API
     - 说明
   * - ``lisa_adc_read()``
     - 读取 ``KEY1`` 的 ADC 电压并判断按下状态。
   * - ``lisa_audio_record_start()`` / ``lisa_audio_record_stop()``
     - 启动和停止固定时长录音。
   * - ``rnnoise_process_frame()``
     - 对一个 480 点 PCM 帧执行特征提取、频带增益和波形重建。
   * - ``tForward()``
     - 对 42 维量化特征执行一次 Thinker 模型推理。
   * - ``lisa_audio_play_write()`` / ``lisa_audio_play_flush()``
     - 写入并等待原始或降噪 PCM 播放完成。

配置说明
--------

.. code-block:: kconfig

   CONFIG_THINKER_AUDIO_DENOISE_MODEL_ADDR=0x30100000
   CONFIG_THINKER_AUDIO_DENOISE_MODEL_SIZE=0x14750
   CONFIG_THINKER_AUDIO_DENOISE_PSRAM_POOL_SIZE=0x18000
   CONFIG_THINKER_AUDIO_DENOISE_SHARE_POOL_SIZE=0x1000
   CONFIG_PSRAM_HEAP_SIZE=0x140000

两段 3 秒 PCM 缓冲区共占 576,000 字节 PSRAM。DSP 工作区和音频驱动缓冲区
同样使用 PSRAM；降噪任务的大栈也放在 PSRAM，避免占满片上 SRAM。

效果验收
--------

本示例的现场录音没有与之严格时间对齐的无噪 ``clean`` 真值，因此主要用于完整
链路和主观试听验收，不能仅凭两次播放计算 PESQ、STOI 或 SI-SDR。

验收时至少确认：

1. 每次按键只触发一次完整链路，录音、推理和两次播放均无异常日志。
2. 原始与降噪播放长度一致，无明显断裂、溢出、削波或异常静音。
3. 在稳定噪声场景中，第二段播放的背景噪声应减弱，同时语音保持可懂。
4. 连续触发多轮后无内存分配失败、设备忙或音频 DMA 错误。

注意事项
--------

1. **按键专用**：本示例按 ``arcs_evb`` 的 ``KEY1`` 电阻网络设置阈值，其他板型需要重新核对原理图和 ``soc/arcs/pinmux.yaml``。
2. **固定采样率**：DSP 帧长 480 对应 48 kHz 下的 10 ms，不能只修改录音采样率而不修改整套特征流程。
3. **模型配套**：替换 ``denoise_arcs.bin`` 时必须同步更新模型尺寸、输入/输出形状和量化 scale。
4. **非实时链路**：示例先完成整段录音和离线降噪，再执行对比播放，不是边录边播的实时降噪实现。
5. **增益安全**：首次试听应从较低扬声器音量开始，避免近距离麦克风与扬声器产生啸叫。