Skip to content

Put the MP4 index at the front of the file with +faststart - #143

Merged
zfleeman merged 1 commit into
mainfrom
zf/mp4-faststart
Nov 6, 2026
Merged

zfleeman merged 1 commit into
mainfrom
zf/mp4-faststart

Conversation

@zfleeman

@zfleeman zfleeman commented Nov 6, 2026

Copy link
Copy Markdown
Owner

Closes #140.

ffmpeg writes an MP4's index (the moov box) after the video data, because it doesn't know where each frame lands until the encode finishes. A player streaming the file from a link (Discord, a browser) has to fetch the end of the file before it can start. -movflags +faststart makes ffmpeg move the index to the front when it finishes, so playback can start from the first few kilobytes.

Change

TwoPass._generate_params() adds "movflags": "+faststart" to the second pass for every MP4 codec. It uses the same "vp9" in codec rule as _output_filename(), so the two can't disagree about which files are .webm. The first pass writes to a null output and doesn't get the flag. +faststart has been in ffmpeg since 2013, so there's no version check.

The flag shows up in the printed and --dry-run commands on its own.

Checked

A real 5-second x264 encode of a phone clip lists its top-level boxes as ftyp, moov, free, mdat (before: ftyp, free, mdat, moov).

Tests

test_twopass.py: for every codec in CODEC_ENCODERS, the last pass has -movflags +faststart unless the codec is vp9, and no earlier pass has -movflags.

@zfleeman
zfleeman merged commit 45949ef into main Nov 6, 2026
6 checks passed
@zfleeman
zfleeman deleted the zf/mp4-faststart branch November 6, 2026 01:55
@zfleeman zfleeman mentioned this pull request Nov 6, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Put the MP4 index at the front of the file with +faststart

1 participant