Perceptual video compression under explicit quality and size constraints.
QualityBound analyzes a video before encoding, searches for an operating point that satisfies a perceptual-quality target, and verifies the result on content that was not used during the search.
Instead of guessing a CRF value, specify the constraints:
VMAF >= 90
output <= 50% of source
QualityBound then searches for a viable AV1 or HEVC encode and checks the final file before publishing it.
Download the latest release for Windows x86-64/ARM64, Linux x86-64/ARM64, or macOS Apple Silicon. Tagged packages include a compatible FFmpeg and FFprobe build. Assets published before the QualityBound rename retain their original filenames.
The macOS release is ad-hoc signed rather than notarized. Gatekeeper may require right-clicking the application and choosing Open. Linux packages require a reasonably recent glibc distribution.
CRF is an encoder setting, not a perceptual-quality measurement. The same CRF can produce very different quality and file sizes on different sources. A fixed bitrate makes size more predictable, but does not guarantee quality. Repeated whole-file trial encodes can answer both questions, but at high cost.
QualityBound treats the desired perceptual quality and file size as constraints:
- Scout scans the timeline for spatial complexity, temporal complexity, and scene boundaries.
- Search windows combine difficult content with coverage across the timeline.
- Candidate encodes are measured with Netflix VMAF.
- Separate holdout windows validate the selected bitrate.
- A failed holdout becomes a search constraint and the search resumes upward.
- The completed encode is published only after its actual size is validated.
Search and validation windows do not overlap. The samples used to choose a bitrate are not the same samples used to validate it.
Read How QualityBound works for the measurement and decision flow, and Smart evaluation for what the current evidence does and does not establish.
QualityBound deliberately does not expose every FFmpeg option. It is designed around a narrower problem: finding a compact encode that satisfies an explicit perceptual-quality target.
It does not aim to be a media editor, format-conversion toolbox, or exhaustive encoder-parameter frontend. Its evidence and validation flow is the product:
- Scout selects windows from scene boundaries, spatial complexity, temporal complexity, and timeline strata.
- Search and validation windows are kept separate.
- Failed holdouts are promoted into the search constraints together.
- Size prediction uses measured sample output rather than requested bitrate.
- A completed size miss becomes an explicit decision and cannot overwrite the requested output silently.
The desktop GUI makes that workflow accessible, but the constraint and verification model is the central feature.
Run from a source checkout:
python -m pip install -r requirements.txt
python main.pyIn the GUI, add or drop files first, adjust encoding settings and the output directory, then click Start Queue. Settings are bound at Start. Right-click overrides apply only to the selected sources; parameter and output-directory overrides are independent and can each be reset to follow the global settings. Resume keeps the current run's settings; a manual retry selects settings again.
Plan or encode from the CLI:
python main.py --cli plan input.mp4
python main.py --cli encode input.mp4 --backend auto --overwriteThe built-in HEVC and AV1 presets use Smart compression by default. The default minimum is VMAF 90; the default maximum output ratio is 70% for HEVC and 50% for AV1. Use fixed-bitrate mode explicitly when compatible VMAF filters are not available:
python main.py --cli encode input.mp4 \
--compression-mode fixed_bitrate \
--ratio 0.76Supported encoding backends are CPU, NVIDIA NVENC, Intel QSV, AMD AMF, and Apple VideoToolbox where the selected FFmpeg build and hardware expose them.
Smart v1 remains the default. To try per-shot allocation, select Smart v2
(experimental) in the GUI Smart options, or pass --smart-algorithm v2_experimental in the CLI. V2 interprets --min-vmaf as a whole-video mean
target, applies local quality floors and scores the complete final output.
It requires CFR SDR and a successful encoder/decoder-configuration preflight;
it may take substantially longer. See Smart v2 for supported
cases, measured limitations and explicit-tool examples.
QualityBound performs runtime encoder smoke tests rather than assuming support
from an encoder name alone.
QualityBound does not silently publish a result that missed its constraints.
- A predicted quality/size conflict follows the configured Smart policy.
- Smart first tries the configured size or quality relaxation. If the remaining size conflict predicts a file larger than its source, the item is skipped.
- Intentional Smart skips follow the separate Copy / Ask / Ignore source output setting. Copy publishes the original file to the requested output path.
- In the GUI, size-conflict and quality-miss questions appear after executable encodes finish. The source-copy question is separate; pending decisions do not block copying skipped sources. Cancelling a constraint question leaves that item in Needs decision.
- A completed file that exceeds the size limit is preserved as a size-miss file for explicit accept, retry, or delete action; it does not overwrite the target.
- CLI exit code
3means a decision is required,2means analysis, encoding or copying failed, and intentional skips remain a successful batch outcome.
Smart measurements are cached as versioned receipts. Quality and size policy changes may reuse measured candidates; source, FFmpeg, encoder, measurement, or sample-scheme changes produce a different receipt identity.
- MP4 output cannot carry bitmap subtitles. MP4 subtitles are encoded as
mov_text, which only accepts text sources, so a PGS, VobSub or DVB subtitle stream cannot be carried into an MP4 output. Planning refuses such a source with the offending codec and publishes nothing, instead of failing after the full video encode. Choose MKV to keep such subtitles; text subtitles and MKV sources are unaffected. See Development, translations, and packaging (Known limitations) for the codec list and the reproduced commands.
- Algorithm and constraint flow
- Architecture
- Development, translations, and packaging
- Evaluation scope and limitations
- Synthetic Smart corpus
- CI and release workflows
- Release contract map
QualityBound is released under the MIT License. Bundled FFmpeg and Netflix VMAF artifacts retain their own licenses and source/build provenance.