# 音频功能 ***Copyright © Quectel Wireless Solutions Co., Ltd. 2026. All rights reserved.*** --- 本文档提供 Quectel Pi M2 开发板（RK3576 平台）**Linux** 音频系统操作的简明指南。系统采用 **ALSA + PipeWire（兼容 PulseAudio）** 的音频架构，从底层驱动到应用层提供完整的音频解决方案。 # 快速开始 Quectel Pi M2 开发板基于瑞芯微 RK3576 平台，音频 Codec 采用 Everest ES8389（I2S 接口，I2C 地址 0x10），音频硬件包含 4 类通道： | **通道类型** | **通道名称** | **硬件对应位置** | **说明** | | --- | --- | --- | --- | | 输入 | 板载 MIC | 板载 MEMS 麦克风 | 内置硅麦，默认录音输入源，无需外接 | | 输入 && 输出 | 耳机 | 3.5 mm 耳机座 | 支持国标/美标耳机，带耳机插入检测（ADC 检测）；耳机插入后系统自动将播放通道切到耳机（同时关闭喇叭 PA），拔出后自动切回喇叭 | | 输出 | SPK (扬声器) | 扬声器接口 | 板载功放（PA），默认喇叭输出，DAC 默认 -6 dB；与耳机共用同一 DAC 音源（均接 HPOL/HPOR），仅通过 PA 使能（spk-con-gpio）控制输出 | | 输出 | HDMI 音频 | HDMI 接口 | 通过 HDMI 输出数字音频（声卡 rockchip-hdmi） | | 输出 | 蓝牙音频 | 蓝牙天线 | A2DP 蓝牙音箱/耳机播放，HFP 免提通话 | ```{image} images/image_Q8LzbGH7goTLjrxNp3Tcbsfqnfh.webp :width: 514px :height: 446px :align: center ``` ```{image} images/image_KoUjbw71eo2VuExEYsmczLU4nXo.webp :width: 942px :height: 593px :align: center ``` 系统提供一组标准音频配置与调试命令，用于完成设备检查、录音、播放和音量控制等常见操作。 > **音频架构说明**：M2 开发板 Debian 系统采用 **PipeWire + WirePlumber** 作为音频服务（替代传统 PulseAudio），并提供 `pactl`/`paplay` 等 PulseAudio 兼容命令行工具。底层仍由 ALSA 驱动声卡硬件。 ## 查看声卡信息 可通过以下命令检查系统声卡与 PCM 设备的加载情况： - 查看声卡列表： ```shell cat /proc/asound/cards ``` 预期输出（M2 开发板）： ```plaintext 0 [rockchipes8389 ]: rockchip-es8389 - rockchip-es8389 rockchip-es8389 1 [rockchipbt ]: simple-card - rockchip,bt rockchip,bt 2 [rockchiphdmi ]: rockchip-hdmi - rockchip-hdmi rockchip-hdmi ``` - 查看已分配的 **pcm** 流列表： ```shell cat /proc/asound/pcm ``` - 查看当前默认音频设备： ```shell aplay -l arecord -l ``` > 说明：若系统未检测到声卡信息或 **PCM** 流，则 **ALSA** 与 **PipeWire** 均无法正常工作。 # ALSA 架构 ## ALSA 概述 ALSA 是 Linux 系统的底层音频架构与驱动核心，直接管理和控制音频硬件。M2 开发板的内核已内置 ES8389 Codec 驱动（`sound/soc/codecs/es8389.c`）及机器驱动（`sound/soc/rockchip/rockchip_multicodecs.c`），设备树中声卡定义于 `rk3576-quectel-pi-m2-audio.dtsi`： - **ES8389 Codec**：I2C 地址 0x10，MCLK 12.288 MHz，走 SAI1（I2S）接口 - **耳机检测**：`hp-det-gpio` + SARADC 检测，支持耳机插入/拔出自动切换 - **喇叭功放**：`spk-con-gpio`（speak_pa_en）控制 PA 使能 - **MIC 输入源切换**：`rockchip,mic-source-switch` 支持板载 MIC / 耳机 MIC 切换 - **HDMI 音频**：声卡 `rockchip-hdmi`，走 SAI6 接口 ### ES8389 主要 ALSA 控件 可通过 `amixer` 查看与设置 ES8389 的全部控制项： ```shell amixer -c 0 scontrols ``` 常用控件： | **控件名** | **说明** | **默认值** | | --- | --- | --- | | DACL Playback Volume | 左声道 DAC 音量（0~255，191=0dB，0.5dB/步） | 179（-6dB） | | DACR Playback Volume | 右声道 DAC 音量（0~255，191=0dB，0.5dB/步） | 179（-6dB） | | ADCL PGA Volume | 左声道麦克风 PGA 增益（0~14） | 8 | | ADCR PGA Volume | 右声道麦克风 PGA 增益（0~14） | 8 | | Speaker | 喇叭开关（DAPM 控件） | on | | Headphone | 耳机开关（DAPM 控件） | on | > **说明**：M2 开发板喇叭默认音量为 **-6 dB**（DAC = 179），已通过 ALSA 路径配置文件（`/usr/share/alsa-card-profile/mixer/paths/analog-output-es8389-m2.conf`）固定，避免喇叭声音过大。如需调整，修改该配置文件中 `volume = 179` 的值（如 -3dB 用 185，-9dB 用 173），或临时用 amixer 调整。 ## 音频录制 ### 板载麦克风录制 **默认录音输入源自动切换规则**：系统通过耳机插入检测（`hp-det-gpio` + SARADC）实时判断耳机插拔状态，并自动切换录音输入源： - **耳机插入时**：默认使用 **耳机麦克风** 录音，无需手动切换 - **耳机未插入时**：默认使用 **板载 MIC** 录音 耳机未插入时，M2 开发板默认录音输入源为板载 MIC。使用 `arecord` 录制： ```shell arecord -D hw:0,0 -f S16_LE -r 48000 -c 2 -d 5 /tmp/record_mic.wav ``` 参数说明： - `-D hw:0,0`：使用声卡 0（rockchip-es8389）PCM 设备 0 - `-f S16_LE`：16 位小端 PCM 格式 - `-r 48000`：采样率 48 kHz - `-c 2`：双声道 - `-d 5`：录制 5 秒 停止录制：录制时长到达 `-d` 指定秒数后自动停止；也可按 `Ctrl+C` 中断。 ### 耳机麦克风录制 **耳机插入后**，系统通过耳机检测自动将录音输入源切换为耳机麦克风（此时耳机 MIC 为默认录音输入源）；耳机拔出后自动切回板载 MIC。也可手动指定： ```shell arecord -D hw:0,0 -f S16_LE -r 48000 -c 2 -d 5 /tmp/record_headset.wav ``` ## 音频播放 ### 喇叭播放 M2 开发板默认音频输出为板载喇叭（经 PA 功放）。使用 `aplay` 播放： **耳机/喇叭自动切换机制**：M2 开发板的喇叭（Speaker）与耳机（Headphone）**共用同一路 DAC 音源**（设备树 audio-routing 中两者均接 HPOL/HPOR），区别仅在于输出通路上的 PA 功放使能。系统通过 `hp-det-gpio` + SARADC 实时检测耳机插入状态： - **耳机插入**：检测到耳机后，系统自动将默认播放通道切换到耳机（Headphone 通路），同时关闭喇叭 PA（`spk-con-gpio` 拉低，Speaker DAPM 断电），声音只从耳机输出；录音输入同步切换到耳机麦克风。 - **耳机拔出**：检测到耳机拔出后，系统自动切回板载喇叭（Speaker 通路），重新使能 PA（`spk-con-gpio` 拉高），声音从喇叭输出；录音输入切回板载 MIC。 因此喇叭与耳机播放的是同一路音频数据，无需分别配置音源，仅硬件输出通路（PA 使能）不同。 ```shell aplay -D hw:0,0 /tmp/test.wav ``` ### 耳机播放 插入耳机后，系统自动将音频路由切换到耳机。也可手动指定播放设备： ```shell aplay -D hw:0,0 /tmp/test.wav ``` ### HDMI 音频播放 HDMI 音频走独立声卡（rockchip-hdmi），使用声卡 2： ```shell aplay -D hw:2,0 /tmp/test.wav ``` ## 音量控制 ### 查看当前音量 ```shell amixer -c 0 sget 'DACL' amixer -c 0 sget 'DACR' ``` ### 设置音量 ```shell # 设置左声道 DAC 音量为 -6dB（179） amixer -c 0 cset numid=51 179 # 设置右声道 DAC 音量为 -6dB（179） amixer -c 0 cset numid=52 179 # 或使用控件名设置（0dB = 191，-6dB = 179，每步 0.5dB） amixer -c 0 sset 'DACL' 179 amixer -c 0 sset 'DACR' 179 ``` 音量数值与 dB 对应关系：`dB = -95.5 + 0.5 × value`，即： - 191 → 0 dB - 179 → -6 dB - 167 → -12 dB - 143 → -24 dB ### 设置麦克风增益 ```shell # 设置左声道 MIC PGA 增益（0~14，每步 3dB） amixer -c 0 sset 'ADCL PGA' 8 # 设置右声道 MIC PGA 增益 amixer -c 0 sset 'ADCR PGA' 8 ``` ### 查看所有 ALSA 控件完整信息 ```shell amixer -c 0 contents ``` # PipeWire / PulseAudio 架构 ## 概述 M2 开发板 Debian 系统使用 **PipeWire + WirePlumber** 作为音频服务框架，并提供 PulseAudio 兼容层（pipewire-pulse），因此所有 `pactl`/`paplay`/`parec` 等 PulseAudio 命令均可直接使用。WirePlumber 负责音频设备与路由的自动管理。 ### 设备查看与管理 **1. 查看可用输出设备（Sinks）** ```shell pactl list short sinks ``` M2 开发板典型输出： ```plaintext 0 alsa_output.platform-es8389-sound.analog-stereo PipeWire s32le 2ch 48000Hz SUSPENDED 1 alsa_output.platform-hdmi-sound.hdmi-stereo PipeWire s32le 2ch 48000Hz SUSPENDED ``` - `alsa_output.platform-es8389-sound.analog-stereo`：板载音频（喇叭/耳机） - `alsa_output.platform-hdmi-sound.hdmi-stereo`：HDMI 音频 - 蓝牙音箱/耳机连接后会动态出现 `bluez_output.xxx` sink **注意：adb进入默认是root，需要进入普通用户**。如下： > ```plaintext > root@linaro-alip:/# pactl list short sinks > Connection failure: Connection refused > pa_context_connect() failed: Connection refused > root@linaro-alip:/# su w > w@linaro-alip:/$ pactl list short sinks > 56 alsa_output.platform-es8389-sound.analog-stereo PipeWire s32le 2ch 48000Hz SUSPENDED > ``` **2. 查看输入设备（Sources）** ```shell pactl list short sources ``` M2 开发板典型输入： ```plaintext 0 alsa_input.platform-es8389-sound.analog-stereo PipeWire s32le 2ch 48000Hz SUSPENDED ``` 蓝牙耳机（HFP）连接后会动态出现 `bluez_input.xxx` source。 **3. 查看详细设备信息** ```shell pactl list sinks pactl list sources ``` ### 设置默认输出/输入设备 ```shell # 设置默认输出为板载喇叭/耳机 pactl set-default-sink alsa_output.platform-es8389-sound.analog-stereo # 设置默认输出为 HDMI pactl set-default-sink alsa_output.platform-hdmi-sound.hdmi-stereo # 设置默认输入为板载 MIC pactl set-default-source alsa_input.platform-es8389-sound.analog-stereo ``` ## 录音 ### 板载 MIC 录音 ```shell pactl set-default-source alsa_input.platform-es8389-sound.analog-stereo parec --file-format=wav /tmp/output_mic.wav ``` 停止录音：按 `Ctrl+C`。 ### 耳机 MIC 录音 **耳机插入后**，WirePlumber 会自动将默认输入路由切换为耳机麦克风（此时耳机 MIC 为默认录音输入源）；耳机拔出后自动切回板载 MIC。也可手动指定： ```shell parec --file-format=wav /tmp/output_headset.wav ``` ## 播放 ### 喇叭/耳机播放 ```shell paplay /tmp/test.wav ``` 默认输出到板载音频。喇叭与耳机共用同一 DAC 音源，系统通过耳机检测自动切换：插入耳机自动切到耳机（关闭喇叭 PA），拔出耳机自动切回喇叭（重新使能 PA），无需手动配置。 ### 指定 sink 播放 ```shell # 播放到板载喇叭/耳机 paplay --device=alsa_output.platform-es8389-sound.analog-stereo /tmp/test.wav # 播放到 HDMI paplay --device=alsa_output.platform-hdmi-sound.hdmi-stereo /tmp/test.wav ``` ## 音量控制 ### 查看/设置输出音量 ```shell # 查看所有 sink 音量 pactl list sinks | grep -E 'Sink|Volume|Mute' # 设置音量（百分比） pactl set-sink-volume @DEFAULT_SINK@ 80% # 静音/取消静音 pactl set-sink-mute @DEFAULT_SINK@ toggle ``` ### 查看/设置输入音量 ```shell # 设置麦克风音量 pactl set-source-volume @DEFAULT_SOURCE@ 80% # 静音麦克风 pactl set-source-mute @DEFAULT_SOURCE@ toggle ``` # GNOME 桌面使用指南 M2 开发板 Debian 系统默认搭载 GNOME 桌面（Wayland），音频设置集成在系统设置中。 ## 打开声音设置 点击右上角状态栏的音量图标 → 选择"声音设置"；或打开"设置"应用 → 选择"声音"。
Screencast From 2026-04-14 04-56-13
## 输出设备切换 在"设置 → 声音 → 输出"中： 1. **设备**：选择输出设备（板载音频 / HDMI / 蓝牙音箱） 2. **音量**：拖动滑块调整输出音量 3. **静音**：点击喇叭图标静音/取消静音 4. **蓝牙设备**：连接蓝牙音箱/耳机后自动出现在设备列表中 > **提示**：板载音频输出（喇叭/耳机）共用同一 DAC 音源，插入耳机时系统自动切换输出到耳机并关闭喇叭 PA，拔出后自动切回喇叭。在 GNOME 声音设置中可见输出设备切换为板载音频/HDMI/蓝牙。 ## 输入设备切换 在"设置 → 声音 → 输入"中： 1. **设备**：选择输入设备（板载 MIC / 耳机 MIC / 蓝牙耳机） 2. **音量**：拖动滑块调整输入（麦克风）音量 3. **测试**：点击麦克风图标进行录音测试 ## 快速音量控制 - **快捷键**：键盘上的音量加减键 / 静音键直接控制 - **顶部状态栏**：点击音量图标拖动滑块 - **托盘快捷菜单**：点击音量图标旁的下拉箭头，可直接切换输出设备 # 蓝牙音频 ## 概述 M2 开发板支持蓝牙音频，蓝牙协议栈使用 BlueZ + PipeWire（libspa-0.2-bluetooth），支持： - **A2DP**：蓝牙音箱/耳机播放高质量立体声音乐 - **HFP**：蓝牙耳机免提通话（含麦克风） - **AVRCP**：蓝牙遥控（播放/暂停/上一首/下一首） 蓝牙音频由 PipeWire 的 BlueZ 插件直接处理，无需经过 ALSA 声卡。设备树中的 `bt-sound`（SAI2 SCO）声卡已在 WirePlumber 配置中禁用（`/etc/wireplumber/wireplumber.conf.d/51-quectel-pi-m2-audio.conf`），音频统一走 A2DP/HFP。 ## 连接蓝牙设备 **方式一（GNOME 图形界面）**： 1. 点击右上角状态栏 → 蓝牙图标（或"设置 → 蓝牙"） 2. 打开蓝牙开关 3. 点击"添加设备"搜索蓝牙音箱/耳机 4. 选择设备完成配对 **方式二（bluetoothctl 命令行）**： ```shell # 进入蓝牙控制台 bluetoothctl # 打开蓝牙 power on # 扫描设备 scan on # 配对并连接（替换为实际 MAC 地址） pair AA:BB:CC:DD:EE:FF trust AA:BB:CC:DD:EE:FF connect AA:BB:CC:DD:EE:FF ``` ## 播放蓝牙音频 连接成功后，蓝牙音箱/耳机会自动成为默认输出设备，直接播放即可： ```shell paplay /tmp/test.wav ``` 也可手动指定蓝牙 sink： ```shell # 查看蓝牙 sink 名称 pactl list short sinks # 播放到蓝牙设备 paplay --device=bluez_output.AA_BB_CC_DD_EE_FF.1 /tmp/test.wav ``` ## 蓝牙耳机麦克风 蓝牙耳机（HFP 模式）的麦克风会自动注册为输入源（`bluez_input.xxx`），用于通话或录音： ```shell # 查看蓝牙输入源 pactl list short sources # 设置蓝牙耳机麦克风为默认输入 pactl set-default-source bluez_input.AA_BB_CC_DD_EE_FF.1 ``` > **说明**：M2 开发板已内置蓝牙麦克风增益优化脚本（`/usr/share/wireplumber/scripts/quectel/bluetooth-mic-gain.lua`），连接蓝牙耳机时自动将麦克风增益设置为 150%，保证通话录音清晰。 # 疑难解答 | **问题** | **可能原因** | | --- | --- | | 录音文件未生成 |
  1. 检查设置指令是否正确。
  2. 操作目录是否有可读写权限。
