3.12. sample_audio 使用说明

3.12.1. 功能概述

sample_audio 是一个音频示例项目，用于验证 X5 平台的音频基本环境，并可作为音频项目的参考实现。项目目前包含两个独立的命令行示例程序：

sample_alsa：基于 ALSA（Advanced Linux Sound Architecture）的音频录制与播放程序。支持通过命令行参数配置采样率、位深、声道、录制时长以及录音/播放设备，可将录制的音频保存为 WAV 格式文件，并提供交互式命令用于录制、播放、查询硬件支持能力。
sample_hat_loopback：面向 Waveshare Audio Driver HAT REV2（ES7210+ES8156）外接声卡的双工 loopback 自检程序，通过「先录音、再边播边录」的两阶段流程，验证 HAT 声卡是否正常注册、能否完成 8 声道双工收发。

注意： EVB 没有板端 Audio Codec，所以使用本 sample 需要搭配外接声卡，可以参考硬件环境搭建章节。

3.12.1.1. 软件架构说明

sample_audio 项目中的两个程序均基于 ALSA 库（libasound）开发，使用 C 语言编写。其中 sample_alsa 主要分为以下几个部分：

解析命令行参数，包括 --capture/--playback 指定录音/播放 PCM 设备，以及 -r/-b/-c/-d/-f 等音频参数
设置 mixer 控件（录音侧 ADC PGA Gain、播放侧 DAC），若声卡上不存在对应控件则打印告警并跳过
录制音频功能，负责从输入设备获取音频数据，按位深做数字增益后写入 WAV 文件
播放音频功能，从 WAV 文件中读取文件头参数并据此配置 PCM 设备，再通过输出设备播放
处理用户交互命令，负责获取用户输入的信息，提供详细参考
查询硬件支持的格式、采样率和声道数

软件架构图：sample_alsa 在获取到用户的 command 之后，根据不同的业务，调用 ALSA 库（libasound）的接口，实现录制、播放、检查硬件支持参数的业务。

3.12.1.2. 代码位置及目录结构

代码位置：app/samples/platform_samples/sample_audio
目录结构：

.
├── sample_alsa
│   ├── Makefile
│   └── sample_alsa.c
└── sample_hat_loopback
    ├── Makefile
    └── sample_hat_loopback.c

sample_alsa/Makefile、sample_hat_loopback/Makefile：分别用于编译两个示例程序的 Makefile 文件。
sample_alsa.c：sample_alsa 程序的主要源代码文件。
sample_hat_loopback.c：sample_hat_loopback 程序的主要源代码文件。

3.12.1.3. 工具位置及目录结构

/app/platform_samples/sample_audio

该目录下包含 sample_alsa 和 sample_hat_loopback 两个子目录，分别存放各自编译后的可执行文件以及程序运行时候输出的音频文件。

3.12.1.4. 背景知识

ALSA 库（libasound）： Linux 系统中用于音频处理的标准库，提供了丰富的音频处理接口，包括 PCM 设备的打开/配置/读写、mixer 控件的设置、硬件能力探测等。
WAV 文件格式：一种无损音频文件格式，被广泛支持和使用，本示例使用标准的 44 字节 PCM WAV 头。
ALSA 设备命名：hw:card,device 表示直接访问声卡 card 上的第 device 个 PCM 设备；plughw: 在其之上增加了一层插件，sample_alsa 仅接受 hw: 形式。

3.12.1.5. API 流程说明

sample_alsa 主要使用以下 ALSA 库的 API 流程（record_audio 和 play_audio 基本一致）：

snd_pcm_open：打开 PCM 设备（录音用 SND_PCM_STREAM_CAPTURE，播放用 SND_PCM_STREAM_PLAYBACK）。
snd_mixer_open / snd_mixer_attach / snd_mixer_selem_register / snd_mixer_load / snd_mixer_find_selem / snd_mixer_selem_set_capture_volume_all / snd_mixer_selem_set_playback_volume_all / snd_mixer_close：用于在录音前设置 ADC PGA Gain、在播放前设置 DAC 等 mixer 控件，找不到对应控件时程序会打印告警并跳过，不会终止运行。
snd_pcm_hw_params_any：初始化硬件参数对象。
snd_pcm_hw_params_set_access：设置数据访问方式（程序固定使用 SND_PCM_ACCESS_RW_INTERLEAVED，即左右声道交错）。
snd_pcm_hw_params_set_format：设置音频格式，设置前用 snd_pcm_hw_params_test_format 探测硬件是否支持指定位深对应的格式，不支持则回退到 SND_PCM_FORMAT_S16_LE。
snd_pcm_hw_params_set_rate_near：设置采样率，设置前用 snd_pcm_hw_params_test_rate 探测硬件是否支持指定采样率，不支持则回退到 44100 Hz。
snd_pcm_hw_params_set_channels：设置声道数。
snd_pcm_hw_params：应用硬件参数到设备。
snd_pcm_hw_params_get_period_size：获取周期大小，用于分配读写缓冲区。
snd_pcm_readi 和 snd_pcm_writei：用于音频数据的读取和写入；当返回 -EPIPE（缓冲区溢出/欠载）时，调用 snd_pcm_prepare 恢复后继续。
snd_pcm_drain：播放结束时排空剩余数据。
snd_pcm_close：关闭 PCM 设备，释放资源。

