✨ 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

``bash


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
`

$3

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

🚀 Quick Start

$3

`bash
llmpeg init
`

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

$3

`bash


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

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

📖 Usage

$3

`bash
llmpeg [options] ""
`

$3

| Option | Alias | Description |
|--------|-------|-------------|
| --model | -m | AI provider to use (openai, claude, gemini, grok) |
| --provider | -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 |

$3

`bash


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
`

$3

`bash


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
`

$3

`bash


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

$3

Convert Formats

`bash
llmpeg "convert video.mov to mp4 with h264 codec"


Output: ffmpeg -i video.mov -c:v libx264 -c:a aac output.mp4


`


Resize Video

`bash
llmpeg "resize video to 720p maintaining aspect ratio"


Output: ffmpeg -i input.mp4 -vf scale=-1:720 output.mp4


`


Create GIF

`bash
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

`bash
llmpeg "extract 1 frame per second as jpg images"


Output: ffmpeg -i input.mp4 -vf fps=1 frame_%04d.jpg


`


$3

Extract Audio

`bash
llmpeg "extract audio from video as mp3 320kbps"


Output: ffmpeg -i input.mp4 -vn -acodec mp3 -ab 320k output.mp3


`


Change Volume

`bash
llmpeg "increase audio volume by 50%"


Output: ffmpeg -i input.mp4 -af "volume=1.5" output.mp4


`


$3

Batch Processing

`bash
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

`bash
llmpeg "stream video to rtmp server"


Output: ffmpeg -re -i input.mp4 -c copy -f flv rtmp://server/live/stream


`


🤖 Supported AI Models

$3


- 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

$3

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

$3

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

$3

- grok-beta (default) - Latest model

⚙️ Configuration

$3

1. CLI flags (highest priority)
2. Environment variables
3. Config file (~/.llmpeg/config.json)
4. .env files

$3

`bash
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"
`

$3

`json
{
"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.

$3

- 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

$3

- 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

$3

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

Example workflow:
`bash
$ 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.

$3

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

$3

- 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

$3

- 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

$3


Native support via pbcopy

$3

Native support via clip

$3

Install one of these utilities:

`bash


X11 users

sudo apt-get install xclip

or

sudo apt-get install xsel

Wayland users

sudo apt-get install wl-clipboard
`

🛠️ Development

`bash


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.

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

📈 Roadmap

- [x] Command history and favorites ✅
- [x] 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

`bash


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

---