CLI reference¶
vexy-vid has two commands, crop and trim. Both read one video, write one
video, and accept --scale to resize the result.
The command-line interface is generated by
Python Fire from the crop() and
trim() function signatures. Run vexy-vid crop --help or
vexy-vid trim --help to see the flags your installed version accepts.
Capitalised flags
--Halign, --Valign and --Letterbox start with a capital letter. Fire
turns each Python parameter name into a flag of the same spelling, so
--letterbox (lower case) is not recognised.
crop¶
Keep a window of a given size and discard the rest.
| Flag | Short | Default | Meaning |
|---|---|---|---|
--input |
-i |
standard input | Input video path. When missing, one line is read from standard input. |
--output |
-o |
generated | Output video path. See Output file names. |
--crop |
-c |
full frame | Size of the window to keep, in any size format. |
--scale |
-s |
none | Size to scale to after cropping. Percentages refer to the cropped size. |
--Halign |
-H |
50 |
Horizontal window position: 0 left, 50 centre, 100 right. |
--Valign |
-V |
50 |
Vertical window position: 0 top, 50 centre, 100 bottom. |
--quality |
-q |
1 |
0 fast, 1 balanced, 2 quality. See Hardware acceleration. |
--verbose |
-v |
False |
Show debug logs and ffmpeg's info output. |
How the window is placed¶
crop computes the window size from --crop, then places it with the
alignment values:
x = (original width − window width) × Halign / 100y = (original height − window height) × Valign / 100
For a 1920×1080 input and --crop 1440x1080 --Halign 0, the window is
1440×1080 at x = 0: the right 480 pixels are removed. With --Halign 100,
the window starts at x = 480 and the left 480 pixels are removed.
--Halign and --Valign accept any number between 0 and 100, and a trailing
% is ignored (--Halign 25% equals --Halign 25).
If the requested window is wider or taller than the input, crop logs a
warning and uses the original dimension for that axis.
If you pass --scale without --crop, crop only scales the video, and
percentages in --scale refer to the original size.
Examples¶
# Exact pixels
vexy-vid crop --crop 1280x720 --input video.mp4
# Aspect ratio, window at the bottom of the frame
vexy-vid crop --crop 16:9 --Halign 0 --Valign 100 --input video.mp4
# Half the width and half the height
vexy-vid crop --crop 50%x50% --input video.mp4
# Crop to 16:9, then scale to 1920x1080
vexy-vid crop --crop 16:9 --scale 1920x1080 --input video.mp4
trim¶
Remove pixels from the edges, like CSS padding in reverse.
vexy-vid trim [--top N] [--right N] [--bottom N] [--left N] [--Letterbox] [--subtitles] --input FILE
| Flag | Short | Default | Meaning |
|---|---|---|---|
--input |
-i |
standard input | Input video path. When missing, one line is read from standard input. |
--output |
-o |
generated | Output video path. |
--top |
-t |
0 |
Pixels (100) or percentage of the height (10%) to remove from the top. |
--right |
-r |
0 |
Pixels or percentage of the width to remove from the right. |
--bottom |
-b |
0 |
Pixels or percentage of the height to remove from the bottom. |
--left |
-l |
0 |
Pixels or percentage of the width to remove from the left. |
--scale |
none | none | Size to scale to after trimming. Percentages refer to the trimmed size. |
--Letterbox |
-L |
False |
Detect and remove black bars at the top and bottom. |
--subtitles |
none | False |
Detect and remove the subtitle band at the bottom. |
--quality |
-q |
1 |
0 fast, 1 balanced, 2 quality. |
--verbose |
-v |
False |
Show debug logs and ffmpeg's info output. |
How manual and detected trims combine¶
--Letterbox sets the top and bottom trims. --subtitles sets the bottom trim.
When you also pass --top or --bottom, trim uses the larger value on each
edge, so a manual value never reduces a detected one.
For a 1080-pixel-tall input with 140-pixel bars and --Letterbox --bottom 200,
the top trim is 140 and the bottom trim is max(200, 140) = 200.
Letterbox detection only affects the top and bottom edges. Use --left and
--right for pillarbox bars.
Limits¶
Before encoding, trim checks the result:
- If the trims leave a width or height of zero or less, or remove more than
half of the width or height,
trimstops withValueError: Trim values too large or invalid. - If the aspect ratio changes by more than 30 %,
trimlogs a warning and continues. - If the detected subtitle band is taller than half of the content height,
trimreduces it to 30 % of the content height and logs a warning.
Examples¶
# Remove fixed amounts
vexy-vid trim --top 100 --bottom 50 --input video.mp4
# Remove 10% from each side
vexy-vid trim --left 10% --right 10% --input video.mp4
# Remove letterbox bars
vexy-vid trim --Letterbox --input video.mp4
# Remove the subtitle band, and at least 20 pixels from the bottom
vexy-vid trim --subtitles --bottom 20 --input video.mp4
# Remove bars, then scale
vexy-vid trim --Letterbox --scale 1920x1080 --input video.mp4
Size formats¶
--crop (in crop) and --scale (in both commands) take a size
specification. It is parsed by parse_size() in vexy_vid/utils.py.
| Format | Example | Result for a 1920×1080 reference |
|---|---|---|
W:H |
16:9 |
The largest 16:9 window that fits: 1920×1080 |
W:H |
4:3 |
1440×1080 |
WxH |
1280x720 |
1280×720 |
P%xP% |
50%x50% |
960×540 |
P% |
50% |
960×540 |
Wx |
1280x |
1280×1080 (height unchanged) |
xH |
x720 |
1920×720 (width unchanged) |
| Mixed | 1280x50% |
1280×540 |
A ratio keeps one full dimension: if the target ratio is wider than the input,
the full width is kept and the height is reduced; otherwise the full height is
kept and the width is reduced. The x separator is not case-sensitive. Any
other format raises ValueError: Unrecognized size format.
The edge flags of trim (--top, --right, --bottom, --left) take a
single value: a pixel count or a percentage.
Output file names¶
When you do not pass --output, the output goes next to the input as
<name>_<command>_<parameters><extension>.
| Command | Output name |
|---|---|
vexy-vid crop --crop 16:9 -i movie.mp4 |
movie_crop_16-9.mp4 |
vexy-vid crop --crop 50%x50% -i movie.mp4 |
movie_crop_50px50p.mp4 |
vexy-vid trim --top 100 --bottom 50 -i movie.mp4 |
movie_trim_t100_b50.mp4 |
vexy-vid trim --Letterbox -i movie.mp4 |
movie_trim_llb.mp4 |
vexy-vid trim --subtitles -i movie.mp4 |
movie_trim_ssub.mp4 |
In crop names, : becomes - and % becomes p. In trim names, each
parameter is written as its first letter followed by its value. An existing
file with the same name is overwritten.
Audio and container¶
The audio stream is copied without re-encoding (-acodec copy). The output
container follows the output file extension, because ffmpeg chooses the muxer
from the file name.
Exit status¶
When an operation fails, the Python exception is printed with a traceback and
vexy-vid exits with status 1.