Compress video to a target size

Most compression tools do what you ask. You point them at a file, they re-encode it, and they hand you back whatever comes out, including when whatever comes out is bigger than what you started with.

Short version. Three of seventeen cases refused to encode at all. The job worked out that re-encoding an already-efficient file would make it larger, and returned the original untouched.

The passthrough verdict#

Our source is a 343.9 KB five-second clip that was already encoded sensibly. Ask for visually-lossless and the honest answer is that there is nothing to win.

The job reached that answer the expensive way, by trying. It ran three probe encodes, scored them, found that hitting the quality target would cost more bytes than the original already spends, and returned passthrough.

Only efficient, the posture that explicitly accepts lower quality, actually compressed: 295.1 KB at VMAF 89.0, a 14% saving.

This matters more than it sounds. A pipeline that re-encodes everything on upload will, on a meaningful fraction of already-optimised files, spend money to make them worse and larger. Both losses are silent. The file still plays.

The dry run was right, twice#

dryRun returns a predicted size, quality and cost without producing output. Two predictions, checked against the real runs:

On the byte target it was exact, to the byte and to the decimal.

On balanced it predicted 371.8 KB against a 343.9 KB original, which is the prediction that re-encoding would grow the file. The real run agreed by refusing to do it. The two are consistent: the dry run tells you what an encode would produce, and the real run applies the judgement about whether that is worth shipping.

Being able to ask “what would this cost me” without paying for the encode is unusual, and on this evidence the answer can be trusted.

effort: fast is not a small compromise#

fast cost 17 VMAF points against balanced. That is not a subtle difference; it is the difference between poor and mediocre.

thorough bought back only 1.8 points over balanced for slightly more time and bytes. So the curve is steep at the cheap end and flat at the expensive end, which is a common shape and a useful one: do not use fast, and do not bother with thorough unless the content is going to be watched a great many times.

The floor#

Two cases asked for ceilings the source could not meet. maxBytes 100 KB and maxBytes 50 KB returned the same 111.5 KB file at VMAF 30.7.

The job returned a low verdict rather than a smaller file, because there was no smaller file to return at that codec and resolution. Asking for half as much did not move the floor.

VMAF 30.7 is unusable by any standard. The row is worth publishing anyway, because an API that always returns exactly the size you requested is either lying or destroying your content, and it is better to see the refusal than to discover the damage later.

What this is really about#

A compressor that always compresses is easy to build and easy to trust incorrectly. The useful behaviours are the ones where it declines: refusing to grow a file, reporting a floor it cannot pass, and telling you in advance what an encode would produce.

None of those show up in a feature list. They show up when you run seventeen cases and read the verdict column.

Where this stops#

One source, seventeen cases, 92 probe encodes, $0.26 to measure. The passthrough result is a property of this file being already well encoded; point the same postures at a bloated export and every one of them will compress. That is the point, though. The job decides per file, and the only way to know which case you are in is to let it look.

The practical version#

How to compress video to a target size covers the commands, the bitrate formula and its failure mode, with the measured distribution behind them: 120 jobs, 667 probe encodes, and a median compression ratio of only 1.41x.