halfsize / Email
Compress a video for email
Gmail stops at 25 MB. Outlook and a lot of corporate servers stop at 20 MB. And the attachment your recipient sees is about a third larger than the file on your disk. Here is the arithmetic, and one command that lands under it.
The 33% nobody accounts for
SMTP is a text protocol. Binary attachments are base64-encoded, which turns every 3 bytes into 4. A 19 MB MP4 becomes roughly 25 MB inside the message. Many providers enforce the limit on the encoded message, not on the file you dragged in.
That is why a video that “is under 20 MB” still bounces. If the limit is 25 MB, aim for a file around 18 MB. If the limit is 20 MB, aim for 14–15 MB.
Rule of thumb: attachment size ≈ file size × 1.37. Compress to limit ÷ 1.37 and stop worrying about it.
One command
$ npx halfsize holiday.mp4 --to 18mb
target 18.0 MB
plan H.264 1280x720 2.19 Mbps audio 128 kbps 2-pass
scale 1920x1080 → 1280x720
output holiday.18mb.mp4
214 MB → 17.62 MB 12x smaller 2.1% under target
VMAF 87.4 SSIM 0.968 slight softeningThe --for email shortcut targets 18 MB, the Gmail-safe number after the base64 tax. --for outlook targets 15 MB for the 20 MB message cap. --to overrides either one.
What it does to the picture
Eighteen megabytes for a one-minute clip is about 2.2 Mbps. That is comfortable for 720p and cramped for 1080p, so the tool downscales instead of starving the larger frame. Measured on a 60-second 1080p30 source at 18 Mbps:
| Target | Output | Resolution | VMAF | Verdict |
|---|---|---|---|---|
| 18 MB | 17.62 MB | 1280×720 | 87.4 | slight softening |
| 15 MB | 14.71 MB | 1280×720 | 86.2 | slight softening |
| 10 MB | 9.77 MB | 960×540 | 82.9 | slight softening |
VMAF is measured against the source at the midpoint. Above 90 reads as “looks the same”; 80–90 is slight softening; 70–80 is visible loss.
When the mailbox still refuses it
Some servers cap the whole mailbox, or scan attachments and reject anything above 10 MB regardless of settings. In that case, do not compress harder — send a link:
- Put the compressed file on any storage you already have and send the URL.
- If the recipient is on the same company network, a shared drive beats email every time.
- For a client who needs the original quality, send the source through a file-transfer service and attach only the compressed preview.
Why not an online compressor?
Because the videos people email are usually the private ones: a passport scan, a contract walkthrough, a child's recital, an unreleased product demo. Uploading that to an ad-funded site to save two minutes is a bad trade. halfsize runs FFmpeg on your machine: no upload, no account, no quota, and no watermark. It also has a local web UI if you would rather click than type:
$ npx halfsize --web
halfsize web UI on http://127.0.0.1:4174FAQ
What is Gmail's actual limit?
25 MB for the encoded message, which is roughly an 18 MB file. Google Drive links do not count against it, but the recipient then needs access.
Why does Outlook reject a 20 MB file?
Because the base64 encoding pushes it past 20 MB. Target 14–15 MB, or ask the recipient's IT what the real cap is.
Can I keep 1080p?
Yes, with --no-downscale. At 18 MB for a minute it will look softer than 720p, but the frame size stays the same. Try --dry-run to see both plans.
Does the recipient need any software?
No. The output is a normal H.264 MP4 with AAC audio and +faststart, which plays in every mail client and phone.
Is it free?
Yes. MIT licensed, no paid tier, no account.