vidcompress 0.1.3

Local video compression powered by WebCodecs — hardware-accelerated, zero FFmpeg required

VidCompress

Local, hardware-accelerated video compression that runs entirely in your browser. No FFmpeg install, no cloud uploads — just two lines of command.

curl -LsSf https://astral.sh/uv/install.sh | sh
uvx vidcompress

How it works

VidCompress launches a tiny local web server and opens a browser tab. All video encoding/decoding happens client-side using the WebCodecs API, which talks directly to your GPU's hardware encoder (VideoToolbox on Mac, NVENC on NVIDIA, AMF on AMD).

┌──────────────────────────────────────────────────────────┐
│  Browser (Chrome/Edge)                                   │
│                                                          │
│  MP4Box.js     VideoDecoder     VideoEncoder   mp4-muxer │
│  (demux)   →   (HW decode)  →  (HW encode) →  (remux)   │
│                                                          │
│  ↕ GPU: VideoToolbox / NVENC / AMF / VA-API              │
└──────────────────────────────────────────────────────────┘
│  Python server (FastAPI) — only serves static files      │
└──────────────────────────────────────────────────────────┘

Your files never leave your machine.

Quick start

With uv (recommended)

# Run directly — no install needed
uvx vidcompress

# Or install globally
uv tool install vidcompress
vidcompress

With pip

pip install vidcompress
vidcompress

From source

git clone https://github.com/arpantripathi/ffmpeg-compression-local.git
cd ffmpeg-compression-local
uv run vidcompress

Features

• Hardware-accelerated — uses your GPU encoder, not software encoding
• Zero dependencies — no FFmpeg, no native libraries to install
• Fully local — nothing leaves your machine
• Codec choice — H.264, H.265 (HEVC), VP9, AV1
• Resolution scaling — downscale to 1080p, 720p, 480p, 360p
• Quality control — adjustable quality slider with exponential bitrate mapping
• Audio re-encoding — automatic AAC/Opus transcoding
• Drag & drop — simple, clean UI

Supported codecs

Codec	Container	Mac (Apple Silicon)	Windows (NVIDIA)	Windows (AMD)
H.264 (AVC)	MP4	VideoToolbox	NVENC	AMF
H.265 (HEVC)	MP4	VideoToolbox	NVENC	AMF
VP9	WebM	Software*	Software*	Software*
AV1	MP4	VideoToolbox (M3+)	NVENC (RTX 40+)	AMF (RX 7000+)

*VP9 encoding may fall back to software on some platforms. Hardware support depends on your browser and GPU drivers.

Performance

Typical encoding speeds for 1080p video (hardware-accelerated):

Codec	Apple M1/M2	NVIDIA RTX 3060+	AMD RX 6000+
H.264	200-400 fps	300-500 fps	200-350 fps
H.265	150-300 fps	200-400 fps	150-250 fps
AV1	60-120 fps (M2+)	100-200 fps (RTX 40+)	80-150 fps

A 10-minute 1080p video typically compresses in 30-90 seconds.

Browser requirements

• Chrome 94+ or Edge 94+ (full WebCodecs support)
• Firefox: partial support (video encoding may not work)
• Safari: partial support (limited codec options)

CLI options

vidcompress [OPTIONS]

Options:
  -p, --port PORT    Port to serve on (default: 8899)
  --host HOST        Host to bind to (default: 127.0.0.1)
  --no-open          Don't open browser automatically
  --version          Show version and exit
  -h, --help         Show help

Development

git clone https://github.com/arpantripathi/ffmpeg-compression-local.git
cd ffmpeg-compression-local

# Run in development
uv run vidcompress

# Or with live reload (edit static files, refresh browser)
uv run vidcompress --port 3000

The Python server is minimal — it only serves static files. All encoding logic is in src/vidcompress/static/app.js.

Architecture

src/vidcompress/
├── __init__.py        # Version
├── __main__.py        # python -m vidcompress
├── cli.py             # CLI argument parsing + server launch
├── server.py          # FastAPI static file server (10 lines)
└── static/
    ├── index.html     # UI structure
    ├── style.css      # Dark theme
    └── app.js         # WebCodecs transcoding pipeline

Frontend pipeline (app.js)

1. Demux — mp4box.js reads the input MP4/MOV and extracts raw encoded samples
2. Decode — VideoDecoder (hardware) decodes samples into raw VideoFrames
3. Resize — OffscreenCanvas scales frames if resolution change is requested
4. Encode — VideoEncoder (hardware) re-encodes frames with the chosen codec/bitrate
5. Mux — mp4-muxer or webm-muxer packages encoded chunks into the output container
6. Download — output is offered as a browser download

Limitations

• Input formats: MP4 and MOV files only (mp4box.js limitation). WebM input is not supported yet.
• File size: Limited by browser memory. Files over ~2 GB may cause issues.
• Codec availability: Depends on your browser, OS, and GPU. H.265 and AV1 encoding may not be available on all systems.
• No B-frame control: WebCodecs doesn't expose fine-grained encoding parameters like CRF or B-frame count.
• Audio: Audio re-encoding may fail for some input formats. The video will still be compressed.

License

MIT