简介：面向Linux/Qt开发者的v4l2摄像头采集与显示录像示例工程，解决视频设备接入、MJPEG流解析、图像格式转换以及Qt界面实时预览和录像保存等问题。资源共210个文件，压缩后3.03MB，以h、c、cpp源码为主，辅以UI界面、库文件（so、a）及配置文件，覆盖驱动接口封装、JPEG解码、Qt显示控件等关键模块。已有547人学习下载。包内集成libjpeg、tinyjpeg、libv4l等组件，可帮助读者理解v4l2 API调用流程、MJPEG到RGB的转换实现，以及如何通过Qt信号槽机制触发录像逻辑；对嵌入式视频采集、交叉编译和Qt应用开发有一定经验的开发者尤为适合。 手里正好有一个项目要落地，需求很简单：USB摄像头出图，Qt显示，还要能录像。东西本身不难，但真做起来，从采集到显示再到编码存储，每一步都有讲究。市面上讲V4L2的教程不少，讲Qt的更是一抓一大把，但把这俩串起来做一套完整方案的，很多文章都只讲了半截，要么停在能出图就收工，要么录像代码写得像玩具。
这篇文章我就按自己实际动手的流程来写，从V4L2采集参数怎么设、buffer怎么管，到Qt端怎么接帧、怎么渲染不撕裂，再到录像模块怎么做时间戳对齐、怎么选封装格式，全部串起来讲一遍。代码都是实际验证过能跑的，方案取舍也会说明原因。想直接抄作业的，按章节往下走就行；想搞明白底层逻辑的，文中也会把关键机制拆开讲透。
1. 整体架构与模块划分
先把整套程序的骨架搭起来。一个典型的V4L2采集显示录像程序，逻辑上可以拆成五个独立模块：设备管理、采集引擎、帧缓冲池、显示渲染、录像编码。
设备管理负责枚举设备、查询能力、设置格式；采集引擎运行在独立线程里，循环DQBUF拿帧、送显示、送编码、再QBUF回收；帧缓冲池是核心的共享内存区域，解决线程间帧传递的同步问题；显示渲染跑在Qt主线程；录像编码建议开独立线程，避免编码耗时堵住采集循环。
这里有一个典型的架构决策：为什么不把采集、显示、录像直接串在一条链路上？我一开始就是串行写的，测试时发现只要录像编码稍微慢一点，采集队列就堵住了，DQBUF超时，画面开始卡顿。后来改成采集线程只管“分发帧”，显示和录像各自从缓冲池取帧处理，问题就消失了。采集线程只负责不丢帧，显示和编码各管各的消费节奏。
技术栈选型上，采集用V4L2是Linux下绕不开的方案，UVC摄像头、MIPI CSI摄像头、甚至部分模拟采集卡都走这个框架；显示用Qt Widgets，这里有个取舍：QWidget的QPainter渲染在嵌入式平台上足够用，如果用QML的话，帧上传Shader会更复杂，除非有高性能3D渲染需求，否则不推荐；录像编码我选了H.264软件编码器，硬件编码虽然更高效，但不同平台的接口不统一，做通用方案还是软编省事。
2. V4L2采集参数与Buffer管理
2.1 设备格式设置的关键点
打开设备之后，第一步不是直接开始采集，而是先查设备能力。
struct v4l2_capability cap; memset(&cap, 0, sizeof(cap)); if (ioctl(fd, VIDIOC_QUERYCAP, &cap) < 0) { // 错误处理 } if (!(cap.capabilities & V4L2_CAP_VIDEO_CAPTURE)) { // 不是视频采集设备 }注意设备节点路径，不同平台差异很大。USB摄像头一般是/dev/video0开始递增，但有些板子把ISP和编码器也注册成video节点，枚举时不能只找/dev/video0，要遍历/dev/video*逐个QUERYCAP，再比对cap.driver或cap.card来确认真正的采集设备。我有一次在RK平台上一共有5个video节点，挨个试到第3个才是MIPI摄像头。
格式协商是整个采集流程里最容易踩坑的地方。
struct v4l2_format fmt; memset(&fmt, 0, sizeof(fmt)); fmt.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; fmt.fmt.pix.width = 1920; fmt.fmt.pix.height = 1080; fmt.fmt.pix.pixelformat = V4L2_PIX_FMT_YUYV; fmt.fmt.pix.field = V4L2_FIELD_NONE; if (ioctl(fd, VIDIOC_S_FMT, &fmt) < 0) { // 格式设置失败 }设完格式必须回读一次，确认设备实际返回的分辨率和像素格式。UVC摄像头比较规矩，基本设什么给什么；有些工控相机或老式Sensor驱动会自作主张改成它支持的分辨率，不回读就会出现采集尺寸和预期不符的诡异问题。
像素格式优先选YUYV而不是MJPEG。虽然MJPEG在USB带宽上占优势（压缩后传输量小），但后续录像编码需要解码成YUV才能工作，白白多一道解压。YUYV是裸数据，内存里直接就是YUV422排列，转RGB也好、送编码器也好都方便。
2.2 Buffer管理与mmap内存映射
Buffer这块推荐使用内核提供的mmap模式。V4L2支持多种IO方式——read/write直接读写、mmap内存映射、userptr用户指针、dmabuf共享——但对普通摄像头采集，mmap是最平衡的方案，省一次内存拷贝，操作也简单。
struct v4l2_requestbuffers req; memset(&req, 0, sizeof(req)); req.count = 4; req.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; req.memory = V4L2_MEMORY_MMAP; if (ioctl(fd, VIDIOC_REQBUFS, &req) < 0) { // 申请buffer失败 }buffer数量我给4个。太少（比如2个）会导致采集驱动和应用程序之间没有足够的缓冲余地，帧率波动时容易丢帧；太多（比如8个以上）会增大延迟，对实时预览不友好。4个是实践下来比较均衡的值。注意REQBUFS之后要逐个QUERYBUF确认每个buffer的长度和偏移，再mmap进用户空间。
struct v4l2_buffer buf; memset(&buf, 0, sizeof(buf)); buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; buf.memory = V4L2_MEMORY_MMAP; buf.index = i; if (ioctl(fd, VIDIOC_QUERYBUF, &buf) < 0) { // 查询buffer失败 } void *buffer = mmap(NULL, buf.length, PROT_READ | PROT_WRITE, MAP_SHARED, fd, buf.m_offset);启动采集流之后，核心循环就是DQBUF拿帧、处理、QBUF归还。
for (;;) { memset(&buf, 0, sizeof(buf)); buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; buf.memory = V4L2_MEMORY_MMAP; if (ioctl(fd, VIDIOC_DQBUF, &buf) < 0) { // 超时或错误 continue; } // 处理帧数据：送往显示和录像 if (ioctl(fd, VIDIOC_QBUF, &buf) < 0) { // 归还buffer失败 } }这里必须注意，DQBUF拿到buffer之后，如果处理耗时太长（编码、显示都算在内），驱动那边可用的buffer就少了，一旦全部占用，采集就阻塞或者丢帧。这也是前面架构设计里强调要拆线程的原因。
3. 图像格式转换与Qt显示渲染
3.1 YUYV转RGB24的原理与实现
大多数摄像头输出的YUYV格式没法直接被Qt的QImage显示，需要转成RGB24或者RGB32。YUYV是YUV422格式，每两个像素共享一组UV分量，排列是Y0 U0 Y1 V0的36字节块。转换公式是标准的BT.601：
uint8_t y0 = yuyv[0]; uint8_t u = yuyv[1] - 128; uint8_t y1 = yuyv[2]; uint8_t v = yuyv[3] - 128; int r0 = y0 + 1.402f * v; int g0 = y0 - 0.344f * u - 0.714f * v; int b0 = y0 + 1.772f * u; int r1 = y1 + 1.402f * v; int g1 = y1 - 0.344f * u - 0.714f * v; int b1 = y1 + 1.772f * u; // 依次填充RGB缓冲区这个转换如果用纯CPU循环做，1080p@30fps大概要占满一个中端ARM核心，性能不太乐观。优化思路有几个方向：查表法替代浮点运算，把乘法和加法变成查数组；SIMD加速向量化处理；有空闲的硬件转码单元直接让硬件做。
实际项目中，如果CPU充裕就直接用上面的公式，简单直接；如果要做性能优化，先把unsigned char和int的转换过程走查表——Y固定查、U/V查表计算后再组合，这样速度能提升一倍以上。再往下就是NEON或SSE优化，这个就按需做了。
3.2 Qt渲染方案选型
Qt端显示视频帧，主流做法有三种，我实际操作下来各有优劣。
QLabel + QPixmap：做法最直接的方案，QImage转QPixmap丢给QLabel的setPixmap。但QPixmap像素在服务端（X11/Wayland），每次显示都要上传一次，性能差。做简单演示可以，正式程序不推荐。
QWidget重写paintEvent + QPainter::drawImage：比QLabel高效，QImage直接进QPainter绘制，省掉了QPixmap转换，内存拷贝少一道。我项目里最终用的就是这种方案。
QOpenGLWidget + 纹理上传：性能天花板最高的方案，GPU直接渲染。但代码复杂度上升，而且要处理纹理格式（YUV420可以通过纹理转换直接在GPU端完成色彩空间转换），调试起来也更麻烦。如果只是显示USB摄像头画面，用不到GPU渲染。
推荐直接走QWidget重写绘图这条路，代码示意如下：
void VideoWidget::paintEvent(QPaintEvent *event) { QPainter painter(this); if (!m_image.isNull()) { QImage scaled = m_image.scaled(this->size(), Qt::KeepAspectRatio, Qt::SmoothTransformation); QRect target((this->width() - scaled.width()) / 2, (this->height() - scaled.height()) / 2, scaled.width(), scaled.height()); painter.drawImage(target, scaled); } else { painter.fillRect(this->rect(), Qt::black); } }重点在于：从采集线程传递帧数据到UI线程时，要避免跨线程直接操作QImage。我的做法是采集线程把帧拷贝到一块共享内存（提前分配好的帧缓冲池），然后通过信号槽通知UI线程刷新，UI线程从共享内存构造QImage进行绘制。这样既避免频繁malloc/free造成的内存碎片，也规避了QObject线程亲和性的坑。
有人可能会问，为什么不直接在采集线程里调用update()？这会导致Qt内部在处理绘制事件的同时还要处理帧数据，容易出现花屏和手风琴撕裂。实测下来用信号槽+共享内存这套方案，画面干净稳定，内存零增长。
4. 录像模块实现与封装
4.1 存储方案的选择
录像需求看起来简单，就是“把采集的帧存成文件”，但具体方案导致的工作量和效果差异很大。
方案A：裸流存储，直接把YUV帧按顺序写入文件。实现最简单，但文件体积巨大。一帧1080p的YUYV数据是192010802≈4MB，按30fps算一秒钟就是120MB，实际操作基本不现实。
方案B：MJPEG打包，利用Linux平台下V4L2采集MJPEG格式的能力，直接把摄像头输出的JPEG帧逐帧写入AVI容器。比较巧妙的做法，体积控制住了，也不必在设备端做转码。但缺点是帧率受限且不同设备MJPEG质量参差，没法统一控制。
方案C：H.264软件编码，把采集到的YUV帧送给x264编码器，产出H.264裸流，再用MP4或MKV封装。效果和体积控制都最好，也是目前主流的通用方案，缺点是需要引入libx264依赖。我最终采用的是这个方案。
如果项目场景对延迟不敏感、主要是集中保存回放，方案C是正确选择。如果场景是需要常开低功耗，那可以考虑把编码放到录像线程中调整线程优先级和编码preset来平衡。
4.2 编码线程与缓冲队列
为了避免视频编码阻塞采集，必须加缓冲队列。我的实现思路：
// 帧数据包装队列，采集线程写入，编码线程取出 QQueue<FrameData> m_frameQueue; QMutex m_queueMutex; QWaitCondition m_queueCond;采集线程每拿到一帧，检查队列长度。如果队列超过20帧（大约半秒钟的缓冲），说明编码线程跟不上采集速度，策略是丢掉最旧的帧，而不是最新帧——丢旧帧能保证录下来的视频内容是实时的，丢新帧则会导致画面卡顿空洞。机械硬盘连续写入场景或者嵌入式平台低性能CPU下，这一招非常关键。
编码这边的线程逻辑是循环取帧，转成YUV420（x264输入要求），送入编码器：
x264_picture_t pic_in, pic_out; x264_picture_alloc(&pic_in, X264_CSP_I420, width, height); pic_in.img.plane[0] = /* Y平面数据 */ pic_in.img.plane[1] = /* U平面数据 */ pic_in.img.plane[2] = /* V平面数据 */ int frame_size = x264_encoder_encode(enc, &nal, &i_nal, &pic_in, &pic_out);编码器参数上，preset设置为veryfast即可，嵌入式平台用ultrafast也可以接受。关键参数是zerolatency（无B帧延迟）和repeat-headers（每个关键帧带上SPS/PPS），后者对播放器兼容性影响很大。有人会遇到录制文件用VLC能打开但放不了MP4的视频，基本都是少了repeat-headers或封装时没写正确extradata导致的。
4.3 封装与时间戳
拿到H.264裸流之后，直接用MP4封装其实需要一个libavformat之类的库。如果需要尽量少依赖，可以只封装成裸流文件或者打包成AVI（AVI对每帧只需写长度和时间戳，实现起来相对简单）。但如果希望获得较好的播放器兼容性，仍然封装成MP4。这里我直接用FFmpeg库做封装，它顺带帮我把时间戳也管了。
AVFormatContext *fmt_ctx; avformat_alloc_output_context2(&fmt_ctx, NULL, "mp4", /*文件名*/); // 设置编码器参数 // ...为了保持音画同步，每一帧送入编码器时要带正确的PTS（显示时间戳）。采集到的帧本身自带V4L2的时间戳，但那个时间戳的单位和后续编码的time_base不一定一致，编码前要做一次换算：
pic_in.i_pts = pts_in_milliseconds; // 统一换算成毫秒FFmpeg封装时会自动根据time_base处理每一帧的显示时间。我之前在项目中曾经直接把frame index当成pts填进去，结果录出来的视频是“fast motion”，播放速度明显不对。后来检查发现是因为没有计算真实的帧间隔，而是按帧序号递增导致时间轴压缩了。要避免这个问题最简单的方法：用单调递增的时钟记录每帧到达时间，再把这个时间戳传到编码帧的pts中。
5. 常见问题排查与性能调优
5.1 画面闪烁或撕裂
显示端出现横纹或撕裂，大多数是因为采集线程写入帧的速度和UI线程绘制读取帧的速度不一致，二者交错导致。解决方式用双缓冲：后台缓冲写数据，前台缓冲只负责绘制，写完后原子交换指针。这个和图形学里的双缓冲是一个道理。在Linux上还可以直接打开双缓冲驱动（v4l2_control设置V4L2_CID_HFLIP等参数），但通用做法还是从应用层把buffer管理好。
排查步骤一般是：先看是不是分辨率设置和实际采集尺寸不匹配，其次是确认绘制是否在UI线程完成，最后检查帧缓冲池有没有发生写一半读一半的并发问题。前两个没发现异常、还是花屏的情况下，重点检查的往往是并发而非渲染。
5.2 视频卡顿和丢帧
卡顿在逻辑上主要有两个方向：一是采集端丢了帧，二是显示端跟不上刷新率。要区分这两个方向，我在测试程序里会打一个帧率统计：统计采集线程DQBUF的帧数和UI线程实际渲染的帧数。如果采集帧率持续接近设置值的30fps、UI渲染只有20fps，那就是显示瓶颈；反之则是采集驱动或buffer数量不够。
显示瓶颈的调优方向非常多，我这里提供几个实操有用的：
- 去掉QPainter的SmoothTransformation，改为FastTransformation，缩放开销能降低不少
- QImage转成RGB32而不是RGB888，因为QImage对32位格式有优化路径
- 如果整个窗口大小和摄像头分辨率是1:1，直接不缩放，drawImage原样绘制
5.3 录像文件和播放器兼容性
录制完了文件播放不了、有声音没画面、拖进度条就崩溃，这类问题的根源基本在封装参数和时间戳两个地方。这里最容易被忽略的是h264裸流的编码参数。有些播放器只认SPS/PPS在关键帧前部的情况，如果你用libx264库忘了设置repeat-headers，只有在流最开始的第一个关键帧处有SPS/PPS，拖拽进度时会找不到解码信息。
另一个问题：MP4文件播放正常但显示时长不对，就是因为pts不连续或者最后一帧的dts没写正确。解决方法是确保封装前对每一帧进行重排序，同时封装器写入时使用正确的duration计算方式，在编码器内部开启x264_param_t.i_bframe = 0可以让这个问题的出现概率降到零。
5.4 内存泄漏与文件句柄排查
长期跑录像机功能的程序，最怕的就是内存持续增长和文件句柄泄漏。内存泄漏主要来自两个地方：一是QImage构造后没有正确释放，另一种是帧缓冲队列的内存管理逻辑有bug。我的排查方法：给程序接了valgrind --tool=memcheck跑20分钟的采集，定位具体泄漏位置；持续抓取/proc/{pid}/fd数量确认文件描述符是否稳定。
有一个更隐蔽的坑：mmap映射的设备buffer使用完毕后必须munmap，否则进程退出时可能留残留映射，导致下次打开设备时设备节点被占用报Device or resource busy。我在开发板调了一个多小时才发现是上次异常退出时mmap没释放干净。
5.5 性能优化建议
如果你跑在低配ARM板子上，CPU资源比较紧张，几个优化建议按性价比排序：
- 分辨率妥协。默认采集1080p，如果CPU吃紧，采集720p再到Qt端放大，比1080p缩放到小窗口要省不少资源。
- 关闭Qt特效。在一些桌面Linux环境里，窗口合成器特效对绘制性能影响很大，嵌入式板子不用桌面环境就不用管这个；如果是桌面环境，可以考虑用
QT_GRAPHICSSYSTEM环境变量强制走软件渲染路径，有时反而更快。 - 编码线程绑定CPU。用
pthread_setaffinity_np把编码线程绑到大核上，同时把采集线程绑到另一个核，避免线程迁移导致的缓存频繁失效。 - 开编译优化。QMake工程里加
QMAKE_CXXFLAGS += -O2，release构建下转换函数性能能提升15%左右。
最后再分享一个实操技巧
录像文件的时间戳同步在很多场景下是个隐藏需求。如果你后续要做录像回放、录像切片，最好在录制的时候同步保存一个时间戳索引文件，格式很简单：每一行记录帧序号、UTC时间、编码后的pts。这样即使最终MP4封装出了问题，也能依靠索引文件做二次修复或关键帧定位。我在项目中这个索引文件还会记录每帧对应的原始inode大小，方便做异常断电时的文件重建。这个技巧算是我踩过坑之后的沉淀，看起来不起眼，但关键时刻能救回一整天的录像数据。
这套v4l2-qt采集显示录像方案，整体链路并不复杂，真正难的是把各个环节的buffer管理、线程协作和时间戳体系理顺。只要按照本文的模块划分，一步步实现并做好每一层的边界隔离，这个程序不会出太离谱的问题。如果你在实际开发中把某个环节玩出了更好的优化，欢迎分享。
本文还有配套的精品资源，点击获取