查询硬件支持能力（对应 c 命令）还会用到：

snd_pcm_hw_params_test_format：逐项测试硬件支持的 PCM 格式。
snd_pcm_hw_params_test_rate：逐项测试硬件支持的采样率。
snd_pcm_hw_params_get_channels_min / snd_pcm_hw_params_get_channels_max：获取硬件支持的最小/最大声道数。

3.12.2. 编译部署

3.12.2.1. 编译

两个示例程序各自独立编译，进入对应目录执行 make 即可：

cd sample_alsa && make        # 编译 sample_alsa
cd sample_hat_loopback && make  # 编译 sample_hat_loopback

比如在该示例代码目录下直接执行：

root@ubuntu:/app/platform_samples/sample_audio/sample_alsa# make

将在当前目录下生成 sample_alsa 可执行文件；sample_hat_loopback 同理。

3.12.2.2. 硬件环境搭建

可以参考开发板使用指南中的 40PIN 接口章节中的接口举例说明：

外接声卡（如 Waveshare Audio Driver HAT REV2）安装到 40PIN 并完成系统侧使能后，可通过 cat /proc/asound/cards 查看实际注册的声卡编号，再据此确定 --capture/--playback 参数中的 card 号。例如 HAT 注册为 card 1 时，录音设备用 hw:1,1、播放设备用 hw:1,0。

3.12.2.3. 程序部署

编译后可执行文件分别位于各自子目录下：

sample_audio/
├── sample_alsa
│   ├── Makefile
│   ├── sample_alsa
│   ├── sample_alsa.c
│   └── sample_alsa.o
└── sample_hat_loopback
    ├── Makefile
    ├── sample_hat_loopback
    ├── sample_hat_loopback.c
    └── sample_hat_loopback.o

板端路径同样按子目录区分：

本 sample 的 sample_alsa 可执行文件位于板端 /app/platform_samples/sample_audio/sample_alsa/sample_alsa
本 sample 的 sample_hat_loopback 可执行文件位于板端 /app/platform_samples/sample_audio/sample_hat_loopback/sample_hat_loopback

3.12.3. sample_alsa 运行

3.12.3.1. 程序运行方法

直接运行可执行文件（使用默认设备 hw:0,0、采样率 48000 Hz、位深 16 bit、双声道、5 秒）：

./sample_alsa

或者使用命令行参数指定配置：

./sample_alsa -r 16000 -b 16 -c 2 -d 5 -f record_test.wav

EVB 没有板端 Codec，实际使用时通常搭配外接声卡。外接声卡注册成功后，可通过 cat /proc/asound/cards 查看其注册到的 card 编号，再用 --capture/--playback 指定对应的 PCM 设备。例如外接声卡注册为 card 1 时，录音设备用 hw:1,1、播放设备用 hw:1,0：

./sample_alsa --capture hw:1,1 --playback hw:1,0

3.12.3.2. 程序参数选项说明

--capture <hw:card,device>     Specify capture PCM device (default hw:0,0)    ( 指定录音设备，仅支持 hw:card,device )
--playback <hw:card,device>    Specify playback PCM device (default hw:0,0)   ( 指定播放设备，仅支持 hw:card,device )
-r <Sampling rate>             Specify sample rate for record or playback     ( 指定采样率 )
-b <Bit depth>                 Specify bit depth for record or playback       ( 指定位深 )
-c <Number of channels>        Specify channels for record or playback        ( 指定声道数 )
-d <Duration>                  Specify duration for record or playback        ( 指定录制时长 )
-f <File name>                 Specify file for record or playback            ( 指定文件名 )
-h                             Show this help message                         ( 显示帮助信息 )

