crop4mkv

Bun TS script that analyzes crop margins of a video and sets the flags for an MKV.

• This script searches with ffmpeg cropdetect at multiple different points in the video to check the crop.
• It then takes the crop per axis that clips the fewest pixels (the safe crop).
• The crop is then saved into the MKV flags with MKVToolNix without touching the video stream.

Video players like MPV read this MKV flag and crop the video at play time.

Usage

Generate and set crop tags for a single file:

crop4mkv ./myVideo.mkv

Generate and set crop tags recursively for a directory:

crop4mkv ./myDir/

Do not write tag to file:

crop4mkv --dryrun PATH

Skip check for the existence of crop tags:

crop4mkv --overwrite PATH

Sometimes a movie or show might have a few scenes that are in a different format. If almost the entire video is 21/9, but one scene is 16/9, it might make sense to ignore that one scene by filtering outliers:

crop4mkv --filter PATH

If you wish filter a large library regularly, you might be interested in the --guard flag. When enabled crop4mkv writes a database into the directory that is scanned, which in turn is used in every consecutive call for skipping already processed files (or files that ffmpeg does not like).

crop4mkv ./myBigAssLibrary/ --guard # create db and ignore already processed files

crop4mkv ./myBigAssLibrary/ --guard --overwrite # create db but do not ignore processed files

For some options, there exist shorthand flags, which you can write together:

crop4mkv PATH -dof # Dryrun, Overwrite, Filter

crop4mkv PATH -o # Overwrite

Prerequisites

• MKVToolNix installed and in PATH.
• ffmpeg installed and in PATH.
• bun installed and in PATH.

I recommend for Windows users to install these dependencies apart from bun with Scoop:

scoop bucket add main
scoop install main/ffmpeg
scoop bucket add extras
scoop install extras/mkvtoolnix

Installation

bun install -g crop4mkv

Images