| Name | ai-ffmpeg-cli JSON |
| Version |
0.2.5
JSON |
| download |
| home_page | None |
| Summary | AI-powered CLI that translates natural language to safe ffmpeg commands |
| upload_time | 2025-08-21 06:12:13 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.10 |
| license | MIT License
Copyright (c) 2025
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
|
| keywords |
ai
audio
automation
cli
conversion
ffmpeg
media-processing
natural-language
video
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# 🎬 ai-ffmpeg-cli
[](https://badge.fury.io/py/ai-ffmpeg-cli)
[](https://pepy.tech/projects/ai-ffmpeg-cli)
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
[](https://codecov.io/github/d-k-patel/ai-ffmpeg-cli)
[](https://github.com/d-k-patel/ai-ffmpeg-cli/actions)
> **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
```bash
# 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
```bash
# Install from PyPI
pip install ai-ffmpeg-cli
```
### Setup
```bash
# 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):
```bash
aiclip
```
```text
╭─────────────────────────────────────── Welcome to Interactive Mode ───────────────────────────────────────╮
│ │
│ ai-ffmpeg-cli v0.2.2 │
│ │
│ 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
┏━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━┓
┃ # ┃ 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):
```bash
aiclip --dry-run "convert input.mp4 to 720p with good quality"
```
## 📖 Usage Examples
### Video Processing
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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"
```
### Subcommands and option placement
You can also use the explicit `nl` subcommand. Put global options before the subcommand:
```bash
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:
```bash
# Incorrect
aiclip aiclip --yes nl "..."
```
## 🔧 Configuration
aiclip uses environment variables and `.env` files for configuration:
```bash
# 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")
## 📁 Output Directory Management
aiclip automatically organizes all generated files in a dedicated output directory:
```bash
# 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
## ⏱️ Duration and Time Handling
aiclip intelligently handles time-based requests for video and GIF creation:
```bash
# 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
```bash
# 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](https://ffmpeg.org/)
- **OpenAI API key** for natural language processing
## 🆘 Troubleshooting
### Common Issues
**"OPENAI_API_KEY is required"**
```bash
# Set your API key
export OPENAI_API_KEY="sk-your-key-here"
# Or add it to .env file
```
**"ffmpeg not found in PATH"**
```bash
# 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](https://github.com/d-k-patel/ai-ffmpeg-cli/issues)
- 💡 **Discussions**: Feature requests and Q&A on [GitHub Discussions](https://github.com/d-k-patel/ai-ffmpeg-cli/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](CONTRIBUTING.md) 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
## 📄 License
MIT License - see [LICENSE](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
---
<p align="center">
<strong>Made with ❤️ by developers who got tired of Googling ffmpeg commands</strong><br>
<sub>🎬 Turn your words into perfect video commands</sub>
</p>
Raw data
{
"_id": null,
"home_page": null,
"name": "ai-ffmpeg-cli",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": "thedkpatel <dhruv@thedkpatel.com>",
"keywords": "ai, audio, automation, cli, conversion, ffmpeg, media-processing, natural-language, video",
"author": null,
"author_email": "thedkpatel <dhruv@thedkpatel.com>",
"download_url": "https://files.pythonhosted.org/packages/f0/c6/038932cee01312d9a43ce52e74296c7cbc09d454f4e876f43ee390238519/ai_ffmpeg_cli-0.2.5.tar.gz",
"platform": null,
"description": "# \ud83c\udfac ai-ffmpeg-cli\n\n[](https://badge.fury.io/py/ai-ffmpeg-cli)\n[](https://pepy.tech/projects/ai-ffmpeg-cli)\n[](https://www.python.org/downloads/)\n[](https://opensource.org/licenses/MIT)\n[](https://codecov.io/github/d-k-patel/ai-ffmpeg-cli)\n[](https://github.com/d-k-patel/ai-ffmpeg-cli/actions)\n\n> **Stop Googling ffmpeg commands. Just describe what you want.**\n\n\n\n**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.\n\n## \u2728 Why ai-ffmpeg-cli?\n\n- \ud83e\udd16 **AI-Native**: Translate plain English to perfect ffmpeg commands\n- \ud83d\udd12 **Safety First**: Preview every command before execution \n- \u26a1 **10x Faster**: Skip the documentation, Stack Overflow, and trial-and-error\n- \ud83c\udfaf **Battle-Tested**: Generates reliable, production-ready commands\n- \ud83d\udd04 **Smart Defaults**: Sensible codec and quality settings out of the box\n\n```bash\n# Instead of this...\nffmpeg -i input.mp4 -vf \"scale=1280:720\" -c:v libx264 -c:a aac -b:v 2000k output.mp4\n\n# Just say this... (cli command is different)\naiclip \"convert input.mp4 to 720p with good quality\"\n```\n\n## \ud83d\ude80 Quick Start\n\n### Installation\n\n```bash\n# Install from PyPI\npip install ai-ffmpeg-cli\n```\n\n### Setup\n\n```bash\n# Set your OpenAI API key\nexport OPENAI_API_KEY=\"sk-your-key-here\"\n\n# Or create a .env file\necho \"OPENAI_API_KEY=sk-your-key-here\" > .env\n```\n\n### First Command\n\nInteractive mode (type your request after launching):\n\n```bash\naiclip\n```\n\n```text\n\u256d\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 Welcome to Interactive Mode \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256e\n\u2502 \u2502\n\u2502 ai-ffmpeg-cli v0.2.2 \u2502\n\u2502 \u2502\n\u2502 AI-powered video and audio processing with natural language \u2502\n\u2502 Type your request in plain English and let AI handle the ffmpeg complexity! \u2502\n\u2502 \u2502\n\u2570\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256f\n\n Available Media Files \n\u250f\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2533\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2533\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2513\n\u2503 Type \u2503 Count \u2503 Files \u2503\n\u2521\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2547\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2547\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2529\n\u2502 Videos \u2502 1 \u2502 \u2022 input.mp4 \u2502\n\u2502 Images \u2502 2 \u2502 \u2022 logo.png \u2502\n\u2502 \u2502 \u2502 \u2022 watermark.png \u2502\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n\n\u256d\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 Output Configuration \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256e\n\u2502 Output Directory: /path/to/your/aiclip \u2502\n\u2502 Generated files will be saved here \u2502\n\u2570\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256f\n\naiclip> convert this video to 720p\n\n\u250f\u2501\u2501\u2501\u2533\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2533\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2533\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2513\n\u2503 # \u2503 Command \u2503 Output \u2503 Status \u2503\n\u2521\u2501\u2501\u2501\u2547\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2547\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2547\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2529\n\u2502 1 \u2502 ffmpeg -i input.mp4 -vf scale=1280:720... \u2502 /path/to/your/aiclip/input_720p.mp4 \u2502 New \u2502\n\u2514\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n\n\u256d\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 Confirmation Required \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256e\n\u2502 \u2502\n\u2502 Run these commands? \u2502\n\u2502 \u2502\n\u2570\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256f\n [y/n]: Using default: Y\n```\n\nOr run a one-shot command (no interactive prompt):\n\n```bash\naiclip --dry-run \"convert input.mp4 to 720p with good quality\"\n```\n\n## \ud83d\udcd6 Usage Examples\n\n### Video Processing\n```bash\n# Convert formats\naiclip \"convert input.mov to mp4 with h264 and aac\"\n\n# Resize videos \naiclip \"downscale video.mp4 to 720p\"\naiclip \"make input.mp4 1080p resolution\"\n\n# Compress files\naiclip \"compress large-video.mp4 to smaller size\"\naiclip \"reduce file size with CRF 23\"\n\n# Create animated GIFs\naiclip \"convert input.mp4 to animated gif\"\naiclip \"create a 5 second animated gif from video.mp4\"\n```\n\n### Audio Operations\n```bash\n# Extract audio\naiclip \"extract audio from movie.mp4 to mp3\"\naiclip \"get audio track from video as wav\"\n\n# Remove audio\naiclip \"remove audio from video.mp4\"\n```\n\n### Trimming & Cutting\n```bash\n# Time-based cutting\naiclip \"trim first 30 seconds from video.mp4\"\naiclip \"keep segment from 2:15 to 3:45 in input.mp4\"\naiclip \"cut out middle 5 minutes\"\n```\n\n### Image Extraction \n```bash\n# Thumbnails\naiclip \"create thumbnail at 10 seconds from video.mp4\"\naiclip \"extract frame at 2:30 as PNG\"\n\n# Frame sequences\naiclip \"extract one frame every 5 seconds\"\naiclip \"get all frames from video as images\"\n```\n\n### Advanced Operations\n```bash\n# Overlays\naiclip \"add watermark logo.png to top-right of video.mp4\" \naiclip \"overlay text on video at position 10:10\"\n\n# Batch processing\naiclip \"convert all .mov files to .mp4\"\n```\n\n## \ud83c\udf9b\ufe0f Command Line Options\n\n```bash\n# One-shot mode (no interaction)\naiclip \"your command here\"\n\n# Skip confirmation prompts \naiclip --yes \"convert video.mp4 to 720p\"\n\n# Preview only (don't execute)\naiclip --dry-run \"compress input.mp4\"\n\n# Use different AI model\naiclip --model gpt-4o-mini \"extract audio\"\n\n# Increase timeout for complex requests\naiclip --timeout 120 \"complex processing task\"\n\n# Verbose logging for troubleshooting\naiclip --verbose \"your command\"\n\n# Specify custom output directory\naiclip --output-dir /path/to/output \"convert video.mp4 to 720p\"\n```\n\n### Subcommands and option placement\n\nYou can also use the explicit `nl` subcommand. Put global options before the subcommand:\n\n```bash\naiclip --yes nl \"thumbnail at 10s from test.mp4\"\naiclip --dry-run --model gpt-4o-mini nl \"compress input.mp4\"\n```\n\nDo not invoke the binary twice:\n\n```bash\n# Incorrect\naiclip aiclip --yes nl \"...\"\n```\n\n## \ud83d\udd27 Configuration\n\naiclip uses environment variables and `.env` files for configuration:\n\n```bash\n# Required\nOPENAI_API_KEY=sk-your-openai-api-key\n\n# Optional\nAICLIP_MODEL=gpt-4o # AI model to use\nAICLIP_DRY_RUN=false # Preview commands by default\nAICLIP_OUTPUT_DIR=aiclip # Default output directory\n```\n\n## \ud83c\udfaf Smart Defaults & Safety\n\n- **Preview First**: Every command is shown before execution\n- **Overwrite Protection**: Warns before overwriting existing files \n- **Sensible Codecs**: Automatically chooses h264+aac for MP4, libx265 for compression\n- **Stream Copy**: Uses `-c copy` for trimming when possible (faster, lossless)\n- **Context Aware**: Scans your directory to suggest input files and durations\n- **Organized Output**: All generated files are saved to a dedicated output directory\n- **Duration Support**: Automatically handles time-based requests (e.g., \"5 second GIF\")\n\n## \ud83d\udcc1 Output Directory Management\n\naiclip automatically organizes all generated files in a dedicated output directory:\n\n```bash\n# Default behavior - files saved to \"aiclip\" folder\naiclip \"convert video.mp4 to 720p\"\n# Output: ./aiclip/video_720p.mp4\n\n# Custom output directory\naiclip --output-dir /path/to/output \"convert video.mp4 to 720p\"\n# Output: /path/to/output/video_720p.mp4\n\n# Environment variable configuration\nexport AICLIP_OUTPUT_DIR=my_outputs\naiclip \"convert video.mp4 to 720p\"\n# Output: ./my_outputs/video_720p.mp4\n```\n\n**Benefits:**\n- \ud83d\uddc2\ufe0f **Organized**: All generated files in one place\n- \ud83d\udd0d **Easy to find**: No more searching through mixed directories\n- \ud83e\uddf9 **Clean workspace**: Input files stay separate from outputs\n- \ud83d\udcca **Progress tracking**: See all your generated files at a glance\n\n## \u23f1\ufe0f Duration and Time Handling\n\naiclip intelligently handles time-based requests for video and GIF creation:\n\n```bash\n# Create GIFs with specific duration\naiclip \"convert video.mp4 to 5 second animated gif\"\naiclip \"create a 10 second animated gif from input.mp4\"\n\n# Time-based video operations\naiclip \"extract first 30 seconds from video.mp4\"\naiclip \"create 15 second clip from input.mp4\"\n\n# Thumbnails at specific times\naiclip \"extract frame at 2:30 from video.mp4\"\naiclip \"create thumbnail at 10 seconds from input.mp4\"\n```\n\n**Supported time formats:**\n- **Seconds**: \"5 second\", \"10s\", \"30 seconds\"\n- **Time codes**: \"2:30\", \"1:45:30\", \"00:02:15\"\n- **Duration**: \"5 second duration\", \"10 second clip\"\n\n## \ud83d\udcca Supported Operations\n\n| Operation | Examples | ffmpeg Equivalent |\n|-----------|----------|-------------------|\n| **Convert** | \"convert to mp4\", \"make it h264\" | `-c:v libx264 -c:a aac` |\n| **Resize** | \"720p\", \"1920x1080\", \"scale to 50%\" | `-vf scale=1280:720` | \n| **Compress** | \"make smaller\", \"CRF 28\" | `-c:v libx265 -crf 28` |\n| **Extract Audio** | \"get audio as mp3\" | `-q:a 0 -map a` |\n| **Trim** | \"first 30 seconds\", \"2:15 to 3:45\" | `-ss 00:02:15 -to 00:03:45` |\n| **Thumbnail** | \"frame at 10s\" | `-ss 00:00:10 -vframes 1` |\n| **Overlay** | \"watermark top-right\" | `-filter_complex overlay=W-w-10:10` |\n| **Batch** | \"all *.mov files\" | Shell loops with glob patterns |\n| **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` |\n\n## \ud83d\udee0\ufe0f Development\n\n```bash\n# Clone and setup\ngit clone https://github.com/d-k-patel/ai-ffmpeg-cli.git\ncd ai-ffmpeg-cli\nmake setup\n\n# Run tests\nmake test\n\n# Check code quality \nmake lint\n\n# Try demo commands\nmake demo\n```\n\n## \ud83d\udccb Requirements\n\n- **Python 3.10+** (uses modern type hints)\n- **ffmpeg** installed and available in PATH\n - macOS: `brew install ffmpeg`\n - Ubuntu: `sudo apt install ffmpeg`\n - Windows: Download from [ffmpeg.org](https://ffmpeg.org/)\n- **OpenAI API key** for natural language processing\n\n## \ud83c\udd98 Troubleshooting\n\n### Common Issues\n\n**\"OPENAI_API_KEY is required\"**\n```bash\n# Set your API key\nexport OPENAI_API_KEY=\"sk-your-key-here\"\n# Or add it to .env file\n```\n\n**\"ffmpeg not found in PATH\"** \n```bash\n# Install ffmpeg\nbrew install ffmpeg # macOS\nsudo apt install ffmpeg # Ubuntu\n# Windows: download from ffmpeg.org\n```\n\n**\"Failed to parse natural language prompt\"**\n- Try being more specific in your request\n- Use `--model gpt-4o` for better accuracy \n- Increase timeout with `--timeout 120`\n- Check your internet connection\n\n**\"No input files found\"**\n- Ensure files exist in current directory\n- Check file extensions match your request\n- Use `ls` to verify available files\n\n**\"Duration not applied to GIF/video\"**\n- Be explicit about duration: \"5 second animated gif\"\n- Use clear time specifications: \"10 second video clip\"\n- Check that the AI model includes duration in the generated command\n\n### Getting Help\n\n- \ud83d\udcd6 **Documentation**: Full guides at [docs link]\n- \ud83d\udcac **Discord**: Join our community for real-time help\n- \ud83d\udc1b **Issues**: Report bugs on [GitHub Issues](https://github.com/d-k-patel/ai-ffmpeg-cli/issues)\n- \ud83d\udca1 **Discussions**: Feature requests and Q&A on [GitHub Discussions](https://github.com/d-k-patel/ai-ffmpeg-cli/discussions)\n\n## \ud83e\udd1d Contributing\n\nWe love contributions! Whether it's:\n\n- \ud83d\udc1b **Bug reports** and feature requests\n- \ud83d\udcd6 **Documentation** improvements \n- \ud83e\uddea **Test cases** for edge scenarios\n- \ud83d\udcbb **Code contributions** for new features\n- \ud83c\udfa8 **Examples** and tutorials\n\nSee our [Contributing Guide](CONTRIBUTING.md) to get started.\n\n## \ud83d\udcc8 What's Next?\n\n- \ud83d\udd04 **Batch Templates**: Save and reuse complex workflows\n- \ud83c\udf9b\ufe0f **GUI Mode**: Visual interface for non-CLI users \n- \u26a1 **Local Models**: Run without internet using local AI\n- \ud83c\udfe2 **Team Features**: Shared commands and analytics\n- \ud83d\udd0c **Integrations**: GitHub Actions, Docker, CI/CD pipelines\n- \ud83c\udfac **Enhanced Duration Support**: Better handling of time-based requests\n- \ud83d\udcc1 **Advanced Output Management**: Custom naming patterns and organization\n\n## \ud83d\udcc4 License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n## \u2b50 Support\n\nIf aiclip saves you time, please:\n- \u2b50 **Star** this repository \n- \ud83d\udc26 **Share** on social media\n- \ud83d\udcdd **Write** a review or blog post\n- \ud83d\udcac **Tell** your developer friends\n\n---\n\n<p align=\"center\">\n <strong>Made with \u2764\ufe0f by developers who got tired of Googling ffmpeg commands</strong><br>\n <sub>\ud83c\udfac Turn your words into perfect video commands</sub>\n</p>",
"bugtrack_url": null,
"license": "MIT License\n \n Copyright (c) 2025\n \n Permission is hereby granted, free of charge, to any person obtaining a copy\n of this software and associated documentation files (the \"Software\"), to deal\n in the Software without restriction, including without limitation the rights\n to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n copies of the Software, and to permit persons to whom the Software is\n furnished to do so, subject to the following conditions:\n \n The above copyright notice and this permission notice shall be included in all\n copies or substantial portions of the Software.\n \n THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n SOFTWARE.\n \n ",
"summary": "AI-powered CLI that translates natural language to safe ffmpeg commands",
"version": "0.2.5",
"project_urls": {
"Bug Tracker": "https://github.com/d-k-patel/ai-ffmpeg-cli/issues",
"Changelog": "https://github.com/d-k-patel/ai-ffmpeg-cli/releases",
"Discussions": "https://github.com/d-k-patel/ai-ffmpeg-cli/discussions",
"Documentation": "https://d-k-patel.github.io/ai-ffmpeg-cli/",
"Funding": "https://github.com/sponsors/d-k-patel",
"Homepage": "https://github.com/d-k-patel/ai-ffmpeg-cli",
"Repository": "https://github.com/d-k-patel/ai-ffmpeg-cli"
},
"split_keywords": [
"ai",
" audio",
" automation",
" cli",
" conversion",
" ffmpeg",
" media-processing",
" natural-language",
" video"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "93643b9cdf3805ff845817149a4a9e46091db14d5d752dea5fb767feeac2607a",
"md5": "d5c868e0b414087161a314333b384f27",
"sha256": "3b8a88acf910422f0f581b993791912eb7251613ce106e6adf661486e4ae8092"
},
"downloads": -1,
"filename": "ai_ffmpeg_cli-0.2.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d5c868e0b414087161a314333b384f27",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 68403,
"upload_time": "2025-08-21T06:12:11",
"upload_time_iso_8601": "2025-08-21T06:12:11.484032Z",
"url": "https://files.pythonhosted.org/packages/93/64/3b9cdf3805ff845817149a4a9e46091db14d5d752dea5fb767feeac2607a/ai_ffmpeg_cli-0.2.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "f0c6038932cee01312d9a43ce52e74296c7cbc09d454f4e876f43ee390238519",
"md5": "8c8b3ef90babddfce789239b1c925a08",
"sha256": "e25498414df1f09026d976541e99b23faa74f5ef64ebfcf8e79acc2e24c668c9"
},
"downloads": -1,
"filename": "ai_ffmpeg_cli-0.2.5.tar.gz",
"has_sig": false,
"md5_digest": "8c8b3ef90babddfce789239b1c925a08",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 91636,
"upload_time": "2025-08-21T06:12:13",
"upload_time_iso_8601": "2025-08-21T06:12:13.024520Z",
"url": "https://files.pythonhosted.org/packages/f0/c6/038932cee01312d9a43ce52e74296c7cbc09d454f4e876f43ee390238519/ai_ffmpeg_cli-0.2.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-21 06:12:13",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "d-k-patel",
"github_project": "ai-ffmpeg-cli",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "ai-ffmpeg-cli"
}
