1. 项目概述与核心价值在音视频开发领域尤其是Windows平台下的C应用开发直接调用FFmpeg库进行H.264或H.265HEVC编码是一个既基础又核心的技能点。很多开发者可能熟悉使用FFmpeg命令行工具进行转码但一旦需要将编码功能深度集成到自己的桌面应用、录屏软件、直播推流客户端或视频处理工具中时命令行调用就显得笨重且不灵活。这时直接使用FFmpeg的C API进行编程调用就成了必由之路。然而FFmpeg的API体系庞大初次接触时光是理清编码器的初始化、数据送显、参数配置这一套流程就足以让人望而却步更别提其中各种结构体字段的含义和内存管理的坑了。这个项目标题“Windows C 使用FFmpeg进行H264/H265编码调用流程介绍有源码”直击了众多C开发者在Windows环境下进行音视频编码集成时的痛点。它承诺的不仅仅是一个概念介绍而是一个带有源码的、可操作的流程指南。这意味着读者期望看到的是一个从零开始、步骤清晰、能编译运行的完整示例而不仅仅是支离破碎的代码片段。核心价值在于“降本增效”降低学习FFmpeg编码API的认知成本提升在Windows C项目中集成高效视频编码的开发效率。无论是为了开发一款简单的桌面录像机还是为一个复杂的视频编辑软件添加导出功能掌握这套流程都是关键一步。2. 环境准备与FFmpeg库集成在Windows上使用C调用FFmpeg第一步也是最容易踩坑的一步就是环境的搭建和库的集成。这里的选择和配置直接决定了后续编码的稳定性和性能。2.1 选择FFmpeg开发包FFmpeg官方并不提供预编译的、方便开发使用的Windows SDK。通常我们有以下几个选择自行编译从FFmpeg官网下载源码在MSYS2或Visual Studio的命令行环境下配置、编译。这是最灵活的方式可以精确控制需要的编解码器、滤镜等模块并生成针对特定CPU指令集如AVX2优化的库。但对于新手或追求快速上手的项目来说编译过程复杂耗时较长。使用第三方预编译包这是最推荐给大多数开发者的方式。网络上一些社区或个人维护者会提供编译好的、包含开发文件.lib, .dll, .h的包。例如gyan.dev这个网站提供的“Release Builds”就非常知名和可靠。它通常提供两种版本Shared动态链接库版本。你的程序运行时需要依赖对应的.dll文件。部署时需将dll与exe放在一起或加入系统路径。Dev静态链接库版本。将FFmpeg代码直接链接进你的可执行文件生成单个exe部署简单但文件体积较大。对于本项目的编码示例我推荐从gyan.dev下载“Essentials”版本的dev开发和shared运行时包。Essentials版本包含了最常用的编解码器和格式足以满足H.264/H.265编码需求。2.2 Visual Studio项目配置假设我们使用Visual Studio 2019或2022。创建一个新的“控制台应用”或“空项目”后需要进行如下配置以x64平台为例包含目录在项目属性 - C/C - 常规 - 附加包含目录中添加FFmpeg开发包的include文件夹路径。例如D:\ffmpeg\include。库目录在项目属性 - 链接器 - 常规 - 附加库目录中添加FFmpeg开发包的lib文件夹路径。例如D:\ffmpeg\lib。附加依赖项在项目属性 - 链接器 - 输入 - 附加依赖项中添加需要链接的库文件。对于视频编码通常需要avcodec.lib avformat.lib avutil.lib swscale.libavcodec是编解码核心avformat用于封装虽然纯编码到裸流可能不需要但好习惯是加上avutil是工具库swscale用于像素格式转换。运行时库确保C/C - 代码生成 - 运行库设置与FFmpeg库的编译选项匹配。通常预编译的FFmpeg库使用/MD或/MDd多线程DLL因此你的项目也应设置为“多线程DLL (/MD)”或“多线程调试DLL (/MDd)”。不匹配会导致链接错误。字符集FFmpeg API使用UTF-8而Windows API常使用宽字符。在项目属性 - 高级 - 字符集中建议设置为“使用多字节字符集”或处理好字符串转换。更现代的做法是全程使用UTF-8并在链接器-命令行中添加/utf-8选项。注意将FFmpeg的bin目录包含所有.dll文件添加到系统的PATH环境变量或者在调试时将bin目录下的所有dll复制到你的项目输出目录如x64\Debug。否则程序运行时将因找不到动态库而崩溃。2.3 第一个测试验证链接配置完成后可以写一个最简单的程序来测试环境是否搭建成功。#include iostream extern C { #include libavcodec/avcodec.h #include libavutil/avutil.h } int main() { std::cout FFmpeg version: av_version_info() std::endl; std::cout Configuration: avcodec_configuration() std::endl; return 0; }如果能够成功编译并运行输出FFmpeg的版本和编译配置信息那么恭喜你最艰难的一步已经跨过。3. H.264/H.265编码核心流程拆解抛开复杂的封装、音视频同步等问题一个最基础的视频编码流程可以抽象为以下几个核心步骤它们构成了编码器调用的骨架。理解这个骨架比一开始就陷入某个API的细节更重要。3.1 流程总览与数据结构整个编码过程围绕着几个核心的FFmpeg结构体展开AVCodec代表一种编解码器如libx264, libx265, h264_nvenc。它像是一个“编解码器类”描述了编解码器的能力和属性。AVCodecContext编解码器上下文。这是核心中的核心它承载了一次编解码会话所需的所有状态信息、参数配置。你可以把它理解为一个“编解码器实例”。AVFrame存储原始未压缩的音频或视频数据。对于视频它包含像素数据data数组、行大小linesize、宽高、像素格式等。AVPacket存储压缩后的编码数据。一个AVPacket可能包含一帧、多帧或一帧的一部分数据。编码流程的伪代码描述如下1. 查找编码器 (avcodec_find_encoder_by_name) 2. 创建编码器上下文 (avcodec_alloc_context3) 3. 配置上下文参数 (设置宽、高、像素格式、码率、帧率等) 4. 打开编码器 (avcodec_open2) 5. 循环 a. 准备或获取一帧原始图像数据 (AVFrame) b. 可能需要进行像素格式转换 (sws_scale) c. 发送帧到编码器 (avcodec_send_frame) d. 循环接收编码后的包 (avcodec_receive_packet) e. 处理包写入文件、发送网络等 6. 刷新编码器发送NULL帧接收剩余包 7. 清理资源3.2 新旧API与关键选择FFmpeg的编码API经历了演变。旧式的avcodec_encode_video2等函数已被标记为废弃。我们必须使用新的“send/receive” API即avcodec_send_frame()和avcodec_receive_packet()。这套API设计更清晰支持更复杂的编码模式如延迟输出、B帧是现代FFmpeg编程的标准。另一个关键选择是编码器后端。对于H.264libx264最流行、最强大的软件编码器质量高参数可调性强但CPU占用也高。h264_nvenc/h264_amf/h264_qsv利用NVIDIA、AMD、Intel显卡的硬件编码器速度极快CPU占用低但同等码率下质量通常略低于libx264且某些高级参数可能不受支持。对于H.265HEVC同理有libx265,hevc_nvenc,hevc_amf,hevc_qsv。选择哪种取决于你的应用场景追求极限质量选软件编码追求性能、低延迟或低功耗选硬件编码。我们的示例将主要以libx264为例因为它的软件实现具有普遍性。4. 编码器初始化与参数配置详解有了流程骨架我们开始填充血肉。初始化阶段是编码质量的奠基阶段参数配置不当会导致编码效率低下或输出不符合预期。4.1 查找与创建编码器上下文#include iostream extern C { #include libavcodec/avcodec.h #include libavutil/opt.h #include libavutil/imgutils.h } int main() { const char* codec_name libx264; // 或 libx265, h264_nvenc const AVCodec* codec avcodec_find_encoder_by_name(codec_name); if (!codec) { std::cerr Codec codec_name not found. std::endl; return -1; } AVCodecContext* codec_ctx avcodec_alloc_context3(codec); if (!codec_ctx) { std::cerr Could not allocate video codec context. std::endl; return -1; } // ... 后续配置 }这里通过编码器名称查找。也可以使用avcodec_find_encoder(AV_CODEC_ID_H264)但通过名称查找更精确特别是当有多个编码器支持同一种编码ID时如多个H.264编码器。4.2 核心参数配置配置AVCodecContext是重中之重。以下是一些必须设置和常用的参数// 1. 基础流参数 codec_ctx-width 1920; // 图像宽度 codec_ctx-height 1080; // 图像高度 codec_ctx-time_base (AVRational){1, 25}; // 时间基这里表示帧率是25fps (1/25秒每帧) codec_ctx-framerate (AVRational){25, 1}; // 帧率与time_base互为倒数 codec_ctx-pix_fmt AV_PIX_FMT_YUV420P; // 编码器期望的输入像素格式。libx264最常用YUV420P。 // 2. 码率控制参数 codec_ctx-bit_rate 4000000; // 目标平均码率单位比特/秒 (4 Mbps) // 码率控制模式CRF恒定质量是x264/x265最常用的质量优先模式 av_opt_set(codec_ctx-priv_data, crf, 23, 0); // CRF值范围0-51越小质量越高23是默认值 av_opt_set(codec_ctx-priv_data, preset, medium, 0); // 编码速度预设从ultrafast到veryslow越慢压缩率越高 // 3. 其他重要参数 codec_ctx-gop_size 250; // 关键帧I帧间隔。250表示每250帧一个I帧。 codec_ctx-max_b_frames 2; // 最大连续B帧数。B帧能提高压缩率但增加解码延迟。 codec_ctx-profile FF_PROFILE_H264_HIGH; // 编码档次如baseline, main, high。影响兼容性和特性。 codec_ctx-level 42; // 编码级别与分辨率、帧率、码率约束有关。4.2对应1080p25fps常用级别。 // 对于H.265profile和level不同 // codec_ctx-profile FF_PROFILE_HEVC_MAIN; // codec_ctx-level 120; // 级别值计算方式与H.264不同参数配置心得time_base和framerate务必设置正确且逻辑一致。time_base是编码器内部的时间刻度framerate是流信息。通常设置time_base 1/framerate。编码输出的AVPacket的pts显示时间戳和dts解码时间戳都是以time_base为单位的。pix_fmt编码器通常只接受特定的像素格式。libx264最常用AV_PIX_FMT_YUV420P。如果你的原始数据是RGB或别的格式必须用libswscale转换。CRF vs ABRcrf恒定速率因子是质量恒定模式在达到指定视觉质量的前提下尽可能降低码率是离线编码的首选。bit_rate平均比特率是码率恒定模式适合流媒体等有带宽限制的场景。两者通常只设一个。通过av_opt_set设置编码器私有参数priv_data是配置x264/x265特定选项的标准方式。preset这是x264/x265最重要的性能/质量权衡参数。ultrafast编码最快但压缩率低文件大veryslow编码极慢但压缩率高文件小。项目开发调试阶段可以用veryfast或faster最终输出再用slow或slower。4.3 打开编码器与创建AVFrame配置完成后就可以打开编码器并准备存放原始帧的AVFrame了。// 打开编码器 if (avcodec_open2(codec_ctx, codec, nullptr) 0) { std::cerr Could not open codec. std::endl; avcodec_free_context(codec_ctx); return -1; } // 创建用于存放原始YUV数据的AVFrame AVFrame* frame av_frame_alloc(); if (!frame) { std::cerr Could not allocate video frame. std::endl; avcodec_free_context(codec_ctx); return -1; } frame-format codec_ctx-pix_fmt; frame-width codec_ctx-width; frame-height codec_ctx-height; // 为frame的数据缓冲区分配内存 if (av_frame_get_buffer(frame, 0) 0) { std::cerr Could not allocate the video frame data. std::endl; av_frame_free(frame); avcodec_free_context(codec_ctx); return -1; }av_frame_get_buffer会根据frame的格式、宽高为其data数组和linesize数组分配合适的内存。对于YUV420Pdata[0]指向Y分量data[1]指向U分量data[2]指向V分量。linesize[0]是Y分量的行字节数通常等于宽度可能有对齐填充linesize[1]和linesize[2]是UV分量的行字节数通常是宽度的一半。5. 数据送显、编码与输出实战初始化工作完成后就进入了主循环不断地准备原始帧送入编码器然后取出编码后的数据包。这里我们模拟生成一个简单的YUV渐变图像进行编码。5.1 生成测试图像与像素格式转换在实际项目中你的原始帧可能来自屏幕采集如DXGI、摄像头如Media Foundation、图像文件解码或OpenGL渲染。这里我们手动生成一个从黑到白的水平渐变YUV图像。// 假设这是我们的“获取一帧原始数据”函数 void fill_yuv_image(AVFrame* frame, int frame_index) { int width frame-width; int height frame-height; // 填充Y分量亮度 for (int y 0; y height; y) { for (int x 0; x width; x) { // 简单的水平渐变从黑(0)到白(255) frame-data[0][y * frame-linesize[0] x] (x * 256) / width; } } // 填充U和V分量色度YUV420P中UV的宽高是Y的一半 for (int y 0; y height / 2; y) { for (int x 0; x width / 2; x) { // 这里我们给一个固定的色度值产生一个偏青色的色调 frame-data[1][y * frame-linesize[1] x] 128; // U frame-data[2][y * frame-linesize[2] x] 64; // V } } }重要提醒如果你的源数据不是YUV420P比如是常见的RGB24来自GDI或BGRA来自DirectX必须使用libswscale进行转换。忽略这一步会导致编码器接收错误数据输出花屏或崩溃。#include libswscale/swscale.h // 创建SwsContext用于转换 SwsContext* sws_ctx sws_getContext( src_width, src_height, src_pix_fmt, // 源宽高及格式如AV_PIX_FMT_BGRA dst_width, dst_height, dst_pix_fmt, // 目标宽高及格式即codec_ctx-pix_fmt SWS_BILINEAR, // 缩放算法 nullptr, nullptr, nullptr ); // 在循环中转换 sws_scale(sws_ctx, src_frame-data, src_frame-linesize, 0, src_height, dst_frame-data, dst_frame-linesize); // 循环结束后销毁 sws_freeContext(sws_ctx);5.2 核心编码循环Send与Receive这是编码流程的心脏。avcodec_send_frame和avcodec_receive_packet的调用需要遵循特定的模式。AVPacket* pkt av_packet_alloc(); if (!pkt) { // 错误处理 } int total_frames 250; // 编码帧数例如一个10秒的25fps视频 for (int i 0; i total_frames; i) { // 1. 准备当前帧 // 确保frame是可写的。对于复用同一个frame的情况可能需要av_frame_make_writable // 这里我们每次生成新的图像内容 fill_yuv_image(frame, i); frame-pts i; // 设置显示时间戳以time_base为单位 // 2. 发送帧到编码器 int ret avcodec_send_frame(codec_ctx, frame); if (ret 0) { std::cerr Error sending a frame for encoding. std::endl; break; } // 3. 循环接收所有可能的编码包 while (ret 0) { ret avcodec_receive_packet(codec_ctx, pkt); if (ret AVERROR(EAGAIN) || ret AVERROR_EOF) { // EAGAIN: 编码器需要更多输入才能产生输出跳出接收循环继续送下一帧 // EOF: 编码器已刷新没有更多输出 break; } else if (ret 0) { // 真正的错误 std::cerr Error during encoding. std::endl; break; } // 成功收到一个编码后的AVPacket std::cout Packet encoded! pts pkt-pts , dts pkt-dts , size pkt-size bytes std::endl; // 4. 处理pkt写入H.264裸流文件(.h264)或进行其他操作 // 例如fwrite(pkt-data, 1, pkt-size, output_file); // 注意裸流文件通常无法被某些播放器直接播放可能需要封装成MP4等格式 av_packet_unref(pkt); // 释放当前packet内部资源以便复用 } }编码循环逻辑解读发送帧avcodec_send_frame将一帧原始数据送入编码器。可以送入NULL这用于刷新编码器告诉编码器没有更多输入了请输出所有缓存的帧。接收包循环发送一帧后需要用一个循环来接收编码器可能输出的所有AVPacket。为什么是循环因为编码器可能因为B帧、延迟输出等原因在送入一帧后并不立即输出对应包或者可能一次输出多个包如SEI信息。返回值处理AVERROR(EAGAIN)编码器说“我收到了输入但我现在没有包可以输出要么给我更多输入要么等我一下延迟”。这时应跳出接收循环继续送下一帧或等待。AVERROR_EOF编码器已被刷新发送了NULL帧并且所有数据都已输出。编码结束。负值且非EAGAIN/EOF发生错误。0成功收到一个包处理它。5.3 刷新编码器与写入文件编码循环结束后编码器内部可能还缓存着一些帧比如最后一组GOP的B帧。需要发送一个NULL帧来刷新编码器。// 刷新编码器送入NULL帧 avcodec_send_frame(codec_ctx, nullptr); while (true) { int ret avcodec_receive_packet(codec_ctx, pkt); if (ret AVERROR_EOF) { // 编码器已被完全刷新所有数据已取出 break; } else if (ret 0) { // 错误处理 break; } // 处理最后的这些包 // fwrite(pkt-data, 1, pkt-size, output_file); av_packet_unref(pkt); }文件写入注意直接将pkt-data写入文件得到的是H.264/H.265的“裸流”Annex B格式通常以00 00 00 01或00 00 01的起始码分隔NALU。这种文件扩展名可以是.h264或.hevc。虽然VLC等播放器可以播放但很多播放器和编辑软件需要标准的容器格式如MP4、MKV。要将编码后的包写入容器需要使用libavformat来创建输出上下文、流并正确写入包包括设置正确的pts,dts,stream_index等这比写裸流复杂得多是另一个重要主题。6. 资源管理与内存泄漏防范FFmpeg API需要手动管理内存不当使用极易导致内存泄漏。必须遵循“谁分配谁释放”的原则并使用正确的释放函数。6.1 核心对象的分配与释放对象分配函数释放函数说明AVCodecContextavcodec_alloc_context3()avcodec_free_context(ctx)释放上下文及其内部所有资源。AVFrameav_frame_alloc()av_frame_free(frame)释放帧结构体及其数据缓冲区如果引用计数为0。AVPacketav_packet_alloc()av_packet_free(pkt)分配包结构。注意av_packet_unref()是减少引用计数不直接释放结构体本身。SwsContextsws_getContext()sws_freeContext(sws_ctx)图像缩放转换上下文。释放顺序通常建议先释放依赖其他对象资源的对象。例如先av_packet_free和av_frame_free最后再avcodec_free_context。但更关键的是确保在释放上下文前不再引用任何由其内部分配的资源如AVFrame的缓冲区。6.2 引用计数与av_packet_unref这是新手最容易出错的地方。AVPacket和AVFrame使用了引用计数机制。av_packet_alloc()创建一个新的包其data和buf通常为NULL。当编码器通过avcodec_receive_packet填充一个包时包内部会持有一个AVBufferRef该缓冲区实际存储编码数据。av_packet_unref(pkt)的作用是减少这个内部缓冲区的引用计数。当引用计数减到0时缓冲区内存会被自动释放同时将pkt-data置为NULLpkt-size置为0。但它不会释放pkt这个结构体本身。在编码循环中我们复用同一个AVPacket* pkt。每次avcodec_receive_packet成功后处理完数据必须立即调用av_packet_unref(pkt)这样编码器在下次填充数据时才能安全地重用或分配新的缓冲区。如果不调用会导致内存泄漏因为旧的缓冲区永远不会被释放。循环结束后调用av_packet_free(pkt)来释放AVPacket结构体本身。AVFrame也有类似的av_frame_unref()函数如果你在循环中复用AVFrame在填充新数据前可能需要调用它或av_frame_make_writable()。7. 常见问题、调试技巧与进阶提示即使流程正确在实际编码中也会遇到各种问题。这里记录一些典型的坑和解决思路。7.1 编码输出花屏、绿屏或错乱首要怀疑对象像素格式不匹配。99%的此类问题源于输入给编码器的AVFrame的像素格式 (pix_fmt)、宽度、高度或行对齐 (linesize) 与编码器上下文 (AVCodecContext) 的配置不符或者与编码器实际期望的不符。务必确认codec_ctx-pix_fmt设置正确。你填充数据的AVFrame其format、width、height与codec_ctx一致。如果你使用了sws_scale转换确保源和目标的参数正确并且转换后的frame-linesize是符合编码器预期的通常编码器能处理一定的行对齐但最好保持一致。检查数据填充手动生成的YUV数据是否越界linesize是步长可能大于宽度。填充时索引应为y * frame-linesize[plane] x。检查颜色空间和范围对于x264有时需要明确设置色彩参数特别是从某些硬件或渲染器获取数据时。codec_ctx-color_range AVCOL_RANGE_JPEG; // 或 AVCOL_RANGE_MPEG codec_ctx-colorspace AVCOL_SPC_BT709; codec_ctx-color_primaries AVCOL_PRI_BT709; codec_ctx-color_trc AVCOL_TRC_BT709;7.2 编码速度慢或CPU占用高调整preset这是最有效的杠杆。从medium调到faster或fast能显著提升编码速度代价是压缩率降低文件变大或同等码率下质量稍差。检查分辨率编码复杂度随分辨率平方增长。1080p比720p慢得多。B帧数量max_b_frames设为0可以降低复杂度减少编码延迟但也会降低压缩率。参考帧数量x264的refs参数可通过av_opt_set设置也影响速度和质量。考虑硬件编码如果速度是首要考量且质量要求可接受切换到h264_nvenc、h264_qsv等硬件编码器是终极方案。初始化流程类似但某些参数如preset的值可能不同需要查阅对应编码器的文档。7.3 编码器无法打开或参数无效检查编码器支持确保你请求的像素格式、profile、level等参数被编码器支持。可以在打开编码器前使用avcodec_find_encoder_by_name找到编码器后打印codec-pix_fmts等数组来查看支持列表。私有参数设置错误通过av_opt_set设置的字符串参数如preset,tune必须是编码器认可的合法值。拼写错误会导致打开失败。Level 和 Resolution 不匹配例如将1080p视频的level设为3.0最高支持720p会导致问题。确保level值符合所选分辨率、帧率和码率的约束。7.4 时间戳PTS/DTS问题如果将来要把编码包写入容器如MP4正确设置AVPacket的pts和dts至关重要。在我们的简单示例中编码器会根据输入的AVFrame::pts自动生成输出包的pts和dts。但你需要理解PTS显示时间戳这一帧应该什么时候被显示。DTS解码时间戳这一帧应该什么时候被解码。由于B帧需要依赖后续的帧来解码所以DTS顺序可能与PTS顺序不同。Timebase时间戳的单位。codec_ctx-time_base定义了编码流的时间基。例如(1, 25)表示每个单位是1/25秒。pts2就表示2 * 1/25 0.08秒。初始PTS通常第一帧的PTS从0开始。但有些场景如直播流拼接可能需要从非0开始。7.5 从简单示例到生产代码本例为了清晰将编码后的裸流包直接打印或写入文件。一个更实用的程序可能需要封装入容器集成libavformat创建AVFormatContext添加视频流将编码后的AVPacket写入MP4/MKV等文件。这涉及到复用器muxer的使用。处理音频实现音频编码并与视频流交错写入容器实现音视频同步。更健壮的错误处理检查每个API调用的返回值提供更详细的错误信息可用av_err2str(ret)将错误码转为字符串。性能优化使用多线程编码设置codec_ctx-thread_count、零拷贝机制如hwaccel、或环形缓冲区来解耦图像采集和编码线程。动态参数根据网络状况或CPU负载动态调整码率ABR或CRF。将这段简单的编码流程掌握牢固就像是学会了音视频编程的“Hello World”。它为你打开了利用代码操控视频数据的大门无论是向后深入封装、滤镜、硬编解码还是向前拓展到网络流媒体、实时通信都有了坚实的起点。在实际编码调试中多使用av_log_set_level(AV_LOG_DEBUG)开启FFmpeg的调试日志它能提供大量内部状态信息是解决问题的利器。