Module plan 

The pure half of the media engine: planning an encode (video bitrate under a size target, quality mode, resolution / fps caps, the audio decision, output container, metadata tags) and the small calculations the run loop uses (the size-target ceiling, overshoot corrections). No ffmpeg — this is what builds without the ffmpeg feature (e.g. for iOS).

Constants

CEILING_MARGIN

How far under the target a predicted CRF encode must land to be used instead of the budget (predictions are within ~5%).

MIN_SAMPLE_SECS

The shortest window for heavy video (4K, 60 fps): measured on a 60 s 4K60 iPhone clip, 1.5 s windows predicted as well as 3 s (+3.3 % vs +3.8 %) in half the time; 1 s drifted to +7 %.

SAMPLE_BIAS

Each sample starts on a keyframe, so samples over-predict by ~8–10% (a 30 s phone clip: 20.4 MB predicted vs 18.7 MB real) — scale that back.

SAMPLE_BIAS_HW

The same for Apple’s hardware encoder, which over-predicts far less: measured on 6 clips × H.264/HEVC (4K60 HDR, 4K30, 720p; the iOS app’s VideoToolbox path, identical on Mac and iPhone), unbiased samples ran 0.88– 1.12 of the real size, mean 1.03; 0.97 puts 11 of 12 within ±10 % (0.92: 8).

SAMPLE_SECS

Sample window length for predicting a CRF encode (see sample_windows).

Functions

ceiling_plan

A size-target plan re-cast as a single-pass CRF encode at the quality preset’s CRF (EncodePlan::ceiling_crf). None for anything else.

corrected_bitrate

The video bitrate for a re-run after an encode of size bytes overshot target: scaled down in proportion, with 3 % headroom. None below the encoder’s floor (no point re-running).

plan

Plan an encode — the pure half of super::Engine::plan, with no ffmpeg: hw_available says whether Apple’s hardware encoder may be used (the media engine asks ffmpeg; another platform asks its own encoder).

predicted_bytes

The predicted final size of plan from its sample encodes: video_bytes of video-only output over sampled_secs, scaled by bias, plus the planned audio and container overhead.

sample_secs

Sample window length: 3 s up to 1080p30, shorter as the pixel rate grows (4K60 → 1.5 s), so a preview of heavy video doesn’t take a minute.

sample_windows

The windows (start, length) in seconds to sample-encode for predicting a quality-mode (CRF) encode’s size, and the bias to apply to their bit rate. Long clips: three windows at 20/50/80 %; short ones (under four windows): the whole clip once — exact, so no keyframe bias to correct. The bias is the encoder’s (SAMPLE_BIAS, or SAMPLE_BIAS_HW for Apple’s).

to_utc

2026-09-26T20:01:54+0300 (also +03:00, Z, fractional seconds) → 2026-09-26T17:01:54Z. None if it doesn’t parse.