🎬 ai-ffmpeg-cli

Stop Googling ffmpeg commands. Just describe what you want.

ai-ffmpeg-cli is an AI-powered CLI that translates natural language into safe, previewable ffmpeg commands. Built for developers, content creators, and anyone who works with media files but doesn't want to memorize complex syntax.

✨ Why ai-ffmpeg-cli?

🤖 AI-Native: Translate plain English to perfect ffmpeg commands
🔒 Safety First: Preview every command before execution
⚡ 10x Faster: Skip the documentation, Stack Overflow, and trial-and-error
🎯 Battle-Tested: Generates reliable, production-ready commands
🔄 Smart Defaults: Sensible codec and quality settings out of the box
🎨 Beautiful Interface: Colorful ASCII art and responsive terminal UI
📊 Token Tracking: Monitor your AI usage and costs in real-time

# Instead of this...
ffmpeg -i input.mp4 -vf "scale=1280:720" -c:v libx264 -c:a aac -b:v 2000k output.mp4

# Just say this... (cli command is different)
aiclip "convert input.mp4 to 720p with good quality"

🚀 Quick Start

Installation

# Install from PyPI
pip install ai-ffmpeg-cli

Setup

# Set your OpenAI API key
export OPENAI_API_KEY="sk-your-key-here"

# Or create a .env file
echo "OPENAI_API_KEY=sk-your-key-here" > .env

First Command

Interactive mode (type your request after launching):

aiclip

                                       ___    ____________    ________ 
                                      /   |  /  _/ ____/ /   /  _/ __ \
                                     / /| |  / // /   / /    / // /_/ /
                                    / ___ |_/ // /___/ /____/ // ____/ 
                                   /_/  |_/___/\____/_____/___/_/      

                                    AI-Powered Video & Audio Processing

                       ────────────────────────────────────────────────────────────

╭─────────────────────────────────────── Welcome to Interactive Mode ───────────────────────────────────────╮
│                                                                                                           │
│  ai-ffmpeg-cli v0.2.5                                                                                     │
│                                                                                                           │
│  AI-powered video and audio processing with natural language                                              │
│  Type your request in plain English and let AI handle the ffmpeg complexity!                              │
│                                                                                                           │
╰───────────────────────────────────────────────────────────────────────────────────────────────────────────╯

               Available Media Files               
┏━━━━━━━━┳━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃  Type  ┃ Count ┃ Files                          ┃
┡━━━━━━━━╇━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ Videos │   1   │ • input.mp4                    │
│ Images │   2   │ • logo.png                     │
│        │       │ • watermark.png                │
└────────┴───────┴────────────────────────────────┘

╭────────────────────────────────────────── Output Configuration ───────────────────────────────────────────╮
│ Output Directory: /path/to/your/aiclip                                                                    │
│ Generated files will be saved here                                                                        │
╰───────────────────────────────────────────────────────────────────────────────────────────────────────────╯

aiclip> convert this video to 720p

📊 parse_intent: 2,073 → 47 (2,120 total) | $0.0057

┏━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━┓
┃ # ┃ Command                                      ┃ Output                                        ┃ Status ┃
┡━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━┩
│ 1 │ ffmpeg -i input.mp4 -vf scale=1280:720...    │ /path/to/your/aiclip/input_720p.mp4           │  New   │
└───┴──────────────────────────────────────────────┴───────────────────────────────────────────────┴────────┘

╭────────────────────────────────────────── Confirmation Required ──────────────────────────────────────────╮
│                                                                                                           │
│  Run these commands?                                                                                      │
│                                                                                                           │
╰───────────────────────────────────────────────────────────────────────────────────────────────────────────╯
 [y/n]: Using default: Y

Or run a one-shot command (no interactive prompt):

aiclip --dry-run "convert input.mp4 to 720p with good quality"

📖 Usage Examples

Video Processing

# Convert formats
aiclip "convert input.mov to mp4 with h264 and aac"

# Resize videos  
aiclip "downscale video.mp4 to 720p"
aiclip "make input.mp4 1080p resolution"

# Compress files
aiclip "compress large-video.mp4 to smaller size"
aiclip "reduce file size with CRF 23"

# Create animated GIFs
aiclip "convert input.mp4 to animated gif"
aiclip "create a 5 second animated gif from video.mp4"

Audio Operations

# Extract audio
aiclip "extract audio from movie.mp4 to mp3"
aiclip "get audio track from video as wav"

# Remove audio
aiclip "remove audio from video.mp4"

Trimming & Cutting

# Time-based cutting
aiclip "trim first 30 seconds from video.mp4"
aiclip "keep segment from 2:15 to 3:45 in input.mp4"
aiclip "cut out middle 5 minutes"

Image Extraction

# Thumbnails
aiclip "create thumbnail at 10 seconds from video.mp4"
aiclip "extract frame at 2:30 as PNG"

# Frame sequences
aiclip "extract one frame every 5 seconds"
aiclip "get all frames from video as images"

Advanced Operations

# Overlays
aiclip "add watermark logo.png to top-right of video.mp4"  
aiclip "overlay text on video at position 10:10"

