AI-FFmpeg-CLI: Turn Plain English into FFmpeg Commands

AI-FFmpeg-CLI is a command-line utility that leverages AI to translate natural language descriptions into complex FFmpeg commands. You no longer need to memorize arcane syntax; simply describe what you want to achieve, and the tool handles the rest.

Key Features:

• Natural Language Interface – Provide a plain English request, and the tool generates the corresponding FFmpeg command.
• Safety Previews – Review the generated command before execution to ensure accuracy and prevent errors.
• Efficiency – Bypass documentation, Stack Overflow threads, and trial-and-error debugging.
• Production-Ready Output – Generates reliable commands suitable for professional workflows.
• Intelligent Defaults – Automatically selects H.264 + AAC for MP4 files and libx265 for high-efficiency compression.
• Terminal UI – Features a clean interface with ASCII headers and a responsive layout.
• Cost Transparency – Displays token usage and estimated API costs for every operation.
• Versatile Operations – Convert formats, resize, compress, generate GIFs, extract or remove audio, trim clips, capture frames, and add watermarks or text overlays.
• Highly Customizable – Supports one-shot mode, auto-confirmation, dry runs, specific AI model selection, custom timeouts, and defined output directories.
• Automatic Organization – Saves generated files in a dedicated folder to keep your source directory clean.
• Smart Time Parsing – Understands intuitive phrases like “5 seconds,” “2:30,” or “the first 30 seconds.”
• Context Awareness – Scans your current directory for media files and suggests them as inputs.
• Overwrite Protection – Provides a warning before overwriting existing files.

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

Now: aiclip "convert input.mp4 to 720p with good quality"

Quick Start

Installation

Install via PyPI:

pip install ai-ffmpeg-cli

Set up your API key

You can configure your OpenAI API key in two ways:

1. Export it to your environment:

export OPENAI_API_KEY="sk-your-key-here"

2. Or save it in a .env file:

echo "OPENAI_API_KEY=sk-your-key-here" > .env

First Run

Interactive Mode – Simply type aiclip. This opens a welcome screen showing media files in the current folder and current output settings. Enter your request, review the generated command, and confirm to run.

One-Shot Command – Execute tasks directly without entering the interactive shell. For example, to preview a compression command:

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

Examples

Video

• Convert Format – aiclip "convert input.mov to mp4 with h264 and aac"
• Resize – aiclip "downscale video.mp4 to 720p" or aiclip "make input.mp4 1080p resolution"
• Compress – aiclip "compress large-video.mp4 to a smaller size" or aiclip "reduce file size with CRF 23"
• Generate GIFs – aiclip "convert input.mp4 to animated gif" or aiclip "create a 5 second animated gif from video.mp4"

Audio

• Extract Audio – aiclip "extract audio from movie.mp4 to mp3" or aiclip "get audio track from video as wav"
• Remove Audio – aiclip "remove audio from video.mp4"

Trim & Cut

• aiclip "trim the first 30 seconds from video.mp4"
• aiclip "keep the segment from 2:15 to 3:45 in input.mp4"
• aiclip "cut out the middle 5 minutes"

Frames & Thumbnails

• Thumbnails – aiclip "create a thumbnail at 10 seconds from video.mp4" or aiclip "extract frame at 2:30 as PNG"
• Frame Sequences – aiclip "extract one frame every 5 seconds" or aiclip "get all frames from video as images"

Advanced Tasks

• Overlays – aiclip "add watermark logo.png to top-right of video.mp4" or aiclip "overlay text on video at position 10:10"
• Batch Processing – aiclip "convert all .mov files to .mp4"

Command-Line Options

You can also use the nl (natural language) subcommand. Global flags should be placed before the subcommand:

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

Note: Avoid repeating the command name (e.g., do not use aiclip aiclip --yes nl).

Configuration

Configure the tool using environment variables or a .env file.

Required:

• OPENAI_API_KEY=sk-your-openai-api-key

Optional:

• AICLIP_MODEL=gpt-4o – Specifies the AI model.
• AICLIP_DRY_RUN=false – Enables preview mode by default.
• AICLIP_OUTPUT_DIR=aiclip – Sets the default output directory.

Smart Defaults & Safety

• Mandatory Previews – Shows the command before execution so you stay in control.
• Overwrite Protection – Alerts you if an output filename already exists.
• Auto-Codec Selection – Defaults to H.264 + AAC for MP4 and libx265 for compression tasks.
• Efficient Trimming – Uses -c copy whenever possible for lossless, instant cutting.
• Context Awareness – Scans your directory to intelligently suggest input files.
• Organized Workspace – Automatically moves all generated files into a dedicated folder.
• Intuitive Time Handling – Processes phrases like "5 second GIF" without requiring specific timecodes.
• Token Transparency – Provides real-time visibility into AI costs.
• Responsive Interface – ASCII art and tables adjust to your terminal’s width.

Output Directory Management

The tool maintains a clean workspace by organizing your files:

• Default Behavior – Saves output to ./aiclip/ (e.g., ./aiclip/video_720p.mp4).
• Custom Folders – Using aiclip --output-dir /path/to/output "convert video.mp4 to 720p" results in /path/to/output/video_720p.mp4.
• Environment Configuration – Setting export AICLIP_OUTPUT_DIR=my_outputs will direct all results to ./my_outputs/.

Keeping generated files separate prevents clutter in your source folders and makes it easier to track project assets.

Token Usage Tracking

Every operation provides an immediate summary of token consumption and estimated cost:

aiclip> convert video.mp4 to 720p
📊 parse_intent: 2,073 → 47 (2,120 total) | $0.0057

In interactive mode, type tokens to view a comprehensive session summary:

                     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       │
└────────────────┴──────────┴───────────────────────────────┘

A summary is also displayed automatically upon exiting the session.

Time & Duration Handling

The tool supports a variety of time formats:

• Seconds: "5 second", "10s", "30 seconds"
• Timecodes: "2:30", "1:45:30", "00:02:15"
• Descriptive Phrases: "5 second duration", "10 second clip"

Examples:

• aiclip "convert video.mp4 to a 5 second animated gif"
• aiclip "extract the first 30 seconds from video.mp4"
• aiclip "extract a frame at 2:30 from video.mp4"

Supported Operations (FFmpeg Equivalents)

Development

To contribute to the project or run a local build, use the following commands:

git clone https://github.com/d-k-patel/ai-ffmpeg-cli.git
cd ai-ffmpeg-cli
make setup    # Install dependencies
make test     # Run the test suite
make lint     # Check code quality
make demo     # Run a demonstration

Requirements

• Python 3.10+ – Utilizes modern type hinting.
• FFmpeg – Must be accessible in your system PATH.
  • macOS: brew install ffmpeg
  • Ubuntu: sudo apt install ffmpeg
  • Windows: Download from ffmpeg.org
• OpenAI API Key – Required for processing natural language requests.
• Color-capable Terminal – Recommended for the best visual experience.

Troubleshooting

"OPENAI_API_KEY is required" Ensure your key is exported to your environment or defined in a .env file.

"ffmpeg not found in PATH" Verify that FFmpeg is installed and your system can locate it.

"Failed to parse natural language prompt" Try making your request more specific. Using a more capable model like gpt-4o or increasing the --timeout value may also help.

"No input files found" Confirm that the media file is in your current working directory and that the file extension is correct.

"Duration not applied to GIF/video" Use explicit phrasing, such as "5 second animated gif" or "10 second clip," to ensure the AI correctly identifies the duration parameter.