简介：面向Linux平台多媒体开发者的Qt、大华摄像机SDK与ffmpeg整合工程包，适合已具备C++与Qt基础、需要打通设备取流到界面显示链路的中高级开发者参考。压缩包共2000个文件，以C源码、头文件、o目标文件、d依赖文件和Makefile/mak构建脚本为主体，并含so/a库文件、texi与readme说明以及大量ffmpeg测试样本和预设，整体约156.52MB。已有1036人学习下载。内容围绕DH_Camera项目展开，可见Qt 5.9.1的Debug构建目录、工程源码与资源文件、大华SDK相关文件，便于对照理解摄像机初始化连接、视频预览抓图、ffmpeg解码取帧及QImage/QPainter显示之间的衔接，也能参考qmake/CMake组织三方依赖的方式，用于复现实验环境、排查编译链接与运行时问题。

1. 摄像机 SDK 模式接进 Linux Qt：先把 FFmpeg 解码链路拆成四段

在 Linux Qt 环境里接网络摄像机 SDK 模式，再交给 FFmpeg 解码，最后把帧画到 Qt 控件上，这条链路最容易翻车的不是解码 API，而是 SDK 回调线程和 Qt 主线程的边界。某安防项目最初用 Qt Multimedia 直接拉 RTSP，预览能出画面，但切到 SDK 私有码流后延迟从 300ms 涨到 1.2s，CPU 还飙高。后来把取流、解析、解码、渲染拆成四段，SDK 回调只做拷贝入队，FFmpeg 在独立线程做 av_parser 和 avcodec_send_packet，Qt 只保留最新一帧，延迟才压回可接受范围。这套拆法适合需要在 Linux 桌面上做多路预览、录像、抓图的从业者，也适合刚接触 Qt/FFmpeg 组合、被回调线程坑过的新手。下面按可复现的步骤拆开讲，参数和踩坑点都给到。

2. Qt 与 FFmpeg 的边界：SDK 取流、解码、上屏各管一段

2.1 为什么不让 Qt Multimedia 直接扛解码

Qt Multimedia 在 Linux 上常见后端是 GStreamer 或 FFmpeg 封装，优点是对 RTSP、本地文件、摄像头设备开箱即用，缺点是控制粒度粗。摄像机 SDK 模式给出来的往往不是标准 RTSP 流，而是私有回调里的裸 H.264/H.265 数据，有的还带私有帧头、私有时间戳、子码流切换逻辑。Qt Multimedia 接不了这种回调，硬接的结果就是自己写一个 GStreamer source，复杂度并不比直接上 FFmpeg 低。

我一般把 Qt Multimedia 定位成“快速验证工具”，不是生产链路。验证阶段可以用它确认摄像机地址、账号、码流是否正常；进入 SDK 模式后，解码交给 FFmpeg，Qt 只负责显示。这样做的直接好处是像素格式、线程数、低延迟标志、丢帧策略都能自己控，出问题也能在每一段打日志，而不是面对一个黑匣子猜。

另一个现实原因是时间戳。SDK 回调通常会给一个采集时间或帧序号，Qt Multimedia 的显示链路会重新组织时间基，PTS 对不齐时预览看不出来，录像和抓图就会暴露问题。FFmpeg 这边可以明确设置pkt->pts、pkt->dts，再用AVFrame::best_effort_timestamp做后续处理，排查延迟时有依据。

2.2 SDK 模式与 RTSP 模式的选型边界

SDK 模式和 RTSP 模式不是谁绝对更好，而是看现场约束。SDK 模式通常延迟更低，回调直出，不经过服务端缓冲；私有协议对认证、加密、设备发现的支持也更完整。代价是依赖厂商运行库，Linux 下要确认 x86_64 还是 ARM64，glibc 版本能不能对上，SDK 线程模型是否允许在回调里做重活。RTSP 模式胜在通用，调试时抓包直观，跨网段和第三方平台兼容性好，但服务端缓冲、认证协商、UDP/TCP 切换都会影响首帧和延迟。

