Move a QuickTime moov Atom Forward with qt-faststart

qt-faststart moves a QuickTime file's moov atom to the front so a player can start streaming before the download finishes. You will end up with a second file with the atom relocated; the original stays untouched. Allow about ten minutes if the input is already available and you have enough free space for a second copy.

1. Check the installed command

This guide uses the qt-faststart supplied by the Ubuntu ffmpeg package installed on this machine. The package version is 7:6.1.1-3ubuntu5+esm13. The local manual page describes two positional arguments, an input QuickTime file and an output QuickTime file. It does not document switches.

$ command -v qt-faststart
/home/linuxbrew/.linuxbrew/bin/qt-faststart
$ dpkg-query -W -f='${Package} ${Version}\n' ffmpeg
ffmpeg 7:6.1.1-3ubuntu5+esm13
$ qt-faststart --help
Usage: qt-faststart <infile.mov> <outfile.mov>
Note: alternatively you can use -movflags +faststart in ffmpeg

The help text is the useful syntax check here. Do not add options copied from another video tool. A path containing spaces must be quoted by the shell.

Checkpoint: You should have the command path, package version and two-file syntax confirmed before touching a movie.

2. Check the source and destination

Choose a destination that does not already contain a valuable file. The program reads the source and writes the destination, so the destination needs enough free space for another copy of the movie. This operation does not need sudo when both files are in a directory you can write.

$ INPUT='/path/to/source.mov'
$ OUTPUT='/path/to/source-faststart.mov'
$ test -r "$INPUT" && echo 'source is readable'
source is readable
$ test ! -e "$OUTPUT" && echo 'destination does not exist'
destination does not exist
$ file "$INPUT"
/path/to/source.mov: ISO Media, Apple QuickTime movie, Apple QuickTime (.MOV/QT)

Replace both placeholders with real paths. The final test is a useful sanity check, but do not treat the .mov suffix as proof of the file format. Keep the input file until the new file has been checked.

3. Rearrange the movie into a new file

Run the command with the input first and the output second:

$ qt-faststart "$INPUT" "$OUTPUT"
ftyp          0 20
wide         20 8
mdat         28 1416
moov       1444 918
 patching stco atom...
 writing ftyp atom...
 writing moov atom...
 copying rest of file...

The atom offsets and sizes vary with the movie. The meaningful result is that the command completes without an error and reports that it wrote the moov atom before copying the rest of the file. A non-zero exit status means you should not use the destination as a finished output.

Warning: Do not use the source path as the destination. In-place conversion is not the documented interface and can destroy the only copy before the rearrangement finishes.

4. Verify the output before replacing anything

First compare the basic file presence and type. The output should be a separate QuickTime movie:

$ test -s "$OUTPUT" && echo 'output is non-empty'
output is non-empty
$ file "$OUTPUT"
/path/to/source-faststart.mov: ISO Media, Apple QuickTime movie, Apple QuickTime (.MOV/QT)
$ ffprobe -v error -show_entries format=format_name,duration,size -of default=noprint_wrappers=1 "$OUTPUT"
format_name=mov,mp4,m4a,3gp,3g2,mj2
duration=12.000000
size=12345678

The exact duration and size depend on the input. If ffprobe is not installed, file still provides a basic check; use the player or validation tool you normally trust for the movie's content. A successful rearrangement does not repair a corrupt or unsupported source.

For a stronger placement check on a file that has not been encrypted or otherwise wrapped, inspect the first atom names with a media-aware tool. The local program's own diagnostic is also useful: the input example above had mdat before moov, while the output was written with moov first. Do not infer correctness from file size alone, because rearranging atoms normally keeps the size unchanged.

5. Replace a previous output safely

If the destination name already exists, stop before running the converter. A safe pattern is to write to a new temporary name in the same directory, verify it, then make a backup and rename it:

$ OUTPUT_NEW='/path/to/source-faststart.mov.new'
$ qt-faststart "$INPUT" "$OUTPUT_NEW"
$ test -s "$OUTPUT_NEW" && ffprobe -v error "$OUTPUT_NEW"
$ cp --preserve=all '/path/to/source-faststart.mov' '/path/to/source-faststart.mov.bak'
$ mv "$OUTPUT_NEW" '/path/to/source-faststart.mov'

Keep the backup until playback and any downstream processing have succeeded. If verification fails before the mv, leave the old output in place and remove only the incomplete .new file after checking its exact path. If the replacement is bad after the rename, restore the backup with mv -- '/path/to/source-faststart.mov.bak' '/path/to/source-faststart.mov'. That recovery overwrites the bad replacement, so confirm both paths before running it.

6. Diagnose the common failures

An error opening the input usually means the path, permissions or file type need checking. An error writing the output can indicate a full filesystem, a read-only directory or an existing destination that cannot be replaced. Check these without escalating privileges:

$ ls -l -- "$INPUT" "$OUTPUT"
$ df -h -- "$(dirname -- "$OUTPUT")"
$ test -w "$(dirname -- "$OUTPUT")" && echo 'destination directory is writable'

If the input has no usable moov atom, is truncated, or uses a structure the utility cannot rearrange, preserve it and investigate with ffprobe or the application that produced it. Do not repeatedly overwrite the same destination while troubleshooting.

For new encoding jobs, the installed help text points to FFmpeg's -movflags +faststart option as an alternative. That is an FFmpeg encoding or remuxing workflow, not an extra option for qt-faststart. Use the separate command only when you have checked its input, codecs and output requirements.

Done means