halfsize / comparison
halfsize vs FFmpeg vs HandBrake
They are not three competitors. FFmpeg is the encoder, HandBrake is a GUI in front of it, and halfsize is a wrapper that does the size arithmetic and the quality check. The useful question is not "which is better" but which number do you control: quality or size?
Side by side
-crf | -b:v 2-pass | HandBrake | halfsize | |
|---|---|---|---|---|
| What you control | quality | size | quality (or avg bitrate) | size |
| Hits an exact size | no | close, after you do the maths | no target-size box since 0.10 | 1–3% under, automatically |
| Resolution decision | manual | manual | manual (filters only) | picked from the budget |
| Overshoot handling | re-encode and guess again | re-encode with a lower bitrate | the same loop, in a GUI | re-encodes once, then reports |
| Quality measurement | libvmaf, by hand | libvmaf, by hand | none built in | VMAF + SSIM + a verdict |
| Install | package manager | package manager | ~150 MB installer | npx halfsize |
| Best at | archives, masters | scripted caps | browsing, previewing, editing | "make this fit 20 MB" |
The only axis that matters
Constant quality and constant size are opposites. -crf 23 holds the picture quality
and lets the byte count land wherever the content dictates: the same 23 on a talking head and on a
fireworks clip can differ by 4×. -b:v 2460k holds the byte rate and lets the quality
land wherever the content dictates.
An upload form with a hard cap is a size problem. Every tool below can solve it; only some of them ask you to do the solving.
FFmpeg -crf: right when size does not matter
$ ffmpeg -i input.mp4 -c:v libx264 -crf 23 -preset medium -c:a aac -b:a 128k out.mp4
One pass, no log files, no arithmetic. For a master file or an archive, this is the correct command and you should stop reading. It is the wrong command the moment a form says 20 MB, because you cannot know the output size without encoding it.
FFmpeg two-pass: correct, but you are the missing half
$ ffmpeg -y -i input.mp4 -c:v libx264 -b:v 2460k -pass 1 -an -f mp4 /dev/null
$ ffmpeg -i input.mp4 -c:v libx264 -b:v 2460k -pass 2 -c:a aac -b:a 128k -movflags +faststart out.mp4
To run that correctly you have to:
- Probe the duration and the real audio bitrate.
- Compute the budget and subtract container overhead.
- Decide whether 1080p fits that budget, or whether 720p would look better at the same bytes.
- Encode, check the size, and adjust if it overshot.
- Measure VMAF to know what it cost.
Steps 1–4 are the whole product. They also break the moment the input changes: the next clip has a different duration, a different audio track, and needs a different bitrate. That is why people end up guessing CRF instead — and why the guess keeps missing.
HandBrake: the same two ideas in a window
HandBrake exposes quality (RF) and average bitrate with 2-Pass Encoding. It lost its target-file-size control in 0.10 back in 2014, so "set the size in HandBrake" describes a version that no longer ships. It is the right tool when you want to scrub through the timeline, pick a range, check a preview frame and queue ten files. It does not compute the budget for you, choose a resolution for you, or tell you what the picture lost.
More detail: HandBrake and the 20 MB cap.
halfsize: it does not encode differently, and that is the point
Underneath, halfsize runs the same libx264/libx265 two-pass encode you
would type yourself. The difference is everything that surrounds it:
- Budget. Target bytes → bitrate, with the file's real duration, audio bitrate, rotation and HDR flags read first.
- Resolution ladder. Walks down from the source size and picks the largest resolution that stays above a bits-per-pixel floor (0.072 for H.264, 0.045 for H.265). That is why a 7× shrink can still look right: fewer pixels, honest bits.
- One retry. If the first encode lands more than 0.5% over the cap, it re-encodes with a corrected bitrate instead of handing you a file the form will reject.
- Proof. VMAF and SSIM on sampled frames, then a verdict in words.
- The caps, built in.
--for discord,--for wechat,--for whatsapp,--for email,--for outlook,--for twitter, and--to 20mbfor anything else. - HDR handled. HLG and PQ sources are tone-mapped to SDR BT.709 inside the same encode, so the output does not end up washed out.
$ npx halfsize input.mp4 --to 20mb
target 20.0 MB
plan H.264 1280x720 2.46 Mbps audio 128 kbps 2-pass
scale 1920x1080 → 1280x720
output input.20mb.mp4
136 MB → 19.45 MB 7.0x smaller 2.7% under target
VMAF 88.3 SSIM 0.971 slight softening
What halfsize does not do
- No editing. No trimming, cuts, or joining. Several files in one command, each encoded on its own: yes; a sequence: no.
- No subtitle or chapter work. Subtitle and extra audio tracks are dropped and reported, not carried over.
- No filter graphs. No crop, denoise, watermark, or colour grading. Encode first, or use FFmpeg or HandBrake for that step.
- No GPU encoders. NVENC/QSV/AMF are much faster, but their rate control is looser and
two-pass ABR is not equivalent; at a fixed byte budget they give you a softer picture. For a
quality-first encode,
ffmpeg -crfon the same machine is faster than halfsize's two passes — that is the trade. - No HDR output. HDR input is converted to SDR on purpose. Keeping HDR tags on 8-bit pixels is what makes phone videos look grey after compression.
- Node.js 18+. It runs FFmpeg as a subprocess and needs a Node runtime to do it, which is
why
npxis the install.
Pick by situation
| Situation | Use | Why |
|---|---|---|
| A form or chat app says 20 MB | halfsize | It solves for size and proves the quality |
| Archiving a master | ffmpeg -crf | Quality is the goal; size is whatever it is |
| Cutting a clip out first | HandBrake or FFmpeg | halfsize does not edit |
| A script or CI job | halfsize --json | Plan, size and VMAF in one document |
| Hundreds of files overnight | ffmpeg -crf | Constant quality is cheaper than per-file VMAF |
| A phone video that looks grey | halfsize | HDR is tone-mapped instead of mis-tagged |
FAQ
Is halfsize a replacement for HandBrake?
No. HandBrake previews, trims, handles subtitles, chapters and batches; halfsize does one job and skips the rest. If you need to look at the picture before you commit, HandBrake or halfsize --web.
Is halfsize slower than -crf?
Yes, roughly twice as slow plus a quality check, because two passes analyse the file twice. On a 10-minute 1080p clip that is minutes, not hours. The reward is a file that fits on the first try.
Why not just use -fs 20M?
-fs stops writing at the limit and can truncate mid-GOP, leaving a file of the right size that stops playing. It also gives you no control over where bits were spent.
Does H.265 help?
It usually keeps more resolution at the same byte budget, at the cost of playback compatibility. --codec h265 switches the plan; VMAF will show whether it actually helped on your clip.
Can I see what it will do before encoding?
npx halfsize input.mp4 --to 20mb --dry-run prints the bitrate, resolution and warnings in under a second.