@usex/llmpeg

LLmpeg

🎥 Transform natural language into FFmpeg commands using AI

Features • Installation • Quick Start • Examples • Models • Contributing

✨ Features

• 🤖 Multi-Model Support: OpenAI, Claude, Gemini, and Grok
• 🎯 Natural Language: Describe tasks in plain English
• 📋 Cross-Platform Clipboard: Works on macOS, Windows, Linux
• ⚡ Direct Execution: Run commands immediately
• 🔐 Secure Configuration: API keys stored locally
• 🎨 Beautiful CLI: Colorful and intuitive interface
• 📚 Command History: Track all generated commands with smart search
• ⭐ Favorites System: Save and organize frequently used commands
• 🏷️ Smart Tagging: Auto-categorize commands for easy retrieval
• 📊 Usage Analytics: View statistics about your command usage
• 🎯 Preset Templates: 30+ built-in presets for common FFmpeg tasks
• 🛠️ Custom Presets: Create your own parameterized templates
• 📁 Category Browser: Organized presets by task type

📦 Installation

# npm
npm install -g @usex/llmpeg

# bun (recommended)
bun install -g @usex/llmpeg

# yarn
yarn global add @usex/llmpeg

# pnpm
pnpm add -g @usex/llmpeg

System Requirements

• Node.js 18.0.0 or higher
• FFmpeg installed on your system (Download FFmpeg)
• API Key from at least one AI provider

🚀 Quick Start

1️⃣ Initialize Configuration

llmpeg init

This creates a configuration file at ~/.llmpeg/config.json with placeholders for your API keys.

2️⃣ Add Your API Key

# Choose your preferred AI provider
llmpeg config --openai YOUR_OPENAI_KEY
llmpeg config --claude YOUR_ANTHROPIC_KEY
llmpeg config --gemini YOUR_GOOGLE_KEY
llmpeg config --grok YOUR_XAI_KEY

3️⃣ Generate Your First Command

llmpeg "convert video.mp4 to gif with 10fps"

📖 Usage

Basic Syntax

llmpeg [options] "<your request in natural language>"

Command Options

Option	Alias	Description
--model <provider>	-m	AI provider to use (openai, claude, gemini, grok)
--provider <model>	-p	Specific model variant (e.g., gpt-4, claude-3-opus)
--copy	-c	Copy command to clipboard
--execute	-e	Execute the generated command immediately
--verbose	-v	Show detailed output

Configuration Commands

# Initialize configuration
llmpeg init [--force]

# Show current configuration
llmpeg config --show

# Set API keys
llmpeg config --openai YOUR_KEY
llmpeg config --claude YOUR_KEY
llmpeg config --gemini YOUR_KEY
llmpeg config --grok YOUR_KEY

# Set preferences
llmpeg config --default-provider claude
llmpeg config --default-model gpt-4-turbo
llmpeg config --auto-copy true

History Commands

# Interactive history browser (default)
llmpeg history

# List recent commands
llmpeg history --list
llmpeg history -l

# Show favorites
llmpeg history --favorites
llmpeg history -f

# Search history
llmpeg history --search "convert to gif"
llmpeg history -s "video compression"

# Filter by tag
llmpeg history --tag video
llmpeg history -t audio

# View statistics
llmpeg history --stats

# Export history
llmpeg history --export json
llmpeg history --export csv

# Clear history (with confirmation)
llmpeg history --clear

Preset Commands

# Interactive preset browser (default)
llmpeg presets

# List all presets
llmpeg presets --list
llmpeg presets -l

# Filter by category
llmpeg presets --category "Video Conversion"
llmpeg presets -c "Audio Processing"

# Search presets
llmpeg presets --search "compress"
llmpeg presets -s "gif"

# Use a specific preset
llmpeg presets --use convert-to-mp4
llmpeg presets -u video-to-gif

# Create custom preset
llmpeg presets --create

# Export all presets
llmpeg presets --export

🎬 Examples

Video Operations

Convert Formats

llmpeg "convert video.mov to mp4 with h264 codec"
# Output: ffmpeg -i video.mov -c:v libx264 -c:a aac output.mp4

Resize Video

llmpeg "resize video to 720p maintaining aspect ratio"
# Output: ffmpeg -i input.mp4 -vf scale=-1:720 output.mp4

Create GIF

llmpeg "create gif from video between 5-10 seconds"
# Output: ffmpeg -i input.mp4 -ss 5 -t 5 -vf "fps=10,scale=320:-1:flags=lanczos" output.gif

Extract Frames

llmpeg "extract 1 frame per second as jpg images"
# Output: ffmpeg -i input.mp4 -vf fps=1 frame_%04d.jpg

Audio Operations

Extract Audio

llmpeg "extract audio from video as mp3 320kbps"
# Output: ffmpeg -i input.mp4 -vn -acodec mp3 -ab 320k output.mp3

Change Volume

llmpeg "increase audio volume by 50%"
# Output: ffmpeg -i input.mp4 -af "volume=1.5" output.mp4

Advanced Operations

Batch Processing

llmpeg "convert all mp4 files to webm with vp9 codec"
# Output: for f in *.mp4; do ffmpeg -i "$f" -c:v libvpx-vp9 "${f%.mp4}.webm"; done

Streaming

llmpeg "stream video to rtmp server"
# Output: ffmpeg -re -i input.mp4 -c copy -f flv rtmp://server/live/stream

🤖 Supported AI Models

OpenAI

• gpt-4o-mini (default) - Fast and efficient
• gpt-4 - Most capable
• gpt-4-turbo - Latest GPT-4 with vision
• gpt-3.5-turbo - Fast and cost-effective

Claude (Anthropic)

