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

🙏 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

Name		Name	Last commit message	Last commit date
Latest commit History 16 Commits
.github		.github
assets		assets
src		src
.gitignore		.gitignore
.npmignore		.npmignore
.npmrc		.npmrc
.release-it.json		.release-it.json
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
bun.lock		bun.lock
bunfig.toml		bunfig.toml
eslint.config.js		eslint.config.js
package.json		package.json
tsconfig.json		tsconfig.json

License

ali-master/llmpeg

Folders and files

Latest commit

History

Repository files navigation