这张表不是让你二选一，而是先定主链路。现场有 SDK 就用 SDK 取流，RTSP 作为备用通道；SDK 拉流失败时切 RTSP，至少能保住预览。代码结构上把“取流”抽象成接口，别让上层 Widget 知道数据从哪来，后面换协议不用重写渲染。

2.3 线程与队列的最小骨架

推荐的最小骨架是四段：SDK 回调线程、解析线程、解码线程、Qt 渲染线程。SDK 回调线程只做深拷贝和入队，解析线程做av_parser_parse2拆帧，解码线程做avcodec_send_packet/avcodec_receive_frame，渲染线程只保留最新一帧并update()。队列必须有界，实时预览场景下队列满时丢旧帧，不要无限堆积，否则延迟会越跑越大。

// stream_queue.h：有界队列，实时预览只保留最新数据 template <typename T> class StreamQueue { public: explicit StreamQueue(size_t cap) : cap_(cap) {} bool TryPush(T&& v) { std::lock_guard<std::mutex> lk(m_); if (q_.size() >= cap_) return false; q_.push_back(std::move(v)); cv_.notify_one(); return true; } bool Pop(T& out, int timeoutMs) { std::unique_lock<std::mutex> lk(m_); if (!cv_.wait_for(lk, std::chrono::milliseconds(timeoutMs), [&] { return closed_ || !q_.empty(); })) return false; if (q_.empty()) return false; out = std::move(q_.front()); q_.pop_front(); return true; } void Close() { std::lock_guard<std::mutex> lk(m_); closed_ = true; cv_.notify_all(); } private: std::mutex m_; std::condition_variable cv_; std::deque<T> q_; size_t cap_; bool closed_ = false; };

逻辑上，这个队列把 SDK 回调和后续解码隔开，回调线程不会因为解码慢而阻塞。参数上，cap_是队列深度，1080p25 的情况下 64 帧约 2.5 秒，延迟敏感场景建议 8 到 16；timeoutMs用 50ms 左右，方便线程退出时及时醒来。Close()必须先于join()调用，否则解析线程可能永远卡在Pop上。

2.4 CMake 里把 SDK、FFmpeg、Qt 分开链接

构建阶段最容易出问题的是库顺序和架构。SDK 的头文件路径、库路径不要写死到 CMakeLists 里，用工具链变量传进来；FFmpeg 用 pkg-config 拿libavcodec、libavutil、libswscale；Qt 只链 Widgets 和 OpenGL 相关模块。这样在 x86 开发机和 ARM 板子上切工具链时不用改源码。