| | 音频播放失败 |
  1. 检查播放文件是否存在。
  2. 检查播放指令是否正确。
| | 喇叭无声 |
  1. 检查喇叭是否接好、PA 功放是否正常。
  2. 检查 DAC 音量是否被静音（`amixer -c 0 sget 'DACL Playback Volume'`）。
  3. 检查默认 sink 是否被切到其他设备。
| | 耳机无声 |
  1. 检查耳机是否插好、是否触发耳机检测。
  2. 检查默认 sink（`pactl list short sinks`）。
| | 耳机插入后仍走喇叭 |
  1. 检查耳机检测（hp-det）是否生效。
  2. 检查 WirePlumber 是否在运行（`systemctl --user status wireplumber`）。
| | HDMI 无声 |
  1. 检查 HDMI 是否连接、显示器是否支持音频回传。
  2. 检查默认 sink 是否切到 HDMI（`pactl set-default-sink alsa_output.platform-hdmi-sound.hdmi-stereo`）。
| | 蓝牙连不上 |
  1. 检查蓝牙是否开启（`bluetoothctl power on`）。
  2. 检查设备是否处于可发现模式。
  3. 检查 PipeWire 蓝牙插件是否安装（`libspa-0.2-bluetooth`）。
| | 蓝牙有声但麦克风无声 |
  1. 确认耳机支持 HFP 免提协议。
  2. 检查默认 source 是否切到 `bluez_input.xxx`。
