1
1
Fork
You've already forked FitCheck
1
A bash and powershell wrapper for FFmpeg that scales CRF to hit a specific size limit
  • PowerShell 50.3%
  • Shell 49.7%
2026年03月27日 02:45:51 -04:00
.gitignore Add scripts and documentation 2026年02月11日 22:03:56 -05:00
CONTRIBUTING.md Add scripts and documentation 2026年02月11日 22:03:56 -05:00
fitcheck.ps1 Refactor with improved search 2026年02月25日 21:45:35 -05:00
fitcheck.sh fix final bump logic 2026年03月27日 02:45:51 -04:00
LICENSE Unlicense 2026年02月26日 16:00:34 -05:00
readme.md Refactor with improved search 2026年02月25日 21:45:35 -05:00

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.

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 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 Search: It encodes these samples at carefully chosen CRF values (using small 0.30 steps under the hood) using a Fibonacci zone search. Starting at CRF 30.00, it takes a large 23-step jump to orient itself, then narrows in through progressively smaller steps, 18, 8, then a final 3-step nudge. Each probe result either confirms the current direction or triggers course correction, so the search always narrows.
  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:

Variable Default Description
LIMIT_KB 39937 The hard size limit in KB (tuned for a 40MB cap with overhead).
TARGET_MIN_KB 37940 Preferred minimum size band; the script tries to land between this and LIMIT_KB.
ARRAY_BASE_100 1800 Absolute minimum CRF (18.00). The search array starts here.
ARRAY_MAX_N 110 Array length; n110 maps to CRF 51.00. The search won't go beyond this.
START_N 40 Starting index (CRF 30.00). The first probe always begins here.
MAX_DUR 180 Max duration in seconds. Clips longer than this are capped.

(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.