在一路写完解封装、解码、格式转换这些零散知识点之后，其实一直缺一个东西：把它们串起来放出来。当时手头正好要用FFmpeg4.1，索性就用它写一个极简视频播放器——能读本地文件、能出画面、能出声音、能基本同步，代码量尽量压到最小。这个东西适合两种人：一种是刚学完FFmpeg各模块API、想看看整合流程的，另一种是手头项目用的恰好是4.1版本、想找一个能快速跑通的最小参考实现。这篇笔记不打算讲高深架构，就讲我实际操作时每一步怎么选、为什么这么写、以及遇到的几个让人卡壳的问题。
1. 为什么用FFmpeg4.1做这个播放器：版本选择与目标边界
先说版本选择这件事。FFmpeg的API在4.x系列里正处在“旧API刚废弃、新API逐渐站稳”的阶段。4.1是2018年底发布的版本，它一方面还在给一些老调用方式留兼容层，另一方面已经把avcodec_send_packet/avcodec_receive_frame这套新解码流程作为推荐用法。选4.1不是因为它新，而是因为在很多存量项目里4.1还活跃着，且新老写法的差异在这个版本上体现得比较典型。用这个版本写播放器，踩到的问题基本能覆盖往后升级到4.4、5.x、6.x时的多数注意点。
然后说说“极简”的定义。我给自己定的边界很明确：不做暂停、不做进度拖动、不做倍速、不做音量面板，只保证一件事——双击一个本地视频文件，它能流畅播完，画面和声音大致对得上。代码不追求封装成类，也不引入复杂线程模型，尽量用单一主循环把整条链路走完。这样做的价值在于把播放器的骨架露出来：解封装、解码、格式转换、渲染、同步，这五件事各自负责什么、接口怎么衔接，全部一目了然。等以后需要加功能，也是在骨架上做加法，而不是在很重的工程框架里改逻辑。
为了控制篇幅，我用的是原生C语言加SDL2，没有碰Qt、OpenGL这些额外依赖。窗口用SDL2创建，渲染用SDL2的纹理接口，这样可以少写不少原生窗口系统代码。音频输出也用SDL2的音频设备接口。换句话说，FFmpeg负责所有媒体数据的处理，SDL2只做两件事：显示画面、播放声音。这个分工是绝大多数极简播放器的通用做法。
2. 环境准备与初始化顺序：FFmpeg4.1各模块的启动细节
2.1 注册组件与打开输入文件
FFmpeg4.1里，很多老示例里都会写av_register_all()，但这个函数在4.0开始已经弃用了。我一开在4.1上编译时还下意识带上了它，结果直接报错。现在正确的做法是什么都不调用，直接用avformat_open_input，封装层的协议和格式是在内部自动注册的。代码第一步就是这个调用：
AVFormatContext *fmt_ctx = NULL; if (avformat_open_input(&fmt_ctx, filename, NULL, NULL) < 0) { // 处理打开失败 } if (avformat_find_stream_info(fmt_ctx, NULL) < 0) { // 处理流信息读取失败 }这个函数的老版本签名会用到一个AVFormatParameters结构，4.1里已经是NULL透传即可。avformat_find_stream_info必须调用，因为很多容器格式里流参数不是立刻可读的，需要通过读取一小段数据才能把宽高、帧率、采样率这些信息填完整。缺了这一步，后面拿流参数时会发现一堆字段还是初始值。
2.2 根据流信息建立解码器
拿到fmt_ctx之后，最省事的选流方法是av_find_best_stream，这个API也是4.x里推荐的方式，比老代码里自己遍历并对比codec_type的写法更可靠，它会考虑很多默认规则，比如优先挑第一个可用的视频流和音频流。
int video_stream_idx = av_find_best_stream(fmt_ctx, AVMEDIA_TYPE_VIDEO, -1, -1, NULL, 0); int audio_stream_idx = av_find_best_stream(fmt_ctx, AVMEDIA_TYPE_AUDIO, -1, -1, NULL, 0);然后需要为每条流单独创建解码器上下文。这个地方是FFmpeg4.x和5.x以后最大的差异点之一。老代码是直接拿stream->codec来用的，4.1里AVStream里的codec字段已经被标记为废弃，正确做法是：
AVCodec *codec = avcodec_find_decoder(stream->codecpar->codec_id); AVCodecContext *codec_ctx = avcodec_alloc_context3(codec); avcodec_parameters_to_context(codec_ctx, stream->codecpar); avcodec_open2(codec_ctx, codec, NULL);codecpar是AVCodecParameters结构，它和codec_ctx里的很多字段是重叠的，因为解码时真正要用的是codec_ctx，所以必须做一次参数搬运。很多人第一次写FFmpeg4.1播放器时，直接拿codec_ctx里没设置过的宽高去算图像大小，结果发现是0，就是因为漏了这一行。这个细节我后来在排查黑屏时又多确认了一遍，后面会详细说。
初始化SDL2的顺序也有讲究。一般先SDL_Init(SDL_INIT_VIDEO | SDL_INIT_AUDIO)，然后创建窗口、渲染器、纹理，最后打开音频设备。音频设备打开比较慢，如果放在视频渲染初始化之前，播放器启动时会顿一下；放在后面则可能先看到窗口弹出来过一会儿才有声音。对于极简播放器，为了启动节奏一致，我是先创建窗口和渲染器，再开音频设备。
3. 解封装到解码：主循环里的读包、送包、取帧
3.1 核心循环长什么样
播放器的主体是下面这个循环：从输入文件里读一个包（packet），根据包属于视频流还是音频流，分别送进对应的解码器，然后从解码器里收集解码后的帧（frame）。在FFmpeg4.1里，打包和解包的过程被拆成了四个函数，替代了曾经一个avcodec_decode_video2包打天下的局面。
while (av_read_frame(fmt_ctx, &pkt) >= 0) { if (pkt.stream_index == video_stream_idx) { avcodec_send_packet(video_codec_ctx, &pkt); while (avcodec_receive_frame(video_codec_ctx, video_frame) == 0) { // 处理视频帧 } } else if (pkt.stream_index == audio_stream_idx) { avcodec_send_packet(audio_codec_ctx, &pkt); while (avcodec_receive_frame(audio_codec_ctx, audio_frame) == 0) { // 处理音频帧 } } av_packet_unref(&pkt); }这套API最典型的坑是返回值处理。avcodec_send_packet和avcodec_receive_frame返回值不只是简单的0和负数，正常工作时send_packet返回0表示成功，但receive_frame可能返回EAGAIN，表示这一帧解码数据还没凑齐，需要继续送包。实际写的时候，我的循环判断是：只要receive_frame返回0，就说明拿到了一个完整帧，否则跳出内层循环继续读下一个包。
3.2 视频帧的时间基：pts换算不能手算
拿到视频帧后，需要记录它的pts。这里的pts是一个整数，单位取决于流的time_base，不同文件可能完全不同。如果不做换算直接拿它当显示时间，那同一个播放器对不同文件的表现会千奇百怪。换算的标准做法是：
double video_time = video_frame->pts * av_q2d(stream->time_base);av_q2d把AVRational变成浮点数，然后用它乘以帧的pts，得到以秒为单位的显示时间。这句话在音视频同步里是绝对的关键，后面所有同步逻辑都建立在这个基础之上。另一个容易踩的坑是video_frame->best_effort_timestamp，在FFmpeg4.1里，某些格式（尤其是一些mp4、mov）中frame的pts不一定可靠，更稳妥的是用best_effort_timestamp，这个字段是框架内部综合了dts和容器信息后给出的一个相对准确的显示时间。极简播放器里我两个都会取，优先用best_effort_timestamp，拿不到再退回pts。
3.3 音频帧的重采样：输出格式必须对齐SDL2
音频侧多一步处理——重采样。解码器输出的音频帧格式（样本格式、采样率、声道布局）是由文件决定的，而SDL2音频设备打开时只接受一种固定格式。因此需要用到swresample库。在FFmpeg4.1里，重采样器的创建参数是：
SwrContext *swr_ctx = swr_alloc_set_opts(...); swr_init(swr_ctx);我这里的目标格式固定为：AV_SAMPLE_FMT_S16、采样率44100、立体声。之所以用S16，是因为SDL2默认的最稳妥格式是16位整型PCM，兼容性最好。44100是CD音质标准采样率，绝大多数设备的原生支持度都很好。立体声则是为了让左右声道信息不丢失。
有了重采样器后，每次拿到一个音频frame，都把它转换成一片连续的S16数据缓冲区，然后直接传给SDL2的音频队列。这里的细节是计算转换后的采样数和字节数：
int out_samples = av_rescale_rnd( swr_get_delay(swr_ctx, src_rate) + frame->nb_samples, dst_rate, src_rate, AV_ROUND_UP); av_samples_alloc(&audio_buf, NULL, channels, out_samples, sample_fmt, 0); swr_convert(swr_ctx, &audio_buf, out_samples, (const uint8_t **)frame->extended_data, frame->nb_samples);4. 渲染与播放：SDL2怎么把帧变成画面和声音
4.1 用YUV纹理减少CPU开销
很多人第一次写播放器会走一条弯路：把解码得到的YUV帧用sws_scale转成RGB，再生成SDL纹理。这确实能出画面，但YUV420到RGB的转换非常昂贵，尤其在1080p视频上，CPU占用会明显上升。极简但专业些的做法是让SDL2直接消费YUV数据，纹理格式用SDL_PIXELFORMAT_IYUV，这对应FFmpeg的AV_PIXEL_FORMAT_YUV420P。这样省掉一次色彩空间转换，解码器输出什么，SDL2就显示什么。
创建纹理时需要注意，纹理格式和宽高必须和视频帧的格式、宽高完全一致。尺寸不一致最常见的是解码器实际输出的宽高和容器信息不完全吻合，尤其是某些分辨率有对齐padding的文件。可以这么处理：
SDL_Texture *texture = SDL_CreateTexture(renderer, SDL_PIXELFORMAT_IYUV, SDL_TEXTUREACCESS_STREAMING, video_codec_ctx->width, video_codec_ctx->height);4.2 把YUV数据填进纹理
对于YUV420P，FFmpeg的AVFrame里有data[0]、data[1]、data[2]三个平面和linesize[0]、linesize[1]、linesize[2]三个行字节数。SDL2更新纹理内容时用SDL_UpdateYUVTexture，它需要的是每个平面的指针和每行的字节数，正好能对上：
SDL_UpdateYUVTexture(texture, NULL, video_frame->data[0], video_frame->linesize[0], video_frame->data[1], video_frame->linesize[1], video_frame->data[2], video_frame->linesize[2]);然后SDL_RenderClear、SDL_RenderCopy、SDL_RenderPresent，这一帧就画上去了。这里有个容易忽略的坑：linesize可能不等于实际宽度，一些解码后的Y平面会有对齐填充，直接用宽度去当成linesize提交纹理，画面会出现竖条纹或半边花屏。正确做法就是老老实实把每个平面的linesize传进SDL_UpdateYUVTexture，让SDL自己去正确处理。
音频侧的SDK接口就简单很多。SDL2打开音频设备后，既不靠回调也不靠事件，直接用SDL_QueueAudio往缓冲区里塞数据即可。打开设备时指定好采样格式、声道数和采样率，FFmpeg重采样得到的S16数据就能直接投喂：
SDL_OpenAudioDevice(NULL, 0, &audio_spec, &obtained, 0); ... SDL_QueueAudio(audio_dev, audio_buf, audio_buf_size);当音频数据填得够快，SDL2内部会自己维护一个播放队列，声音就连续了。这个模式天然的优点是不需要处理音频回调里的复杂数据搬运逻辑，非常适合极简播放器。
5. 音视频同步：极简方案怎么做到“差不多对得上”
5.1 以音频为主时钟
音视频同步有很多流派，极简播放器里最省心且效果最可靠的思路是：音频做主时钟，视频去追音频。原理很简单，人的听觉对声音间断比对画面断层更敏感，所以尽量让音频连续播放，视频按音频的时间点去匹配显示。
那么怎么获得当前播放的音频时间？用SDL2的队列模式时，可以算：
int queued = SDL_GetQueuedAudioSize(audio_dev); double audio_clock = total_samples_played / sample_rate; audio_clock -= (double)queued / (sample_rate * channels * bytes_per_sample);这里的思路是：每次投入音频数据时，记录累积投喂了多少采样数，折算成总播放时长；再减去当前还排队没播完的数据量，就得到当前正在播放的时刻。这个方法不需要SDL2回调，也不需要额外线程，是队列模式下最直接的时钟实现。
5.2 视频帧等待与跳帧
有了音频时钟，视频帧的调度就是用它的pts对应的时间减去当前音频时钟，得到一个差值delta：
- delta > 0，说明视频帧还没到显示时间，那就sleep delta毫秒再显示。
- delta < 0，说明这一帧已经过了播放时间，如果负得不多（比如小于50ms），眼睛不太会察觉，可以照常显示；如果负得太多，就跳过这一帧不渲染，让时间轴快速追上。
这个逻辑翻译成代码就是：
double frame_time = frame_pts_seconds; double delay = frame_time - audio_clock; if (delay > 0.01) { SDL_Delay((Uint32)(delay * 1000)); } else if (delay < -0.05) { // 跳过帧 return; }把这段逻辑放在渲染之前，就实现了最基本的音视频同步。实际播放时，人的感知范围对几十毫秒的误差并不敏感，所以这套方案在绝大多数本地文件上都能达到可接受的效果。
5.3 这个同步方案的短板
这个极简同步方案的短板也很明显。第一，它假设音频设备和音频数据始终正常，如果音频解码跟不上，整个时间轴都会崩；第二，它没有处理视频本身帧率异常变化的问题；第三，对seek操作没有考虑，一旦中途跳转，音频时钟和当前包的时序就会错乱。放在这个笔记项目里这些短板是可以接受的，但如果后续要做播放器的进阶功能，音频时钟的维护方式和帧调度策略就要换成更健壮的模型。
播放结束时还有一个顺序问题。最稳妥的顺序是：先关音频设备（停掉SDL_CloseAudioDevice），再释放渲染器和纹理，然后清理解码上下文，最后关闭输入文件。如果顺序反了，音频设备还在播放已释放的缓冲区，会随机出现崩溃或杂音。
6. 实测踩坑记录：FFmpeg4.1下最容易卡住的几个点
6.1 黑屏且一直没有画面
我在第一次跑通程序时，遇到过解码正常但SDL窗口全黑的问题。检查顺序是：先打印video_frame的宽高和pix_fmt，确实都是解码器输出的有效值；再检查纹理创建参数，发现当时用了一个常量宽高写死，而文件分辨率并不匹配。把宏改成video_codec_ctx->width和video_codec_ctx->height后画面立刻出来了。这个坑提醒我，FFmpeg4.1的AVCodecContext在open2之后，宽高、像素格式等字段才是真正确认后的值，流信息里的codecpar只是参考值。
6.2 画面撕裂和横向条纹
另一个问题是部分视频播放时画面出现横条状的撕裂，看纹理填充数据没有问题，最后发现是linesize和实际宽度的关系。某个测试视频解码出来的linesize[0]比宽度多了一些字节，如果直接把video_frame->width当成linesize传给SDL_UpdateYUVTexture，画面就会错行。这个问题的本质就是前文说的对齐填充。排查方法很简单：打印宽度和三个linesize，凡是两者不等的，就必须老老实实用linesize。
6.3 音频从生硬到卡顿再到顺畅
音频这边也经历过一次卡顿。最初我在主循环里每解码出一帧音频就往SDL队列里塞，本以为队列够大就没问题，但遇到一个采样率48kHz、6声道的高码率文件时，主循环一次塞入的数据量特别大，队列瞬间堆高，系统音频延迟直接到了半秒以上，声音和画面错位严重。后来把重采样目标格式统一为S16、44100Hz、双声道，单帧数据量大大减小，延迟恢复到可接受范围。这个例子也说明了为什么极简播放器也要认真做重采样配置，不只是为了格式一致，更是为了控制音频延迟。
6.4 退出时偶发崩溃
退出时崩溃这个bug让我排查了很久。问题出在音频设备还没关闭、程序主线程也跟着退出，但SDL2内部音频线程还在访问队列。处理方式是主动先把所有音视频帧、Packet都释放干净，再SDL_CloseAudioDevice，等音频线程退出后，再销毁渲染器相关资源。顺序对了之后这个偶发崩溃就再没出现过。
6.5 关于avcodec_send_packet返回EAGAIN的低频情况
FFmpeg4.1上的解码器在正常情况下，send_packet一直返回0，receive_frame返回EAGAIN是很正常的，这代表需要继续喂包。但有些特殊情况（比如部分H.264 B帧较多的文件），send_packet也可能返回EAGAIN，表示内部缓冲满了，需要先调用receive_frame把已解码的帧取出来，再继续送包。由于我的主循环里send_packet只调用了一次，初版代码没处理这种情况，结果某次测试时画面卡在开头几秒不动，排查后才注意到send_packet返回了EAGAIN而事件循环已经跳过了这次数据。稳妥写法是，if返回值小于0且不是EAGAIN，才按异常处理；EAGAIN时下一轮循环继续喂。
7. 从极简到可以落地的下一步：还能往哪里加
这个播放器跑通之后，家禽就很自然地问：如果要在实际项目里用，该加什么。先说最迫切的三个方向。
一是媒体控制能力。暂停本质上是停止读取包和暂停音频时钟更新；seek要处理的事就多了，得调用avformat_seek_file，清空解码器内部缓冲（avcodec_flush_buffers），还要重置音频时钟和SDL队列。倍速播放则要在重采样环节调整采样数，或者在时间调度上按比例压缩参考时钟，无论哪种思路都会牵扯到同步逻辑。二是硬解加速。FFmpeg4.1的h264_cuvid、hevc_cuvid等硬件解码器可以在avcodec_find_decoder之前通过av_hwdevice_ctx_create来配置，但CPU回调的YUV数据很可能要经过hwupload/hwdownload的拷出，纹理填充方式也需要适配硬件帧。三是滤镜链。如果你想做旋转、裁剪、加字幕、加滤镜，需要在解码和渲染之间插入avfilter_graph，这是FFmpeg工程里最庞大的模块之一，极简播放器作为骨架正好可以给它预留一个扩展点。
在个人学习路径上，这个项目最大的收获不是代码量本身，而是真正建立了“一帧数据从文件到屏幕上那个像素”的完整流程观念。以后再去看各种播放器源码，或者写其他语言绑定时，脑子里始终有一个清晰的骨架在，哪些地方是FFmpeg管的，哪些地方是SDL2管的，出了问题也知道先去查哪一段。
如果笔记看到这里的读者也想自己动手写一版，我最后的建议是：不要一上来就追求把暂停、进度条这些全部做成。先把这篇文章里的五步链路调通，确保本地各类常见格式（mp4、mov、mkv）都能正常播放且同步可接受，然后再挑一个方向去扩展。播放器这种项目，真正的难点永远不在某个API怎么调，而在于你愿不愿意把每个异常情况都按“数据是从哪里来、到哪里去、中间谁在排队”的思路去追根究底。你把这个思路练顺了，FFmpeg版本往后怎么升级，其实都只是换个别名而已。
