目錄一、先建立心智模型FFmpeg 為什么難調(diào)試二、第一層命令行級調(diào)試80% 問題止步于此1?. 把日志等級拉滿必會2?. 用 ffprobe先排除「輸入源問題」高頻坑3?. 拆解 filtergraphfilter 調(diào)試核心技巧三、第二層API 級調(diào)試libav* 項(xiàng)目必看1?. 接管 FFmpeg 日志別用 printf2?. 打印時(shí)間戳90% 音畫不同步的根因3?. AVERROR一定要轉(zhuǎn)成可讀字符串四、第三層GDB / 崩潰級調(diào)試真·硬核1?. 編譯 FFmpeg必須帶符號2?. GDB 啟動 斷點(diǎn)套路3?. SIGSEGV / Assertion failed 標(biāo)準(zhǔn)流程五、第四層性能調(diào)試卡頓 / CPU 100%1?. 先確認(rèn)瓶頸在哪一層2?. 性能三件套看 filter 成本Linux 神器 perf硬件加速快速驗(yàn)證六、GUI / Overlay / Qt 場景的特殊坑你這個(gè)場景重點(diǎn)線程模型一定要對overlay filter 調(diào)試參數(shù)七、FFmpeg 調(diào)試 Checklist覺得有用就請您幫忙點(diǎn)贊轉(zhuǎn)發(fā)收藏吧您的鼓勵(lì)是我創(chuàng)作的動力多謝看官。由于能力水平有限文中的錯(cuò)誤或不嚴(yán)謹(jǐn)?shù)牡胤皆谒y免還請批評指正。本文面向中高級開發(fā)者系統(tǒng)梳理 FFmpeg 調(diào)試的 4 個(gè)層級命令行級 → 日志級 → 源碼/GDB 級 → 性能 崩潰級。你將掌握為什么 FFmpeg 報(bào)錯(cuò)信息總是「語焉不詳」以及如何讓它開口說話-v、-report、AV_LOG_DEBUG的正確打開方式用 GDB core dump 定位SEGV/Assertion failed的完整流程filtergraph尤其是 overlay / scale調(diào)試的專用技巧性能問題卡頓、掉幀、CPU 飆高如何用ffprobe perf VTune拆解一套可直接復(fù)用的「FFmpeg 調(diào)試 Checklist」一、先建立心智模型FFmpeg 為什么難調(diào)試FFmpeg 調(diào)試難本質(zhì)不是工具問題而是架構(gòu)問題CLI (ffmpeg.c) └── libavformat (demux / mux) └── libavcodec (decode / encode) └── libavfilter (filtergraph) └── 硬件加速 / 線程池 / 內(nèi)部 buffer 池典型痛點(diǎn)現(xiàn)象真實(shí)原因只說Error while filteringfiltergraph 某節(jié)點(diǎn) init 失敗但錯(cuò)誤信息被吞卡住不動線程池死鎖 / muxer 等 B-frame 緩存花屏?xí)r間基不一致 / width/height 對齊問題偶發(fā)崩多線程 use-after-free結(jié)論不要只盯著最后一行 Error要順著「模塊邊界」查。二、第一層命令行級調(diào)試80% 問題止步于此1?. 把日志等級拉滿必會ffmpeg -v debug -i in.mp4 -vf scaleiw/2:ih/2 out.mp4日志等級優(yōu)先級由低到高quiet panic fatal error warning info verbose debug trace實(shí)戰(zhàn)建議場景推薦看 filter 初始化-v verbose看時(shí)間戳 / PTS-v debug看內(nèi)存分配/refcount-v trace非常吵黃金組合ffmpeg -v verbose -report -i in.mp4 ...-report會自動生成ffmpeg-YYYYMMDD-hhmmss.log包含完整命令行 環(huán)境變量 所有日志線上問題必開。2?. 用ffprobe先排除「輸入源問題」高頻坑原則ffmpeg 崩 ≠ ffmpeg 的鍋先證偽輸入文件ffprobe -v debug -show_streams -show_frames -select_streams v in.mp4重點(diǎn)看codec_typevideo width1920 height1080 pix_fmtyuv420p r_frame_rate30/1 start_time1.4 ← 很多花屏/卡頓的根因 time_base1/90000經(jīng)典信號ffprobe 輸出含義start_time 0 concatPTS 漂移pix_fmtnv12但 filter 只認(rèn) yuv420pswscale 自動插入隱式慢nb_framesunknownVBR 缺索引3?. 拆解 filtergraphfilter 調(diào)試核心技巧錯(cuò)誤姿勢-vf scale1080:-2,overlay10:10,drawtexttexttest,formatyuv420p正確姿勢二分法拆 graph# Step1 只跑 scale -vf scale1080:-2,formatyuv420p # Step2 加 overlay -vf scale1080:-2,formatyuv420p,overlay10:10 # Step3 加 drawtext高級技巧dump filter 中間結(jié)果ffmpeg -i in.mp4 -vf scaleiw/2:ih/2,split2[a][b];[a]null[aout] \ -map [aout] step1.yuv或直接輸出 rawvideoffmpeg -i in.mp4 -vf scale -f rawvideo -pix_fmt yuv420p out.yuv用ffplay看中間幀ffplay -f rawvideo -pix_fmt yuv420p -s 960x540 out.yuv三、第二層API 級調(diào)試libav* 項(xiàng)目必看1?. 接管 FFmpeg 日志別用 printfav_log_set_level(AV_LOG_DEBUG); av_log_set_callback(my_log_cb); void my_log_cb(void *ptr, int level, const char *fmt, va_list vl) { if (level av_log_get_level()) return; fprintf(stderr, [FFmpeg][%s] , av_default_item_name(ptr)); vfprintf(stderr, fmt, vl); }小技巧av_default_item_name(ptr)會打出模塊名[h264 0x55...] [Parsed_overlay_0]一眼知道是哪個(gè)模塊在說話。2?. 打印時(shí)間戳90% 音畫不同步的根因av_log(NULL, AV_LOG_INFO, pts%s dts%s tb%d/%d\n, av_ts2str(pkt-pts), av_ts2str(pkt-dts), st-time_base.num, st-time_base.den);推薦宏#define PTS_LOG(pkt, st) \ av_log(NULL, AV_LOG_DEBUG, %s pts:%s dts:%s\n, \ st-codecpar-codec_type AVMEDIA_TYPE_VIDEO ? V : A, \ av_ts2timestr(pkt-pts, st-time_base), \ av_ts2timestr(pkt-dts, st-time_base))3?.AVERROR一定要轉(zhuǎn)成可讀字符串新手寫法if (ret 0) printf(error %d\n, ret);正確寫法char errbuf[AV_ERROR_MAX_STRING_SIZE]; av_strerror(ret, errbuf, sizeof(errbuf)); fprintf(stderr, avcodec_send_packet failed: %s\n, errbuf);四、第三層GDB / 崩潰級調(diào)試真·硬核1?. 編譯 FFmpeg必須帶符號./configure \ --enable-debug3 \ --disable-stripping \ --disable-optimizations \ --extra-cflags-O0 -fno-omit-frame-pointer make -jRelease 優(yōu)化下 GDB backtrace 基本不可讀調(diào)試時(shí)必須關(guān) O22?. GDB 啟動 斷點(diǎn)套路gdb --args ./ffmpeg -i in.mp4 out.mp4常用斷點(diǎn)break avcodec_send_packet break av_buffersink_get_frame break avfilter_graph_config break report_and_exit看 filter 初始化失敗b avfilter_graph_config run bt3?. SIGSEGV / Assertion failed 標(biāo)準(zhǔn)流程ulimit -c unlimited ./ffmpeg ... gdb ./ffmpeg coreGDB 三板斧bt full # 看完整調(diào)用棧 frame N # 切到 ffmpeg / 你的 frame p *ctx p *frame p frame-buf[0] # 看 buffer ref 是否懸空FFmpeg 常見崩潰模式速查backtrace 特征結(jié)論libavfilter/avfilter.c:144filter 沒 unref frameff_thread_decode_frame線程 unsafe 的 codecav_malloc - abortOOM / 內(nèi)存池被吃光五、第四層性能調(diào)試卡頓 / CPU 100%1?. 先確認(rèn)瓶頸在哪一層ffmpeg -v verbose -benchmark -i in.mp4 out.mp4看結(jié)尾輸出bench: utime12.34s stime1.2s rtime5.6s現(xiàn)象瓶頸rtime ≈ utime單線程 CPUutime 很低但 rtime 很長IO / mux 阻塞filtergraph 吃滿scale / overlay 太重2?. 性能三件套看 filter 成本-vf scale1920:1080,setptsPTS,null加/減 filter 對比時(shí)間一測一個(gè)準(zhǔn)。Linux 神器 perfperf top -p $(pidof ffmpeg)看到swscale/hscale_fast→ 換zscale或 hwaccel硬件加速快速驗(yàn)證ffmpeg -hwaccel cuda -i in.mp4 -vf hwupload,scale_nppw1280:h720 out.mp4六、GUI / Overlay / Qt 場景的特殊坑你這個(gè)場景重點(diǎn)你在 Qt 里畫 OverlayWidget FFmpeg典型問題線程模型一定要對解碼線程 → AVFrame (YUV) → 拷貝 → UI 線程 → QImage/QPainter常見錯(cuò)在avcodec_receive_frame里直接QImage::loadFromDataAVFrame被 filter 自動 unref 后 UI 還在畫安全模式av_frame_ref(ui_frame, frame); // 或 copy 到 cv::Mat / QImage buffer emit frameReady();overlay filter 調(diào)試參數(shù)overlayxW-w-10:yH-h-10:formatyuv420p:eof_actionpass調(diào)試時(shí)加-vf formatyuv420p,overlay...,formatyuv420p避免swscale 在 graph 里偷偷插 3 次七、FFmpeg 調(diào)試 Checklist是否先用 ffprobe 確認(rèn)輸入文件 是否開了 -v verbose -report filtergraph 是否二分法拆解過 AVERROR 是否 av_strerror 打印 崩潰是否用帶符號版本 gdb bt full 性能問題是否確認(rèn) scale/filter 成本 多線程是否保證 AVFrame 生命周期