音频功能¶
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 免提通话 |
系统提供一组标准音频配置与调试命令，用于完成设备检查、录音、播放和音量控制等常见操作。
音频架构说明：M2 开发板 Debian 系统采用 PipeWire + WirePlumber 作为音频服务（替代传统 PulseAudio），并提供
pactl/paplay等 PulseAudio 兼容命令行工具。底层仍由 ALSA 驱动声卡硬件。
查看声卡信息¶
可通过以下命令检查系统声卡与 PCM 设备的加载情况：
查看声卡列表：
cat /proc/asound/cards
预期输出（M2 开发板）：
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 流列表：
cat /proc/asound/pcm
查看当前默认音频设备：
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 的全部控制项：
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 录制：
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。也可手动指定：
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 使能）不同。
aplay -D hw:0,0 /tmp/test.wav
耳机播放¶
插入耳机后，系统自动将音频路由切换到耳机。也可手动指定播放设备：
aplay -D hw:0,0 /tmp/test.wav
HDMI 音频播放¶
HDMI 音频走独立声卡（rockchip-hdmi），使用声卡 2：
aplay -D hw:2,0 /tmp/test.wav
音量控制¶
查看当前音量¶
amixer -c 0 sget 'DACL'
amixer -c 0 sget 'DACR'
设置音量¶
# 设置左声道 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
设置麦克风增益¶
# 设置左声道 MIC PGA 增益（0~14，每步 3dB）
amixer -c 0 sset 'ADCL PGA' 8
# 设置右声道 MIC PGA 增益
amixer -c 0 sset 'ADCR PGA' 8
查看所有 ALSA 控件完整信息¶
amixer -c 0 contents
PipeWire / PulseAudio 架构¶
概述¶
M2 开发板 Debian 系统使用 PipeWire + WirePlumber 作为音频服务框架，并提供 PulseAudio 兼容层（pipewire-pulse），因此所有 pactl/paplay/parec 等 PulseAudio 命令均可直接使用。WirePlumber 负责音频设备与路由的自动管理。
设备查看与管理¶
1. 查看可用输出设备（Sinks）
pactl list short sinks
M2 开发板典型输出：
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.xxxsink
注意：adb进入默认是root，需要进入普通用户。如下：
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）
pactl list short sources
M2 开发板典型输入：
0 alsa_input.platform-es8389-sound.analog-stereo PipeWire s32le 2ch 48000Hz SUSPENDED
蓝牙耳机（HFP）连接后会动态出现 bluez_input.xxx source。
3. 查看详细设备信息
pactl list sinks
pactl list sources
设置默认输出/输入设备¶
# 设置默认输出为板载喇叭/耳机
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 录音¶
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。也可手动指定：
parec --file-format=wav /tmp/output_headset.wav
播放¶
喇叭/耳机播放¶
paplay /tmp/test.wav
默认输出到板载音频。喇叭与耳机共用同一 DAC 音源，系统通过耳机检测自动切换：插入耳机自动切到耳机（关闭喇叭 PA），拔出耳机自动切回喇叭（重新使能 PA），无需手动配置。
指定 sink 播放¶
# 播放到板载喇叭/耳机
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
音量控制¶
查看/设置输出音量¶
# 查看所有 sink 音量
pactl list sinks | grep -E 'Sink|Volume|Mute'
# 设置音量（百分比）
pactl set-sink-volume @DEFAULT_SINK@ 80%
# 静音/取消静音
pactl set-sink-mute @DEFAULT_SINK@ toggle
查看/设置输入音量¶
# 设置麦克风音量
pactl set-source-volume @DEFAULT_SOURCE@ 80%
# 静音麦克风
pactl set-source-mute @DEFAULT_SOURCE@ toggle
GNOME 桌面使用指南¶
M2 开发板 Debian 系统默认搭载 GNOME 桌面（Wayland），音频设置集成在系统设置中。
打开声音设置¶
点击右上角状态栏的音量图标 → 选择"声音设置"；或打开"设置"应用 → 选择"声音"。
输出设备切换¶
在"设置 → 声音 → 输出"中：
设备：选择输出设备（板载音频 / HDMI / 蓝牙音箱）
音量：拖动滑块调整输出音量
静音：点击喇叭图标静音/取消静音
蓝牙设备：连接蓝牙音箱/耳机后自动出现在设备列表中
提示：板载音频输出（喇叭/耳机）共用同一 DAC 音源，插入耳机时系统自动切换输出到耳机并关闭喇叭 PA，拔出后自动切回喇叭。在 GNOME 声音设置中可见输出设备切换为板载音频/HDMI/蓝牙。
输入设备切换¶
在"设置 → 声音 → 输入"中：
设备：选择输入设备（板载 MIC / 耳机 MIC / 蓝牙耳机）
音量：拖动滑块调整输入（麦克风）音量
测试：点击麦克风图标进行录音测试
快速音量控制¶
快捷键：键盘上的音量加减键 / 静音键直接控制
顶部状态栏：点击音量图标拖动滑块
托盘快捷菜单：点击音量图标旁的下拉箭头，可直接切换输出设备
蓝牙音频¶
概述¶
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 图形界面）：
点击右上角状态栏 → 蓝牙图标（或"设置 → 蓝牙"）
打开蓝牙开关
点击"添加设备"搜索蓝牙音箱/耳机
选择设备完成配对
方式二（bluetoothctl 命令行）：
# 进入蓝牙控制台
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
播放蓝牙音频¶
连接成功后，蓝牙音箱/耳机会自动成为默认输出设备，直接播放即可：
paplay /tmp/test.wav
也可手动指定蓝牙 sink：
# 查看蓝牙 sink 名称
pactl list short sinks
# 播放到蓝牙设备
paplay --device=bluez_output.AA_BB_CC_DD_EE_FF.1 /tmp/test.wav
蓝牙耳机麦克风¶
蓝牙耳机（HFP 模式）的麦克风会自动注册为输入源（bluez_input.xxx），用于通话或录音：
# 查看蓝牙输入源
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%，保证通话录音清晰。
疑难解答¶
问题 |
可能原因 |
|---|---|
录音文件未生成 |
|
音频播放失败 |
|
喇叭无声 |
|
耳机无声 |
|
耳机插入后仍走喇叭 |
|
HDMI 无声 |
|
蓝牙连不上 |
|
蓝牙有声但麦克风无声 |
|
英文名词缩写对照表¶
本文档中出现的英文名词缩写说明如下：
音频硬件与技术¶
缩写 |
英文全称 |
中文含义 |
作用 |
|---|---|---|---|
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/蓝牙耳机） |