CompressCore

Fast, local, size-targeted video compression with hardware acceleration, all in the CLI

Compress any video to an exact file size. Perfect for Discord, Slack, email, or any platform with upload limits.
Uses Apple VideoToolbox for ultra-fast hardware-accelerated encoding.

---

Performance

Tested on MacBook Air M4 - up to 7x faster than realtime:

Input	Size	Target	Output	Compression	Time
60s 1440p video	446 MB	10 MB	9.9 MB	45.2x smaller	8.4s
2min 4K video	1.18 GB	25 MB	24.7 MB	47.5x smaller	32.4s
30s 1080p clip	136 MB	10 MB	9.9 MB	13.8x smaller	8.4s

Smart FPS optimization automatically reduces framerate for low-bitrate targets to keep text sharp and readable.

---

Features

• Size-targeted - Specify exact output size (10MB, 25MB, etc.)
• Hardware accelerated - Uses Apple VideoToolbox for fast encoding
• Smart quality - Automatically trades FPS for quality at low bitrates
• Screen recording optimized - Spatial AQ preserves text and UI elements
• HDR compatible - Auto-converts HDR to SDR for compatibility
• Clipboard copy - Copy outputted file with -c for instant sharing
• Replace original - Use -r to replace the original file
• Delete original - Use -d to delete the original after compression

---

Installation

One-liner (Recommended)

curl -sSL https://raw.githubusercontent.com/ishsharm0/compresscore/main/install.sh | bash

From source

git clone https://github.com/ishsharm0/compresscore.git
cd compresscore
pip install -e .

Requirements

• macOS (VideoToolbox is macOS-only)
• Python 3.9+
• FFmpeg - brew install ffmpeg

---

Usage

# Basic - compress to 10MB (Discord default)
cpc video.mov

# Copy to clipboard after compression
cpc video.mov -c

# Replace original file
cpc video.mov -r

# Delete original after compression
cpc video.mov -d

# Custom target size
cpc video.mov -t 25MB

# Specify output path
cpc video.mov -o compressed.mp4

# Use H.264 for maximum compatibility
cpc video.mov --codec h264

# Verbose mode (see FFmpeg output)
cpc video.mov -v

All Options

Option	Default	Description
-t, --target	10MB	Target output size (supports arbitrary sizes: 5MB, 8MB, 12MB, 25MB, 8M, 7.63MiB, 8000KB, 8000000, .008GB)
-o, --output	<input>_compressed.mp4	Output file path
-c, --copy		Copy output to clipboard - directly paste wherever you want.
-r, --replace		Replace original file (output keeps same name)
-d, --delete		Delete original file after successful compression
--codec	hevc	Video codec (hevc or h264)
--max-width	1920	Maximum output width
--fps	60	Maximum framerate
-v, --verbose		Show detailed FFmpeg output
-q, --quiet		Output only the result path

---

How It Works

1. Analyze - Probe input for duration, resolution, and audio
2. Calculate - Determine available bitrate from target size
3. Optimize - For low bitrates, reduce FPS for sharper frames
4. Encode - Hardware-accelerated VideoToolbox encoding
5. Verify - Check output size, adjust if needed

Quality Optimizations

Feature	Purpose
Spatial AQ	Preserves text and UI in screen recordings
Lanczos scaling	Sharp downscaling, ideal for text
Smart FPS	Lower FPS = more bits per frame = sharper image
HDR→SDR	Automatic colorspace conversion
hvc1 tag	QuickTime/iOS compatibility

---

Python API

from compresscore import compress, probe, parse_size_to_bytes
from pathlib import Path

# Check video info
info = probe(Path("input.mov"))
print(f"{info.duration_s}s, {info.width}x{info.height}")

# Compress to target size
result = compress(
    input_path=Path("input.mov"),
    output_path=Path("output.mp4"),
    target_bytes=parse_size_to_bytes("8MB"),
)
print(f"Compressed to {result.video_kbps} kbps")

---

License

MIT © 2026