简介:面向QT C++开发者,提供基于FFmpeg调用USB摄像头并实现H264编码录制的完整示例工程。内容聚焦于摄像头采集、实时预览、多线程处理与编码输出MP4的完整链路,适合具备一定C++基础、希望快速掌握FFmpeg集成的开发者。压缩包共1152个文件,总大小约111MB,包含15个cpp源码、322个h头文件、20个lib及16个a静态库、108个dll、21个so动态库、4个exe可执行程序,以及大量png位图和bmp图片资源,覆盖编译依赖、界面素材与运行环境。目前已吸引1125人学习下载。借助这套压缩包可以拿到可直接参考的QT工程配置、FFmpeg调用示例和编码器连接方案,结合实际代码梳理avformat_open_input、libx264编码、QThread视频线程等关键步骤,有助于在真实项目中快速搭建摄像头显示与H264录像模块。 最近在做一个桌面工具,需求很直白:电脑上插几个USB摄像头,程序里要能实时显示画面,还得一键开始录像,输出H264编码的MP4文件。技术栈选了Qt C++,视频处理交给FFmpeg,这个组合在Windows和Linux上都能跑,而且不依赖系统专有API,通用性比直接用DirectShow或MediaFoundation好太多。整套流程跑通后,画面实时预览、录制、停止、再录一段,全部顺利,今天把这段实操经验完整记录下来,给准备入坑的朋友一个参考。
1. 整体架构与方案选型
1.1 为什么是Qt C++ + FFmpeg,而不是其他组合
USB摄像头采集这一块,解决方案其实不少:OpenCV的VideoCapture、Qt Multimedia的QCamera、纯Windows下的DirectShow,都能做。但我最终选了FFmpeg作为采集和编码的核心,原因有三。
第一,FFmpeg对USB摄像头的兼容性最广。USB摄像头在Windows下走的是UVC协议,通过DirectShow暴露采集接口,在Linux下走的是V4L2驱动。FFmpeg把这两套底层封装成了统一的API,avformat_open_input打开设备文件,av_read_frame读数据帧,上层代码几乎不用关心系统差异。换到树莓派或嵌入式Linux板子上,代码改个设备名就能跑。
第二,录制环节是FFmpeg的强项。H264编码、MP4封装、时间戳处理、音视频交错写入,这些如果用微软Media Foundation或DirectShow的录制管线去写,光初始化一批COM接口就要命了,而且网上的资料翻来覆去就那几篇。FFmpeg的libavcodec和libavformat一把梭,编码器、容器、重采样全都有,省心。
第三,Qt在这里的角色很纯粹:做UI界面和画面显示。Qt的跨平台窗口、事件循环、信号槽机制非常成熟,配合FFmpeg的工作线程,不会互相干扰。
1.2 核心模块划分与数据流
整个程序的逻辑可以拆成三个模块:采集模块、编码录制模块、显示模块。它们之间是生产者-消费者的关系。
采集线程(FFmpeg读帧) → 原始帧数据(YUV/NV12) → 显示线程(转换RGB,QImage刷新)
↓
编码线程(H264编码,写MP4)
采集线程负责从摄像头读原始帧,一帧大约几MB(以720p YUYV为例,一帧是1280×720×2 ≈ 1.8MB)。显示线程拿到后做像素格式转换,转成RGB32再显示。编码线程独立跑,做H264编码并写MP4文件。
这个结构的关键是:采集和编码分开线程处理,否则UI会一卡一卡的。桌面摄像头的采集速率一般是30fps,也就是说每33毫秒就有一帧数据过来,如果UI线程里同步做格式转换和编码,处理器忙不过来,界面刷新就掉帧了。
实际操作中我用了一个简单的帧队列,采集线程把帧投进队列,显示线程和编码线程各自从队列取帧。队列要设上限(比如5帧),满了就丢最老的帧,保证实时性,不让内存无限增长。
2. 环境准备与关键依赖
2.1 Qt版本、编译器与FFmpeg库的匹配
先说环境,这步踩坑最多。我开发环境是Windows 10 + Qt 5.15.2 + MSVC2019 64位 + FFmpeg 4.4。如果按这个组合走,基本顺滑。特别提醒一点:编译器和FFmpeg的位数必须一致,64位Qt配64位FFmpeg,32位就配32位,混着用链接阶段会报一堆LNK2019。
Qt安装时选MSVC编译器套件,不要选MinGW,因为社区编译的FFmpeg二进制基本都是MSVC或MinGW适配套,混用会导致符号名不匹配,链接报错。如果你非要MinGW,那就得自己用MSYS2编译FFmpeg了,折腾时间多半天不止,不划算。
FFmpeg的获取方式,推荐直接到官方release页面下载已编译好的shared版本,包含dll和头文件。要确认下载的是dev版本(头文件和lib)还是shared版本(dll和exe),两个都得下,解压后目录结构如下:
ffmpeg-4.4-full_build/
├── bin/
│ ├── avcodec-58.dll
│ ├── avformat-58.dll
│ ├── avutil-56.dll
│ └── ...
├── include/
│ ├── libavcodec/
│ ├── libavformat/
│ └── ...
└── lib/
├── avcodec.lib
├── avformat.lib
└── ...
在Qt .pro文件里配置头文件和库路径,大概这样:
INCLUDEPATH += $$PWD/ffmpeg/include
LIBS += -L$$PWD/ffmpeg/lib \
-lavcodec \
-lavformat \
-lavutil \
-lswscale \
-lswresample
记得把ffmpeg/bin目录下的dll复制到程序运行目录,或者直接加到系统PATH,否则程序启动会报找不到avcodec-58.dll,新手在这里卡住的不在少数。
2.2 确认摄像头支持的格式与分辨率
这个步骤容易被忽略,但直接影响后续代码。不同型号的USB摄像头支持的像素格式和分辨率列表不一样,有的支持YUYV,有的支持MJPEG,分辨率可能是320×240、640×480、1280×720甚至1920×1080。
可以在命令行用FFmpeg工具直接查看:
ffmpeg -list_devices true -f dshow -i dummy
ffmpeg -list_options true -f dshow -i video="USB Camera"
Windows下用dshow,Linux下用v4l2:
v4l2-ctl --list-formats-ext -d /dev/video0
我的摄像头采集出来的原始格式是YUYV,720p@30fps。如果摄像头支持MJPEG,最好优先选MJPEG,因为它的数据量是压缩过的,总线传输压力小,CPU占用也低。但MJPEG帧解码需要额外挂mjpeg解码器,编码链路多一环。我在本例中使用YUYV作为输入,走的是多数USB摄像头的默认路径。
3. 摄像头采集与实时显示实现
3.1 打开设备、探测视频流参数
FFmpeg把摄像头抽象成一个输入设备,所以打开摄像头跟打开一个视频文件在API层面是一样的。代码核心逻辑如下:
AVFormatContext* fmtCtx = nullptr;
AVInputFormat* inputFmt = av_find_input_format("dshow");
// Linux下用 v4l2 代替 dshow,inputFmt = av_find_input_format("v4l2");
AVDictionary* options = nullptr;
av_dict_set(&options, "framerate", "30", 0);
av_dict_set(&options, "video_size", "1280x720", 0);
CString deviceName = "video=USB Camera"; // Windows dshow 的设备名带 video= 前缀
int ret = avformat_open_input(&fmtCtx, deviceName, inputFmt, &options);
if (ret != 0) {
// 设备被占用或不存在,走错误处理
}
ret = avformat_find_stream_info(fmtCtx, nullptr);
// 遍历 stream,找到 AVMEDIA_TYPE_VIDEO 的索引
这里有个细节:DShow设备名是 video=摄像头名称 ,在avformat_open_input里作为url传入,格式固定,不能写错。Linux下就是 /dev/video0 ,直接传路径就行。
打开设备后,从 fmtCtx->streams[videoIndex]->codecpar 里可以拿到宽高、像素格式、帧率这些参数,后面编码器和sws_scale都要用。
3.2 像素格式转换与QImage显示
摄像头输出的YUYV格式(属于YUV422)没法直接在Qt的QImage里显示,QImage支持的格式是RGB32、RGB565这些。所以每帧数据必须用FFmpeg的sws_scale转成RGB32再显示。转换上下文创建一次,后面每帧复用:
SwsContext* swsCtx = sws_getContext(
srcWidth, srcHeight, AV_PIX_FMT_YUYV422,
srcWidth, srcHeight, AV_PIX_FMT_RGB32,
SWS_BILINEAR, nullptr, nullptr, nullptr);
显示刷新我用了QTimer驱动,定时器间隔设成1/帧率,比如30fps就是33ms。每次定时器触发,从帧队列里取最新一帧,转换成QImage,再让QLabel刷新:
QImage img(rgbBuffer, width, height, QImage::Format_RGB32);
ui->label->setPixmap(QPixmap::fromImage(img));
这里有个坑:QImage构造时,如果你之前用的是AVFrame的linesize,而QImage构造时没传bytesPerLine,或者传错了,图像会歪斜、颜色诡异。同一个分辨率,AVFrame的内存对齐(默认32字节对齐)跟QImage期望的可能不一致。正确做法是让QImage用AVFrame的linesize作为bytesPerLine:
QImage img(frame->data[0], width, height, frame->linesize[0], QImage::Format_RGB32);
或者是sws_scale转出来以后,自己分配一个干净的RGB缓冲区,用width×4作为行字节数。两种都行,但一定不要混。
3.3 显示画面偏绿或偏色的定位思路
如果图像显示出来偏绿、颜色发紫或者画面上下颠倒,优先检查三件事:设备输出的原始像素格式是否跟sws_getContext设置一致;转换后QImage的Format和bytesPerLine是否匹配;有没有做垂直翻转。多数USB摄像头输出的像素排列是自下而上的(bottom-first),发现上下颠倒后,给sws_scale传一个 srcSliceH 为负数的参数,或者直接对图做 mirrored(false, true) 翻转即可。这个问题在OpenCV里很常见,在FFmpeg里同理。
4. H264编码与MP4录制实现
4.1 编码器初始化与参数选择
录制部分,我用libx264做H264编码。选择x264而不是硬件编码器(如Intel QSV、NVIDIA NVENC),看重的是它普适性最强,任何电脑都能软编,不依赖显卡,方便移植。当然,有硬件编码器的话可以后边再优化。
先创建编码器上下文:
const AVCodec* codec = avcodec_find_encoder_by_name("libx264");
AVCodecContext* encCtx = avcodec_alloc_context3(codec);
encCtx->width = 1280;
encCtx->height = 720;
encCtx->time_base = {1, 30};
encCtx->framerate = {30, 1};
encCtx->pix_fmt = AV_PIX_FMT_YUV420P;
encCtx->codec_type = AVMEDIA_TYPE_VIDEO;
AVDictionary* encOpts = nullptr;
av_dict_set(&encOpts, "preset", "veryfast", 0);
av_dict_set(&encOpts, "tune", "zerolatency", 0);
av_dict_set(&encOpts, "profile", "high", 0);
码率这里我给的是2Mbps。720p@30fps的画面,一般1.5Mbps到4Mbps之间都能接受。经验值是:
| 分辨率 | 帧率 | 建议码率 |
|---|---|---|
| 640×480 | 30 | 500Kbps ~ 1Mbps |
| 1280×720 | 30 | 1.5Mbps ~ 4Mbps |
| 1920×1080 | 30 | 3Mbps ~ 8Mbps |
摄像头画面相对静态(桌面摄像头场景),2Mbps输出质量已经很好了。要是运动很多,比如对着车间流水线拍,码率得往上提,不然有块效应。
preset=veryfast 是编码速度和压缩率的折中,录制场景推荐。 tune=zerolatency 比较关键,它告诉x264尽量别缓存帧,降低端到端延迟,直播和实时录制都有用。GOP设置我给了60,也就是2秒一个关键帧:
encCtx->gop_size = 60;
encCtx->max_b_frames = 2;
B帧这里要注意,它影响延迟,也影响播放器seek的准确性。录完后用剪辑软件逐帧拖,B帧太多会让时间线定位不精准。录制推荐 max_b_frames = 0 ,也就是纯IP帧序列,代价是文件大一些,但编辑体验好很多。
4.2 初始化输出文件(MP4容器)
MP4封装要先把上下文建好,再往里面添加视频流:
AVFormatContext* outCtx = nullptr;
avformat_alloc_output_context2(&outCtx, nullptr, "mp4", "recording.mp4");
AVStream* outStream = avformat_new_stream(outCtx, nullptr);
avcodec_parameters_from_context(outStream->codecpar, encCtx);
outStream->time_base = encCtx->time_base;
ret = avio_open(&outCtx->pb, "recording.mp4", AVIO_FLAG_WRITE);
ret = avformat_write_header(outCtx, nullptr);
有一点必须强调:MP4的 moov 原子在文件末尾,如果不正常调 av_write_trailer ,文件可能损坏甚至打不开。所以程序退出或录制停止时,一定要记得调 av_write_trailer ,否则前面写的一大堆数据全都白搭。
4.3 编码录制主循环
采集的每一帧要喂给编码器,然后把编码器输出的packet写到MP4。核心逻辑:
AVFrame* frame = av_frame_alloc();
frame->format = encCtx->pix_fmt;
frame->width = encCtx->width;
frame->height = encCtx->height;
av_frame_get_buffer(frame, 32);
// 每帧:把摄像头原始帧通过 sws_scale 转换到 YUV420P
sws_scale(swsCtx, srcFrame->data, srcFrame->linesize, 0, height,
frame->data, frame->linesize);
frame->pts = frameCount++;
ret = avcodec_send_frame(encCtx, frame);
while (ret >= 0) {
AVPacket pkt;
av_new_packet(&pkt, 0);
ret = avcodec_receive_packet(encCtx, &pkt);
if (ret == AVERROR(EAGAIN) || ret == AVERROR_EOF) {
av_packet_unref(&pkt);
break;
}
av_packet_rescale_ts(&pkt, encCtx->time_base, outStream->time_base);
pkt.stream_index = outStream->index;
av_interleaved_write_frame(outCtx, &pkt);
av_packet_unref(&pkt);
}
PTS的坑主要在这里:编码器输入帧的PTS必须是一个连续递增的序号,从0开始,1、2、3...这样才不会导致输出文件时间轴混乱。不要拿采集的实时系统时间直接当PTS,因为系统时间的差值不是恒定1/framerate,会导致视频播放速度忽快忽慢。
av_interleaved_write_frame 会自己处理交错写入,但前提是传进来的packet PTS是递增的。如果中间掉帧了,PTS依然要保持连续序号,不要跳号,否则播放器快进会出现时间轴错乱。
4.4 录制结束要做的几件事
停止录制时,需要依次完成以下几件事,顺序不能乱:
- 先
avcodec_send_frame(encCtx, nullptr),通知编码器flush,把缓冲区的剩余帧吐出来,然后循环avcodec_receive_packet直到返回AVERROR_EOF,这些packet也要正常写入MP4。 - 再
av_write_trailer(outCtx),把MP4索引信息落盘。 - 然后
avio_closep(&outCtx->pb),关闭文件句柄。 - 最后释放编码器上下文、格式上下文,关闭摄像头。
很多人录出来的MP4文件播放器打不开,十有八九是flush没做或者trailer没写。我调试时就在程序里加了日志,确认停止流程完整执行才放心。
5. 常见问题、坑点与排查技巧实录
5.1 打开摄像头失败或黑屏
这类问题排在第一位。打开设备返回 -5 (AVERROR_IO)时,首先想到设备被占用。QQ、微信、浏览器都可能在后台占用了摄像头,Windows下摄像头只能被一个进程独占,关掉所有可能占用摄像头的软件再试。其次检查设备名是否正确,要用 ffmpeg -list_devices true -f dshow -i dummy 查出来的设备名,注意名称里的空格和标点。还有就是设备被系统权限锁定,Windows设置里的摄像头权限要打开。
黑屏不报错的,多半是编码器输入帧的数据不对。我遇到过一种情况:摄像头输出MJPEG格式,但代码只处理了YUYV的分支,导致解码失败,画面一直是黑的。解决办法是加个判断,如果 codecpar->codec_id 是MJPEG,先走 avcodec 解码成原始帧。
5.2 画面撕裂或闪烁
画面上下撕裂,通常是采集帧率和显示帧率不一致导致。比如摄像头实际是25fps,你显示刷新设成30fps,偶尔会重复或丢帧。解决方案:不要硬编码帧率,从 codecpar->avg_frame_rate 里解析实际帧率:
AVRational rate = fmtCtx->streams[videoIndex]->avg_frame_rate;
double fps = av_q2d(rate);
然后动态计算显示刷新定时器的时间间隔,公式是 1000 / fps 毫秒。另外,显示线程取帧时,用最新帧,不用队列里的旧帧,这样能避免累积延迟。我的策略是每次取队列尾部的一帧,然后清空队列,保证看到的永远是实时的画面。
5.3 录制文件卡顿或无法快进
H264编码后文件在本地播放流畅,但放到剪辑软件或网盘预览时拖动卡,原因通常是关键帧间隔太长。剪辑软件想要精确定位,需要有足够多的关键帧。把 gop_size 调小一点,比如帧率的1倍(30),或直接设为帧率的一半(15),虽然文件大一点,但拖动体验好很多。
另一个原因是PTS不连续。排查方法:用 ffprobe 查看文件流信息:
ffprobe -show_packets recording.mp4
查看每个packet的pts是否递增且间隔均匀。如果pts有跳变,肯定是代码里PTS赋值出了问题,重新按帧计数序号设置即可。
5.4 libx264找不到或编码器创建失败
运行时报 codec not found 或者 avcodec_find_encoder_by_name("libx264") 返回空指针,八成是FFmpeg版本没带x264。官方Windows build的FFmpeg分两个版本:一个是GPL版,包含libx264;一个是LGPL版,不带。下载时认准名字里带 gpl 或 full 的版本,否则编码器初始化直接返回空。
如果自己编译FFmpeg,configure时记得加:
./configure --enable-gpl --enable-libx264
这一步对很多人是拦路虎,但用官方编译好的二进制就能绕开这个坑。Linux下用包管理器安装也可以,Ubuntu/Debian里:
sudo apt install ffmpeg libavcodec-dev libavformat-dev libavutil-dev libswscale-dev libx264-dev
5.5 录制过程中程序崩溃,多半是内存问题
采集、显示、编码三个线程同时访问同一帧数据,不做同步就会出现崩溃或花屏。我的做法是给帧队列加互斥锁,入队出队都走锁保护,帧数据用引用计数管理,用完立刻释放 av_frame_free 。码率高的场景下,线程间拷贝数据是开销大头,可以用AVFrame的refcount机制, av_frame_ref 和 av_frame_unref 共享缓冲,避免深拷贝。
还有一点,Qt的QImage在跨线程创建和销毁时,要在持有QImage的那个线程里操作,否则偶尔会崩溃。我的做法是显示线程完成转换生成QImage,再通过信号槽传递给UI线程的QLabel刷新,不要在UI线程里做格式转换,UI线程只负责显示。
5.6 窗口关闭时崩溃
程序退出顺序不对,崩溃率很高。正确顺序:先停止采集线程,再释放编码器和格式上下文,最后再销毁Qt窗口。我已经养成习惯了,在 closeEvent 里先发个停止信号,等工作线程退出才 event->accept() 。否则窗口先销毁,工作线程还在往UI控件塞帧数据,空指针访问直接崩溃。
Windows下退出时还会遇到一个典型的坑: avformat_close_input 会阻塞几秒,因为要跟摄像头驱动做一次握手,这是正常现象。用户会以为程序卡死了,但其实是FFmpeg在做清理,稍等即可。
5.7 Qt打包分发时找不到FFmpeg DLL
程序做好了,发给同事跑,双击却提示缺一堆dll。Windows下用Qt自带的 windeployqt 工具拷贝Qt运行库,FFmpeg的dll要手动复制过去。为了方便,我写了目录结构:
dist/
├── app.exe
├── Qt5Core.dll
├── Qt5Gui.dll
├── Qt5Widgets.dll
├── platforms/
│ └── qwindows.dll
├── avcodec-58.dll
├── avformat-58.dll
├── avutil-56.dll
├── swscale-5.dll
└── swresample-3.dll
windeployqt app.exe 会把Qt相关的dll自动放到exe目录下,FFmpeg的dll手动拷贝进bin目录,跟exe放一起就行。Linux下就是 ldd app 看依赖,把缺的动态库拷到 $ORIGIN/lib 目录下,再用rpath指到相对路径。
6. 性能优化与后续扩展
6.1 CPU占用与延迟优化
软编x264的CPU占用在720p@30fps下, veryfast 大约占一个中端CPU的10-20%。如果希望CPU占用更低,可以用 ultrafast 预设,代价是文件更大、画质略降。延迟方面做了零延迟调优后,画面到编码输出的端到端延迟实测在100ms以内,对本地录制完全无感知。
如果项目后期要求多个摄像头同时录制,CPU吃紧,优先考虑硬件编码。FFmpeg里切换编码器很简单,把 libx264 换成 h264_qsv (Intel核显)或 h264_nvenc (NVIDIA独显),编码器上下文初始化参数稍作调整就能跑通。当然要确认目标机器有对应硬件,而且运行环境有对应驱动。
6.2 录制成定时录像或按文件大小自动切片
实际业务里常遇到要按时间段分段录像,比如每10分钟一个文件。这个实现起来不复杂:编码进程记录当前文件已写入的字节数或时长,超过阈值就执行一次停止录制流程,然后重新初始化新的MP4文件继续写。注意两个文件之间会有几帧的间隙,如果要求无缝衔接,最好在编码线程里用双缓冲上下文,一边写旧文件,一边开启新文件,这里不展开,有兴趣可以自己琢磨。
6.3 增加音频录制
很多录像场景不只要画面,还要声音。USB摄像头内置麦克风,或者外接USB声卡。FFmpeg处理音频比视频简单得多,打开另一个输入流,解码后用swr_convert转成AAC,采样率设成44100或48000,双声道。把音频和视频分别用独立的编码线程处理,然后交织写入同一个MP4。PTS对齐是关键点:音频时间戳要跟视频PTS对齐,否则后面音画不同步。这里不细讲,但方向是:用采样数推导音频PTS,视频用帧序号推导,两者在写容器时各自按自己的time_base换算。
6.4 本地实时预览与RTMP推流的统一结构
如果以后要往服务器推流,当前架构不需要推到重来。把写MP4那一步,换成 avformat_write_header 初始化RTMP输出,其余编码逻辑完全复用。同一个采集数据流,同时喂给录制文件和推流端,做一边本地存档一边直播的工具,这套架构天然支持多路输出。我现在就在计划把推流功能加进去,到时候可以再写一篇完整分享。
几句掏心窝的话
这次把QT C++和FFmpeg打通,回头看的感受是:FFmpeg做后端音视频处理,Qt做界面,这套组合的可靠性远超预期。踩过的坑主要集中在三块:PTS时间戳、像素格式转换、线程同步。PTS是概念理解问题,一旦想明白帧序数和播放时间的关系,写起来就顺了;像素格式转换是细心问题,分清输入格式、编码格式、显示格式分别是什么,就没那么多歪门邪道的bug;线程同步是工程习惯问题,严格按照生产者和消费者的模型设计,及时加锁、及时释放,程序就不会莫名其妙崩。
最后分享一个小习惯:每次调整FFmpeg相关代码后,我微信上给自己发一段录好的测试视频,然后在手机上看一眼,拖动进度条快进,确认一切正常,这个步骤能帮我快速发现很多电脑上发现不了的封装问题。希望这篇内容对你有帮助,也欢迎有类似项目经验的同行多交流。
3129



被折叠的 条评论
为什么被折叠?



