anthwlock/untrunc: repairing truncated MP4 and MOV files with a healthy reference video

What problem untrunc solves, and who has that problem

An MP4 or MOV file is a container: media samples are stored in one region and an index (the moov atom) describes where each sample sits, how long it lasts and how it is coded. Cameras and recorders usually write that index at the end of the recording. If the power fails, the card is pulled, or the process is killed, the media data may be on disk while the index is missing or cut short. The file will not open in a player, and a plain remux with ffmpeg has nothing to remux against.

untrunc addresses exactly that case. The README describes it as restoring a damaged (truncated) mp4, m4v, mov, 3gp video, and it states the precondition plainly: you need another video file which isn't broken. The tool takes the sample structure of the healthy file and reuses it to reconstruct the index of the broken one. The intended user is someone with a camera, a drone or a recorder that produced one bad clip and at least one good clip from the same device and settings. The README adds a candid qualifier: and some luck.

How the reference-file reconstruction actually works

The input is a pair: a working file and a broken file. The working file supplies the container layout and the codec parameters that the broken file is missing. The broken file supplies the media payload, which is usually intact up to the point where recording stopped. The tool walks the healthy file's track and chunk structure and applies it to the damaged file's bytes, producing a new file whose index points at the real samples.

This fork, according to the README, changes several things in that pipeline relative to ponchio/untrunc. It claims to be more than 10 times faster and to use low memory, which matters because the original approach loaded large amounts of data. It adds support for files larger than 2GB, the ability to skip over unknown bytes, generic handling of all tracks with fixed-width chunks such as twos and sowt, handling of invalid atom lengths, and support for GoPro and Sony XAVC videos. It can also stretch or shrink video to match audio duration, which is a post-reconstruction correction rather than a repair of the container itself. A logging system is exposed through the -v parameter. The README notes that for FFmpeg versions later than 8.1, struct definition mismatches can occur if upstream changes the internal FFCodec struct, and points to src/ff_internal.h; that is a build-time coupling to FFmpeg internals, not an abstraction the project controls.

Installing untrunc on Linux, macOS and Windows

On a Debian or Ubuntu system with system FFmpeg libraries, the README gives these commands. The first line installs the development packages, then make builds the binary from the repository sources, and the last line copies it into the path.

sudo apt-get install libavformat-dev libavcodec-dev libavutil-dev
make
sudo cp untrunc /usr/local/bin

If you prefer a pinned FFmpeg instead of the system one, the README offers a target that downloads and builds a specific version. The README states that untrunc works great with ffmpeg 3.3.9, and the Makefile maps targets such as untrunc-33, untrunc-60 and untrunc-81 to FFmpeg 3.3.9, 6.0 and 8.1 respectively.

sudo apt-get install yasm wget
make FF_VER=3.3.9
sudo cp untrunc /usr/local/bin

On macOS with Homebrew, the README supplies flags so that Homebrew headers are found while local FFmpeg headers take precedence.

brew install ffmpeg yasm
CPPFLAGS="-I/opt/homebrew/include" LDFLAGS="-L/opt/homebrew/lib" make

For Windows, the README directs users to the automated builds on the releases page rather than a local compile. A Dockerfile is also present: it builds in an Ubuntu 22.04 stage, strips the binary, and copies it into a runtime image that runs as a non-root user with /bin/untrunc as the entry point. The README shows the build and a run that mounts a host video directory at /mnt.

docker build -t untrunc .
docker image prune --filter label=stage=intermediate -f
docker run --rm -v ~/Videos/:/mnt untrunc /mnt/ok.mp4 /mnt/broken.mp4

A snap package is also published: the README gives sudo snap install --edge untrunc-anthwlock.

A first repair run, and the optional libui GUI

The usage pattern is two positional arguments, healthy file first, broken file second. The README's own example uses m4v files and states that the tool should churn away and hopefully produce a playable file named after the broken one with a _fixed suffix.

./untrunc /path/to/working-video.m4v /path/to/broken-video.m4v

