vidio-cli 0.1.0

A simple and easy-to-use ffmpeg wrapper for common video operations

vidio-cli

A simple and easy-to-use ffmpeg wrapper for common video operations.

Features

• Stupidly Easy: Simple CLI commands for common video operations.
• Powerful Defaults: Sensible defaults make it work great out of the box.
• Focused v1 Scope: Core commands people use repeatedly, without feature bloat.

Requirements

• Python 3.10+
• ffmpeg (must be installed and in your PATH)

v1 Command Scope

vidio-cli 0.1.0 intentionally focuses on practical, high-frequency tasks:

• list / ls: find video files quickly
• info: inspect metadata and streams
• trim: cut clips by time range
• resize: scale for delivery targets
• crop: convert to target aspect ratios
• concat: place videos side-by-side or stacked
• grid: build multi-video collages
• to-gif: convert clips to GIF with good defaults

Commands that are less consistently useful (for example, niche one-off transforms) are deferred to later releases.

Installation

# Using pip
pip install vidio-cli

# Using uv
uv pip install vidio-cli

Usage

# Get help
vidio --help

# Get help for a specific command
vidio concat --help

Concatenate Videos

# Concatenate videos horizontally
vidio concat video1.mp4 video2.mp4 output.mp4

# Concatenate videos vertically
vidio concat video1.mp4 video2.mp4 output.mp4 --vertical

List Video Files

# List videos in current directory (ls-style output)
vidio list
# or use the shorter alias
vidio ls

# List with detailed information (duration, resolution, codec)
vidio ls --list

# Search recursively in subdirectories
vidio ls --recursive

# Use table format instead of ls-style
vidio ls --table

# Get JSON output for scripting
vidio ls --json

Video Information

# Display detailed metadata about a video file
vidio info video.mp4

# Get machine-readable JSON output
vidio info video.mp4 --json

# Calculate exact frame count (slower but accurate)
vidio info video.mp4 --exact-frames

Create Video Grids

# Arrange videos in a 2x2 grid (auto-calculated)
vidio grid video1.mp4 video2.mp4 video3.mp4 video4.mp4 output.mp4

# Specify grid dimensions
vidio grid video1.mp4 video2.mp4 video3.mp4 video4.mp4 output.mp4 --rows 2 --cols 2

# Control cell size and add padding
vidio grid video1.mp4 video2.mp4 video3.mp4 video4.mp4 output.mp4 --width 640 --height 360 --padding 10

# Change background color
vidio grid video1.mp4 video2.mp4 video3.mp4 video4.mp4 output.mp4 --background white

Trim Videos

# Trim from 30 seconds to 90 seconds
vidio trim input.mp4 output.mp4 --start 30 --end 90

# Trim from 1:30 for 45 seconds duration
vidio trim input.mp4 output.mp4 --start 1:30 --duration 45

# Trim from beginning to 2:15
vidio trim input.mp4 output.mp4 --end 2:15

# Trim using different time formats
vidio trim input.mp4 output.mp4 --start 0:01:30 --end 0:02:45

Resize Videos

# Resize to specific dimensions (maintains aspect ratio)
vidio resize input.mp4 output.mp4 --width 1920 --height 1080

# Scale by percentage
vidio resize input.mp4 output.mp4 --scale 0.5  # 50% of original size

# Resize width only (height auto-calculated)
vidio resize input.mp4 output.mp4 --width 1280

# Resize height only (width auto-calculated)  
vidio resize input.mp4 output.mp4 --height 720

# Force exact dimensions (may distort)
vidio resize input.mp4 output.mp4 -w 1920 -h 1080 --force-aspect

Convert to GIF

# Basic conversion with optimized palette
vidio to-gif video.mp4 output.gif

# High quality with custom frame rate
vidio to-gif video.mp4 output.gif --fps 15 --quality high

# Small file size for web
vidio to-gif video.mp4 output.gif --scale 0.3 --fps 8 --quality low

# Convert specific time range
vidio to-gif video.mp4 output.gif --start 10 --duration 5

# Custom width with different dithering
vidio to-gif video.mp4 output.gif --width 800 --dither bayer

# Fast conversion (skip optimization)
vidio to-gif video.mp4 output.gif --no-optimize

Crop Videos

# Crop to center square (perfect for Instagram)
vidio crop input.mp4 output.mp4 --preset center-square

# Crop to 16:9 aspect ratio
vidio crop input.mp4 output.mp4 --preset 16:9

# Crop to 9:16 aspect ratio (vertical/portrait)
vidio crop input.mp4 output.mp4 --preset 9:16

# Crop to 4:3 aspect ratio
vidio crop input.mp4 output.mp4 --preset 4:3

# Custom crop region (centered)
vidio crop input.mp4 output.mp4 --width 1280 --height 720

# Custom crop with specific position
vidio crop input.mp4 output.mp4 -w 1280 -h 720 --x 100 --y 50

Development

# Clone the repo
git clone https://github.com/matanb/vidio-cli.git
cd vidio-cli

# Install dependencies
uv sync --group dev

# Run tests
uv run pytest -q

# Run lint
uv run ruff check .

License

MIT