简介untrunc 是一套基于 C 编写的视频文件修复工具源码面向 Linux 命令行使用者和音视频开发人员用来修复录制中断、传输截断导致损坏的常见视频如 MP4、M4V、MOV、3GP 文件M4A 等音频也可通过类似方式处理。使用时需另备一个同源未损坏的视频作为参考并具备基本编译能力。工程内包含完整代码共 42 个文件主体是 23 个 C 源文件和 10 个头文件分模块覆盖 H.264、AAC、MPEG-4、HEVC 等编码格式的原子解析与重建逻辑同时附带 Qt 工程文件、Dockerfile 与说明文档便于在 IDE 中调试代码、快速搭建 Linux 构建环境是研究 MP4/MOV 容器结构、Libav 内部头文件调用方式的轻量样板能直观展示此类工具从输入解析到输出重建的完整流程。对于刚接触视频封装格式的读者也可通过阅读源码理清 MP4 原子结构。资源包仅 72KB模块划分清晰已有 1668 人学习浏览适合需要深入视频封装层排查问题或二次开发的工程师收藏参考。1. 截断的 mp4 为什么会打不开untrunc 修的其实是缺失的“骨架”手机录视频录到一半没电文件留在存储卡里拷到电脑上播放器直接报损坏或者进度条拖不动。这类文件圈里叫“截断的 mp4”坏的多半不是画面数据而是文件尾部的 moov 索引没写全。untrunc 的做法是拿一个同类型、没中断过的 mp4 当模板把损坏文件的帧重新对齐补出可播的新文件对 mp4、m4v、mov、3gp 都适用。MP4 的索引块 moov 通常在文件末尾录制中断时它没写全画面数据 mdat 其实大多还在。播放器找不到骨架就把整个文件判死修复的关键是把骨架重建出来这正是 untrunc 做的事。下面从容器结构讲到命令行最后给你几条现实里最容易踩的坑。2. 先说透 moov 与 mdat为什么 untrunc 需要一个“同款”参考视频2.1 MP4 的骨架长在文件尾巴上截断丢的就是骨架MP4、m4v、mov、3gp 这四种后缀看着不一样底层都源自 MPEG-4 Part 12 的 ISO BMFF 容器区别主要在扩展名约定和部分兼容性限制。理解 untrunc 怎么工作先从容器布局说起。一个正常写完的 MP4 会包含几个关键 boxftyp文件类型、mdat音视频样本数据、moov元数据索引。moov 通常被写在文件末尾里面装的是 trak、stbl 这些子结构以及一张记录“每个样本放在哪、多大、什么时间戳”的表。播放器打开文件后先去尾巴找 moov找到这张表才能定位 mdat 里的每一帧。截断文件的情况恰恰相反录制设备是一边写 mdat 一边累积数据等到正常停止时才把 moov 刷到磁盘。如果中途断电或拔出存储卡moov 要么不存在要么只写了一半。数据帧在现场基本都还在但播放器没有索引不知道从哪个字节开始读、读到哪算一帧于是整个文件被判定损坏。用一张表列出这些索引项缺失时的典型症状排查时会很有用moov 里缺的东西负责的 box播放器典型表现样本偏移stco / co64时长显示 0纯黑画面样本大小stsz跳转失效进度条乱跳时间戳stts / ctts花屏音画不同步关键帧位置stss拖进度条后卡住转圈2.2 参考视频为什么必须是“同款”帧结构决定了恢复成败untrunc 的思路不是凭空猜索引而是拿一个“没坏的同款视频”当尺子量出损坏文件中每个样本的边界。它先完整解析参考视频的 moov得到一组 frame size 序列和时间戳节奏然后去损坏文件里按这套节奏扫描 mdat找到实际数据后重建一份新的 moov 写进输出文件。这意味着参考视频与损坏视频的“录制指纹”越接近扫描越准。“类似”这个词具体指什么常见要求有三点编码器一致都是 H.264 就都 H.264拿 H.265 当参考会全盘错位、分辨率与帧率一致、GOP 结构一致关键帧间隔相同。至于画面内容是不是同一个场景完全不重要重要的是帧边界节奏。参考视频在理论上是“类似”的就够了但实际恢复时我一般倾向于“尽量同款”同样设备、同样 App、同样设置录出来的另一个视频是首选比如行车记录仪的循环片段、监控摄像头同一通道的过往文件。因为这类设备经常用固定 GOP 和固定码率录制帧序列几乎一模一样untrunc 的扫描准确率最高。如果只能拿到一个别人拍的旅游视频但分辨率和帧率对上了也值得试——H.264 的帧结构并没有想象中那么大的差异。参考视频不需要和损坏文件同样长。untrunc 只需要从头开始稳定解析几十到几百个样本就能建立结构模型所以参考视频只留前几十秒往往够用。但有一个前提参考视频本身必须完整可播不能也是截断的否则它输出的 frame size 序列本身就是错的恢复出来的文件自然更糟。2.3 没有现成参考视频时最稳的三个替代方案第一如果损坏文件本身是手机录的去云相册或微信传输记录里找同一个时间段的其他视频哪怕是几秒的 Live Photo 片段也经常能匹配上。第二用 ffmpeg 把损坏文件当成输入硬读一遍有时候 moov 没全坏ffmpeg 的 -c copy 能直接重封装出部分可用文件这时重封装结果本身就是很好的参考“参考”不需要是原始截断文件。第三到专门提供 mp4 测试样片的地方下载同分辨率同码率的通用样片虽然内容不同但 H.264 的 frame size 节奏与多数实拍视频差别不大属于“没有更好选择时的兜底”。这里要提醒一句参考视频的时长和内容在 untrunc 眼里只是样本真正重要的是编码层参数。你在 ffprobe 里能看到的分辨率、帧率、profile、level 才是判断“同款”的关键。不要把大量时间花在找同一场景的视频上先对着 ffprobe 输出把编码参数对齐成功率提升立竿见影。mp4 测试样片这类资源真正有用的地方也在参数匹配而不是画质好坏。如果手头一个相似视频都没有也不要直接放弃。先把损坏文件用 ffprobe 试读能看到任一视频流就说明 mdat 还在恢复就有基础。接下来按这一节的替代方案排序从 ffmpeg 重封装开始试比盲跑 untrunc 更容易得到能用的素材。2.4 ffprobe 体检30 秒判断这个文件有没有救损坏文件拿回来第一步不是立刻跑 untrunc而是先做一次“体检”。ffprobe 是最直接的检查工具ffprobe -v error -show_entries streamcodec_name,codec_type,duration,width,height -of json damaged.mp4这条命令会尝试解析文件里的所有流信息。正常文件会输出视频流和音频流各自的编码名、时长、宽高截断文件通常会直接报 moov 相关的错误。如果命令能列出视频流哪怕没有时长也说明 mdat 里有一部分数据可读恢复希望很大。如果连一个流都列不出来也不代表没救——有些记录仪的写入顺序是 moov 完全在尾部文件系统已经把文件识别成不可读ffprobe 看不见 mdat 里的数据。遇到后面这种情况先别急着跑 untrunc用十六进制查看工具查一下文件尾部有没有 ftyp 或 moov 字样确认容器结构是否完整。如果 ffprobe 能列出视频流但音频流缺失说明 moov 部分写入了mdat 可能完整恢复成功率会高一些。如果连分辨率和帧率都能读出来那这个文件也许不需要 untrunc直接用 ffmpeg -c copy 重封装可能就够了。体检的意义在于判断损坏程度、确认编码参数并顺便拿到修复后应当对齐的分辨率、帧率。这个信息在找参考视频时同样用得上。3. 跑通 untrunc 的最小命令从编译到输出可播放文件3.1 在 Ubuntu 上用源码编译 untrunc依赖只有三个库untrunc 本身是个很轻的命令行工具源码基于 ffmpeg 的 libavformat 和 libavcodec 库拿到源码后编译步骤很简单。我一般在干净的 Ubuntu 环境上这样做sudo apt update sudo apt install -y build-essential libavformat-dev libavcodec-dev libavutil-dev cd untrunc make依赖里 build-essential 提供 gcc 和 make另外三个 libav 开头的库负责解析容器和视频编码流。untrunc 的 Makefile 很简单只要头文件和库路径能被编译器找到就能编过一般不需要再配 pkg-config。个别发行版还会提示缺 libz-dev遇到时补上即可。编译完成后当前目录会出现一个 untrunc 可执行文件。进了源码目录但 make 失败时先看报错是不是缺头文件而不是代码问题——大多数所谓“编译失败”其实是依赖没装全。我在服务器上第一次编译时就因为少了 libavutil-dev 卡了半天输出报错全是“av_xxx 未定义”补装依赖后一分钟编完。编译完别忘了检查文件是否有执行权限。如果是从 Windows 传到 Linux 的源码包偶尔会出现换行符或权限问题导致 make 报错用 dos2unix 处理源码文件是常见办法。这一步不复杂但值得单独讲因为 untrunc 的新手教程很少提编译环境。3.2 最小恢复命令参考文件加损坏文件输出文件会多一个 _fixed 后缀编译完就能跑了。最基础的命令只需要两个位置参数第一个是参考视频第二个是损坏视频。./untrunc reference.mp4 damaged.mp4命令执行后untrunc 会先解析 reference.mp4 的 moov打印出视频流和音频流的基本信息接着进入 scanning 阶段在 damaged.mp4 的 mdat 里逐帧扫描匹配最后输出一个新文件。输出名是在损坏文件名基础上加_fixed后缀比如 damaged_fixed.mp4原文件不会被覆盖。这个设计很实用跑失败了原文件还在随时可以换参数重来。我个人习惯第一次跑就加 -v 参数把详细日志留下来定位问题会快很多./untrunc -v reference.mp4 damaged.mp4-v 开启 verbose 模式会打印解析参考文件时看到的每个 box 名字以及扫描损坏文件时每找到一组样本的偏移量和大小。日志里如果出现类似“sample size too large”的提示基本可以判断参考与损坏文件的帧结构不匹配后续结果不会好及时换参考重跑别等输出。另外untrunc 的命令行选项不复杂跑之前用 -h 看一眼最稳妥。不同修改版的选项不完全一样但常见的就是 -v 详细日志和 -m 这类控制扫描范围的参数。网上很多“修复失败”的案例最后发现是加了一个参考文件根本不支持的参数新手尽量保持最小命令先跑通再调参。3.3 用 ffprobe 校验输出文件时长、分辨率、帧率一项项打勾修复完不要直接拿去剪辑软件里用先做一次快速体检。untrunc 能跑通不代表结果正确尤其是参考文件匹配度不高时输出文件可能只有几秒、帧率错乱或者没有音频。我先用 ffprobe 看基本参数ffprobe -v error -show_entries formatduration,size -of json damaged_fixed.mp4 ffprobe -v error -select_streams v:0 -show_entries streamcodec_name,width,height,r_frame_rate -of json damaged_fixed.mp4第一条命令看输出文件的时长和文件大小第二条看视频流编码、分辨率和帧率。把这两项和参考视频对比编码名字、宽高、帧率不一致的说明扫描阶段已经错位修复结果不可信。时长方面损坏文件的时长理论上应该接近参考视频的“结构总时长”但如果你录制的是间断内容也可能偏短需要结合播放器预览判断。ffprobe 只能证明索引能被读出来真正要过的是播放器这关。我用本地播放器打开输出文件依次做三件事从头播放 10 秒看画面是否正常拖动进度条到 30%、70% 位置看是否秒开有音轨的话听一段是否与画面同步。拖进度条这个动作特别能暴露 stss 和 stco 的错误如果损坏文件的数据段本身完好修复后的视频应当能正常跳转。修复完成后建议顺手把输出文件的 moov 挪到文件头方便后续在网络播放或剪辑工具里更快打开。这一步用 ffmpeg 重封装ffmpeg -i damaged_fixed.mp4 -c copy -movflags faststart finalized.mp4-c copy 不重新编码只调整容器结构把 moov 前置。这一步同时还能校验文件整体是否可读如果 ffmpeg 在这一步报错说明修复结果并没完全通过回到更换参考视频这步重跑。最后不要急着删损坏文件等所有校验通过再清给自己留点后悔药。提示ffprobe 读不出来不代表文件没救先看文件尾部有没有 moov 残留再决定跑不跑 untrunc。4. 避坑untrunc 恢复视频的 5 个高频翻车现场4.1 输出文件只有几秒画面在第一个关键帧后卡死现象命令正常跑完输出文件生成但播放器里只看得到开头一两秒之后黑屏或定格。原因扫描阶段匹配了参考视频的 frame size 序列但损坏文件的后续数据可能已经错位也可能录制时插入了分段导致后续帧没被正确映射。这类情况在行车记录仪素材里特别常见断电后的文件往往分段写在存储卡不同区域untrunc 只按连续结构扫描遇到分段就断了。解决先换一个更“同款”的参考视频重跑优先选同设备同录制设置的文件。如果换参考还不行用 ffmpeg 先把损坏文件重封装一轮再以重封装结果为输入尝试恢复。卡死位置前后的数据损坏程度不同untrunc 的恢复率也随之变化不要指望一次成功。4.2 日志卡在 scanning 阶段半小时不退出现象命令行停在这一阶段CPU 占满输出文件迟迟不出现。原因untrunc 要对损坏文件的每个字节区间做匹配文件越大扫描越久。存储卡损坏严重时无效数据区域会拖慢匹配速度直接从 USB 读卡器扫描时IO 延迟还会让等待时间成倍拉长。解决先把损坏文件复制到本地固态盘避免从读卡器直接扫描。然后看一下参考视频是否设置的帧率过高比如 60fps 样本庞大考虑用 ffmpeg 把参考视频降到与目标一致的帧率。最后确认没有参数把扫描范围撑大必要时用 -h 查看当前版本的扫描控制参数限制范围。扫描慢不是死锁多数情况下耐心等待半小时左右会有结果。4.3 画面恢复了但输出文件没有声音现象修复后的 mp4 有画面没声音音轨完全缺失剪辑软件里也看不到音频波形。原因untrunc 原始版本的数据重建重点是视频流对 AAC 音频流的支持取决于源码分支和版本。很多设备录制音频时使用交错写入截断后音频样本边界更难重建所以画面能修、声音修不回来是常态。解决优先选用带音频恢复功能的分支版本社区维护的 untrunc-av 等增强版就是为这个场景准备的。其次可以把受损文件中还有效的音轨抽出来再混流试着这样处理ffmpeg -i damaged_fixed.mp4 -i damaged.mp4 -map 0:v -map 1:a? -c:v copy -c:a aac -shortest out.mp4这条命令能成立的前提是损坏文件的音频流能被 ffmpeg 识别。如果完全读不到只能接受无声版本这也是截断恢复的局限。4.4 能播放但拖动进度条就花屏或转圈现象顺序播放正常一跳转就出现绿屏、花屏或者加载图标。原因stss 关键帧表重建得不完整播放器跳转时定位到非关键帧解码器没有参考帧可用。换句话说关键帧表是错的但参考帧本身还在数据区里。解决先试一次重封装加上生成时间戳的选项ffmpeg -fflags genpts -i damaged_fixed.mp4 -c copy -movflags faststart out.mp4如果重封装后跳转依旧有问题说明关键帧表错得比较彻底回到参考视频选择这一环把参考视频的 GOP 参数与损坏文件对齐后重跑 untrunc。跳转问题在恢复工具输出里很常见不是媒体数据坏了而是索引细节没补齐。4.5 随便找了个不相关视频当参考跑完发现输出文件还是坏现象命令不报错输出文件也能打开但画面全是花屏或者播放几秒就断。原因参考视频与损坏视频的编码结构差异太大比如一个是 H.264 高清、一个是 H.265 低码率frame size 节奏完全对不上重建出来的 moov 是错位拼接。untrunc 对参考视频的匹配程度有一种说不清的玄学成分但根本因素还是编码参数是否接近。解决先不要着急跑 untrunc用 ffprobe 确认参考与损坏文件的编码器、分辨率、帧率三项。差异大的先转码参考视频到相同参数参考只是结构模板转码不会损害它的模板作用。这一条是新手最容易踩的以为“能跑通就等于能修复”实际 untrunc 对参考质量极其敏感宁可多花两分钟处理参考也不要拿毫不相关的视频硬跑。5. 提高恢复率的技巧先把参考视频和损坏文件预处理到位再跑 untrunc到这一步你已经知道 untrunc 的原理、命令和翻车点了。最后一个建议是别把参考视频从素材库拖出来就直接跑先花两分钟预处理恢复成功率会有肉眼可见的提升。第一个技巧把参考视频的编码参数强制转成与损坏文件一致。用 ffprobe 读出损坏文件的宽高和帧率然后用 ffmpeg 转码参考视频ffmpeg -i reference.mp4 -vf scale1920:1080,fps30 -c:v libx264 -preset veryfast -g 30 -pix_fmt yuv420p ref_prepared.mp4这条命令把参考视频统一成 1920x1080、30fps、GOP30 的 H.264 文件。scale 和 fps 对齐分辨率与帧率-g 30 把参考的关键帧间隔固定为 30 帧这对许多固定 GOP 的录制设备来说正好匹配。preset 用 veryfast 就够了参考模板不需要高画质编码结构才是关键。第二个技巧损坏文件头部也受伤时先用 ffmpeg 的容错模式尝试直接重封装ffmpeg -err_detect aggressive -i damaged.mp4 -c copy recover_try.mp4如果能出可播文件就省掉 untrunc 这一步如果只能出几秒也把它留在磁盘上后续可以用它辅助判断原文件的真实时长。别小看这几秒它比任何参考视频都更接近损坏文件的真实录制参数。第三个技巧跑完 untrunc 后不要急着覆盖原文件先对比时长确认无误后再清理。我自己的习惯是每修一批文件都保留参考视频、预处理后的参考文件、untrunc 输出、ffmpeg 重封装版四个文件直到素材交付才删除。早期我为了省磁盘空间跑完就删参考结果后续发现输出文件在某个播放器上跳转异常想再修就得重新找参考白白浪费了时间。希望帮到你。本文还有配套的精品资源点击获取
