fix(cli): a re-encode of a media file over the cap is limited to fit it - #7376

What

hyperframes cloud render re-encodes a media file the asset API caps, at crf 18. crf bounds quality, not size, so a source over the 200 MiB cap can come out of a long encode still over it, and the render then fails with Media upload failed: ... is N MB after re-encoding at visually lossless quality, over the 200.0 MB a HeyGen asset can hold. The person waits through the whole encode and then gets the refusal.

Why

The encode's size depends only on the quality target, so any re-encode can end over the cap and be refused after the whole encode. The cap is known before the encode starts, so the encode can be bounded by it.

How

Every video re-encode (x264, x265 and VP9) adds -maxrate and -bufsize for 85% of the cap over the clip's length (the trimmed length when only played segments are kept), less the preset's audio bitrate. crf stays the quality target, so the limit only bites where crf alone would exceed the budget; a source under the cap is covered too, because a file in an efficient codec can leave an x264 crf 18 encode larger than itself. On a very long video the one-second limit can also clamp a short peak that would have fit on average. VP9 (the alpha preset) takes the same rate as -b:v, because its -b:v 0 constant-quality mode ignores -maxrate. Audio and images are unchanged. sizeLimitArgs in cloud/offload.ts owns the arithmetic.

The buffer is one second on purpose: an average-bitrate target (-b:v at 95% of the cap with a 2 s buffer) overshot the cap on a 10 s noise clip (217 MiB against 200 MiB), so the limit is a one-second VBV cap on top of crf, not an average-bitrate target.

Test plan

• cloud/offload.sizeLimit.test.ts: the arithmetic (200 MiB over 100 s with 320 kbit/s audio gives 13940k) and no limit when audio fills the budget; a real ffmpeg run on an 8 s noise clip that crf 18 alone leaves over a 1 MiB cap and the limited encode fits; limitFor limits any video by its (or its cut's) length, leaves audio and images alone, and adds -b:v for VP9. fails without the fix: without sizeLimitArgs the file does not import, and with the limit removed from the args the second case is over the cap.

• All 16 files under src/cloud/ pass (180 tests), on Linux with ffmpeg.

• Real repro through the CLI source (bun, stub API, no key): a 10 s 1920x1080 noise mp4 of 513 MiB. On main the re-encode ran 131 s and failed with 302.4 MB after re-encoding ... over the 200.0 MB. On this branch the same project passes the size check (the run then stops at the stub API's upload, which has no upload URL), in 77 s.

• Unit tests added/updated

• Manual testing performed

• Documentation updated (not applicable)

• Comments follow CONTRIBUTING.md "Comments"

Not exercised: the HDR (x265) and alpha (VP9) presets against a real over-cap source, a source whose audio is long and large, and Windows and macOS ffmpeg builds.