> ## Documentation Index
> Fetch the complete documentation index at: https://dragonwingdocs.qualcomm.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 音频

IQ-8275 音频子系统由低功耗 AI(LPAI)驱动,通过 PipeWire 提供先进的语音 UI 和音频体验。

## 主要特性

* **低功耗 AI(LPAI)** 子系统,实现高效音频处理
* **PipeWire** 多媒体服务器,实现低延迟音频路由
* **硬件加速**的编码/解码
* **Fluence ECNS** — 先进的回声消除和噪声抑制
* **多种音频接口** — I2S、TDM、SoundWire

## 硬件配置

<img src="https://mintcdn.com/qualcomm-prod/P0rmO3AZfXx7cgqQ/Ubuntu/images/peripheral-interfaces/audio-components.png?fit=max&auto=format&n=P0rmO3AZfXx7cgqQ&q=85&s=18d211565b4e113db93f7a043f262186" width="1208" height="526" data-path="Ubuntu/images/peripheral-interfaces/audio-components.png" />

* **扬声器:** 板载 MAX98357 I2S 功放;连接随附的两个迷你扬声器即可听到输出。HS0\_MI2S 由左右声道共用以实现立体声。
* **麦克风:** HS2\_MI2S 上的单个板载麦克风(MMICT5848),默认配置为左声道
  **扬声器连接:**

<img src="https://mintcdn.com/qualcomm-prod/tRWO8v_Df_ujnDuD/Ubuntu/images/peripheral-interfaces/IQ8275_Audio_speakers_connection.png?fit=max&auto=format&n=tRWO8v_Df_ujnDuD&q=85&s=e1d739f39fac73ad325f165862beb34a" width="971" height="437" data-path="Ubuntu/images/peripheral-interfaces/IQ8275_Audio_speakers_connection.png" />

## 架构

<img src="https://mintcdn.com/qualcomm-prod/tRWO8v_Df_ujnDuD/Ubuntu/images/peripheral-interfaces/Audio_architecture.png?fit=max&auto=format&n=tRWO8v_Df_ujnDuD&q=85&s=ddb96acde9da3ddd6d888b47f259e2cb" width="1376" height="899" data-path="Ubuntu/images/peripheral-interfaces/Audio_architecture.png" />

| 组件              | 描述                                                       |
| --------------- | -------------------------------------------------------- |
| **PipeWire**    | 多媒体服务器;替代 PulseAudio;低延迟、灵活的媒体处理                         |
| **WirePlumber** | 会话/策略管理器;处理默认 sink/source、自动连接规则                         |
| **PAL**         | 平台抽象层(Platform Abstraction Layer);提供音频专用 API 和 DSP 图操作   |
| **AGM**         | 音频图管理器(Audio Graph Manager);基于 ALSA 的混音器控制以及 PCM/压缩插件    |
| **ARGS/GSL**    | AudioReach 图服务;负责音频图的初始化和创建                              |
| **SPF**         | 信号处理框架(Signal Processing Framework);运行在 LPAI DSP 上的模块化框架 |

## 配置文件

| 组件             | 位置                                  |
| -------------- | ----------------------------------- |
| ALSA 声卡注册      | `/proc/asound/cards`                |
| UCM2 配置文件      | `/usr/share/alsa/ucm2/<card-name>/` |
| PipeWire 配置    | `/etc/pipewire/`                    |
| WirePlumber 规则 | `/usr/share/wireplumber/`           |

### 验证音频栈

```bash theme={null}
cat /proc/asound/cards                                   # List registered ALSA sound cards
aplay -l                                                 # List playback (output) devices
arecord -l                                               # List capture (input) devices
systemctl --user status pipewire wireplumber --no-pager  # Confirm the audio services are active
wpctl status                                             # Show the default sink/source and routing
pw-top                                                   # Live view of the audio graph (Ctrl+C to exit)
```

**预期结果:** `/proc/asound/cards` 至少列出一张声卡,且 `aplay -l` 和 `arecord -l` 各显示一个设备。例如:

```text theme={null}
 0 [<card-name>     ]: <driver> - <card description>
                       <card long name>

**** List of PLAYBACK Hardware Devices ****
card 0: <card-name> [<card description>], device 0: <pcm-name> []
  Subdevices: 1/1
```