| # 英文名词缩写对照表 本文档中出现的英文名词缩写说明如下： ## 音频硬件与技术 | **缩写** | **英文全称** | **中文含义** | **作用** | | --- | --- | --- | --- | | DACL / DACR | DAC Left / DAC Right | 左/右声道数模转换器 | ES8389 左右声道独立的 DAC 音量控制通道 | | PGA | Programmable Gain Amplifier | 可编程增益放大器 | 麦克风输入通道的增益放大器，用于调节录音灵敏度（0~14，每步 3dB） | | DAPM | Dynamic Audio Power Management | 动态音频电源管理 | Linux ASoC 子系统的电源管理机制，按音频通路使用情况自动开关各级电源/PA | | HPOL / HPOR | Headphone Output Left / Right | 耳机左/右声道输出 | ES8389 耳机输出引脚，喇叭与耳机共用此音源 | | DMIC | Digital Microphone | 数字麦克风 | 直接输出数字信号的麦克风（M2 板载 MEMS 硅麦） | | SAI | Serial Audio Interface | 串行音频接口 | Rockchip 处理器的音频接口控制器（SAI1 接 ES8389，SAI6 接 HDMI，SAI2 接蓝牙 SCO） | | SCO | Synchronous Connection-Oriented | 同步面向连接链路 | 蓝牙语音通话的同步链路，用于 HFP 免提通话 | | SARADC | Successive Approximation Register ADC | 逐次逼近型模数转换器 | 用于耳机插入检测（读取耳机检测引脚电压判断插拔状态） | ## 蓝牙协议 | **缩写** | **英文全称** | **中文含义** | **作用** | | --- | --- | --- | --- | | A2DP | Advanced Audio Distribution Profile | 高级音频分发协议 | 蓝牙传输高质量立体声音乐（蓝牙音箱/耳机播放） | | HFP | Hands-Free Profile | 免提协议 | 蓝牙耳机免提通话，支持麦克风输入（语音通话/录音） | | AVRCP | Audio/Video Remote Control Profile | 音视频遥控协议 | 蓝牙遥控操作（播放/暂停/上一首/下一首） | | BLE | Bluetooth Low Energy | 低功耗蓝牙 | 低功耗蓝牙通信，用于低速率数据传输与设备连接 | | BlueZ | BlueZ Bluetooth Stack | BlueZ 蓝牙协议栈 | Linux 官方蓝牙协议栈，配合 PipeWire 实现蓝牙音频 | ## 系统与软件 | **缩写** | **英文全称** | **中文含义** | **作用** | | --- | --- | --- | --- | | PipeWire | PipeWire | PipeWire 多媒体服务 | 新一代 Linux 音频/视频服务框架，管理音频设备与路由（M2 默认音频服务） | | WirePlumber | WirePlumber | WirePlumber 会话管理器 | PipeWire 的会话与策略管理器，负责设备发现、路由与音量策略 | | pactl | PulseAudio Control | PulseAudio 控制工具 | 命令行查看/控制音频设备（sink/source、音量、路由） | | sink | Sink | 音频输出端 | 音频数据输出设备（喇叭/耳机/HDMI/蓝牙音箱） | | source | Source | 音频输入端 | 音频数据输入设备（板载 MIC/耳机 MIC/蓝牙耳机） | # 资源与支持 - [ALSA 介绍]() - [PipeWire 文档]() - [WirePlumber 文档]()