FitCheck

A cross-platform FFmpeg automation script that intelligently finds the optimal CRF for 40 MB file targets using predictive sampling and adaptive iteration. Perfect for platforms with strict upload limits.

Table of Contents

1. Requirements
2. Downloads
3. Windows Usage (PowerShell)
4. Linux & macOS Usage (Bash)
5. How It Works
6. Script Options & Tweaks
7. Troubleshooting
8. License

Requirements

Before running the script, you must have FFmpeg installed.

• Check: Open your terminal/PowerShell and type ffmpeg -version.
• Install: Download at ffmpeg.org. (Bumps by 2)
• Windows tip: Use winget install ffmpeg in PowerShell.

Downloads

Download the appropriate script for your system:

• Windows: fitcheck.ps1
• Linux/macOS: fitcheck.sh

Windows Usage (PowerShell)

The Windows version uses PowerShell (.ps1) for native path handling and performance.

1. Enable Scripting

Windows restricts scripts by default. Open PowerShell as Administrator and run:

Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

2. Run the Script

Navigate to the folder containing your downloaded script and video, then run:

# Standard run
.\fitcheck.ps1 -InputFile "myvideo.mp4"
# Verbose mode (shows FFmpeg progress/errors)
.\fitcheck.ps1 -InputFile "myvideo.mp4" -v

Linux & macOS Usage (Bash)

1. Make it Executable

After downloading, open your terminal in that folder and grant permissions:

chmod +x fitcheck.sh

2. Run the Script

# Standard run
./fitcheck.sh input.mp4
# Verbose mode (shows FFmpeg progress/errors)
./fitcheck.sh input.mp4 -v

How It Works

FitCheck uses a "Test & Adjust" loop to find the highest quality that fits your target size:

1. Analysis: The script extracts the frame rate and total duration. It automatically calculates an ideal GOP (Group of Pictures) for smooth playback.
2. Automatic Naming: You only need to provide the input file. The script automatically names the output as filename-fitcheck.mp4.
3. Smart Sampling: Instead of a single slice, it builds a short sample from multiple segments across the video to better reflect different content types, while automatically handling short clips so it doesn’t try to seek into empty space.
4. Pre-Flight Loop: It encodes these samples at carefully chosen CRF values (using small 0.30 steps under the hood). If the projected size is over 40MB, it adjusts the CRF (trading quality for size) using a binary-style search inside a "high probability" zone instead of just bumping blindly.
5. Final Render: It processes the full video (capped at 180s) using the CRF value selected during the pre-flight stage.
6. The Safety Net: If the final file still manages to creep over the limit (common in high-motion scenes), the script catches it, bumps the quality down slightly, and re-renders. If the result lands far under the target band, it may bump quality back up one notch unless it already knows that setting will overshoot.

Script Options & Tweaks

You can open the scripts in a text editor to customize these variables:

(Internally, CRF is handled as an integer in "hundredths" so the script can move in 0.30 steps, e.g., 30.00 → 29.70 → 29.40.)

Troubleshooting

• "Permission Denied": On Linux/Mac, ensure you ran chmod +x fitcheck.sh.
• "File cannot be loaded because running scripts is disabled": (Windows) Run the Set-ExecutionPolicy command mentioned in the Windows section.
• "command not found: ffprobe": FFmpeg isn't in your System PATH. Restart your terminal or PC after installation.
• Inaccurate Projections: High-motion videos (gaming, sports, birds in flight) are harder to predict than static shots. The script is designed to catch these in the "Final Render Loop" and fix them automatically.
• Short Videos: The script automatically detects if a video is under 30 seconds and adjusts its sampling logic so it doesn't try to "seek" into empty space.

License

This project is released into the public domain under the Unlicense. Feel free to use, modify, and distribute it however you like.