cmake_minimum_required(VERSION 3.16) project(ipc_qt_ffmpeg_demo LANGUAGES CXX) set(CMAKE_CXX_STANDARD 17) find_package(QT NAMES Qt6 Qt5 COMPONENTS Widgets OpenGL REQUIRED) find_package(Qt${QT_VERSION_MAJOR} COMPONENTS Widgets OpenGL REQUIRED) find_package(PkgConfig REQUIRED) pkg_check_modules(FFMPEG REQUIRED libavcodec libavformat libavutil libswscale) add_executable(demo src/main.cpp src/sdk_adapter.cpp src/parser_worker.cpp src/decoder.cpp src/video_widget.cpp ) target_include_directories(demo PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/include ${FFMPEG_INCLUDE_DIRS} ${SDK_INCLUDE_DIR} # 由工具链文件传入，不要把厂商路径写死 ) target_link_directories(demo PRIVATE ${SDK_LIB_DIR}) target_link_libraries(demo PRIVATE Qt${QT_VERSION_MAJOR}::Widgets Qt${QT_VERSION_MAJOR}::OpenGL ${FFMPEG_LIBRARIES} ${SDK_LIBS} # 按实际库名替换，例如取流库、播放库 ) target_compile_options(demo PRIVATE ${FFMPEG_CFLAGS_OTHER})

逻辑上，find_package(QT NAMES Qt6 Qt5 ...)让工程同时兼容 Qt5 和 Qt6，避免换环境就重写链接；pkg_check_modules把 FFmpeg 的头文件和库一次性带进来。参数上，SDK_INCLUDE_DIR、SDK_LIB_DIR、SDK_LIBS通过 CMake 工具链文件或命令行传入，交叉编译时尤其要确认SDK_LIBS的架构与目标板一致。运行阶段如果报找不到.so，先看ldd demo，再检查RPATH和部署目录，不要急着怀疑解码代码。

3. SDK 回调取流：裸流进 av_parser 前必须做的三件事

3.1 回调线程里只做拷贝与入队

摄像机 SDK 的回调线程是别人的地盘，在里面做解码、加锁、刷新 UI 都属于把风险往自己身上揽。常见做法是回调里只判断数据有效性、拷贝一份、打时间戳、入有界队列，然后立刻返回。拷贝看起来浪费，但比在回调里阻塞安全得多；如果 SDK 支持零拷贝且生命周期明确，再考虑引用外部缓冲，否则不要省这一步。

// sdk_callback.cpp：SDK 回调线程只做拷贝和入队 #include "stream_queue.h" #include "demo_sdk.h" // 示例头文件，函数名按你手上 SDK 替换 struct EncodedFrame { int channel = 0; int streamType = 0; uint64_t ptsUs = 0; std::vector<uint8_t> data; }; static StreamQueue<EncodedFrame> g_queue(16); void OnEncodedData(int channel, int streamType, const unsigned char* data, int size, uint64_t ptsUs, void* user) { if (!data || size <= 0) return; EncodedFrame f; f.channel = channel; f.streamType = streamType; f.ptsUs = ptsUs; f.data.assign(data, data + size); // 深拷贝，回调返回后 SDK 可以复用缓冲 if (!g_queue.TryPush(std::move(f))) { // 队列满时丢旧帧还是丢新帧，按业务选；实时预览优先丢旧帧 EncodedFrame drop; g_queue.Pop(drop, 0); g_queue.TryPush(std::move(f)); } }

逻辑上，OnEncodedData的签名要按实际 SDK 文档对齐，示例里的demo_sdk.h只是占位。参数上，ptsUs优先用 SDK 给的时间戳；SDK 不给时间戳时，在回调里用std::chrono::steady_clock打点，单位统一成微秒，后面算延迟才不会混。队列深度 16 是低延迟起点，网络抖动大再往上调；丢帧策略要固定，不要一会儿丢旧帧一会儿丢新帧，否则 PTS 会乱。

注意：回调里不要调用avcodec_send_packet，也不要把QImage或 Qt 控件指针传进来。SDK 回调线程不是 Qt 主线程，跨线程碰 UI 是随机崩溃的源头。

3.2 av_parser 拆帧与 AVPacket 引用计数

SDK 回调给的数据不一定是完整帧，可能一次给半帧，也可能一次给多帧。av_parser_parse2的职责就是按 H.264/H.265 的起始码和 NAL 边界拆出完整访问单元。解析线程从队列取EncodedFrame，把数据喂给 parser，拿到pkt->size > 0后再送解码。这里的关键是：parser 输出的pkt->data可能指向你传入的缓冲，不能长期持有，跨线程必须复制或立刻消费。

// parser_worker.cpp：解析线程内完成拆帧，pkt 不跨线程裸传 extern "C" { #include <libavcodec/avcodec.h> } #include "stream_queue.h" void ParserWorker::Run() { AVCodecParserContext* parser = av_parser_init(AV_CODEC_ID_H264); AVPacket* pkt = av_packet_alloc(); while (running_) { EncodedFrame f; if (!queue_.Pop(f, 50)) continue; const uint8_t* p = f.data.data(); int left = static_cast<int>(f.data.size()); while (left > 0) { int used = av_parser_parse2(parser, codecCtx_, &pkt->data, &pkt->size, p, left, f.ptsUs, f.ptsUs, 0); p += used; left -= used; if (pkt->size > 0) { pkt->pts = pkt->dts = f.ptsUs; DecodePacket(pkt); // 同一线程内立刻送解码，避免裸指针跨线程 } } } av_packet_free(&pkt); av_parser_close(parser); }

逻辑上，av_parser_parse2每次吃掉used字节，剩下的继续留在left里，直到一轮数据喂完。参数上，AV_CODEC_ID_H264要按实际码流换成AV_CODEC_ID_H265，不要用“先按 H.264 试，失败再换”的玄学做法，码流类型在登录或开流时就应该确定。pkt->pts和pkt->dts这里都填 SDK 时间戳，如果后续要做 B 帧重排，再按 FFmpeg 的时间基换算；实时预览不涉及 B 帧时，简单填同值就够。

如果解析线程和解码线程必须分开，不要直接把pkt指针塞进另一个队列。正确做法是用av_new_packet分配一块新缓冲，把pkt->data拷进去，再设置 pts/dts 入队；或者用av_packet_ref前先确保 packet 是 refcounted 的。血泪经验是：parser 输出直接跨线程，十有八九会在跑几分钟后花屏或崩溃，因为原始缓冲已经被 SDK 复用了。

3.3 登录、开流、重连参数表

SDK 模式的参数不少，但真正影响稳定性的就那几个。下面这张表是接新 SDK 时我一般会先对齐的字段，具体函数名和取值范围按厂商文档填，不要照抄示例值。

重连逻辑单独放在sdk_adapter里，不要散落在 UI 代码中。SDK 断线回调里只置一个原子标志，由后台线程做Logout -> 等待 -> Login -> StartRealPlay，重连成功后清空旧队列，避免上一段码流的残留帧把新画面顶花。开流前先查 SDK 状态，不要连续调用StartRealPlay，有些 SDK 重入后会直接返回失败，日志里只给一个模糊错误码。

3.4 用抓包和日志确认码流类型

花屏、绿边、解码报Invalid NAL unit size时，先别改解码器，先确认喂进去的到底是 H.264 还是 H.265、是 Annex-B 还是 AVCC。常见做法是打开 FFmpeg 日志级别，把前几个包的pkt->size、起始字节、AVCodecParserContext返回值打出来；同时用 SDK 自带的抓流工具或保存一段裸流，用ffprobe看编码格式。日志里如果出现连续很多pkt->size == 0，说明 parser 没等到完整帧，检查回调是不是把一帧拆成了多次，或者队列丢帧把关键 NAL 丢了。

提示：调试阶段可以把原始码流落盘成.h264/.h265文件，用ffplay直接播。文件能播、内存里不能播，问题就在拆帧和跨线程；文件也不能播，问题在 SDK 取流或码流类型。

4. FFmpeg 解码到 Qt 上屏：像素格式、时间基与双缓冲

4.1 解码器打开与硬解回退

解码器打开这一步，软解和硬解的差别主要在AVCodecContext的初始化和hw_device_ctx。Linux 上常见硬解是 VAAPI，部分嵌入式板子有厂商自己的硬解接口。硬解不是必选项，SDK 给的是私有封装或裸流时，先确认硬解能不能吃这种格式；不能吃就老老实实软解，别为了 CPU 数字好看把链路搞得更复杂。

// decoder.cpp：先软解跑通，再按需挂硬解 extern "C" { #include <libavcodec/avcodec.h> } bool Decoder::Open(AVCodecID id) { const AVCodec* codec = avcodec_find_decoder(id); if (!codec) return false; ctx_ = avcodec_alloc_context3(codec); ctx_->flags |= AV_CODEC_FLAG_LOW_DELAY; ctx_->thread_count = 2; // 低延迟场景别开太多解码线程 ctx_->thread_type = FF_THREAD_SLICE; return avcodec_open2(ctx_, codec, nullptr) == 0; } bool Decoder::Send(const AVPacket* pkt) { return avcodec_send_packet(ctx_, pkt) == 0; } bool Decoder::Receive(AVFrame* frame) { int ret = avcodec_receive_frame(ctx_, frame); if (ret == AVERROR(EAGAIN) || ret == AVERROR_EOF) return false; return ret == 0; }

逻辑上，Open只负责找解码器和开上下文，Send/Receive分开调用，符合 FFmpeg 新解码 API 的推拉模型。参数上，thread_count不是越大越好，1080p 低延迟预览给 2 到 4 个线程通常够用，线程太多会拉高首帧时间；AV_CODEC_FLAG_LOW_DELAY对部分编码器有效，不要指望它单独解决延迟。硬解挂载时先调用avcodec_get_hw_config看pix_fmt，再用av_hwdevice_ctx_create建上下文，失败就回退软解，日志里把失败原因打全。

4.2 sws_scale 转 RGBA 的代价与替代

FFmpeg 解出来的帧常见是AV_PIX_FMT_YUV420P或NV12，Qt 的QImage直接画 YUV 并不方便，所以很多 demo 用sws_scale转成 RGBA。这个转换在 1080p25 下不算致命，但多路预览时会明显吃 CPU，而且每次sws_scale都是一次全帧拷贝。能接受就用，不能接受就换 QOpenGLWidget 直接上传 YUV 纹理，把转换交给 GPU。

// convert.cpp：YUV 转 RGBA，QImage 持有自己的像素内存 extern "C" { #include <libswscale/swscale.h> } void ConvertToRgba(AVFrame* src, QImage& out, SwsContext*& sws) { sws = sws_getCachedContext(sws, src->width, src->height, static_cast<AVPixelFormat>(src->format), src->width, src->height, AV_PIX_FMT_RGBA, SWS_BILINEAR, nullptr, nullptr, nullptr); out = QImage(src->width, src->height, QImage::Format_RGBA8888); uint8_t* dst[4] = { out.bits(), nullptr, nullptr, nullptr }; int dstStride[4] = { static_cast<int>(out.bytesPerLine()), 0, 0, 0 }; sws_scale(sws, src->data, src->linesize, 0, src->height, dst, dstStride); }

逻辑上，sws_getCachedContext复用转换上下文，避免每帧重新初始化；QImage在这里分配自己的内存，out.bits()指向这块内存，生命周期跟着QImage走。参数上，SWS_BILINEAR是质量和速度的折中，预览够用；如果只做缩放不做色彩空间转换，可以换SWS_FAST_BILINEAR。dstStride必须用bytesPerLine()，不要手写width * 4，否则某些对齐场景会画歪。

4.3 QImage 渲染与双缓冲

Qt 这边不要把解码线程直接连到paintEvent。正确做法是解码线程产出QImage，通过Qt::QueuedConnection投到 UI 线程，Widget 里只保留最新一帧，update()合并重绘。这样即使解码帧率高于屏幕刷新率，也不会积压一堆待画帧。

// videowidget.cpp：只保留最新帧，避免 UI 队列堆积 void VideoWidget::OnFrameReady(const QImage& img) { QMutexLocker lock(&mutex_); pending_ = img; // 覆盖旧帧，实时预览不追帧 update(); } void VideoWidget::paintEvent(QPaintEvent*) { QPainter p(this); QMutexLocker lock(&mutex_); if (!pending_.isNull()) { p.drawImage(rect(), pending_, pending_.rect()); } }

逻辑上，OnFrameReady在 UI 线程执行，pending_只保存最后一帧，绘制时按控件矩形缩放。参数上，QMutex的临界区要短，不要在锁里做缩放或格式转换；如果要做零拷贝，把QImage换成QOpenGLWidget的纹理上传，在paintGL里用glTexSubImage2D更新纹理，能省掉一次绘制拷贝。双缓冲的意义不是“画得更快”，而是“不把解码线程的节奏带进 UI 线程”。

4.4 时间基与帧率控制

FFmpeg 的AVFrame带pts和time_base，SDK 给的时间戳往往是毫秒或微秒。上屏前要统一到同一个时间基，否则算延迟、做录像、抓图都会错位。实时预览可以不按 PTS 严格排队，但必须用 PTS 判断帧的新旧，队列满时丢旧帧而不是丢新帧。帧率控制不要用sleep硬压，按渲染时钟丢帧更稳。

// time_base.cpp：把 SDK 微秒时间戳换成 FFmpeg 时间基 AVRational tb{1, 1000000}; // 微秒 int64_t ToFramePts(uint64_t ptsUs) { return av_rescale_q(static_cast<int64_t>(ptsUs), tb, ctx_->time_base); }

逻辑上，av_rescale_q把 SDK 时间戳换算到解码器时间基，送 packet 前设置pkt->pts，收 frame 后用frame->best_effort_timestamp反算显示时间。参数上，tb要和 SDK 给的时间单位一致，SDK 给毫秒就改成{1, 1000}；不要同时混用steady_clock和 SDK 时间戳，延迟统计会得出互相矛盾的数。帧率控制以渲染线程的刷新节奏为准，解码线程只管产出，UI 线程按需取最新帧。

5. 避坑与排查：回调、花屏、延迟、退出四类翻车记录

5.1 回调里直接解码导致画面卡死

现象：预览跑十几秒后画面卡住，SDK 日志显示回调超时，主线程点按钮没反应，CPU 占用并不高。

原因：SDK 回调线程里直接调用avcodec_send_packet或sws_scale，解码一慢就把回调堵住；有些 SDK 的回调线程和内部心跳共用一个线程池，堵久了会触发断流或假死。另一个隐蔽原因是回调里加了QMutex，UI 线程正好持有同一把锁，双方互等。

解决：回调里只做拷贝和入队，解码放到独立线程；队列必须有界，满了丢旧帧；回调里不要碰 Qt 对象，不要qDebug()打大段日志。排查时在回调入口和出口各打一个时间戳，算单次回调耗时，超过 5ms 就要警惕。把回调线程和解码线程分开后，卡死问题通常会直接消失。

5.2 花屏与绿边：parser 边界和 SPS/PPS

现象：画面顶部绿条、马赛克，或者第一帧正常，后续每隔几秒花一次；日志里偶发Invalid NAL unit size、no frame。

原因：parser 没拿到完整帧就被喂了下一段数据；或者回调丢帧时把 SPS/PPS 丢了，解码器缺少参数集；还有一种是 H.265 码流按 H.264 解析，NAL 头长度判断全错。跨线程传pkt->data裸指针也会花屏，因为 SDK 已经复用了原缓冲。

解决：固定码流类型，H.264 和 H.265 不要混；解析线程内消费pkt，跨线程必须复制；队列丢帧时保留关键 NAL，至少不要丢 SPS/PPS；用ffprobe确认裸流格式，再对比内存里前几个包的起始码。绿边还可能是sws_scale的linesize没对齐，检查dstStride是否用了bytesPerLine()。

5.3 延迟越跑越大：队列无界与 PTS 错乱

现象：刚开流延迟 200ms，跑十分钟后变成 2 秒，重启又恢复；抓包看网络正常，解码线程 CPU 不高。

原因：队列无界，解码比取流慢时帧越堆越多；或者渲染线程按 PTS 排队，遇到时间戳跳变后一直等“旧帧”，新帧进不来。还有一种是 SDK 回调时间戳单位变了，前面按微秒算，后面按毫秒算，延迟统计直接失真。

解决：所有队列有界，实时预览只保留最新帧；渲染线程不要做严格 PTS 排队，按到达顺序取最新帧，PTS 只用于统计和录像；时间戳单位在入口统一，SDK 给什么单位就在适配层换好，别让下游猜。排查时打印队列深度和端到端延迟，延迟随队列深度线性上涨，就说明消费端慢了，先查解码和渲染，不要先怪网络。

5.4 退出崩溃：AVFrame 生命周期与线程停止顺序

现象：关闭预览窗口时偶发段错误，堆栈在av_frame_free或avcodec_close；有时不崩，但进程退不干净。

原因：SDK 回调还在跑，队列已经被销毁；或者解码线程还在用AVCodecContext，主线程先free了；AVFrame被渲染线程引用，解码线程已经av_frame_unref。本质是停止顺序错了。

解决：先停 SDK 取流，再关队列唤醒阻塞线程，然后join解析和解码线程，最后释放 FFmpeg 上下文和 Qt 资源。停止标志用原子变量，不要用普通bool；Close()之后不要再TryPush。退出路径写成一个函数，别在窗口析构里散落一堆delete，顺序错了很难复现。

// shutdown.cpp：先断源，再关队列，最后 join void Player::Stop() { sdk_.StopRealPlay(); // 1. 停 SDK 回调 sdk_.Logout(); callbackQueue_.Close(); // 2. 唤醒解析线程 parserThread_.join(); decodeThread_.join(); renderThread_.quit(); renderThread_.wait(); // 3. 最后停渲染线程 }

逻辑上，停止顺序遵循“数据源 -> 队列 -> 消费者 -> 渲染”的反向依赖，谁生产数据谁先停。参数上，join不要带超时后直接detach，detach 只是把崩溃推迟；renderThread_.wait()要放在最后，确保QImage不再被引用。退出崩溃这类问题，复现一次就要把顺序固定下来，不要靠“多关几次就好了”。

6. 进阶验证：用 PTS 打点和丢帧策略把延迟压到可测

6.1 打点：从回调到上屏的三段时间

优化延迟前先量三段：SDK 回调入口到入队、入队到解码出帧、出帧到paintEvent。每段用steady_clock打微秒时间戳，随帧结构体带到渲染线程，在paintEvent里算总耗时。不要只打“解码耗时”，那只是中间一段，用户感知的是端到端。

// latency.cpp：随帧携带时间戳，上屏时统一结算 struct TimedFrame { QImage image; uint64_t sdkUs = 0; uint64_t decodeDoneUs = 0; }; void VideoWidget::OnFrameReady(const TimedFrame& f) { const uint64_t now = NowUs(); qDebug() << "sdk_to_decode" << (f.decodeDoneUs - f.sdkUs) / 1000.0 << "decode_to_paint" << (now - f.decodeDoneUs) / 1000.0 << "total" << (now - f.sdkUs) / 1000.0; QMutexLocker lock(&mutex_); pending_ = f.image; update(); }

逻辑上，时间戳跟着帧走，避免在多个线程里各算各的。参数上，单位统一微秒，打印时除 1000 得毫秒；采样不要每帧都打日志，抽 1/25 或者用环形缓冲统计 P95，否则日志本身会拖慢渲染。

6.2 低延迟参数与丢帧策略

低延迟不是把thread_count调到 1 就完事。解码线程保留 2 到 4 个，队列深度 8 到 16，渲染只取最新帧；网络抖动大时允许丢旧帧，但不丢 SPS/PPS。硬解能降 CPU 但不一定降延迟，首帧时间反而可能变长，先用软解跑基线，再逐项替换。

6.3 一套可复现的验收表

验收时固定三件事：同一路摄像机、同一分辨率、同一网络条件。先跑 30 分钟看内存和队列深度，再人为断网 10 秒看重连和首帧，最后切主/子码流看参数是否生效。每次改解码参数只动一项，不然出了问题不知道是哪一项的锅。

这份 demo 把 SDK 适配层、parser、decoder、QOpenGLWidget 渲染拆成四个目录，拿到后先跑空窗口，再替换sdk_adapter里的函数名，最后按验收表打点。需要这份链路 demo 的，按项目页里的目录取用即可。从那以后我每次接新 SDK，都会先把回调到上屏的三段耗时打出来，再谈优化；希望帮到你。

本文还有配套的精品资源，点击获取