简介基于FFmpeg与Qt的RTSP实时显示示例工程面向C/Qt开发者和音视频入门学习者解决从IP摄像头拉取RTSP流、解码并在Qt界面上实时显示的问题。压缩包共9个文件大小仅13KB以C源文件、头文件、界面文件和工程文件为主源码实现拉流、解码与渲染界面文件定义窗口布局工程文件负责构建另附说明文档与许可证整体结构精简清晰便于按模块阅读修改。已有259人学习适合想通过紧凑示例快速掌握FFmpeg解码链路与Qt绘图配合的读者。工程代码覆盖RTSP连接建立、流信息获取、视频解码、YUV到RGB转换及QImage绘制等关键环节并在定时器驱动下持续刷新画面直接打开工程编译即可运行稍作修改可接入不同摄像头也可作为播放器或监控客户端的扩展起点。 做嵌入式或者上位机开发的人迟早会遇到这么一件事要把摄像头的画面拉到自己的程序里显示出来。网络摄像头基本都走RTSP协议而要在桌面端快速做一套实时预览工具FFmpeg加Qt几乎是绕不开的组合。我最早折腾这个项目的时候手头既有海康的球机也有树莓派摄像头还试过用VLC命令行拉流加OpenCV显示折腾一圈之后最终才稳定在FFmpeg取流、Qt绘制这条路上。这篇博文就完整聊聊这套方案的原理、选型思路、核心代码和实际踩坑记录。这套FFmpeg-QT-RTSP方案的核心价值在于它能让你用一套代码同时对接海康、大华、宇视以及各类RTSP摄像机不依赖厂商SDK而且对硬件性能要求低解码归FFmpeg、渲染归Qt边界清晰容易扩展。后续无论是加录像、加截图、加AI识别都是在这个底子上加模块的事。适合正在纠结“怎么把网络摄像头接进自己软件”的开发者参考也适合刚接触音视频开发、想把RTSP拉流链路跑通的新手直接照抄作业。1. 项目概述与需求场景拆解1.1 为什么需要RTSP实时显示因为网络摄像机几乎没有例外地暴露RTSP协议。无论是海康的rtsp://admin:密码IP:554/Streaming/Channels/101还是小米摄像头走ONVIF间接取流底层都是RTSP做会话协商、RTP做数据承载。你要在自研软件里实时看到画面本质上就是完成“RTSP握手 - 收取RTP包 - 解H.264/H.265 - 转RGB - 上屏渲染”这条链路。自己从零实现RTSP客户端不是不行但周期极长。协议里SDP解析、NALU分片重组、I帧P帧缓存、音视频同步每一项都能写一本书。FFmpeg已经把这些全部封装好了几十行代码就能拿到解码后的原始帧省掉的不只是时间还有调试协议栈时那种生不如死的体验。1.2 技术选型为什么是FFmpeg Qt很多人第一反应是用OpenCV的VideoCapture拉RTSP简单是简单但有两个硬伤一是OpenCV的RTSP实现基于FFmpeg封装出错信息不透明遇到花屏、断流往往无从下手二是OpenCV做渲染本身很弱配合Qt显示还需要不断做Mat到QImage的转换中间会多出不必要的内存拷贝。用FFmpeg原生API的好处是每一步都能拿到详细日志从打开流、查找流信息、打开解码器到逐帧解码哪个环节出问题一眼就能定位。Qt负责显示则非常贴合桌面应用开发习惯QLabel、QWidget、QOpenGLWidget都能渲染配合QTimer或者独立线程做刷新跟整个界面系统完美融合。我最终的选择是FFmpeg 6.x做拉流和解码Qt 6.x做界面和绘制软解为主、后续性能不够再切硬解。这种组合的兼容性和可控性是最平衡的。1.3 典型应用场景与影响范围这套能力能覆盖的场景相当广。安防行业里最典型的就是无人值守监控工作站室内停车场、仓库、机房这种地方一台工控机接十几路摄像头软件里用网格视图实时预览生产车间里质检工位旁的大屏把工位摄像头画面投上去辅助人工检查还有实验室里的视觉检测设备先显示画面再叠加识别结果框方便现场调试置信度阈值。简单说只要你写的软件需要“看懂”摄像头画面这套链路就是地基。2. 核心技术原理拆解2.1 RTSP拉流整体流程用FFmpeg拉RTSP流的逻辑用一张流程就能说清avformat_open_input() 建立网络连接 - avformat_find_stream_info() 探测流信息 - avcodec_find_decoder() 查找H.264/H.265解码器 - avcodec_open2() 打开解码器 - 循环 av_read_frame() 读取压缩帧 - avcodec_send_packet() 送入解码器 - avcodec_receive_frame() 取回解码后的原始帧 - sws_scale() 将YUV转为RGB - 将QImage传入UI线程绘制你需要理解的一个关键点是RTSP在FFmpeg里只是一个输入协议的封装真正耗时耗力的是RTP包的接收、排序、组包以及H.264码流的解码。所以avformat_open_input的URL参数虽然只是简单一行rtsp://...但内部已经做了一大堆网络交互。关于解码器选择有个小原则H.264优先用h264解码器H.265优先用hevc。FFmpeg的avcodec_find_decoder会根据编码ID自动匹配一般不需要手工指定。但如果碰到摄像头输出的是MJPEG格式则解码器是mjpeg走的是静态图序列的思路解码速度极快但帧率一般较低。2.2 像素格式转换为什么绕不开摄像头真实输出格式几乎都是YUV420P而Qt的QImage只支持RGB32、ARGB32等格式。中间必须经过一次色彩空间转换。这一步通常是新人最容易忽略、却也最好出问题的地方。YUV和RGB的转换有严格数学公式但你不必关心具体公式FFmpeg已经封装好了libswscale。需要做的是初始化一个SwsContextm_pSwsCtx sws_getContext( iWidth, iHeight, AV_PIX_FMT_YUV420P, iWidth, iHeight, AV_PIX_FMT_RGB32, SWS_BILINEAR, NULL, NULL, NULL );这里的iWidth和iHeight是从解码器上下文里拿到的真实分辨率通常正好是1920x1080、1280x720这种。如果源分辨率是奇数比如很多低端摄像头的720x576sws_getContext也能正常处理但转换后的数据存在对齐问题建议统一用av_image_alloc分配目标缓冲区。为什么我建议转成RGB32而不是RGB24因为RGB32在内存里每个像素占4字节含Alpha通道正好和QImage的Format_RGB32一一对应不需要再做行对齐处理代码最简。RGB24每像素3字节写入QImage时还需要指定bytesPerLine容易因为对齐问题导致图像倾斜或错位。2.3 Qt侧渲染线程模型实时显示最怕的就是界面卡顿。千万不要在主线程里直接拉流和解码因为av_read_frame是个阻塞调用遇到网络抖动就是几百毫秒起步主线程被卡住整个界面就变成“未响应”。正确的做法是双线程模型一个解码线程负责拉流解码把得到的QImage放进队列UI线程用QTimer定时从队列里取最新帧显示。队列长度要尽力压实建议最多保留1到2帧新帧来了直接覆盖旧帧这样延迟才是最低的。为什么用QTimer而不是解码线程直接调用update()触发重绘因为Qt的界面绘制必须发生在主线程跨线程直接操作控件是危险的。通过QTimer定期取帧既保证了线程安全又能通过调整定时器间隔来控制显示刷新率。比如摄像头是25帧定时器设40ms刷新一次即可不用追求跟解码帧率完全同步。3. 实操从环境配置到画面显示3.1 环境准备与依赖安装我用的组合是FFmpeg 6.0加Qt 6.5操作系统Windows 11。FFmpeg我从gyan.dev下载的Windows构建版解压后包含bin、include、lib三个目录。Qt则直接装在线安装器选择MSVC 64位组件。在Qt Creator里配置FFmpeg头文件和库路径时有一个非常容易踩的坑FFmpeg的bin目录必须加入系统PATH环境变量否则程序启动时找不到avcodec-60.dll、avformat-60.dll这些动态库直接报“应用程序无法启动”。更稳妥的做法是把FFmpeg的dll直接拷贝到程序生成目录。.pro文件里这样配置INCLUDEPATH D:/dev/ffmpeg/include LIBS -LD:/dev/ffmpeg/lib \ -lavformat \ -lavcodec \ -lavutil \ -lswscale注意链接顺序-lavformat要放在-lavcodec前面因为libavformat依赖后者。链接器是按顺序找符号的顺序错了会报一堆无法解析的外部符号。3.2 核心代码实现首先创建一个VideoDecoder类负责拉流解码。构造函数里初始化FFmpeg相关结构VideoDecoder::VideoDecoder(const QString rtspUrl) { avformat_network_init(); m_pFmtCtx avformat_alloc_context(); // 用超时参数避免网络阻塞过久 AVDictionary *options nullptr; av_dict_set(options, rtsp_transport, tcp, 0); av_dict_set(options, stimeout, 5000000, 0); // 5秒超时 if (avformat_open_input(m_pFmtCtx, rtspUrl.toStdString().c_str(), nullptr, options) ! 0) { qCritical() 打开RTSP流失败; } avformat_find_stream_info(m_pFmtCtx, nullptr); // 找到视频流索引 for (int i 0; i m_pFmtCtx-nb_streams; i) { if (m_pFmtCtx-streams[i]-codecpar-codec_type AVMEDIA_TYPE_VIDEO) { m_iVideoStreamIndex i; break; } } // 打开解码器 AVCodecParameters *codecParams m_pFmtCtx-streams[m_iVideoStreamIndex]-codecpar; const AVCodec *decoder avcodec_find_decoder(codecParams-codec_id); m_pCodecCtx avcodec_alloc_context3(decoder); avcodec_parameters_to_context(m_pCodecCtx, codecParams); avcodec_open2(m_pCodecCtx, decoder, nullptr); }这里有一个非常影响稳定性的经验rtsp_transport强制设为tcp。默认情况下FFmpeg可能选择UDP传输UDP在局域网内乍一看延迟更低但稍微有点丢包就会导致画面花屏或解码器报错。TCP虽然理论延迟高几毫秒但可靠性和画面完整性好得多实际体感几乎没有差别。然后实现逐帧解码的主循环void VideoDecoder::run() { AVPacket *packet av_packet_alloc(); AVFrame *frame av_frame_alloc(); while (!m_bStop) { int ret av_read_frame(m_pFmtCtx, packet); if (ret 0) { emit errorOccurred(读取视频帧失败); break; } if (packet-stream_index m_iVideoStreamIndex) { avcodec_send_packet(m_pCodecCtx, packet); while (avcodec_receive_frame(m_pCodecCtx, frame) 0) { QImage image convertFrameToImage(frame); emit frameReady(image); } } av_packet_unref(packet); } av_frame_free(frame); av_packet_free(packet); }convertFrameToImage把AVFrame里的YUV数据转为QImage。这里分配一个固定大小的缓冲区避免每帧都重新分配内存QImage VideoDecoder::convertFrameToImage(AVFrame *frame) { int w m_pCodecCtx-width; int h m_pCodecCtx-height; if (m_pSwsCtx nullptr) { m_pSwsCtx sws_getContext(w, h, m_pCodecCtx-pix_fmt, w, h, AV_PIX_FMT_RGB32, SWS_BILINEAR, nullptr, nullptr, nullptr); m_rgbBuffer new uint8_t[av_image_get_buffer_size(AV_PIX_FMT_RGB32, w, h, 1)]; } uint8_t *dstData[1] { m_rgbBuffer }; int dstLinesize[1] { w * 4 }; sws_scale(m_pSwsCtx, frame-data, frame-linesize, 0, h, dstData, dstLinesize); QImage image(m_rgbBuffer, w, h, QImage::Format_RGB32); return image.copy(); // 深拷贝避免缓冲区复用导致的花屏 }最后这个image.copy()非常关键。QImage构造时只包装了外部缓冲区指针并没有复制数据。如果直接返回引用解码线程下一次写入缓冲区覆盖数据时UI线程还没来得及绘制就已经花了。深拷贝增加了一次内存拷贝但保证了显示正确性这个开销可以接受。UI侧就简单了在QLabel上显示图片void MainWindow::onFrameReceived(const QImage image) { m_pLabel-setPixmap(QPixmap::fromImage(image).scaled( m_pLabel-size(), Qt::KeepAspectRatio, Qt::SmoothTransformation)); }3.3 编译打包与发布检查程序写完后直接用Qt Creator的Release模式编译然后用windeployqt工具收集Qt依赖windeployqt myRtspPlayer.exe这个命令自动把Qt相关的DLL和插件目录拷到exe同目录。但windeployqt不会管FFmpeg的DLL需要手动把FFmpeg的bin目录下几个关键文件一起拷过去avcodec-60.dll、avformat-60.dll、avutil-56.dll、swscale-5.dll。还有一个让人头疼的经典报错“windows no qt platform plugin could be initialized”。这个问题的根源是程序找不到platforms插件目录。解决办法就是确保生成目录下有platforms/qwindows.dllwindeployqt会正确生成这个目录结构。4. 常见问题与排查技巧4.1 画面卡顿与高延迟这是实时显示最常见的痛点。我用一个参数组合把局域网内延迟稳定控制在150ms以内rtsp_transport设为tcp减少UDP重传导致的乱序等待解码线程和UI线程之间用队列缓冲最多1帧丢旧帧保新帧av_read_frame后面不要加额外的QThread::msleep让解码速度跑满如果还是要继续压延迟可以尝试降低分辨率解码在avcodec_open2之前用avcodec_parameters_to_context再修改width和height让解码器在低分辨率模式下工作代价是清晰度下降。适合仅需要预览、不需要完整分辨率的场景。帧率上不去的另一个常见原因是丢关键帧等待。H.264存在I帧和P帧之分P帧必须依赖前面的帧才能解码。如果因为某种原因丢了一个I帧解码器要等到下一个I帧来才能恢复画面这个等待间隔就是摄像头的I帧间隔。解决办法是登录摄像头后台把视频编码的GOP或者叫I帧间隔从默认的50改到25或者更小。4.2 黑屏、花屏与加载失败黑屏问题先自查三件事摄像头IP是否能ping通RTSP地址是否带端口和路径认证用户名密码是否正确。在项目里给avformat_open_input加打印av_log_set_level(AV_LOG_DEBUG);这样你能在控制台看到HTTP 401认证失败、连接超时这类具体原因。很多人上来就怀疑代码逻辑其实是IP网段都不通白白耽误时间。花屏基本上都是RTP包丢失或乱序导致的。如果已经强制TCP传输再检查交换机端口是否千兆、网线是否老化。无线网络环境下做视频预览体验极差掉包太严重我不建议用WiFi传实时视频。加载失败还有一种隐蔽情况摄像头同时被多个客户端点播有些低端摄像头有最大连接数限制。一旦超过限制新的RTSP会话就建立不起来。这时关闭其它预览窗口或者去摄像头后台看在线用户列表。4.3 我踩过的坑汇总整合一下我在这个项目里遇到的报错和解决方法症状根因解法程序启动找不到avcodec DLLFFmpeg bin目录未加入PATH把DLL拷到exe目录或设置PATHCould not open codec链接库顺序错误 / 缺少对应解码器调整.pro链接顺序检查FFmpeg构建是否含h264解码画面撕裂或局部花屏QImage浅拷贝指向复用缓冲区返回前使用image.copy()深拷贝连接超时但网络正常stimeout未设置默认无限等待设置stimeout5000000帧率远低于预期GOP过长I帧间隔大摄像头后台缩短I帧间隔高分辨率画面模糊软解帧率过低导致抽帧降低预览分辨率或换硬解这里面最让我记忆深刻的是sws_scale导致的绿边问题。有次摄像头分辨率是1920x1080没错但实际有效画面是1920x1080裁切后的内容解码器返回的width和height是对的但frame-linesize不等于width * 4做YUV转RGB时如果直接按width算图像右边会出现绿色条纹。后面参考FFmpeg官方例程所有行宽数据都从linesize拿问题彻底解决。5. 这套方案还能怎么扩展完成了基础的RTSP实时显示之后后续能扩展的方向非常多。录制回放是最常见的需求——内部其实就是把FFmpeg解码前的AVPacket原封不动地写入MP4文件注意要等收到第一个关键帧再开写否则文件打不开。截图则是在拿到QImage后直接image.save()也可以叠加OSD文字和时间戳再做保存。如果做AI视觉可以把解码线程每秒抽取的帧传给推理引擎给Qt界面叠加上检测框时只要把YUV转RGB后的QImage和检测结果叠加即可。实际运行时注意控制推理频率别每一帧都推给模型否则CPU和内存都被吃满。还有一点要提前规划的是多路显示。16路摄像头做九宫格或者十六宫格预览时解码线程数量要控制好每路摄像头一个线程但UI做统一管理。当某个画面在界面上不可见时比如切到了其它宫格页主动停掉对应RTSP会话等切回来再重新连接这样系统资源占用能省下一大半。当初我做完这个项目最大的体会是FFmpeg这套API虽然看起来繁琐但它的设计处处考虑到了工程上会遇到的异常情况只要跟着官方的解码流程走再配上一套健壮的线程模型RTSP实时显示就是一件非常稳固的事。希望这篇实操笔记能帮你少走几次弯路尤其是那个image.copy()深拷贝的问题我至少见五个同行在这个坑里栽过跟头。本文还有配套的精品资源点击获取