简介一套基于FFmpeg与SDL2的音频播放示例工程面向音视频开发入门及进阶读者演示用FFmpeg解码MP3文件、以SDL2输出音频并通过链表队列完成解码端与播放端的数据传递便于理解音视频播放线程中的缓冲、同步与内存管理思路。压缩包共231个文件大小约15.45MB主体包括C工程文件ffmpeg_sdl_audio_player.cpp、151个头文件、VS解决方案与vcxproj配置以及avcodec、avformat、SDL2等10个lib库和8个dll动态库另附2个MP3与1个AAC测试音频、编译脚本和gitignore等可直接用于工程复现。已有1116人学习此资源。除完整工程源码外还能一并获得配套的依赖库、示例音频、构建脚本及编译产物省去自行收集FFmpeg与SDL2开发环境的麻烦同时可从内容预览中看到的avcodec-55.dll、SDL2.dll等文件快速核对不同版本模块的调用关系适合对照博文边读边调试、二次开发播放器功能。 在音视频开发这个圈子里FFmpeg和SDL2的搭配几乎算得上必修课。FFmpeg负责搞定音视频的解码、转码、过滤这些脏活累活SDL2则提供跨平台的窗口、事件、音频输出接口。很多人一上来就盯着视频播放折腾恨不得马上渲染出画面其实音频播放才是最容易让人卡住的环节。原因在于音频对实时性要求极高数据稍微断流、错位耳朵立刻就能听出来容不得半点马虎。这次分享的是一个基于FFmpeg加SDL2播放音频的最小实现。它做的事情很简单读取一个音频文件MP3、WAV、AAC、FLAC都行用FFmpeg解封装、解码成PCM数据再交给SDL2的音频设备输出。项目虽小但把FFmpeg的解码链路、SDL2的音频播放机制、音视频同步的起点——音频时钟——都串起来了。适合刚接触音视频开发的人练手也适合想搞清楚音频播放原理、准备做播放器的人当骨架参考。我自己第一次跑通这段代码的时候最大的感受是原来解码出来的数据和能听到的声音之间还隔着一层“重采样”的坑。1. 项目拆解为什么是FFMPEGSDL2这个组合1.1 明确分工一个负责解码一个负责出声FFmpeg和SDL2在音频播放这件事上各管一段职责非常清晰。FFmpeg做的事情是从文件里读出封装格式比如MP3的帧结构、MP4的box找到音频流交给解码器还原成原始的PCM采样数据。它管的是“数据怎么变成人能理解的音频信号”。SDL2管的是“这些PCM数据怎么送到声卡上让扬声器发出声音”。换句话说FFmpeg负责从有损压缩的容器里救出原始波形SDL2负责把波形变成声波。选SDL2而不是直接用系统底层API是因为SDL2抽象了Windows的WASAPI/WaveOut、Linux的ALSA/PulseAudio、macOS的CoreAudio。一段代码写完换个平台基本上只需要重新编译不需要改播放逻辑。如果你在Windows上想用Win32原生的waveOutOpen在Linux上想直接操作ALSA那代码就得写两套维护成本高出一截。SDL2在这里扮演的是“硬件访问的标准接口”角色开发效率和可移植性都更好。这个搭配还有一个隐藏优势SDL2的音频播放是回调驱动的它会在内部维护一个缓冲区当声卡需要数据时通过回调函数向你索要。这个机制和FFmpeg解码这种“按包读取”的模式天然互补你只需要在回调里往缓冲区填数据SDL2负责按采样率节奏消耗它音频播放的实时性就有了基本保证。1.2 数据流链路从压缩编码到耳朵里的声音整个音频播放的数据链路可以概括为文件字节流 → AVPacket压缩数据包 → AVFrame解码后的PCM帧 → 重采样后的PCM缓冲 → SDL2音频设备。用生活中的例子来类比这一步有点像一个“解压缩矿泉水”的过程。文件里的音频是浓缩液压缩编码FFmpeg把浓缩液兑水还原成可以喝的液体PCM但还原出来的液体浓度和容器瓶的形状可能不匹配。SDL2这个瓶子只认固定的规格——比如44100Hz、双声道、16位整型——于是你需要用重采样器swr把还原出来的液体调整成瓶子能装下的规格然后倒进去。整个过程听起来不复杂但中间任何一步的参数对不上出来的声音就会变速、变调或者全是噪音。理解这条数据流是写好这个项目的前提也是之后排查问题时的索引。比如播放速度偏快多数情况是SDL2读取数据的速度快于解码速度或者采样率设置不匹配声音刺耳沙哑大概率是采样格式没对上把浮点数据当整型解释了。2. 开发环境搭建与工具链准备2.1 FFmpeg库的获取与链接方式FFmpeg官方不直接提供Windows的二进制包需要到第三方编译站下载。常见的选择是gyan.dev的build版本或者BtbN的GitHub Release版本。下载时注意选对架构如果你的代码是64位程序就用x86_64的库如果你是32位程序就下载x86_32版本。这一点极其重要混用的后果是链接时各种符号找不到或者运行时报出诡异的0xC0000005内存访问错误。Linux环境就省事多了直接用包管理器。Ubuntu系装libavcodec-dev libavformat-dev libavutil-dev libswresample-devFedora系装ffmpeg-develAlmaLinux用户可能需要先启用EPEL和CRB仓库才能拿到FFmpeg包。macOS用户用Homebrew装ffmpeg即可头文件和库文件会一并装好。链接阶段需要添加的库在Windows上一般是avformat.lib avcodec.lib avutil.lib swresample.lib顺带把SDL2.lib也链上。很多人栽在漏了avutil.lib上实际上avformat和avcodec都依赖它链接顺序错了或者漏引都会导致“无法解析的外部符号”之类的一大串错误。2.2 CLion与VS2019工程配置要点CLion用的是CMake配置方式比较直观。假设FFmpeg的目录是D:/libs/ffmpegSDL2的目录是D:/libs/SDL2CMakeLists.txt里核心部分只需要这样写include_directories(D:/libs/ffmpeg/include D:/libs/SDL2/include) link_directories(D:/libs/ffmpeg/lib D:/libs/SDL2/lib) target_link_libraries(audio_player avformat avcodec avutil swresample SDL2)Visual Studio里则需要在项目属性里配置“附加包含目录”和“附加库目录”然后在“链接器→输入→附加依赖项”里手动加上前面那几个lib名字。还要注意一点SDL2要求你定义SDL_MAIN_HANDLED宏否则它会把你的main函数替换成SDL2自己的入口导致奇怪的链接错误。Dev-C 5.11这个老古董其实也能配只是稍微麻烦。需要去SDL2的官网下载MinGW开发库FFmpeg则要找MinGW版编译的静态库。把include路径和lib路径填进“项目→项目属性→参数”里确保编译器是64位版本否则库加载不进来。不过我的建议是如果条件允许尽早切换到VS或者CLionDev-C的调试体验实在太折磨人了。2.3 拿到库之后先做个自检环境配置完别急着写正式代码先写几行验证调用能否成功。比如获取一下FFmpeg的版本号printf(FFmpeg version: %s\n, av_version_info());再调用一次SDL初始化if (SDL_Init(SDL_INIT_AUDIO) 0) { printf(SDL_Init failed: %s\n, SDL_GetError()); }这一步能帮你快速区分“库没配好”和“代码写错了”两类问题。我自己用的办法是编译一个什么都不干、只打印版本号的小程序跑通了再往上堆功能省得后面排错时还要怀疑工具链。3. 音频播放核心流程实现3.1 初始化解封装与解码器第一步是打开输入文件并探测音频流。FFmpeg会把整个文件当成一个AVFormatContext来处理。打开文件后通过av_find_best_stream找到音频流的索引AVFormatContext *fmt_ctx NULL; if (avformat_open_input(fmt_ctx, filename, NULL, NULL) 0) { // 文件不存在或格式无法识别 } if (avformat_find_stream_info(fmt_ctx, NULL) 0) { // 无法获取流信息 } int audio_stream_idx av_find_best_stream(fmt_ctx, AVMEDIA_TYPE_AUDIO, -1, -1, NULL, 0);拿到流索引后从fmt_ctx-streams[audio_stream_idx]里取出codecpar用它的编码ID找到解码器并打开。这一步需要注意不要再使用老的codec字段直接复制新版FFmpeg已经移除了流里直接挂载解码器的做法必须用avcodec_find_decoder和avcodec_open2。解码器的初始化还包括申请AVCodecContext把codecpar里的参数用avcodec_parameters_to_context复制进去。这里顺便把解码后要用的AVFrame和AVPacket都申请好后续循环里就不需要反复分配了。3.2 解码循环与还原原始采样数据核心解码循环看起来简单读包、送包、取帧。while (av_read_frame(fmt_ctx, pkt) 0) { if (pkt-stream_index audio_stream_idx) { int ret avcodec_send_packet(codec_ctx, pkt); if (ret 0) continue; // 送包失败跳过 while (ret 0) { ret avcodec_receive_frame(codec_ctx, frame); if (ret AVERROR(EAGAIN) || ret AVERROR_EOF) break; if (ret 0) break; // 拿到了一个解码后的frame准备处理 } } av_packet_unref(pkt); }需要注意的细节是avcodec_send_packet和avcodec_receive_frame是一对多、多对一的关系。一个AAC帧解出来恰好是一个1024采样的音频块但某些编码器比如某些MP3变体可能一包数据解出多个帧所以要内层再套一个循环直到返回EAGAIN表示解码器当前已耗完输入需要新包。这个逻辑漏掉的后果是丢音频听感上就是声音断断续续。解码出来的AVFrame其data[0]、data[1]等字段存储的是PCM数据。这里有一个隐藏陷阱FFmpeg内部解码得到的音频样本格式多数情况下是AV_SAMPLE_FMT_FLTP浮点型、Planar排列也就是左右声道分别存放在data[0]和data[1]两个独立缓冲里。而SDL2最便于处理的格式是AUDIO_S16SYS16位整型、交错排列左右声道交织在同一个缓冲里。如果不做转换直接交给SDL2播放出来的声音大部分情况下不是无声就是尖锐刺耳的白噪音。3.3 重采样把FFmpeg的格式翻译成SDL2的格式重采样就在这里出场用的库是libswresample核心函数是swr_convert。先建立转换器指定输入格式为解码器的参数输出格式是我们想要的目标格式SwrContext *swr swr_alloc_set_opts(NULL, out_ch_layout, // 输出声道布局比如AV_CH_LAYOUT_STEREO AV_SAMPLE_FMT_S16, // 输出样本格式 out_sample_rate, // 输出采样率 in_ch_layout, // 输入声道布局 in_sample_fmt, // 输入样本格式从frame里取 in_sample_rate, // 输入采样率 0, NULL); swr_init(swr);重采样通常在拿到每一帧之后做而不是统一在初始化时做。因为某些文件内部可能存在采样率变化帧与帧之间的参数不完全一致。保险起见可以在循环里检测frame-sample_rate和frame-channels是否与当前swr配置一致不一致就重建swr。转出来的数据是16位整型交错数据存进一个自行维护的缓冲区等待SDL2来取。这里要特别注意缓冲区的管理因为解码和播放的速度天然不匹配缓冲区可能被写满也可能被读空。简单处理方式是只保留一个“待播放数据队列”队列用互斥锁保护SDL2回调里取数据主解码循环里放数据。3.4 SDL2音频设备初始化和播放循环SDL2初始化音频设备指定回调函数和期望的格式。由于我们上一步已经强制把音频转成了S16交错这里的参数就变得稳妥了SDL_AudioSpec want, have; SDL_zero(want); want.freq out_sample_rate; // 比如44100 want.format AUDIO_S16SYS; want.channels 2; want.samples 4096; // 缓冲区大小单位是帧 want.callback audio_callback; // 数据回调 want.userdata audio_state; SDL_AudioDeviceID dev SDL_OpenAudioDevice(NULL, 0, want, have, 0); SDL_PauseAudioDevice(dev, 0);samples参数是SDL2内部缓冲区的帧数这个值不能太离谱太小会频繁触发回调影响性能太大则延迟明显。一般取512到4096之间视频项目里可以适当取大一些来缓解卡顿。回调函数从自己的队列里取出数据拷贝到stream指向的缓冲区void audio_callback(void *userdata, Uint8 *stream, int len) { AudioState *st (AudioState *)userdata; SDL_memset(stream, 0, len); // 从st-buffer中拷贝len字节到stream不够就拷多少算多少 }SDL2会按照采样率自动调用这个回调每次调用间隔和内部缓冲区大小挂钩。拷贝数据的逻辑用SDL_memcpy就行如果队列数据不够剩下的位置补零这样听到的声音不会爆音而是轻微停顿。补零之后还能顺便记录一下当前实际播放到的时间位置为后面做音视频同步留了接口。主播放循环简单得多解码、入队、控制退出while (playing) { // 读包解码并压入待播放队列 // 每压入一批数据打印一次播放进度 SDL_Delay(10); }SDL_Delay在这里是必要的否则纯解压循环会把CPU跑满而且等待队列数据的节奏会变得混乱播放器界面如果长这样的话会非常卡。4. 我踩过的坑与排查清单4.1 SDL_OpenAudioDevice返回0的常见原因这个函数失败通常是参数不合法最常见的坑是采样率填了0或者格式填了AUDIO_S16而不是AUDIO_S16SYS。还有一个不常见但真实存在的坑在Windows上如果程序入口用了SDL2的main重定义但项目类型是控制台而没有启用SDL2的main替换也会导致初始化失败。排查方法是打印SDL_GetError()如果提示audio device already open那大概率你在上一次运行的窗口没有正常关闭设备句柄没释放。解决方式是检查流程确保打开失败后调用SDL_CloseAudioDevice并且只打开一次。4.2 播放速度偏快或偏慢声音像“花栗鼠”几乎都是采样率不匹配导致的。FFmpeg解码出来的采样率存在frame-sample_rate里这个值不一定是源文件上标称的采样率某些容器可能写错。你要做的不是盲信源文件的元数据而是以解码帧里实际拿到的值为准。输出给SDL2的采样率必须和swr输出端的采样率保持一致否则每秒钟播放的数据量不对音调就会改变。我在调试这个项目时特意在重采样后打印了实际输出的采样点数和采样率对照SDL2希望的freq值很快就能发现不一致。有时候源文件是48000HzSDL2那边用44100Hz打开出来的声音就像开了1.1倍速还带点尖锐感。4.3 声音断断续续、有卡顿常见原因有两个一是SDL2回调里做了太耗时的操作比如直接在回调里解码。这是典型的反面教材回调函数必须短平快只做内存拷贝任何涉及锁、文件IO、解码的操作都会拖垮SDL2的节奏。二是队列锁粒度太大主线程持锁时间过长导致回调饿死听感就是播放断流。解决方式是把解码和播放分离得更彻底。主线程只负责向队列写入回调只负责从队列读取锁的持有时间控制在“只拷贝这一段数据”的范围内。另外还可以给队列设定一个最大长度超过阈值就暂停解码防止内存无限上涨。4.4 无声但程序正常运行这种问题最磨人因为没有任何报错。排查方向是从数据链路末端向起点倒推。先在回调里故意塞一段固定频率的正弦波测试SDL2是否正常工作能听到声音说明SDL2链路没问题。再检查swr输出的数据长度是否和SDL2期望的长度一致。最后确认重采样前帧是否真的解码出数据很多情况下根本原因出在avcodec_receive_frame的循环条件写错丢掉了第一批帧。根据我的经验90%的“无声”问题出在重采样格式配错或SDL2回调没有被真正触发。你可以临时在回调里加一个计数变量每被调用一次加一播放两秒后打印出来。如果计数为0那就是SDL2初始化有问题或者设备处于暂停状态没调用SDL_PauseAudioDevice(dev, 0)。下面整理了一个常见问题速查表方便后面快速定位现象最可能的原因排查动作打开文件失败路径错误或封装格式不支持检查文件是否存在用ffprobe验证声音尖锐刺耳样本格式不匹配确认swr输出是S16不是FLTP播放速度异常采样率不一致打印frame-sample_rate与SDL2 freq声音断续卡顿回调中做了解码或加锁太久回调只做内存拷贝无声但数据在流动SDL2设备未取消暂停SDL_PauseAudioDevice(dev, 0)程序退出崩溃队列释放顺序不对先停SDL2设备再销毁解码器和上下文4.5 还有几个边界情况需要留意文件末尾的收尾处理容易被忽略。读文件循环结束之后要调用一次avcodec_send_packet并传入NULL让解码器把缓冲的最后几个帧吐出来否则文件尾部会丢一小段音频。另外AAC文件的结尾经常有若干帧是静音数据这是编码器灌入的填充不影响播放不必当成异常。音频设备关闭时要先SDL_PauseAudioDevice(dev, 1)暂停再调用SDL_CloseAudioDevice(dev)最后再释放FFmpeg各个上下文。顺序反了容易出现野指针在Windows上表现为随机崩溃在Linux上可能表现为段错误。5. 这个项目还能往哪个方向扩展播放音频只是起步往这个骨架上加功能很快就能做出一个可用的音频播放器。比较顺手的扩展方向有四个。第一个是音量控制。SDL2提供了SDL_MIX_MAXVOLUME和SDL_MixAudioFormat在回调里把要拷贝的数据先混音调整音量再输出就能实现软件音量控制不需要动系统音量。这个技术在播放器里特别实用因为系统音量和应用音量分开控制是基本体验。第二个是暂停和继续。暂停的本质是停止向SDL2队列喂数据同时记住当前播放位置。但SDL2的设备一旦暂停回调就不会再触发已播放的位置会停在暂停前的状态。恢复时只需要继续从队列取数据即可。需要注意暂停期间的队列数据管理最好在暂停时把积压数据清掉否则恢复后会出现“突进”的效果。第三个是音频可视化。FFmpeg解码出的PCM数据可以直接拿来算频谱配合SDL2的渲染功能画柱状图或波形图。这个方向能顺带学到FFT变换和图形渲染算是一个有趣的小项目。第四个是音频时钟。在回调里维护一个变量记录已经播放了多少个采样点除以采样率就是当前的播放时间。这个时间是整个播放器做音视频同步的基准视频播放器里的AV sync就是靠它来实现的。做成这个功能距离自己写一个简单的视频播放器就不远了。我做完音频播放后最大的一个收获是理解了“驱动”这个词的含义。SDL2的回调并不是你调它而是它在声卡需要数据时反过来找你。所有设计都要围绕“数据能不能跟上回调消耗”来思考。搞懂这一点后面做低延迟播放、做直播音频采集都会轻松很多。如果你刚踩进FFmpeg的坑建议先把这个项目啃下来它值得你花一到两个周末慢慢折腾。本文还有配套的精品资源点击获取