`wpctl status` 应列出默认的 **Sink** 和 **Source**(均以 `*` 标记)。如果 `/proc/asound/cards` 为空,或 `wpctl status` 未显示默认 sink 或 source,则说明音频栈未正常启动:请参见下方的故障排除部分。

## 音频播放与录制

### PipeWire 播放

<Steps>
  <Step title="将音频文件推送到设备">
    将一段简短的测试音频复制到设备上,以便有内容可播放。`test.wav` 可以是任意小型 PCM WAV 文件(48 kHz、16 位立体声效果较好):可以使用主机上现有的文件,或使用 `ffmpeg -f lavfi -i "sine=frequency=440:duration=5" -ar 48000 -ac 2 test.wav` 创建一个。

    ```bash theme={null}
    scp test.wav ubuntu@<ip-addr>:/home/ubuntu/
    ```
  </Step>

  <Step title="设置默认 sink 和音量">
    ```bash theme={null}
    wpctl status
    wpctl set-default <sink-node>
    wpctl set-volume @DEFAULT_AUDIO_SINK@ 1.0
    ```
  </Step>

  <Step title="播放音频">
    ```bash theme={null}
    pw-play /home/ubuntu/test.wav -v
    ```

    您应该能通过连接的扬声器听到音频播放,`pw-play` 在运行时会打印进度和峰值电平读数。按 `Ctrl+C` 停止。
  </Step>
</Steps>

### PipeWire 录制

<Steps>
  <Step title="设置默认 source 和音量">
    ```bash theme={null}
    wpctl status
    wpctl set-default <mic-node>
    wpctl set-volume @DEFAULT_AUDIO_SOURCE@ 1.0
    ```
  </Step>

  <Step title="开始录制">
    ```bash theme={null}
    pw-record /home/ubuntu/record.wav -v
    ```

    按 `Ctrl+C` 停止。
  </Step>
</Steps>

<Note>
  `1.0` 表示 100% 音量。
</Note>

### GStreamer 音频

<Tabs>
  <Tab title="采集">
    ```bash theme={null}
    gst-launch-1.0 -v pulsesrc volume=10 ! audioconvert ! wavenc ! \
      filesink location=/home/ubuntu/audio.wav
    ```
  </Tab>

  <Tab title="播放">
    ```bash theme={null}
    gst-launch-1.0 -e filesrc location=/home/ubuntu/audio.wav ! \
      wavparse ! audioconvert ! pulsesink volume=10

    gst-launch-1.0 -e filesrc location=/home/ubuntu/audio.mp3 ! \
      mpegaudioparse ! mpg123audiodec ! pulsesink volume=10
    ```
  </Tab>
</Tabs>

## 故障排除

<AccordionGroup>
  <Accordion title="播放时没有音频输出">
    ```bash theme={null}
    wpctl status
    wpctl set-volume @DEFAULT_AUDIO_SINK@ 1.0
    systemctl --user restart wireplumber
    aplay -l
    ```
  </Accordion>

  <Accordion title="麦克风无法采集音频">
    ```bash theme={null}
    arecord -l
    arecord -D hw:0,0 -f S16_LE -r 48000 test.wav
    pw-cli ls Node | grep -i source
    systemctl --user status pipewire pipewire-pulse wireplumber
    ```
  </Accordion>

  <Accordion title="音频播放卡顿或有杂音">
    ```bash theme={null}
    pw-metadata -n settings
    pw-top
    ```

    **修复 — 增大 PipeWire 缓冲区:**

    ```bash theme={null}
    mkdir -p ~/.config/pipewire/pipewire.conf.d
    cat > ~/.config/pipewire/pipewire.conf.d/99-custom-buffer.conf << 'EOF'
    context.properties = {
        default.clock.quantum = 1024
        default.clock.min-quantum = 1024
    }
    EOF
    systemctl --user restart pipewire wireplumber
    ```
  </Accordion>

  <Accordion title="PipeWire 服务无法启动">
    ```bash theme={null}
    systemctl --user status pipewire pipewire-pulse wireplumber
    rm -rf ~/.config/pipewire ~/.config/wireplumber
    systemctl --user daemon-reload
    systemctl --user restart pipewire pipewire-pulse wireplumber
    ```
  </Accordion>
</AccordionGroup>

## 资源

* [PipeWire 文档](https://docs.pipewire.org/)
* [AudioReach GitHub](https://github.com/audioreach)
* [AudioReach 文档](https://audioreach.github.io/)