> ## 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/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/GfyA_U32cnx0UaZ3/Linux/images/peripheral-interfaces/iq8275-speakers-connected.png?fit=max&auto=format&n=GfyA_U32cnx0UaZ3&q=85&s=51ee7aa9cdbacc072fc21ff3bbccd56a" width="1078" height="389" data-path="Linux/images/peripheral-interfaces/iq8275-speakers-connected.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 图服务(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/)