Skip to main content
skill CX Codex

halfsize — Claude Code skill: video compression and setup

The halfsize Claude Code skill compresses videos to a target size and measures quality with VMAF and SSIM. It activates when a file must fit a platform limit or its quality loss needs measuring.

MIT ★ 116 updated 2026-11-15

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add YKLovePython/halfsize --skill halfsize -a claude-code
Open on GitHub

What halfsize does

halfsize compresses video to a requested size with a local CLI. It calculates the bitrate, selects a resolution, encodes the file twice, then reports VMAF and SSIM scores. The video stays on the machine and is never uploaded.

A single command can process several files. The --no-downscale flag keeps the original resolution, while --no-audio removes the soundtrack. Use --dry-run to inspect the plan before encoding, or request JSON output. H.264 is the default; H.265 trades away some compatibility. FFmpeg is required. If its binary was not downloaded, repair the installation with npx halfsize@latest --fix and retry. Output files go beside their inputs.

What it helps with

  • compress a video to an exact size limit
  • fit a clip within Discord or Gmail file caps
  • measure quality loss after compression
  • process several videos with one command

Example prompts for the agent

  • Compress input.mp4 to 25 MB and report its quality score.
  • Make clip.mp4 small enough to send through Discord.
  • Compare the compressed video's quality using VMAF and SSIM.

How to install halfsize

1Skills CLI (Vercel)

npx skills add YKLovePython/halfsize --skill halfsize -a claude-code

2Manually: put the files in place

~/.claude/skills/halfsize/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/halfsize/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about halfsize

How do I install halfsize in Claude Code?

Run npx skills add YKLovePython/halfsize --skill halfsize -a claude-code. The skill file is placed at ~/.claude/skills/halfsize/SKILL.md.

What does halfsize do?

It compresses videos locally with FFmpeg to a requested size, then measures quality using VMAF and SSIM. The video is not uploaded.

What does halfsize need to run?

FFmpeg is required. If its binary download fails, run npx halfsize@latest --fix and retry the command.

Source text

SKILL.md · MIT
---
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.

If a run fails with "FFmpeg was not found" (npm sometimes skips the binary download
behind a proxy), repair it in place, then retry the same command:

```bash
npx halfsize@latest --fix
```

## How to read the result

- `0.3% under target` — good; it deliberately aims slightly under hard caps
- `VMAF >= 90` — looks the same; `80-90` — slight softening; `< 70` — visible loss
- The JSON result includes `output.file`, `output.bytes`, `quality.vmaf`, `quality.ssim`,
  `accuracy`, and `verdict`.

## Rules

- Do not upload the user's video anywhere, and do not suggest an online compressor as a first step.
- Do not promise "no quality loss". Report the measured VMAF/SSIM and the verdict.
- If the source is already smaller than the target, stop and tell the user instead of re-encoding.
- HDR sources (iPhone HLG, HDR10/PQ) are tone-mapped to SDR automatically. Do not warn about washed-out colors unless the user asks to keep HDR.
- If the target is below the minimum the duration can hold, the CLI exits with the smallest achievable size. Report that number and suggest a larger target or trimming, instead of rerunning with `--force`.
- Prefer H.264 unless the user asks for smaller files or accepts H.265 compatibility tradeoffs.
- Write the output next to the input unless the user asks for a specific `--out` path.

© YKLovePython · MIT · YKLovePython/halfsize

Similar skills

All skills for Notes, tasks and projects →

Project sponsors

Companies that keep this analytics open