• claude-3-haiku-20240307 (default) - Fast and efficient
• claude-3-sonnet-20240229 - Balanced performance
• claude-3-opus-20240229 - Most capable

Google Gemini

• gemini-1.5-flash (default) - Fast multimodal
• gemini-1.5-pro - Advanced reasoning
• gemini-pro - Balanced performance

Grok (xAI)

• grok-beta (default) - Latest model

⚙️ Configuration

Priority Order

• CLI flags (highest priority)
• Environment variables
• Config file (~/.llmpeg/config.json)
• .env files

Environment Variables

export OPENAI_API_KEY="your-key"
export ANTHROPIC_API_KEY="your-key"
export GOOGLE_GENERATIVE_AI_API_KEY="your-key"
export XAI_API_KEY="your-key"
export LLMPEG_DEFAULT_PROVIDER="claude"

Config File Structure

{
  "openai": {
    "apiKey": "your-openai-key",
    "defaultModel": "gpt-4o-mini"
  },
  "claude": {
    "apiKey": "your-claude-key",
    "defaultModel": "claude-3-haiku-20240307"
  },
  "gemini": {
    "apiKey": "your-gemini-key",
    "defaultModel": "gemini-1.5-flash"
  },
  "grok": {
    "apiKey": "your-grok-key",
    "defaultModel": "grok-beta"
  },
  "defaultProvider": "openai",
  "autoCopy": false
}

🎯 Preset Templates

LLmpeg includes 30+ professionally crafted presets for common FFmpeg tasks, organized by category. Each preset is a parameterized template that guides you through the process.

Built-in Preset Categories

• Video Conversion: MP4, WebM, AVI, MOV conversions with optimal settings
• Video Compression: Optimize for web, Discord, social media platforms
• GIF Creation: Create high-quality GIFs with palette optimization
• Audio Processing: Extract, convert, normalize audio tracks
• Video Editing: Trim, merge, watermark, resize videos
• Effects & Filters: Blur, stabilize, color correction
• Social Media: Instagram, TikTok, YouTube optimized formats
• Streaming: RTMP streaming setup for various platforms
• Advanced: Frame extraction, thumbnail generation, batch processing

Preset Features

• Smart Parameters: Each preset includes customizable parameters with validation
• Difficulty Levels: Marked as beginner, intermediate, or advanced
• Common Use Marking: Quickly find the most popular presets
• Examples: See how each preset works with real examples
• Custom Presets: Create and save your own templates

Using Presets

• Browse: Use llmpeg presets to explore available templates
• Select: Choose a preset that matches your task
• Customize: Fill in the required parameters (files, quality, etc.)
• Execute: Generate and run the FFmpeg command

Example workflow:

$ llmpeg presets
> Browse by category
> Video Conversion
> Convert to MP4
> Input file: movie.avi
> Quality: 23 (Medium)
✓ Generated command: ffmpeg -i movie.avi -c:v libx264 -crf 23 -c:a aac output.mp4

📚 Command History & Favorites

LLmpeg automatically tracks all your generated commands, making it easy to reuse, organize, and learn from your past work.

Interactive History Browser

The interactive mode provides a user-friendly interface to:

• Browse recent commands with arrow keys
• Search through your entire history
• Mark commands as favorites
• Add tags and categories
• Copy or execute commands directly
• View detailed statistics

Smart Features

• Auto-tagging: Commands are automatically tagged based on content (video, audio, conversion, etc.)
• Usage tracking: See how often you use each command
• Favorites: Star frequently used commands for quick access
• Categories: Organize commands by project or purpose
• Export/Import: Backup your history or share with team members

History Storage

• History is stored in ~/.llmpeg/history.json
• Maximum 1000 commands are kept (favorites are never deleted)
• Failed attempts are also tracked for learning purposes

📋 Clipboard Support

macOS

Native support via pbcopy

Windows

Native support via clip

Linux

Install one of these utilities:

# X11 users
sudo apt-get install xclip
# or
sudo apt-get install xsel

# Wayland users
sudo apt-get install wl-clipboard

🛠️ Development

# Clone repository
git clone https://github.com/ali-master/llmpeg
cd llmpeg

# Install dependencies
bun install

# Development
bun run start:dev        # Run in dev mode
bun run start:cli:dev    # Run CLI in dev mode

# Build
bun run build           # Build for production
bun run test:types      # Type checking
bun run format          # Format code
bun run lint            # Lint code

🤝 Contributing

We love contributions! Please see our Contributing Guide for details.

• Fork the repository
• Create your feature branch (git checkout -b feature/amazing-feature)
• Commit your changes (git commit -m 'Add amazing feature')
• Push to the branch (git push origin feature/amazing-feature)
• Open a Pull Request

📈 Roadmap

• Command history and favorites ✅
• Preset templates for common tasks ✅
• Interactive mode for command refinement
• Integration with popular video platforms
• Web interface
• VSCode extension
• Team collaboration features
• AI-powered command suggestions based on history
• Plugin system for custom extensions

🐛 Troubleshooting

No API key found

# Check your configuration
llmpeg config --show

# Ensure at least one API key is set
llmpeg config --openai YOUR_KEY

Command execution fails

• Ensure FFmpeg is installed: ffmpeg -version
• Use verbose mode: llmpeg -v "your command"
• Check the generated command before executing

Clipboard not working

• Linux: Install xclip, xsel, or wl-copy
• WSL: May need additional configuration
• Use manual copy as fallback

📄 License

MIT © Ali Torki

🙏 Acknowledgments

• Vercel AI SDK - AI model integration
• Bun - JavaScript runtime
• Commander.js - CLI framework
• Chalk - Terminal styling

_{Built with ❤️ by Ali Torki, for developers. Happy encoding! 🎬}

⭐ Star us on GitHub • 🐦 Follow on Linkedin