halfsize

WeChat and Discord both stop at 20 MB. Email chokes around the same. So you open a video editor, guess a bitrate, export, check the size, export again, and still can't tell whether the picture got worse.

halfsize turns that into one command:

npx halfsize wedding.mp4 --to 25mb

It computes the bitrate, picks the resolution that actually fits, encodes twice, then measures the result with SSIM and VMAF so you know whether it still looks the same.

  halfsize 0.1.11

  source.mp4
  23.2 MB  8s  1920x1080  30.00 fps  h264

  target     2.00 MB
  plan       H.264  960x540  1.81 Mbps  audio 128 kbps  2-pass
  scale      1920x1080 -> 960x540
  estimate   1.94 MB  (12x smaller)
  output     source.2mb.mp4

  measuring quality                                        done in 1s

  23.2 MB  ->  1.99 MB   12x smaller   0.4% under target
  VMAF 84.4   SSIM 0.968   slight softening

  -> C:\Videos\source.2mb.mp4

Why this exists

"Make it smaller" is a solved problem. "Make it fit in exactly 20 MB, and tell me if it still looks right" is the part every tool makes you guess at.

• HandBrake is excellent, but it asks you to think in codecs, RF values, and presets.
• Online compressors work until you remember you just uploaded a private video to a stranger.
• ffmpeg can do all of this. Nobody remembers the 11 flags, and almost nobody checks VMAF afterwards.

halfsize is the missing 5%: a target size you type, and a quality score you can read.

Quick start

Requires Node.js 18+. FFmpeg is bundled on first install; if it cannot be downloaded, halfsize uses your system install instead.

# compress to a size
npx halfsize video.mp4 --to 25mb

# or just name the app you are uploading to
npx halfsize video.mp4 --for discord

# several files in one go
npx halfsize clip1.mp4 clip2.mp4 clip3.mp4 --to 10mb

# smaller file, same quality budget
npx halfsize video.mp4 --to 10mb --codec h265

# quality-first mode when size does not matter
npx halfsize video.mp4 --crf 23

# preview the plan without encoding
npx halfsize video.mp4 --to 25mb --dry-run

# machine-readable, for scripts
npx halfsize video.mp4 --to 25mb --json

Install it globally if you will use it more than once:

npm install -g halfsize

In CI

The same compression runs in GitHub Actions, and the quality report lands in the build log:

- uses: YKLovePython/halfsize-action@v1
  with:
    files: artifacts/recording.mp4
    args: --to 20mb

halfsize-action on the GitHub Marketplace.

The local web app

npx halfsize --web

Opens http://127.0.0.1:4174 — drag a video in, pick 20 MB / 16 MB / 5 MB or type your own limit, and watch the encode. The file goes to a temporary folder on your own machine; nothing is sent anywhere.

After each run you can download a share card (the image at the top of this README) with the real numbers on it.

Step-by-step guides with measured quality numbers: Discord 20 MB · WhatsApp 16 MB · WeChat 20 MB · email attachments · X / Twitter · any 20 MB limit · FFmpeg target size · compress without uploading.

Which size do I need?

The email rows are smaller on purpose: base64 makes the attachment about 37% bigger than the file, so an 18 MB MP4 is what fits in a 25 MB message. Caps change; --to always overrides the preset. Full table, with what each cap counts and the measured VMAF at each size: size limits by platform · every target size explained · video size calculator.

Use it from an agent

The repo ships a skill in skills/halfsize/SKILL.md. Install it with the skills CLI so Claude Code, Codex, Cursor, OpenCode and the rest pick it up automatically:

npx skills add YKLovePython/halfsize

Or copy the folder into your agent's skills directory by hand (for Claude Code: .claude/skills/halfsize/). Either way the agent can turn "make this fit in 25 MB" into a compression plus a measured quality report, instead of guessing a bitrate.

If your client speaks MCP instead, halfsize is also a single-tool MCP server:

{
  "mcpServers": {
    "halfsize": { "command": "npx", "args": ["-y", "halfsize", "--mcp"] }
  }
}

That gives the agent one tool, compress_video(input, target, output?, codec?, verify?), backed by the same CLI and the same JSON report. It is stdio only: no port, no daemon, nothing listening. Per-client setup (Claude Code, Claude Desktop, Cursor, VS Code) is on MCP server.

How it works

1. Probe. Read duration, resolution, frame rate, audio bitrate, rotation, and HDR metadata.
2. Budget. Total bitrate = target bytes × 8 ÷ duration, minus audio, minus a small container overhead.
3. Pick a resolution. Walk a ladder from the source size down to 240p and choose the largest one whose pixels fit the budget at that codec's bits-per-pixel target (H.264: 0.072 bpp, H.265: 0.045 bpp). This is why a 12× shrink still looks reasonable: the encoder gets to spend its bits on fewer pixels.
4. Encode twice. Two-pass ABR with libx264 or libx265. Pass one learns where the bits are needed; pass two spends them. Output is yuv420p, AAC audio, +faststart, and tagged hvc1 for H.265 so it plays on Apple devices. HLG/PQ sources are tone-mapped to SDR BT.709 in the same pass; without that, 8-bit pixels keep their HDR tags and look grey.
5. Prove it. Sample three points in the video, compute SSIM at each, and VMAF at the midpoint. Compare against thresholds and print a verdict in plain language.

VMAF ≥ 95  indistinguishable
VMAF ≥ 90  looks the same
VMAF ≥ 80  slight softening
VMAF ≥ 70  visible loss
below 70   clearly degraded

VMAF is Netflix's perceptual metric; it correlates with human judgement far better than PSNR or bitrate. It is not magic, but it is a much better answer than "trust me".

What each size costs

Same 60-second 1080p clip, default settings, measured on a normal laptop: