Skip to content

julianromli/fastcompress

BranchesTags

Repository files navigation

🎬 FastCompress

The easiest way to compress videos from your terminal

Version Platform License FFmpeg

One-click video compression with FFmpeg. No manual setup, no complex commands – just select your video and go.

FastCompress automatically downloads FFmpeg, detects your videos, and compresses them with smart presets. Perfect for content creators, developers, and anyone who needs to compress videos quickly.

🎥 Input:  video.mp4 (500 MB)
⚡ Compress with 1 click
💾 Output: video_compressed.mp4 (300 MB)
✨ 40% smaller, excellent quality

✨ Features

  • 🚀 Zero Configuration - Auto-downloads and installs FFmpeg on first run
  • 🎯 Smart Presets - High, Medium, Low quality options + Custom mode
  • 🔍 Interactive UI - Arrow key navigation & real-time search (PowerShell)
  • 📊 Detailed Statistics - File size, reduction percentage, compression time
  • 🖥️ Cross-Platform - Windows (PowerShell & CMD) and macOS support
  • 💻 Three Versions - Choose the best for your platform and shell
  • 🎨 Beautiful UI - ANSI colors, progress indicators, professional layout
  • ⚡ Fast & Efficient - Uses FFmpeg's libx264 with optimized settings
  • 🛡️ Safe - Preview before compression, never overwrites without asking
  • 📦 Portable - Single script file, no installation needed

🚀 Quick Start

Windows (PowerShell) - Recommended

# 1. Download compress_video.ps1
# 2. Put it in your video folder
# 3. Right-click → Run with PowerShell

# Or from terminal:
cd "D:\My Videos"
.\compress_video.ps1

macOS (Bash)

# 1. Download compress_video.sh
# 2. Make it executable
chmod +x compress_video.sh

# 3. Run it
./compress_video.sh

Windows (CMD)

# 1. Download compress_video.bat
# 2. Double-click to run

# Or from Command Prompt:
cd "D:\My Videos"
compress_video.bat

📦 Installation

Prerequisites

All platforms:

  • FFmpeg will be automatically downloaded on first run
  • No manual installation required! 🎉

System Requirements:

  • Windows: Windows 10/11 (PowerShell 5.1+) or Windows 7+ (CMD)
  • macOS: macOS 10.13+ with Bash
  • Disk Space: ~200 MB (for FFmpeg)
  • Internet: Required for first-time FFmpeg download only

Download FastCompress

Option 1: GitHub Releases (Recommended)

# Download latest release
https://github.com/julianromli/fastcompress/releases/latest

Option 2: Clone Repository

git clone https://github.com/julianromli/fastcompress.git
cd fastcompress

Option 3: Direct Download

📖 Usage

Step-by-Step Guide

1️⃣ FFmpeg Check (First Run Only)

On first run, FastCompress will:

  • Check if FFmpeg is installed
  • Offer to download and install automatically (~130 MB)
  • Install to script directory or system-wide (macOS Homebrew)

2️⃣ Select Your Video

  • PowerShell: Use ↑↓ arrow keys to navigate, type to search
  • macOS/CMD: Enter the number of your video

3️⃣ Choose Quality Preset

1. High Quality   (CRF 23) → 80% original size, excellent quality
2. Medium Quality (CRF 28) → 60% original size, very good quality
3. Low Quality    (CRF 32) → 40% original size, good quality
4. Custom         → Set your own CRF and preset

4️⃣ Confirm & Compress

  • Review settings
  • Confirm compression
  • Watch progress indicator
  • Get detailed statistics!

Example Session

╔═══════════════════════════════════════════════════════╗
║                   FastCompress v1.0                   ║
║              Video Compression Made Easy              ║
╚═══════════════════════════════════════════════════════╝

[1/5] Checking FFmpeg availability...
  ✓ FFmpeg found

[2/5] Scanning for video files...
  ✓ Found 5 video file(s)

