Video Toolbox
Complete video processing toolkit for AI agents. One script, 14 commands, zero hassle.
Powered by BytesAgain | hello@bytesagain.com
Description
Video Toolbox is a complete, production-ready video processing skill that wraps ffmpeg/ffprobe into a single, agent-friendly bash script. Unlike simpler tools that only extract frames, Video Toolbox covers the entire video processing workflow — from inspection to trimming, conversion, compression, watermarking, GIF creation, audio extraction, and beyond.
Every command includes input validation, meaningful error messages, and sensible defaults. Designed so an AI agent can confidently process any video file without memorizing ffmpeg's sprawling option syntax.
Requirements
- ffmpeg (>= 4.0) with libx264, libx265, libvpx-vp9, libmp3lame, libvorbis
- ffprobe (bundled with ffmpeg)
- bash (>= 4.0)
- python3 (for arithmetic and JSON parsing)
Install on Debian/Ubuntu: sudo apt install ffmpeg python3
Install on macOS: brew install ffmpeg python3
Commands
| Command | Description | Key Options |
|---|---|---|
info | Show video metadata (resolution, duration, codecs, bitrate, fps, audio) | --json for machine-readable output |
trim | Cut a segment from a video | --start, --end, --duration |
resize | Change video resolution | --width, --height, --scale (e.g. 0.5) |
convert | Convert between formats (mp4, webm, avi, mov, mkv) | --format, --codec |
extract-frames | Extract frames as images | --fps, --count, --format (jpg/png) |
extract-audio | Extract audio track to file | --format (mp3/wav/aac/flac) |
compress | Reduce file size | --quality (low/medium/high) |
thumbnail | Generate thumbnail(s) | --time, --width, --count |
gif | Convert video segment to animated GIF | --start, --duration, --fps, --width |
merge | Concatenate multiple videos | Multiple --input files |
watermark | Add text watermark overlay | --text, --position, --fontsize, --color, --opacity |
speed | Change playback speed (0.25x–4x, chain atempo) | --speed |
rotate | Rotate video (90°, 180°, 270°) | --angle |
metadata | View or edit file metadata | --set key=value, --clear |
Usage
# Get video info
bash scripts/main.sh info --input input.mp4
# Get video info as JSON
bash scripts/main.sh info --input input.mp4 --json
# Trim 30 seconds starting at 1:00
bash scripts/main.sh trim --input input.mp4 -o clip.mp4 --start 00:01:00 --duration 30
# Extract 10 frames evenly spaced (as jpg)
bash scripts/main.sh extract-frames --input input.mp4 -o ./frames/ --count 10 --format jpg
# Compress to medium quality
bash scripts/main.sh compress --input input.mp4 -o smaller.mp4 --quality medium
# Convert to WebM with specific codec
bash scripts/main.sh convert --input input.mp4 -o output.webm --format webm --codec libvpx-vp9
# Create GIF from first 5 seconds
bash scripts/main.sh gif --input input.mp4 -o preview.gif --start 0 --duration 5 --fps 10
# Add watermark with position and style
bash scripts/main.sh watermark --input input.mp4 -o marked.mp4 --text "© 2026" --position bottom-right --fontsize 32 --color yellow --opacity 0.8
# 2x speed (chain atempo for values outside 0.5-2.0)
bash scripts/main.sh speed --input input.mp4 -o fast.mp4 --speed 2.0
# 4x speed (auto-chains atempo filters)
bash scripts/main.sh speed --input input.mp4 -o fast4x.mp4 --speed 4.0
# 0.25x slow motion
bash scripts/main.sh speed --input input.mp4 -o slow.mp4 --speed 0.25
# Merge videos
bash scripts/main.sh merge --input part1.mp4 --input part2.mp4 --input part3.mp4 -o full.mp4
# Resize by scale factor
bash scripts/main.sh resize --input input.mp4 --scale 0.5
# Resize to specific dimensions
bash scripts/main.sh resize --input input.mp4 --width 1280 --height 720
# Generate thumbnail at specific time with width
bash scripts/main.sh thumbnail --input input.mp4 --time 00:00:30 --width 640
# Generate 5 thumbnails evenly spaced
bash scripts/main.sh thumbnail --input input.mp4 --count 5
# View metadata
bash scripts/main.sh metadata --input input.mp4
# Set metadata
bash scripts/main.sh metadata --input input.mp4 --set "title=My Video"
# Clear all metadata
bash scripts/main.sh metadata --input input.mp4 --clear -o clean.mp4
How the Agent Should Use This Skill
- Determine the user's goal (e.g., "make this video smaller", "grab a thumbnail", "convert to GIF").
- Map to the appropriate command from the table above.
- Run
bash scripts/main.sh <command> [options]from the skill directory. - The script outputs the result file path on success, or a clear error message on failure.
- Report the result to the user, including output file path and any relevant stats (file size, duration, resolution).
Common Options
| Option | Short | Description |
|---|---|---|
--input | -i | Input file (required for most commands) |
--output | -o | Output file (auto-generated if not specified) |
--start | -s | Start time (HH:MM:SS or seconds) |
--end | -e | End time |
--duration | -d | Duration |
--quality | -q | Quality preset: low, medium, high (compress only) |
Output Behavior
- All commands print the output file path on the last line of stdout on success.
- Errors go to stderr with a descriptive message and non-zero exit code.
- The
infocommand prints human-readable text by default, or JSON with--json. - Unknown options produce a warning on stderr and are skipped.
Notes
- Input files are never modified. All operations produce new output files.
- If
-o/--outputis omitted, a sensible default name is generated (e.g.,input_trimmed.mp4). - The script auto-detects codec support and falls back gracefully.
- Timestamps accept both
HH:MM:SSand seconds (e.g.,90=00:01:30). - Speed changes outside ffmpeg's native atempo range (0.5–2.0) are handled via chained atempo filters.
File Structure
video-toolbox/
├── SKILL.md # This file
├── tips.md # Usage examples and pro tips
└── scripts/
└── main.sh # The main processing script
💬 Feedback & Feature Requests: https://bytesagain.com/feedback Powered by BytesAgain | bytesagain.com