说明：--capture/--playback 仅接受 hw:card,device 形式（直接 hw 访问，不支持 plughw:/plug:），可省略 hw: 前缀简写为 card,device。播放时实际使用的采样率、声道、位深以 WAV 文件头为准，命令行 -r/-c/-b 仅作用于录音。

3.12.3.3. 运行效果

程序将根据用户指定的参数录制音频，并在录制结束后保存为 WAV 文件，再根据用户命令进行播放。

直接执行的效果（默认设备 hw:0,0）：

root@buildroot:/app/platform_samples/sample_audio/sample_alsa# ./sample_alsa
Audio Recording and Playback Program
Settings:
  Capture Device        : hw:0,0
  Playback Device       : hw:0,0
  Sampling Rate         : 48000 Hz
  Bit Depth             : 16 bit
  Channels              : 2
  Duration              : 5 seconds
  File Name             : record_test.wav

***************  Command Lists  ***************
 q  -- Quit
 r  -- Start recording
 p  -- Playback
 c  -- Check hardware support
 h  -- Print help message

Command:

使用外接声卡（注册为 card 1）的效果：

root@buildroot:/app/platform_samples/sample_audio/sample_alsa# ./sample_alsa --capture hw:1,1 --playback hw:1,0
Audio Recording and Playback Program
Settings:
  Capture Device        : hw:1,1
  Playback Device       : hw:1,0
  Sampling Rate         : 48000 Hz
  Bit Depth             : 16 bit
  Channels              : 2
  Duration              : 5 seconds
  File Name             : record_test.wav

***************  Command Lists  ***************
 q  -- Quit
 r  -- Start recording
 p  -- Playback
 c  -- Check hardware support
 h  -- Print help message

Command:

使用命令行参数指定音频参数的效果：

root@buildroot:/app/platform_samples/sample_audio/sample_alsa# ./sample_alsa --capture hw:1,1 --playback hw:1,0 -r 16000 -b 16 -c 2 -d 5
Audio Recording and Playback Program
Settings:
  Capture Device        : hw:1,1
  Playback Device       : hw:1,0
  Sampling Rate         : 16000 Hz
  Bit Depth             : 16 bit
  Channels              : 2
  Duration              : 5 seconds
  File Name             : record_test.wav

***************  Command Lists  ***************
 q  -- Quit
 r  -- Start recording
 p  -- Playback
 c  -- Check hardware support
 h  -- Print help message

Command:

录制时候的效果（外接声卡上未找到 ADC PGA Gain 控件时，会打印告警并跳过该设置继续录制）：

Command: r
Warning: mixer control 'ADC PGA Gain' not set on hw:1,1 (skipped)
         Use amixer -c <card> contents to check control names.
Start recording: record_test.wav (5 sec, 48000 Hz, 2 ch, 16 bit, device hw:1,1)
Recording finished: record_test.wav (960000 bytes, 5.00 sec, 48000 Hz, 2 ch, 16 bit)

Command:

说明：Warning: mixer control 'ADC PGA Gain' not set 表示在 hw:1,1 对应的声卡上没有找到名为 ADC PGA Gain 的 mixer 控件，程序会跳过该增益设置并继续录制，不影响后续流程；可用 amixer -c <card> contents 查看该声卡实际支持的控件名。Recording finished 行中的 960000 bytes 为录音数据字节数，计算方式为 采样率 × 声道数 × (位深/8) × 时长 = 48000 × 2 × 2 × 5。

播放时候的效果：

Command: p
Playing file: record_test.wav (48000 Hz, 2 ch, 16 bit, 5.00 sec, device hw:1,0)
[ 2208.795534] es8156_startup start
Playback finished: record_test.wav

Command:

说明：以 [ xxxxxxx ] 开头的行（如 [ 2208.795534] es8156_startup start）是内核打印到控制台的日志，此处为 es8156 codec 启动时内核输出的信息，并非 sample_alsa 程序本身打印的内容。Playing file 行中的参数来自 WAV 文件头，而非命令行参数；若 WAV 文件头与命令行设置不一致，程序还会额外打印一条 Note: WAV format differs from current CLI settings ... 提示。

检查硬件支持的效果（实际情况会根据硬件支持有所变化）：

Command: c
capture_device:
Supported formats:
Format                        Support                                           Description
----------------------------------------------------------------------------------------------
S8                            Signed 8 bit                                      Not Supported
U8                            Unsigned 8 bit                                    Not Supported
S16_LE                        Signed 16 bit Little Endian                       Supported
S16_BE                        Signed 16 bit Big Endian                          Not Supported
U16_LE                        Unsigned 16 bit Little Endian                     Not Supported
U16_BE                        Unsigned 16 bit Big Endian                        Not Supported
S24_LE                        Signed 24 bit Little Endian                       Supported
S24_BE                        Signed 24 bit Big Endian                          Not Supported
U24_LE                        Unsigned 24 bit Little Endian                     Not Supported
U24_BE                        Unsigned 24 bit Big Endian                        Not Supported
S32_LE                        Signed 32 bit Little Endian                       Not Supported
S32_BE                        Signed 32 bit Big Endian                          Not Supported
U32_LE                        Unsigned 32 bit Little Endian                     Not Supported
U32_BE                        Unsigned 32 bit Big Endian                        Not Supported
IEC958_SUBFRAME_LE            IEC-958 Little Endian                             Not Supported
IEC958_SUBFRAME_BE            IEC-958 Big Endian                                Not Supported
MU_LAW                        Mu-Law                                            Not Supported
A_LAW                         A-Law                                             Not Supported
IMA_ADPCM                     Ima-ADPCM                                         Not Supported
MPEG                          MPEG                                              Not Supported
GSM                           GSM                                               Not Supported

Channels                      SupportNum
--------------------------------------------------------
Max                              2
Min                              2

Sampling Rate (Hz)            Support
--------------------------------------------------------
8000                           Supported
16000                          Supported
22050                          Supported
44100                          Supported
48000                          Supported
96000                          Not Supported
192000                         Not Supported
playback_device:
Supported formats:
Format                        Support                                           Description
----------------------------------------------------------------------------------------------
S8                            Signed 8 bit                                      Not Supported
U8                            Unsigned 8 bit                                    Not Supported
S16_LE                        Signed 16 bit Little Endian                       Supported
S16_BE                        Signed 16 bit Big Endian                          Not Supported
U16_LE                        Unsigned 16 bit Little Endian                     Not Supported
U16_BE                        Unsigned 16 bit Big Endian                        Not Supported
S24_LE                        Signed 24 bit Little Endian                       Supported
S24_BE                        Signed 24 bit Big Endian                          Not Supported
U24_LE                        Unsigned 24 bit Little Endian                     Not Supported
U24_BE                        Unsigned 24 bit Big Endian                        Not Supported
S32_LE                        Signed 32 bit Little Endian                       Not Supported
S32_BE                        Signed 32 bit Big Endian                          Not Supported
U32_LE                        Unsigned 32 bit Little Endian                     Not Supported
U32_BE                        Unsigned 32 bit Big Endian                        Not Supported
IEC958_SUBFRAME_LE            IEC-958 Little Endian                             Not Supported
IEC958_SUBFRAME_BE            IEC-958 Big Endian                                Not Supported
MU_LAW                        Mu-Law                                            Not Supported
A_LAW                         A-Law                                             Not Supported
IMA_ADPCM                     Ima-ADPCM                                         Not Supported
MPEG                          MPEG                                              Not Supported
GSM                           GSM                                               Not Supported

Channels                      SupportNum
--------------------------------------------------------
Max                              2
Min                              2

Sampling Rate (Hz)            Support
--------------------------------------------------------
8000                           Supported
16000                          Supported
22050                          Supported
44100                          Supported
48000                          Supported
96000                          Not Supported
192000                         Not Supported

***************  Command Lists  ***************
 q  -- Quit
 r  -- Start recording
 p  -- Playback
 c  -- Check hardware support
 h  -- Print help message

Command:

退出程序时候的效果：

Command: q
Quit

Command: root@buildroot:/app/platform_samples/sample_audio/sample_alsa#

3.12.4. sample_hat_loopback

3.12.4.1. 功能概述

sample_hat_loopback 是专门用于 Waveshare Audio Driver HAT REV2（ES7210+ES8156）外接声卡的双工 loopback 自检程序。它通过「先录一段语音、再边播边录」的两阶段流程，验证 HAT 声卡是否正常注册、能否完成 8 声道双工收发，并依据回采通道的峰值给出 PASS/FAIL 结论。固定参数为 8 声道、16000 Hz、16 bit、周期 512 帧，录音设备 plughw:1,1、播放设备 plughw:1,0。

3.12.4.2. 软件架构说明