# Batch processing
aiclip "convert all .mov files to .mp4"

🎛️ Command Line Options

# One-shot mode (no interaction)
aiclip "your command here"

# Skip confirmation prompts  
aiclip --yes "convert video.mp4 to 720p"

# Preview only (don't execute)
aiclip --dry-run "compress input.mp4"

# Use different AI model
aiclip --model gpt-4o-mini "extract audio"

# Increase timeout for complex requests
aiclip --timeout 120 "complex processing task"

# Verbose logging for troubleshooting
aiclip --verbose "your command"

# Specify custom output directory
aiclip --output-dir /path/to/output "convert video.mp4 to 720p"

Interactive Mode Features

# View token usage statistics anytime
aiclip> tokens

# Beautiful ASCII art welcome screen
# Responsive terminal UI that adapts to your screen width
# Real-time token usage tracking with cost estimates

Subcommands and option placement

You can also use the explicit nl subcommand. Put global options before the subcommand:

aiclip --yes nl "thumbnail at 10s from test.mp4"
aiclip --dry-run --model gpt-4o-mini nl "compress input.mp4"

Do not invoke the binary twice:

# Incorrect
aiclip aiclip --yes nl "..."

🔧 Configuration

aiclip uses environment variables and .env files for configuration:

# Required
OPENAI_API_KEY=sk-your-openai-api-key

# Optional
AICLIP_MODEL=gpt-4o              # AI model to use
AICLIP_DRY_RUN=false            # Preview commands by default
AICLIP_OUTPUT_DIR=aiclip        # Default output directory

🎯 Smart Defaults & Safety

Preview First: Every command is shown before execution
Overwrite Protection: Warns before overwriting existing files
Sensible Codecs: Automatically chooses h264+aac for MP4, libx265 for compression
Stream Copy: Uses -c copy for trimming when possible (faster, lossless)
Context Aware: Scans your directory to suggest input files and durations
Organized Output: All generated files are saved to a dedicated output directory
Duration Support: Automatically handles time-based requests (e.g., "5 second GIF")
Token Transparency: Real-time tracking of AI usage and costs
Responsive UI: ASCII art and tables adapt to your terminal width

📁 Output Directory Management

aiclip automatically organizes all generated files in a dedicated output directory:

# Default behavior - files saved to "aiclip" folder
aiclip "convert video.mp4 to 720p"
# Output: ./aiclip/video_720p.mp4

# Custom output directory
aiclip --output-dir /path/to/output "convert video.mp4 to 720p"
# Output: /path/to/output/video_720p.mp4

# Environment variable configuration
export AICLIP_OUTPUT_DIR=my_outputs
aiclip "convert video.mp4 to 720p"
# Output: ./my_outputs/video_720p.mp4

Benefits:

🗂️ Organized: All generated files in one place
🔍 Easy to find: No more searching through mixed directories
🧹 Clean workspace: Input files stay separate from outputs
📊 Progress tracking: See all your generated files at a glance

📊 Token Usage Tracking

aiclip provides complete transparency into your AI usage and costs:

# Real-time token usage displayed after each operation
aiclip> convert video.mp4 to 720p
📊 parse_intent: 2,073 → 47 (2,120 total) | $0.0057

# View detailed session statistics anytime
aiclip> tokens

                     Token Usage Summary                     
┏━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Metric         ┃    Value ┃ Details                       ┃
┡━━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ Session ID     ┃ a1b2c3d4 ┃ Started at 14:30:15           │
│ Duration       ┃     45.2s ┃ Session duration              │
│ Operations     ┃        3 ┃ Total operations performed    │
│ Input Tokens   ┃    6,142 ┃ Total tokens sent to AI       │
│ Output Tokens  ┃      156 ┃ Total tokens received from AI │
│ Total Tokens   ┃    6,298 ┃ Combined input + output       │
│ Estimated Cost ┃  $0.0171 ┃ Based on OpenAI pricing       │
└────────────────┴──────────┴───────────────────────────────┘

# Session summary displayed at the end of each session

Features:

💰 Cost Transparency: Real-time cost estimates based on current OpenAI pricing
📈 Usage Analytics: Track tokens per operation and session totals
🕒 Session Tracking: Monitor duration and operation counts
🎯 Model-Specific: Accurate token counting for GPT-4o, GPT-3.5-turbo, and more
📊 Beautiful Tables: Rich formatting that adapts to your terminal

⏱️ Duration and Time Handling

aiclip intelligently handles time-based requests for video and GIF creation:

# Create GIFs with specific duration
aiclip "convert video.mp4 to 5 second animated gif"
aiclip "create a 10 second animated gif from input.mp4"

# Time-based video operations
aiclip "extract first 30 seconds from video.mp4"
aiclip "create 15 second clip from input.mp4"

# Thumbnails at specific times
aiclip "extract frame at 2:30 from video.mp4"
aiclip "create thumbnail at 10 seconds from input.mp4"

Supported time formats:

Seconds: "5 second", "10s", "30 seconds"
Time codes: "2:30", "1:45:30", "00:02:15"
Duration: "5 second duration", "10 second clip"

📊 Supported Operations

Operation	Examples	ffmpeg Equivalent
Convert	"convert to mp4", "make it h264"	`-c:v libx264 -c:a aac`
Resize	"720p", "1920x1080", "scale to 50%"	`-vf scale=1280:720`
Compress	"make smaller", "CRF 28"	`-c:v libx265 -crf 28`
Extract Audio	"get audio as mp3"	`-q:a 0 -map a`
Trim	"first 30 seconds", "2:15 to 3:45"	`-ss 00:02:15 -to 00:03:45`
Thumbnail	"frame at 10s"	`-ss 00:00:10 -vframes 1`
Overlay	"watermark top-right"	`-filter_complex overlay=W-w-10:10`
Batch	"all *.mov files"	Shell loops with glob patterns
GIF Creation	"animated gif", "5 second gif"	`-vf fps=10,scale=320:-1:flags=lanczos,split[s0][s1];[s0]palettegen[p];[s1][p]paletteuse -c:v gif`

🛠️ Development

# Clone and setup
git clone https://github.com/d-k-patel/ai-ffmpeg-cli.git
cd ai-ffmpeg-cli
make setup

# Run tests
make test

# Check code quality  
make lint

# Try demo commands
make demo

📋 Requirements

Python 3.10+ (uses modern type hints)
ffmpeg installed and available in PATH
- macOS: brew install ffmpeg
- Ubuntu: sudo apt install ffmpeg
- Windows: Download from ffmpeg.org
OpenAI API key for natural language processing
Terminal with color support for the best visual experience

🆘 Troubleshooting

Common Issues

"OPENAI_API_KEY is required"

# Set your API key
export OPENAI_API_KEY="sk-your-key-here"
# Or add it to .env file

"ffmpeg not found in PATH"

# Install ffmpeg
brew install ffmpeg          # macOS
sudo apt install ffmpeg      # Ubuntu
# Windows: download from ffmpeg.org

"Failed to parse natural language prompt"

Try being more specific in your request
Use --model gpt-4o for better accuracy
Increase timeout with --timeout 120
Check your internet connection

"No input files found"

Ensure files exist in current directory
Check file extensions match your request
Use ls to verify available files

"Duration not applied to GIF/video"

Be explicit about duration: "5 second animated gif"
Use clear time specifications: "10 second video clip"
Check that the AI model includes duration in the generated command

Getting Help

📖 Documentation: Full guides at [docs link]
💬 Discord: Join our community for real-time help
🐛 Issues: Report bugs on GitHub Issues
💡 Discussions: Feature requests and Q&A on GitHub Discussions

🤝 Contributing

We love contributions! Whether it's:

🐛 Bug reports and feature requests
📖 Documentation improvements
🧪 Test cases for edge scenarios
💻 Code contributions for new features
🎨 Examples and tutorials

See our Contributing Guide to get started.

📈 What's Next?

🔄 Batch Templates: Save and reuse complex workflows
🎛️ GUI Mode: Visual interface for non-CLI users
⚡ Local Models: Run without internet using local AI
🏢 Team Features: Shared commands and analytics
🔌 Integrations: GitHub Actions, Docker, CI/CD pipelines
🎬 Enhanced Duration Support: Better handling of time-based requests
📁 Advanced Output Management: Custom naming patterns and organization
📊 Usage Analytics: Historical token usage tracking and reporting
🎨 Theme Customization: Customizable color schemes and ASCII art fonts

📄 License

MIT License - see LICENSE file for details.

⭐ Support

If aiclip saves you time, please:

⭐ Star this repository
🐦 Share on social media
📝 Write a review or blog post
💬 Tell your developer friends

Made with ❤️ by developers who got tired of Googling ffmpeg commands
_{🎬 Turn your words into perfect video commands}

Name		Name	Last commit message	Last commit date
Latest commit History 34 Commits
.github		.github
docs		docs
src/ai_ffmpeg_cli		src/ai_ffmpeg_cli
tests		tests
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
bandit_report.json		bandit_report.json
mkdocs.yml		mkdocs.yml
pyproject.toml		pyproject.toml

Uh oh!

License

d-k-patel/ai-ffmpeg-cli

Folders and files

Latest commit

History

Repository files navigation

🎬 ai-ffmpeg-cli

✨ Why ai-ffmpeg-cli?

🚀 Quick Start

Installation

Setup

First Command

📖 Usage Examples

Video Processing

Audio Operations

Trimming & Cutting

Image Extraction

Advanced Operations

🎛️ Command Line Options

Interactive Mode Features

Subcommands and option placement

🔧 Configuration

🎯 Smart Defaults & Safety

📁 Output Directory Management

📊 Token Usage Tracking

⏱️ Duration and Time Handling

📊 Supported Operations

🛠️ Development

📋 Requirements

🆘 Troubleshooting

Common Issues

Getting Help

🤝 Contributing

📈 What's Next?

📄 License

⭐ Support

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Sponsor this project

Uh oh!

Packages 0

Uh oh!

Languages

Packages