halfsize CLI
A CLI that shrinks a video to an exact size locally with FFmpeg and reports VMAF and SSIM quality scores, with a skill for agents
- 101 ★ on the repository
- Last commit
- MIT
Minimal access
Why this level
- Runs FFmpeg and writes a new file next to the source, makes no network calls after install
- npm downloads an FFmpeg binary during install
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add cli/halfsizeDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewMinimal accessThe tool runs nothing and makes no network calls.
- Runs FFmpeg and writes a new file next to the source, makes no network calls after install
- npm downloads an FFmpeg binary during install
This is third-party code. Review the repository files before installing.
What it does
halfsize shrinks a video to a size you set: 25mb, 700k or the name of an app such as discord. The command works out the bitrate, picks a resolution from a ladder down to 240p, encodes in two passes with H.264 or H.265 and writes a new file next to the original with a size suffix. The source stays untouched and nothing is uploaded. After encoding it measures the result. SSIM is computed at three points in the clip and VMAF at the midpoint, and the verdict is printed in words from indistinguishable to visible loss. HDR clips from an iPhone (HLG and PQ) are tone-mapped to SDR in the same pass, so colors do not turn grey. The `--json` flag returns the plan, how close the output landed to the target and the quality scores for scripts. The repository ships a skill at `skills/halfsize/SKILL.md`. It teaches an agent to run `npx halfsize`, read the result and avoid promising no quality loss. There is also a local web app (`npx halfsize --web`) and a GitHub Actions step.
Who it is for. People who send video through messengers and mail with a file cap, and Claude Code, Codex or Cursor agents asked to fit a clip to a platform.
Good fit when
- A 130 MB clip has to go to Discord, and the free account cap is 20 MB
- An agent should fit a screen recording into 16 MB for WhatsApp and report how much quality it cost
- Before uploading to a service you want to see the compression plan without encoding: `--dry-run` shows it
- A video artifact lands in CI after a test and has to shrink to the build limit through the GitHub Actions step
- You want to know how badly a 5 MB target damages the picture: compare VMAF across several sizes
Not a fit when
- You need editing, cutting or captions: the tool only compresses and joins nothing
- The source is already smaller than the target: the skill tells the agent to stop and report instead of re-encoding
- HDR must be preserved: HLG and PQ clips are tone-mapped to SDR
- You need a format or codec beyond H.264 and H.265, such as AV1
Example request
Compress promo.mp4 so it fits in Discord and show me the quality scoreLimitations
- Node.js 18 or newer is required. On first install npm downloads an FFmpeg build, and behind a proxy or TLS inspection the download can fail.
- The `--for` caps (Discord 20 MB, WhatsApp 16 MB, Gmail 18 MB) are valid for November 2026 and change over time. `--to` always takes precedence.
- If the target is below the minimum for that duration, the command returns the smallest achievable size. `--force` makes it encode anyway.
- The project is at 0.1.x, so the interface may change.
How to disable. Delete the `halfsize` folder from `.claude/skills/` or from another agent's skills directory to remove the skill. `npm uninstall -g halfsize` removes the global package. `npx halfsize` installs nothing into the system beyond the npm cache.
FAQ
How do I compress a video to 20 MB for Discord?
Run `npx halfsize video.mp4 --for discord`. The command aims at 20 MB and picks a resolution to fit that budget. For any other size use `--to 25mb`.
Is the video uploaded anywhere?
No. Encoding runs locally through FFmpeg, and the skill explicitly forbids an agent from uploading the file or suggesting an online compressor first.
How do I install the halfsize skill in Claude Code?
Run `npx skills add YKLovePython/halfsize`. You can also copy the folder by hand into `.claude/skills/halfsize/`.
How is halfsize different from HandBrake or plain ffmpeg?
HandBrake expects you to think in codecs and presets, and ffmpeg needs about eleven flags. halfsize takes a target size and reports VMAF and SSIM after encoding.
What if halfsize cannot find FFmpeg?
Run `npx halfsize --doctor`: it lists the FFmpeg and encoders it found. Variables `HALFSIZE_FFMPEG` and `HALFSIZE_FFPROBE` point to your own build, and on macOS `brew install ffmpeg` works.
Discussion
No questions or reviews yet.
Related
CLI toolsffmpeg-skill — a skill and MCP server: an agent cuts and joins video, fixes audio, adds captions and exports for TikTok and Reels with local FFmpeg
The frames CLI puts screenshots and screen recordings into official Apple bezels and detects the device from the frame size
Skill and .cdaf format: a text description of a video next to the file, so an agent reads it instead of re-watching the clip.
An agent edits short talking-head videos: transcript, subtitles, B-roll and export for Xiaohongshu, Douyin and WeChat Channels
A CLI for programmatic video from HTML: the agent assembles frames from templates and renders a finished MP4 on your machine
An FFmpeg-style command that cuts video locally and sends heavy jobs to the Volcengine cloud: enhancement, ASR, OCR
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Repository stars | Main difference |
|---|---|---|---|
| halfsize (this card) | no | 101 | |
| ffmpeg-skill | no | 5,244 | editing, captions and export through FFmpeg, while halfsize does one job: a target size with a quality score |
| video-use | no | 30,939 | editing with pause cutting and color grading, does not target a file size |
README in short
The README opens with the messenger size-cap problem and a comparison with HandBrake and online compressors. It continues with a quick start, the local web app, a table of platform caps, the five processing steps, the measured cost of each size and a flag reference. Separate sections cover installing behind a proxy, an FAQ and connecting the skill to an agent.
README badge
Original SKILL.md
---
name: halfsize
description: Compress a video to an exact target size (20 MB, 16 MB, 700k, ...) on the local machine with FFmpeg, then verify quality with VMAF/SSIM. Use when a user needs a video to fit a platform cap, asks to "make this smaller", or wants to know what a size cut costs in quality.
---
# halfsize
`halfsize` is a local CLI. It does the bitrate math, picks a resolution, encodes twice,
and reports the measured quality. It never uploads the file.
## When to use this
- "Make this fit in 25 MB" / "Discord won't take it" / "WeChat says the file is too big"
- "Compress this but don't ruin it" — run it and report VMAF instead of guessing
- "How small can this go?" — try a target and read the verdict
## Commands
```bash
# exact size
npx halfsize input.mp4 --to 25mb
# let a platform cap pick the size
npx halfsize input.mp4 --for discord
npx halfsize input.mp4 --for gmail # 18 MB, safe under the 25 MB message cap
npx halfsize input.mp4 --for outlook # 15 MB, safe under the 20 MB message cap
# several files, one command
npx halfsize a.mp4 b.mp4 c.mp4 --to 10mb
# smaller, at the cost of compatibility
npx halfsize input.mp4 --to 10mb --codec h265
# keep resolution, accept a worse ratio
npx halfsize input.mp4 --to 25mb --no-downscale
# no soundtrack
npx halfsize input.mp4 --to 10mb --no-audio
# inspect the plan without encoding
npx halfsize input.mp4 --to 25mb --dry-run --json
# machine-readable result (plan, accuracy, VMAF, SSIM)
npx halfsize input.mp4 --to 25mb --json
```
With more than one input, `--json` returns `{ "files": [ ... ] }`.
If `npx halfsize` is unavailable, use `npx github:YKLovePython/halfsize` with the same flags.