sample_hat_loopback 同样基于 ALSA 库（libasound）开发，使用 C 语言编写，并额外使用 pthread 实现录音/播放的双工并行。它面向 Waveshare Audio Driver HAT REV2（ES7210+ES8156）外接声卡，主要分为以下几个部分：

声卡检测模块，解析 /proc/asound/cards 查找名为 duplexaudio 的声卡，并校验其是否注册为 card 1（与 plughw:1,1/plughw:1,0 对应）
阶段1 录音模块，打开 plughw:1,1 录制 5 秒 8 声道语音，保存为 record_first.wav 并打印各声道峰值
阶段2 双工模块，通过两个 pthread 并行执行——播放线程连续播放阶段1 录音 2 次（中间间隔 2 秒静音），录音线程同时录制完整 8 声道流，保存为 sample_hat_loopback.wav
峰值判定模块，统计回采数据中 ch7/ch8（PCB loopback）与 ch1-ch4（有线 loopback）的峰值，峰值 ≥ 500（即该通道 PCM 采样绝对值的最大值达到 500；16-bit 量程为 0–32768，达到 500 表示回采通路确实采到有效信号而非底噪/静音）判定 PASS，否则判定 FAIL

软件架构图：sample_hat_loopback 在 main 入口先检测 HAT 声卡，再依次进入阶段1 录音、阶段2 双工（pthread 双线程边播边录），最后由峰值判定模块给出 PASS/FAIL 结论，期间依赖 libasound 的 PCM 接口、pthread 线程库以及文件系统存储 WAV。

程序运行流程如下：

启动时通过 /proc/asound/cards 查找名为 duplexaudio 的声卡，并校验其是否注册为 card 1（与 plughw:1,1/plughw:1,0 对应）。若未检测到 HAT 或卡号不符，则打印排查提示并退出。
阶段1：打开 plughw:1,1 录音设备，对麦克风讲 5 秒话，将 8 声道语音保存为 record_first.wav，并打印各声道峰值。
阶段2：再次打开录音与播放设备，通过两个线程（pthread）并行执行——播放线程将阶段1 录到的语音连续播放 2 次（中间间隔 2 秒静音），录音线程同时录制完整的 8 声道流，保存为 sample_hat_loopback.wav。
统计回采数据中 ch7/ch8（PCB loopback 通道）与 ch1-ch4（有线 loopback 通道）的峰值，峰值 ≥ 500 即判定 PASS，否则判定 FAIL。

3.12.4.3. API 流程说明

sample_hat_loopback 同样基于 ALSA 库（libasound）开发，并额外使用 pthread 实现双工并行。主要 API 流程：

hat_find_card_index：解析 /proc/asound/cards，定位 HAT 声卡编号。
snd_pcm_open：分别打开录音（SND_PCM_STREAM_CAPTURE）与播放（SND_PCM_STREAM_PLAYBACK）PCM 设备，使用 plughw:1,1/plughw:1,0。
snd_pcm_hw_params_any / snd_pcm_hw_params_set_access / snd_pcm_hw_params_set_format / snd_pcm_hw_params_set_channels / snd_pcm_hw_params_set_rate_near / snd_pcm_hw_params_set_period_size_near / snd_pcm_hw_params_set_buffer_size_near / snd_pcm_hw_params：配置并应用硬件参数。
snd_pcm_prepare：准备设备。
pthread_create / pthread_join：创建并等待录音、播放两个线程。
snd_pcm_readi / snd_pcm_writei：录音线程读取、播放线程写入音频数据；返回 -EPIPE 时调用 snd_pcm_prepare 恢复。
snd_pcm_close：关闭 PCM 设备。
自定义 write_wav：将 8 声道 PCM 数据写入标准 WAV 文件。

3.12.4.4. 程序运行方法

在板端进入 sample_hat_loopback 目录直接运行（程序无命令行参数，固定使用 plughw:1,1/plughw:1,0）：

cd /app/platform_samples/sample_audio/sample_hat_loopback
./sample_hat_loopback

运行前请确认：

音频子卡已安装在 40PIN 上

3.12.4.5. 运行效果

音频子卡检测通过并完成两阶段测试的典型输出：

OK: ALSA card 1 'duplexaudio' matches Audio Driver HAT REV2 driver config.
     Driver/overlay check only confirm the mounted board is
     Waveshare Audio Driver HAT REV2 (ES7210+ES8156), 3x DIP OFF, then continue.
     playback plughw:1,0  capture plughw:1,1