[3/5] Select video to compress
  → vacation.mp4                     1250.88 MB  [MP4]
    birthday.mov                      850.45 MB  [MOV]
    presentation.avi                  425.12 MB  [AVI]

[4/5] Select compression quality
  Select option: 2 (Medium Quality)

[5/5] Confirmation
  Input:  vacation.mp4
  Output: vacation_compressed.mp4
  Quality: Medium Quality (CRF 28)

✓ Compression completed successfully!

File Size Comparison:
  Original:   1250.88 MB
  Compressed:  750.53 MB
  Reduction:   40.0%
  Time Taken:  3.5 minutes

🎯 Compression Guide

Understanding Quality Presets

Preset CRF Quality Use Case File Size
High 23 ⭐⭐⭐⭐⭐ Excellent Archival, professional ~80% original
Medium 28 ⭐⭐⭐⭐ Very Good YouTube, sharing ~60% original
Low 32 ⭐⭐⭐ Good Drafts, previews ~40% original
Custom 0-51 Variable Advanced users Variable

When to Use Each Preset

🏆 High Quality (CRF 23)

  • Wedding videos, important events
  • Professional content, archival
  • When quality matters most
  • Minimal visible quality loss

🎯 Medium Quality (CRF 28) ⭐ Most Popular

  • YouTube uploads
  • Social media content
  • General purpose compression
  • Best balance of size and quality

💾 Low Quality (CRF 32)

  • Draft videos
  • Internal reviews
  • Long recordings (lectures, meetings)
  • When file size is critical

⚙️ Custom

  • Fine-tune CRF (0-51)
  • Choose encoding preset (ultrafast to slow)
  • Advanced users with specific needs

CRF Value Guide

Lower CRF = Better Quality, Larger File
Higher CRF = Lower Quality, Smaller File

18-23: High quality (recommended for important videos)
23-28: Medium quality (best for most use cases)
28-35: Low quality (good for drafts)
35+:   Very low quality (not recommended)

🖥️ Platform Comparison

Feature Matrix

Feature PowerShell macOS Bash Windows CMD
Auto FFmpeg Download ✅ Yes ✅ Yes (2 methods) ✅ Yes
Navigation ⭐ Arrow keys 📝 Numbered 📝 Numbered
Search/Filter ⭐ Real-time ⚠️ Simplified ❌ No
Colors ⭐ Full ANSI ⭐ Full ANSI ⚠️ Limited
Progress ⭐ Spinner ⭐ Spinner ⚠️ Text
Best For Windows 10/11 Mac users Older Windows

Which Version Should I Use?

Windows Users:

  • ✅ Use compress_video.ps1 (PowerShell) for best experience
  • ⚠️ Use compress_video.bat (CMD) for Windows 7/8 or compatibility

macOS Users:

  • ✅ Use compress_video.sh (Bash) - only option

Linux Users:

  • ⚠️ Bash version may work with modifications
  • FFmpeg URLs need updating for Linux

🛠️ Advanced Usage

Supported Video Formats

  • .mp4 - MP4 (most common)
  • .mkv - Matroska
  • .avi - AVI
  • .mov - QuickTime
  • .webm - WebM

Output Naming

Input: vacation.mp4
Output: vacation_compressed.mp4

Files are saved in the same directory with _compressed suffix.

FFmpeg Parameters

FastCompress uses optimized FFmpeg settings:

ffmpeg -i input.mp4 \
  -vcodec libx264 \      # H.264 codec
  -crf 23 \              # Quality (0-51)
  -preset medium \       # Encoding speed
  -acodec aac \          # Audio codec
  -b:a 192k \            # Audio bitrate
  output.mp4

Custom Compression

For advanced users, Custom mode allows:

  • CRF range: 0-51 (lower = better quality)
  • Presets: ultrafast, fast, medium, slow
  • Audio bitrate: Auto-adjusted based on CRF

📊 Performance Benchmarks