After the run, look for broken-video_fixed.m4v next to the input. If the result does not play, the README's support guidance is to rerun with -v for a more detailed output and to keep both the healthy and the corrupt file, since those may be needed to investigate.

./untrunc -v /path/to/working-video.m4v /path/to/broken-video.m4v

The GUI is optional and is built separately. It is included in the automated Windows builds, and building it yourself requires libui, after which make untrunc-gui produces the graphical binary. The README does not describe the GUI's workflow beyond that, so treat the command line as the documented path and the GUI as a convenience layer.

Where untrunc fails, and when it is the wrong tool

The reference-file requirement is the hard boundary. The README says the example working video should ideally be from the same camera, and that if it is not, the chances to fix it are slim. That is not a disclaimer bolted on at the end; it is the mechanism. A reference from a different device can have a different track count, different codec parameters and a different chunk layout, and applying it to your bytes produces a file that still will not decode correctly.

Truncation is also a narrower diagnosis than most people assume. If the moov atom is present but the media data is overwritten, zeroed or partially lost, there is nothing for the reconstructed index to point at. If the card was formatted or the file was copied with an interrupted transfer, the damage is not a missing tail. untrunc reconstructs structure; it does not recover missing payload.

The build side carries its own risk. The README warns that for FFmpeg versions later than 8.1, changes to the internal FFCodec struct can cause struct definition mismatches and potentially undefined behaviour. That means a successful compile against a very new FFmpeg is not proof of a correct binary. Pinning to one of the versions the Makefile targets, or using the container image, is the more predictable route. Finally, the README itself frames the outcome with some luck, and no success rate is documented anywhere in the repository, so a failed run on one file says nothing about the next.

untrunc against generic ffmpeg-based repair

The obvious alternative is ffmpeg itself, which most people already have. The difference is what each tool knows. A command such as ffmpeg -i broken.mp4 -c copy out.mp4 asks ffmpeg to read the container and rewrite it; if the moov atom is missing or truncated, there is no index to read, and the operation fails or produces a file with no usable duration. ffmpeg assumes a valid container and works from it.

untrunc inverts that assumption. It treats the healthy file as the specification of the container and the broken file as the payload, which is why it can produce output where a remux cannot. The cost is the dependency on a matching reference and the fact that the tool is coupled to FFmpeg's internal structures at build time rather than only to its public API. If your file is intact and merely in the wrong container, use ffmpeg. If your file is truncated and you have a sibling recording from the same camera, that is the case untrunc exists for.

Licence, maintenance and the cost of upgrading

The repository is licensed GPL-2.0, with COPYING at the top level. If you redistribute a binary built from this source, or ship it inside a product, the GPL obligations attach to that distribution; that is a question for your own legal review, not something this article can settle. Using it internally to repair your own footage is a different situation from embedding it.

The last push to the repository was on 2026-08-21, so the codebase is not dormant, but the latest tagged release dates from 2020-03-24. In practice that means the Windows builds and the snap channel may lag the source, and anyone who wants current behaviour should build from the master branch rather than trust the release artifact. Upgrading is not free: the Makefile pins FFmpeg versions through targets like untrunc-33 and untrunc-81, and the README's warning about FFCodec struct changes means that moving to a newer FFmpeg can require source changes. The safest upgrade path is to rebuild against a version the Makefile already names, or to use the Dockerfile, which defaults to the shared system libraries and accepts FF_VER as a build argument.

Editorial conclusion

Adopt anthwlock/untrunc when you still have a healthy clip from the same camera and you can build the binary from source or accept the automated Windows build; it is the practical choice for a truncated recording that ffmpeg refuses to open. Do not adopt it when you have no reference file, when the damage is not a truncation but a corrupted or overwritten middle section, or when a commercial repair service with a support contract is the requirement. Before you rely on it, run the binary with -v on a copy of the broken file, confirm the output plays end to end, and check whether your system ffmpeg version is one of the ones the Makefile targets, because a struct mismatch in FFCodec is documented as a source of undefined behaviour.

Frequently asked questions

Official sources

1. anthwlock/untrunc on GitHub
2. Issues
3. License: GPL-2.0
4. README
5. Releases