简介这是一份基于FFmpeg与Qt的摄像头RTSP流实时显示示例工程面向C/Qt开发者及音视频入门学习者能帮助解决从网络拉流到画面渲染的完整链路问题。工程共9个文件包括3个cpp实现文件、2个h头文件、1个ui界面文件及pro工程配置整体仅13KB结构精简、模块划分清晰适合快速阅读并迁移。已有259人学习下载。实现中覆盖RTSP连接与取流、H.264解码、YUV转RGB的swscale转换以及通过QImage在QLabel上定时刷新显示同时包含事件响应、异常处理和多线程优化思路可帮助开发者理解FFmpeg与Qt协作的典型模式并在此基础上扩展音视频同步、画面调整等功能。 做安防或者工业视觉的人应该都遇到过这种需求不给任何SDK只给你一个摄像头IP让你在桌面上把画面实时显示出来。我这次处理的就是这么个事方案很直接——FFmpeg负责把RTSP流拉下来解码Qt负责把画面画到界面上。网上这个FFmpeg-QT-rtsp-master.zip项目基本就是这套思路的参考实现麻雀虽小五脏俱全。这篇文章就从头把它拆一遍把关键API、线程模型、延迟优化和坑位都讲清楚新手可以照着落老手也能看看有没有比自己工程里更顺手的做法。RTSP在摄像头领域太常见了海康、大华、小米这些设备基本都支持端口默认554地址里带用户名密码。但真正把RTSP流在桌面端实时显示出来牵扯的不只是拉流这一件事怎么解码、怎么转格式、怎么塞进Qt的界面刷新循环里不卡顿、多路流怎么处理这些都是实际工程里躲不开的问题。结合这些年踩过的坑我把这套方案的完整思路从选型到实现逐步展开。1. 项目整体思路FFmpeg Qt这套组合到底解决了什么问题1.1 选型背后的逻辑先说FFmpeg。很多人把FFmpeg理解成“一个视频转码工具”命令行用得多其实它更准确的身份是一个多媒体处理框架协议解析、解复用、解码、缩放、编码、封装全部覆盖。对RTSP而言FFmpeg内部已经把RTSP客户端整套流程封装好了包括SDP会话描述解析、RTP/RTCP收发、NALU组帧甚至H.264/H.265的SPS/PPS提取都由库代劳。你在工程里只需要调avformat_open_input传一个RTSP地址进去剩下的事情FFmpeg替你搞定。Qt这边则负责另一半跨平台窗口、事件循环、信号槽。QImage可以直接访问像素缓冲拿来承接FFmpeg解码出来的视频帧非常顺手。FFmpeg解码输出通常是YUV420P格式经过sws_scale转成RGB32之后一行代码就能包成QImage丢给界面去绘制。两个库的分工非常清晰FFmpeg管“拿到并还原画面”Qt管“把画面给人看”。有人可能会问为什么不用GStreamerGStreamer当然也能做RTSP拉流显示但是它的插件模型和pipeline概念学习曲线陡峭调试时经常需要在命令行工具和C API之间来回切换。相比之下FFmpeg的API相对扁平从打开流到拿到解码帧链路直观出了问题网上资料也最多。Qt自带的QMediaPlayer也能放RTSP但它在Windows上底层走的是WMF或DirectShow对自定义协议和底层帧访问非常不友好想做图像处理或者多路拉流基本使不上劲。1.2 RTSP拉流的核心流程RTSP本身是一个控制协议负责发起播放、暂停、关闭这些会话动作可以理解成一个遥控器真正承载视频数据的是一路或多路RTP流类似快递货车把货一车车运过来。FFmpeg把“遥控器”和“货运信息”都整合进了AVFormatContext这一层抽象里所以你不需要关心RTSP信令交互的细节。在代码层面整套流程的骨架大概是这样的avformat_network_init(); AVFormatContext *fmtCtx nullptr; // 打开RTSP地址设置传输方式为TCP AVDictionary *opts nullptr; av_dict_set(opts, rtsp_transport, tcp, 0); if (avformat_open_input(fmtCtx, url, nullptr, opts) ! 0) { // 打开失败 } // 查找流信息找到视频流索引 avformat_find_stream_info(fmtCtx, nullptr); int videoIndex av_find_best_stream(fmtCtx, AVMEDIA_TYPE_VIDEO, -1, -1, nullptr, 0); // 拿到解码器 AVCodec *codec avcodec_find_decoder(fmtCtx-streams[videoIndex]-codecpar-codec_id); AVCodecContext *codecCtx avcodec_alloc_context3(codec); avcodec_parameters_to_context(codecCtx, fmtCtx-streams[videoIndex]-codecpar); avcodec_open2(codecCtx, codec, nullptr);打开之后进入循环每次av_read_frame拿回来一个AVPacket判断它是视频流的包之后交给解码器解码解出来的是AVFrame再经过像素格式转换变成QImage显示。这个过程在demo里是核心具体代码下一节详细说。2. 工程搭建与核心代码实现2.1 FFmpeg环境准备库从哪来、怎么配Windows下推荐直接到FFmpeg官网下载编译好的dev和shared包dev包里有头文件和导入库shared包里是运行时要用的dll。解压到指定目录比如F:/ffmpeg然后在Qt的.pro文件里加两行INCLUDEPATH F:/ffmpeg/include LIBS -LF:/ffmpeg/bin -lavformat -lavcodec -lavutil -lswscale -lswresample注意这里的-L指向的是dll所在目录FFmpeg的Windows导入库和dll放在一起Qt在运行时会去加载dll。程序跑起来之前把ffmpeg/bin下的avformat-*.dll、avcodec-*.dll、avutil-*.dll、swscale-*.dll、swresample-*.dll几个文件拷到exe同级目录否则会报找不到dll。Linux下就省事多了直接装开发包sudo apt install libavformat-dev libavcodec-dev libavutil-dev libswscale-dev libswresample-dev版本建议用5.x或6.x以上老版本里不少API已经被标记为废弃。比如早期常用的avcodec_decode_video2在新版本中彻底移除取而代之的是avcodec_send_packet加avcodec_receive_frame这一对接口。如果下载的demo是老代码编译时会报一堆“deprecated declaration”这时候别硬着头皮忽略警告新老接口的解码流程差异会直接影响画面是否正常输出。2.2 核心代码拆解先看初始化RTSP的部分这段基本是固定的只要参数配置正确绝大多数摄像头都能打开extern C { #include libavformat/avformat.h #include libavcodec/avcodec.h #include libswscale/swscale.h } // 打开RTSP流 AVFormatContext *fmtCtx avformat_alloc_context(); AVDictionary *options nullptr; av_dict_set(options, rtsp_transport, tcp, 0); if (avformat_open_input(fmtCtx, url.toStdString().c_str(), nullptr, options) ! 0) { qDebug() open failed; return; } // 查找流信息 if (avformat_find_stream_info(fmtCtx, nullptr) 0) { qDebug() find stream info failed; return; } // 找视频流 int videoIndex av_find_best_stream(fmtCtx, AVMEDIA_TYPE_VIDEO, -1, -1, nullptr, 0); AVCodecParameters *codecParams fmtCtx-streams[videoIndex]-codecpar; AVCodec *codec avcodec_find_decoder(codecParams-codec_id); AVCodecContext *codecCtx avcodec_alloc_context3(codec); avcodec_parameters_to_context(codecCtx, codecParams); avcodec_open2(codecCtx, codec, nullptr);解码显示循环是另一块核心。这里有一个细节av_read_frame返回的AVPacket如果指向视频流用完之后必须调av_packet_unref释放否则长时间跑会内存泄漏。解码拿到的AVFrame是YUV数据屏幕显示前要转成RGB用sws_getContext建一个转换器SwsContext *swsCtx sws_getContext( codecCtx-width, codecCtx-height, codecCtx-pix_fmt, codecCtx-width, codecCtx-height, AV_PIX_FMT_RGB32, SWS_BILINEAR, nullptr, nullptr, nullptr); QImage img(codecCtx-width, codecCtx-height, QImage::Format_RGB32); uchar *rgbBuf img.bits(); AVPacket pkt; while (running) { if (av_read_frame(fmtCtx, pkt) 0) { if (pkt.stream_index videoIndex) { if (avcodec_send_packet(codecCtx, pkt) 0) { AVFrame *frame av_frame_alloc(); if (avcodec_receive_frame(codecCtx, frame) 0) { int outLinesize[1] { img.bytesPerLine() }; sws_scale(swsCtx, frame-data, frame-linesize, 0, codecCtx-height, rgbBuf, outLinesize); // 这里frameReady信号发给界面线程 emit frameReady(img); } av_frame_free(frame); } } av_packet_unref(pkt); } }demo里通常把这段逻辑拆出来放到一个独立线程类里解码线程负责拉帧、解码、转格式、发信号界面线程收到信号更新显示。这里有个非常容易踩的坑QImage用emit frameReady(img)传出去之后如果收发两端在同一线程就是直接引用传递没问题但解码在子线程、界面在主线程时跨线程信号会触发QueuedConnection参数会被拷贝而QImage的拷贝默认是浅拷贝像素缓冲是共享引用计数的子线程下一次循环就会覆盖缓冲界面那边可能显示花屏或者一片黑。稳妥的做法是在发信号前复制一份比如emit frameReady(img.copy())保证数据独立。3. 实时显示的关键细节线程、刷新与延迟3.1 为什么必须用独立线程拉流解码av_read_frame是一个阻塞操作摄像头没有数据或者网络不稳定的时候它会一直卡在那里等待。如果你把这个调用放在GUI线程只要RTSP流稍微一卡整个窗口就跟着无响应、鼠标转圈界面拖都拖不动。所以拉流解码一定要放子线程这可以说是RTSP播放器的最低要求了不这么做后期没办法继续往上加功能。Qt在这方面比较省心解码线程里把QImage通过QTimer配合信号发到主线程槽函数连接方式用默认的AutoConnection即可。跨线程时信号槽会自动切换成队列连接解码线程不用直接操作任何界面控件从根源上避免了线程安全问题。唯一要留意的是线程退出的时机析构的时候置一个running标志让av_read_frame循环退出然后wait等待线程结束接着按顺序释放AVCodecContext、AVFormatContext、SwsContext这些资源。顺序别搞反先释放解码器再释放格式上下文否则某些摄像头固件会直接让进程崩溃。3.2 延迟控制和缓存策略RTSP拉流最让人头疼的是延迟和越跑越卡这两个问题。默认情况下FFmpeg的RTSP传输模式是UDPUDP丢包不重传延迟小但画质容易花反过来TCP模式有重传机制画面稳定但稍有延迟。实时预览我基本无脑选TCP因为丢包造成的马赛克和花屏在安防场景里比几十毫秒延迟更致命。如果延迟还是偏大还有两招比较管用。第一招是把AVFormatContext的flags加上AVFMT_FLAG_NOBUFFER和AVFMT_FLAG_FLUSH_PACKETS让解复用层尽量少积压数据第二招是解码速度跟不上时主动丢旧帧比如解码队列里积压超过一定阈值就直接跳到最新的关键帧开始解保证界面始终显示当前时刻的画面而不是历史画面。// 设置低延迟 fmtCtx-flags | AVFMT_FLAG_NOBUFFER;这条经验是我在调试一个网络不太稳定的摄像头时总结出来的一开始画面延迟越来越大几秒后直接卡成幻灯片排查下来发现是解码线程持续从网络缓冲读到旧数据界面永远在追一个追不上的时间点。后来改成每读到一个帧先比较时间戳如果和系统时间差太多就直接丢掉重新拉画面才恢复实时。3.3 不同摄像头RTSP地址的差异与兼容性摄像头RTSP地址没有一个统一标准每家厂商的路径格式都不同这是新手最容易卡壳的地方。常见的有这么几种海康rtsp://用户名:密码IP:554/Streaming/Channels/101101是主码流102是子码流大华rtsp://用户名:密码IP:554/cam/realmonitor?channel1subtype0subtype为0主码流、1子码流小米rtsp://用户名:密码IP:8554/unicast/c15/s0/live端口经常不是默认554宇视rtsp://用户名:密码IP:554/MediaInput/channel1/substream1调试的时候建议先用ffprobe验证地址能不能开ffprobe rtsp://user:pass192.168.1.64:554/Streaming/Channels/101ffprobe能输出流信息说明地址和网络都没问题代码再连不上就去排查代码里的参数设置ffprobe都连不上那纯粹是地址或网络的问题不用纠结于程序本身。如果手头没有真实摄像头也可以用FFmpeg在自己电脑上临时搭一个RTSP测试源把本地视频文件变成一路RTSP流ffmpeg -re -i test.mp4 -c copy -f rtsp rtsp://127.0.0.1:8554/live这条命令需要本机跑一个RTSP服务器比如mediamtx跑起来后你的程序和ffplay都能用这个地址做联调。网上还有一些公开测试RTSP流拿VLC或者ffplay打开看一眼确认网络环境通不通再开始写代码这是效率最高的调试路径。4. 常见问题与排查实录4.1 高频报错和解决方案运行RTSP播放程序的过程中报错几乎是不可避免的。下面这张表是我做这套方案时整理的高频问题基本能覆盖大部分场景现象可能原因解决办法启动报“no Qt platform plugin could be initialized”部署时缺少platforms目录或qt.conf用windeployqt处理发布目录确保exe同级有platforms/qwindows.dllavformat_open_input返回失败地址错误/认证失败/网络不通/端口被防火墙拦截先用ffprobe验证地址检查摄像头端口和账号密码尝试rtsp_transporttcp画面持续黑屏解码帧未进入显示流程/引脚格式转换错误/未等到关键帧确认sws_scale目标格式是RGB32检查QImage的Format和bits指针在emit前打日志判断是否能进入绘图分支延迟越来越大最终卡死网络缓冲积压/解码速度跟不上开启TCP模式设置NOBUFFER标志丢旧帧只保留最新画面改用子码流解码线程崩溃AVPacket未unref/AVFrame重复释放/sws_scale参数不匹配检查每轮循环av_packet_unrefav_frame_free在receive_frame之后调用确认sws_getContext的宽高与codecCtx一致多路流同时打开时卡顿单线程串行解码多路视频每路流分配独立解码线程或用硬解码NVDEC/QSV降低CPU压力这里单独展开说一个黑屏场景。有一次接入一个第三方摄像头代码在ffplay里测试一切正常但程序里窗口始终黑屏。排查到最后发现问题出在sws_scale的输入宽高和摄像头实际输出不一致——摄像头在连接初期输出了低分辨率的首帧随后切换到设置的分辨率而我的sws_getContext是按初始分辨率建的后续帧分辨率一变转换就失败了。解决办法是在每次receive_frame之后判断frame-width和frame-height是否变化变了就重建SwsContext这是处理真实摄像头时常见的动态参数变化问题。4.2 编译和打包发布时的隐藏坑开发环境里程序跑得好好的一打包发给别人就报各种错这个阶段踩坑的频率最高。常见的痛点集中在三块第一是FFmpeg库和Qt工具的匹配问题。Windows下如果你用MinGW编译Qt程序却链接了MSVC版本的FFmpeg导入库链接器会报一堆无法解析的外部符号。反过来也一样。装库之前先确认Qt套件是MinGW还是MSVC然后下载对应版本的FFmpeg这个步骤能省下大量排查时间。第二是Debug和Release混用。FFmpeg的dll只有Release版程序以Debug模式运行时也可以正确加载但输出日志里的内存检测会频繁提示异常性能也会受影响实际发布一律用Release构建。Qt的Debug和Release依赖的库路径不同windeployqt会自动处理只要别手动去拷贝dll就不会串。第三是发布时dll遗漏。Qt程序在目标机器上运行最典型的报错就是“no Qt platform plugin could be initialized”这通常是platforms插件没放到exe同级目录导致的。先在Qt的命令行环境里用windeployqt处理一遍再把FFmpeg那几个dll手动拷贝到exe目录基本就齐了。验证方法很粗暴把exe和dll放一台干净机器上跑一下缺什么补什么。5. 还能扩展出哪些实用功能5.1 抓图、录像和OSD叠加实时显示只是第一步实际项目里往往还要加抓图和录像。抓图非常简单解码线程里emit frameReady之前QImage::save(capture.jpg)一行就搞定。关键是可以顺手加上OSD信息比如时间戳、通道号、摄像头名称利用QPainter直接在QImage上绘制QPainter painter(img); painter.setPen(Qt::green); painter.drawText(10, 30, QDateTime::currentDateTime().toString(yyyy-MM-dd HH:mm:ss)); painter.end();如果要录像建议别直接录解码后的RGB帧那样文件大且CPU占用高。更合理的是把av_read_frame拿到的原始AVPacket转封装成MP4画质无损CPU占用几乎为零。这也是很多安防平台录像模块的做法。桌面端如果只是做本地预览和简易存储这招完全够用。5.2 画面分析与音频可视化解码线程拿到AVFrame之后并不是只能转成QImage显示完全可以在这个节点做图像处理再输出。比如智能车赛道上常见的“搜线”拿到灰度图做二值化提取赛道边界比如对接深度摄像头拿到点云数据直接在界面上渲染。等于把FFmpeg的解码能力和OpenCV、QCustomPlot这些库串成一条流水线实时显示只是整条线的第一环。如果摄像头带麦克风或者接了音频流FFmpeg也可以同时解音频。把PCM采样数据攒一批做FFT变换再用QCustomPlot画频域图甚至直接切换成“时域波形/频域频谱”双视图这在声纹监测、环境异常检测这些场景里非常实用。整体扩展性很强显示层换成仪表盘、雷达图都没问题核心架构不用动只要在帧数据流里把视频帧、音频帧分发给不同的消费者就行。我个人在实际调试中最大的体会是这类项目第一次跑通时基本都会有一两个报错但报错不可怕怕的是没有一个清晰的排查顺序。先把环境变量和dll目录理干净再用ffplay验证RTSP地址有效性然后写代码从初始化到解码一步步打日志整个过程其实很快。建议拿到这套demo之后先跑通本地推流接入真实摄像头时再逐个适配地址差异这样效率最高。本文还有配套的精品资源点击获取