format: 8ch 16000Hz 16bit period=512
=== phase 1: speak into mic (5s) ===
saved record_first.wav (80000 frames, 5.0s)
phase1 peak: ch1=xxxx ch2=xxxx ch3=xxxx ch4=xxxx ch5=xxxx ch6=xxxx ch7=xxxx ch8=xxxx

=== phase 2: play voice x2 (gap 2s) + capture ===
capture length: 12.0s
saved sample_hat_loopback.wav (192000 frames, 12.0s)
phase2 peak: ch1=xxxx ch2=xxxx ch3=xxxx ch4=xxxx ch5=xxxx ch6=xxxx ch7=xxxx ch8=xxxx

PASS: PCB loopback ch7/ch8 (peak xxxx)

判定说明：

若 ch7/ch8（HAT 板载 PCB loopback 通道）峰值 ≥ 500，打印 PASS: PCB loopback ch7/ch8 (peak xxxx)，表示 HAT 板载回采通路正常。
若 ch7/ch8 不达标但 ch1-ch4（外接线 loopback 通道）峰值 ≥ 500，打印 PASS: wired loopback ch1-ch4 (peak xxxx)，并附带 ch7/ch8 峰值提示。
若两组通道峰值均低于 500，打印 FAIL: no loopback ...，表示未检测到有效回采，需检查 HAT 安装、DIP 开关与系统使能配置。

HAT 未检测到时的输出：

FAIL: Audio Driver HAT REV2 not detected (missing 'duplexaudio').

Please check:
  1. HAT on 40-pin header, all 3 DIP switches OFF
  2. srpi-config -> Interface Options -> Audio -> Audio Driver HAT V2
  3. Reboot after setup: sync && reboot
  4. Run: cat /proc/asound/cards

说明：上述输出中的 xxxx 为各通道实际采样峰值，会随麦克风输入、播放音量及接线情况变化。程序最终返回值：PASS 为 0，FAIL 为 1，可在脚本中据此判断测试结果。

3.12.5. 常见问题

程序无法打开音频设备：

确保 ALSA 库已正确安装，并且音频设备驱动正常工作。
确认指定的设备字符串格式正确，sample_alsa 仅接受 hw:card,device（不支持 plughw:/plug:），可用 cat /proc/asound/cards 查看实际可用的 card 编号。

录音时出现 Warning: mixer control 'ADC PGA Gain' not set ... (skipped) 告警：

表示当前声卡上没有名为 ADC PGA Gain 的 mixer 控件，程序会跳过该增益设置并继续录制，属于正常现象。可用 amixer -c <card> contents 查看该声卡实际支持的控件名，必要时修改源码中的 control_name 以匹配实际控件。

录制的音频文件无法播放：

确保音频文件格式正确，使用 wav 文件。
sample_alsa 录制时会按位深对采样做数字增益（默认 gain=10），若播放时出现削波失真，可在源码 record_audio() 中调小或关闭 gain 后重新编译。

播放时参数与命令行设置不一致：

sample_alsa 播放时以 WAV 文件头中的采样率、声道、位深为准配置 PCM 设备，命令行 -r/-c/-b 仅作用于录音。若文件头与命令行设置不一致，程序会打印 Note: WAV format differs from current CLI settings ... 提示，属正常行为。

程序运行时出现缓冲区溢出错误（Buffer overflow error occurred!）：

这可能是由于硬件参数设置不当或设备驱动问题，尝试调整参数或检查驱动。程序遇到该错误（-EPIPE）会自动调用 snd_pcm_prepare 恢复并继续，少量出现可忽略，频繁出现则需排查系统负载与采样参数。

sample_hat_loopback 提示 FAIL: Audio Driver HAT REV2 not detected：

确认 HAT 已正确安装在 40PIN 上，3 个 DIP 开关全部为 OFF；
通过 srpi-config -> Interface Options -> Audio -> Audio Driver HAT V2 使能后执行 sync && reboot 重启；
重启后执行 cat /proc/asound/cards，确认存在 duplexaudio 且编号为 1（程序固定使用 plughw:1,1/plughw:1,0）。

sample_hat_loopback 提示 FAIL: no loopback：

表示 ch7/ch8 与 ch1-ch4 回采峰值均低于阈值 500。请检查 HAT 板载 PCB loopback 通道是否正常，或在 ch1-ch4 上外接有线 loopback；同时确认阶段1 对麦克风讲话有正常输入（参考 phase1 peak 输出）。