UncropMKV: The Complete Guide to Restoring Full‑Frame VideoRestoring a movie or TV episode to its original full-frame presentation can dramatically improve viewing quality and preserve the creator’s intended composition. UncropMKV is a tool designed to automate much of that work for MKV files: it detects and removes post-production cropping and letterboxing while restoring correct aspect ratio, frame size, and related metadata. This guide walks through what UncropMKV does, when to use it, how it works, step‑by‑step instructions (including common options), troubleshooting, and best practices to produce reliable full‑frame results.
What UncropMKV does — quick overview
UncropMKV analyzes an MKV file (typically one that has been cropped or letterboxed) and attempts to reconstruct the original video frame by:
- Detecting the active video area (visible pixels vs. black bars or masked regions).
- Restoring the original resolution and aspect ratio by adding back previously removed pixels or adjusting display aspect metadata.
- Updating container metadata (pixel dimensions, DAR/SAR, and crop flags) so players present the video at the intended framing.
- Optionally exporting the results as a new MKV or providing remuxing instructions.
When to use UncropMKV
Use UncropMKV when:
- A video file displays black bars or has been cropped in a way that removes information needed for proper framing.
- You want to restore the director’s intended composition or match other releases for consistent presentation.
- You’re preparing a library where consistent aspect ratio and full-frame playback matter (e.g., archival, home theatre, screening).
Do not use it when:
- The original source truly lacks the cropped areas (i.e., cropping removed content permanently from the source).
- You need pixel-perfect restoration of removed image areas — UncropMKV cannot recreate missing picture content; it restores frame parameters and removes letterboxing/crop wrappers when possible.
How it works (technical summary)
UncropMKV combines pixel analysis with container-level adjustments:
- Pixel analysis: The tool scans frames (or representative keyframes) to locate uniform black borders or masked regions and determines crop rectangles.
- Aspect and SAR/DAR calculations: From the detected active area and the container/codec properties, it computes display aspect ratio (DAR) and sample aspect ratio (SAR) needed to restore original presentation.
- Remuxing and metadata editing: It updates the MKV container to set new pixel dimensions, display widths/heights, and removes crop flags or adds padding where appropriate. It may also call external tools (ffmpeg, mkvmerge) to perform remuxes, add padding, or rewrap streams.
UncropMKV cannot:
- Recover pixels that were permanently cut from the source (no content generation).
- Always detect non-black letterboxing (e.g., colored bars or soft masks) without manual guidance.
Installation and prerequisites
Typical prerequisites:
- A modern OS (Windows, macOS, Linux).
- MKV tools such as mkvmerge/mkvtoolnix installed and available in PATH.
- FFmpeg installed if re-encoding, padding, or advanced remuxing is required.
- Python/Node runtime only if using a script-wrapper version; many distributions are standalone executables.
Install steps (example, generic):
- Download the UncropMKV package for your OS or clone the repository.
- Install mkvtoolnix and ffmpeg:
- Windows: use installers and ensure paths added to Environment Variables.
- macOS: use Homebrew (
brew install mkvtoolnix ffmpeg). - Linux: use your package manager (
apt,dnf,pacman) or compile from source.
- Place UncropMKV executable/script in a folder and ensure it’s executable.
Basic usage — step by step
- Prepare a copy of your source MKV (work on copies; never overwrite originals).
- Run an analysis pass to detect crop and aspect data. Example command patterns (replace with the tool’s actual syntax):
- uncropmkv –analyze input.mkv –output report.txt
- Review the analysis report. It should show detected crop rectangle, original container dimensions, and suggested target DAR/SAR.
- Apply the recommended fix:
- uncropmkv –apply input.mkv –output fixed.mkv This either remuxes with corrected display metadata or pads the video to the detected original dimensions.
- Test fixed.mkv in multiple players (VLC, MPC-HC, mpv) and on target devices (TV, projector) to ensure correct display.
Note: Some distributions offer a “dry run” mode showing remux commands (mkvmerge/ffmpeg) without executing them. Use that to inspect what will change.
Common options and what they do
- –analyze: scan video and report detected crop and aspect.
- –apply / –fix / –remux: perform the changes and produce a new MKV.
- –pad / –add-padding: physically add pixel rows/columns to restore frame dimensions (requires re-encoding or ffmpeg filterchains if codec/container doesn’t support void padding).
- –set-dar / –set-sar: manually enforce a display aspect ratio or sample aspect ratio.
- –frames N or –scan-interval: control how many frames or which frames are used for detection (more frames = safer detection for inconsistent bars).
- –black-threshold: adjust sensitivity for what counts as “black” (useful for near-black letterboxing).
- –no-reencode: attempt container-only changes (fast, no quality loss) — works only when padding or metadata changes suffice.
- –debug / –verbose: produce extended logs for troubleshooting.
Examples
Example 1 — fast container-only fix (no re-encode):
- Analyze to get suggested mkvmerge commands, then run mkvmerge with adjusted display widths/height or display unit flags to remove cropping.
Example 2 — pad with ffmpeg (if container-only change isn’t enough):
- Use ffmpeg pad filter to add back black pixels to reach the original frame size; re-encode or copy streams as supported:
ffmpeg -i input.mkv -vf "pad=width:height:x:y:color=black" -c:v libx264 -crf 18 -c:a copy output_padded.mkv(Adjust width/height/x/y based on analysis.)
Troubleshooting
- False detection (tool misses non-black bars or variable masks): increase frame samples (–frames) or lower black threshold. If still failing, manually specify crop values.
- Players still show black bars after fix: check player zoom/letterbox settings and verify the file’s display aspect ratio fields with mkvinfo or mediainfo.
- Quality loss after padding: avoid re-encoding when possible; use container-only solutions or lossless rewrap/copy. If re-encoding is unavoidable, use high-quality settings (e.g., libx264 CRF 18–22).
- Mixed content (scenes with subtitles burned into the bars): manual review is necessary — automatic tools may misinterpret embedded elements.
Best practices
- Keep originals and work on copies.
- Run analysis over multiple frames or the entire file if possible to handle variable bars.
- Prefer container-only fixes (metadata and remux) to avoid re-encoding.
- Check results in multiple players and on target display devices.
- Document the change (notes in filename or sidecar text) so library organization remains clear.
Limitations and ethical considerations
- Restoring metadata and padding is safe and legal when performed on your legally obtained content. Do not use tools to bypass DRM or distribute copyrighted material.
- UncropMKV cannot resurrect permanently removed visual data — it restores presentation, not lost content.
Quick checklist before you start
- Backup original MKV.
- Install mkvtoolnix and ffmpeg.
- Run analysis and inspect results.
- Choose container-only remux if possible; otherwise prepare to pad/re-encode with high-quality settings.
- Verify on multiple players and displays.
If you’d like, I can:
- Provide exact command examples tailored to your OS and the UncropMKV command syntax you’re using.
- Walk through a specific file if you paste its mediainfo or the UncropMKV analysis report.
Leave a Reply