必须先初始化音频子系统，否则SDL_OpenAudioDevice返回0且SDL_GetError()提示“Audio subsystem is not initialized”；需调用SDL_Init(SDL_INIT_AUDIO)或组合初始化，失败时应检查SDL_GetError()。
SDL2播放PCM音频必须先初始化音频子系统
不调用 SDL_Init(SDL_INIT_AUDIO) 就直接开设备，SDL_OpenAudioDevice 会返回 0，且 SDL_GetError() 返回 “Audio subsystem is not initialized”。这是最常被跳过的一步，尤其在从图形示例迁移到纯音频时。
实操建议：
- 务必在创建窗口或加载资源前调用
SDL_Init(SDL_INIT_AUDIO)，若已初始化其他子系统（如视频），用按位或组合：SDL_Init(SDL_INIT_AUDIO | SDL_INIT_VIDEO) - 初始化失败时检查
SDL_GetError()，不要只依赖返回值是否为 0 - Windows 上若遇到 “DirectSound: No audio device found”，可能是后台禁用了音频服务，或当前用户无音频设备访问权限（少见但真实）
回调函数里不能阻塞、不能 malloc、不能调用 SDL_Delay
SDL 音频回调由独立线程（或硬件中断上下文）触发，执行时间必须极短。一旦回调耗时超过缓冲区播放时长（比如你设了 512 样本 @44.1kHz ≈ 11.6ms），就会立刻出现卡顿、爆音甚至设备静音。
常见错误现象：
立即学习“C++免费学习笔记（深入）”；
- 回调里用
fread()从磁盘读 PCM —— 磁盘 I/O 延迟远超毫秒级，必掉帧 - 回调里调用
malloc()或std::vector::push_back()—— 内存分配可能触发锁或页错误 - 写了个 while 循环等数据就绪 —— 直接卡死音频线程
正确做法是：提前把 PCM 数据喂进一个无锁环形缓冲区（如 std::array + 两个原子索引），回调里只做 memcpy 和索引更新。例如：
void audio_callback(void* userdata, Uint8* stream, int len) {
auto* buf = static_cast<AudioBuffer*>(userdata);
int available = buf->available();
int to_copy = std::min(len, available);
memcpy(stream, buf->peek(), to_copy);
buf->consume(to_copy);
// stream 剩余部分保持为 0（静音），避免残留噪声
memset(stream + to_copy, 0, len - to_copy);
}SDL_AudioSpec 的 format 字段必须与 PCM 数据实际格式严格一致
填错 format 是无声/爆音的头号原因。比如你手头是 16-bit signed little-endian PCM（常见于 WAV），却设成 AUDIO_S16MSB，每个样本会被 SDL 当作大端解析，结果全乱。
关键参数对照：
- 16-bit signed PCM, little-endian →
AUDIO_S16LSB - 16-bit signed PCM, big-endian →
AUDIO_S16MSB - 32-bit float PCM, native endian →
AUDIO_F32SYS（不是AUDIO_F32，后者是别名但部分旧版本不识别） - 8-bit unsigned PCM →
AUDIO_U8（注意：不是AUDIO_S8，符号位不同）
如果你不确定原始数据格式，用十六进制编辑器打开文件看前几个字节，或用 ffprobe -v quiet -show_entries stream=bits_per_sample,codec_name -of default 查。
使用 SDL_OpenAudioDevice 而非 SDL_OpenAudio 以获得更可控的设备选择
SDL_OpenAudio 是旧 API，固定使用默认设备，且无法指定设备名、无法设置是否允许重采样。现代项目应统一用 SDL_OpenAudioDevice。
实操要点：
- 第一个参数传
nullptr表示默认输出设备；若要指定设备，先用SDL_GetAudioDeviceName(i, 0)枚举，再传设备名字符串 - 第四个参数（
wanted）必须填完整：freq、format、channels、samples（缓冲区样本数，非字节数）缺一不可 - 第五个参数（
obtained）传非空指针，SDL 会写入实际使用的参数——务必检查它是否和wanted一致，尤其format和freq可能被硬件强制转换 - 若
obtained->format != wanted->format，说明 SDL 做了内部转换，此时你要确保输入 PCM 数据格式仍匹配wanted->format，否则转换逻辑可能出错
容易被忽略的是 samples 值：它决定回调触发频率和延迟。设太小（如 64）易受调度干扰；设太大（如 8192）导致明显延迟。通常 512–2048 是较稳的选择。
