> ## 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-9075 音频子系统由低功耗 AI（LPAI）提供支持，通过 PipeWire 提供先进的语音 UI 和音频体验。

## 主要特性

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

## 硬件配置

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

* **扬声器：** 板载扬声器，配备 MAX98357 I2S 功放；HS0\_MI2S 左右声道共用以实现立体声
* **麦克风：** HS2\_MI2S 上的单个板载麦克风（MMICT5848），默认配置为左声道

**扬声器连接：**

<img src="https://mintcdn.com/qualcomm-prod/Bh7DlgudKfjY_3Wf/Linux/images/peripheral-interfaces/IQ9075_Audio_speakers_connection.png?fit=max&auto=format&n=Bh7DlgudKfjY_3Wf&q=85&s=08b0a52f7ef7efb065e5e375024974cf" width="1078" height="412" data-path="Linux/images/peripheral-interfaces/IQ9075_Audio_speakers_connection.png" />

## 架构

<img src="https://mintcdn.com/qualcomm-prod/T1k4QQ7G3l_dE-rX/Linux/images/peripheral-interfaces/Audio_architecture.png?fit=max&auto=format&n=T1k4QQ7G3l_dE-rX&q=85&s=d26635d92ec937149c2a715bf6637894" width="1376" height="899" data-path="Linux/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 Graph Service；负责音频图的初始化和创建                  |
| **SPF**         | 信号处理框架（Signal Processing Framework）；LPAI DSP 上的模块化框架   |

## 配置文件

| 组件                | 位置                        |
| ----------------- | ------------------------- |
| ALSA 声卡注册         | `/proc/asound/cards`      |
| WirePlumber 规则与配置 | `/usr/share/wireplumber/` |

### 验证音频栈

```bash theme={null}
# Confirm ALSA card and devices
cat /proc/asound/cards
aplay -l
arecord -l

# Confirm PipeWire + WirePlumber services
systemctl  status pipewire wireplumber --no-pager

# Validate default sink/source
wpctl status

# Monitor graph
pw-top
pw-cli ls Node
```

## 音频播放与录制

### PipeWire 播放

<Steps>
  <Step title="将音频文件推送到设备">
    ```bash theme={null}
    scp test.wav root@<ip-addr>:/opt/
    ```
  </Step>

  <Step title="设置默认 sink 和音量">
    ```bash theme={null}
    wpctl status   # Find sink node marked with *
    wpctl set-default <sink-node>   # If not already set
    wpctl set-volume @DEFAULT_AUDIO_SINK@ 1.0
    ```
  </Step>

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

    命令行输出应类似如下：

    <img src="https://mintcdn.com/qualcomm-prod/Bh7DlgudKfjY_3Wf/Linux/images/peripheral-interfaces/pipewire_playback.png?fit=max&auto=format&n=Bh7DlgudKfjY_3Wf&q=85&s=ba11900ed8e51cd65d1490fb85efa6aa" width="566" height="332" data-path="Linux/images/peripheral-interfaces/pipewire_playback.png" />

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

### PipeWire 录制

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

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

    命令行输出应类似如下：

    <img src="https://mintcdn.com/qualcomm-prod/Bh7DlgudKfjY_3Wf/Linux/images/peripheral-interfaces/pipewire_record.png?fit=max&auto=format&n=Bh7DlgudKfjY_3Wf&q=85&s=e2c51a157a8f92060ee4a5aec7e0d874" width="566" height="229" data-path="Linux/images/peripheral-interfaces/pipewire_record.png" />

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

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

### GStreamer 音频

<Tabs>
  <Tab title="录制">
    ```bash theme={null}
    # PCM capture
    gst-launch-1.0 -v pulsesrc volume=10 ! audioconvert ! wavenc ! \
      filesink location=/opt/audio.wav

    # FLAC capture
    gst-launch-1.0 -v pulsesrc volume=10 ! audioconvert ! flacenc ! \
      filesink location=/opt/audio.flac
    ```
  </Tab>

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

    # MP3 playback
    gst-launch-1.0 -e filesrc location=/opt/audio.mp3 ! \
      mpegaudioparse ! mpg123audiodec ! pulsesink volume=10

    # FLAC playback
    gst-launch-1.0 -e filesrc location=/opt/audio.flac ! \
      flacparse ! flacdec ! pulsesink volume=10
    ```
  </Tab>
</Tabs>

## 日志采集

```bash theme={null}
# PipeWire logs
journalctl -u pipewire
journalctl  -u wireplumber

# Live debugging
journalctl -u pipewire -f

# Kernel audio driver logs
sudo dmesg
```

## 故障排查

<AccordionGroup>
  <Accordion title="播放时无音频输出">
    ```bash theme={null}
    wpctl status
    wpctl set-volume @DEFAULT_AUDIO_SINK@ 1.0
    systemctl restart pipewire pipewire-pulse wireplumber



    pw-play /opt/test.wav -v


    # Check services
    systemctl status pipewire pipewire-pulse wireplumber
    ```
  </Accordion>

  <Accordion title="音频播放卡顿或有杂音">
    ```bash theme={null}
    # Check CPU load
    top

    # Check PAL media config (expect rate=48000, ch=2, fmt=2)
    grep "setDeviceMediaConfig" /var/log/syslog

    # Check for underruns
    dmesg | grep -i -e underrun -e xrun -e lpass -e audio

    # Check PipeWire quantum
    pw-metadata -n settings

    # Monitor real-time
    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 restart pipewire wireplumber
    ```

    **修复——将音频转换为 48 kHz 16 位立体声：**

    ```bash theme={null}
    ffmpeg -i input.wav -ar 48000 -ac 2 -sample_fmt s16 output.wav
    ```
  </Accordion>

  <Accordion title="PipeWire 服务无法启动">
    ```bash theme={null}
    systemctl status pipewire pipewire-pulse wireplumber
    journalctl -u pipewire -u wireplumber -b

    # Reset configuration
    rm -rf ~/.config/pipewire ~/.config/wireplumber
    systemctl  daemon-reload
    systemctl  restart pipewire pipewire-pulse wireplumber

    # Reinstall if needed
    sudo apt install --reinstall pipewire wireplumber pipewire-pulse
    ```
  </Accordion>
</AccordionGroup>

## 高级功能

### 用于 VoIP 的回声消除（ECNS）

```bash theme={null}
# VoIP record
pw-record /opt//record_voip.wav -v --target=voip-tx0

# VoIP playback
pw-play /opt/record_voip.wav -v --target=voip-rx0
```

功能：自适应回声消除、平稳与非平稳噪声抑制、声学回声路径消除。

## 资源

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