Sample Results (1080p, 10-minute video)

Preset Original Compressed Saved Quality Time
High 500 MB 400 MB 100 MB (20%) Excellent 3 min
Medium 500 MB 300 MB 200 MB (40%) Very Good 2.5 min
Low 500 MB 200 MB 300 MB (60%) Good 2 min

Results vary based on video content, resolution, and hardware

🐛 Troubleshooting

FFmpeg Download Fails

Problem: "Download failed" or "No internet connection"

Solution:

  1. Check your internet connection
  2. Try manual installation:
    • Windows: Download from GitHub
    • macOS: Install via Homebrew: brew install ffmpeg
  3. Place ffmpeg.exe (Windows) or ffmpeg (macOS) in script folder

PowerShell Execution Policy

Problem: "Scripts are disabled on this system"

Solution:

# Run as Administrator
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

# Or right-click script → Run with PowerShell

macOS Permission Denied

Problem: "Permission denied" when running script

Solution:

chmod +x compress_video.sh
./compress_video.sh

No Videos Found

Problem: "No video files found in current folder"

Solution:

  1. Ensure you're in the correct directory
  2. Check file extensions (must be: mp4, mkv, avi, mov, webm)
  3. Place script in the same folder as your videos

Compression Fails

Problem: "Compression failed" error

Solution:

  1. Check if input file is corrupted (try playing it)
  2. Ensure sufficient disk space (~2x input file size)
  3. Try different quality preset
  4. Check FFmpeg is working: ffmpeg -version

🤝 Contributing

Contributions are welcome! Please read CONTRIBUTING.md for guidelines.

Ways to contribute:

  • 🐛 Report bugs and issues
  • 💡 Suggest new features
  • 📝 Improve documentation
  • 🧪 Add test cases
  • 🌍 Add translations
  • ⭐ Star this repository!

Areas for improvement:

  • Batch compression support
  • Hardware acceleration (NVENC, QuickSync)
  • GUI version
  • Additional video formats
  • Linux support
  • Configuration file

📄 License

MIT License - see LICENSE file for details

TL;DR: Free to use, modify, and distribute. No warranty provided.

🙏 Acknowledgments

  • FFmpeg Team - For the amazing encoding engine
  • BtbN - For FFmpeg Windows builds
  • evermeet.cx - For macOS FFmpeg builds
  • Homebrew - For package management on macOS

📞 Support

Having issues?

  1. Check the Troubleshooting section
  2. Review AGENTS.md for technical details
  3. Open an issue on GitHub

Feature requests?

🌟 Show Your Support

If FastCompress helped you, please:

  • ⭐ Star this repository
  • 🐦 Tweet about it
  • 📝 Write a blog post
  • 💬 Tell your friends

📈 Changelog

v1.0 (2025-01-05)

  • ✨ Initial release
  • ✅ PowerShell version with full features
  • ✅ macOS Bash version
  • ✅ Windows CMD version
  • ✅ Auto FFmpeg download
  • ✅ Interactive file selection
  • ✅ 4 compression presets
  • ✅ Detailed statistics
  • ✅ Progress indicators
  • 📚 Comprehensive documentation

👨‍💻 Author

Faiz Intifada

  • GitHub: @julianromli
  • Created with ❤️ for easier video compression

📜 Citation

If you use FastCompress in your research or project, please cite:

@software{fastcompress2025,
  author = {Intifada, Faiz},
  title = {FastCompress: Interactive Video Compression Tool},
  year = {2025},
  url = {https://github.com/julianromli/fastcompress}
}

FastCompress v1.0 | Making video compression simple and accessible for everyone.

⬆ Back to Top

About

Fast Compress your videos with FFMPEG Powered. Easy to Use!

Resources

Readme

License

MIT license

Contributing

Contributing
Activity

Stars

8 stars

Watchers

0 watching

Forks

1 fork
Report repository

Releases

No releases published

Packages

No packages published

Languages