Mediallm
Natural language to FFmpeg, instantly and privately
Installation
npx mediallmAsk AI about Mediallm
Powered by Claude Β· Grounded in docs
I know everything about Mediallm. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
ββββ βββββββββββββββββββ βββ ββββββ βββ βββ ββββ ββββ
βββββ βββββββββββββββββββββββββββββββββββ βββ βββββ βββββ
βββββββββββββββββ βββ βββββββββββββββββ βββ βββββββββββ
βββββββββββββββββ βββ βββββββββββββββββ βββ βββββββββββ
βββ βββ βββββββββββββββββββββββββ ββββββββββββββββββββββ βββ βββ
βββ ββββββββββββββββββ ββββββ ββββββββββββββββββββββ βββ
Natural language to FFmpeg, instantly and privately
Privacy-First β’ Local LLM β’ FFmpeg made effortless
Documentation β’ Installation β’ Quick Start β’ Usage β’ Configuration β’ Contributing
Overview
MediaLLM transforms media processing by bridging the gap between human language and FFmpeg complexity. This Python package enables you to manipulate videos, audio files, images, and subtitles using simple, conversational commands powered by local AI models.
Instead of memorizing complex FFmpeg syntax, simply describe what you want: "convert this video to MP4," "extract the audio as high-quality MP3," or "compress this video to a smaller size." MediaLLM understands your intent and generates the precise commands needed, all while keeping your data completely private through local processing.
Why MediaLLM?
Whether you're a developer automating video workflows, a content creator resizing clips for social media, or someone who just needs to convert files without diving into technical manuals, MediaLLM meets you where you are.
- Skip the FFmpeg manual - Say goodbye to cryptic command syntax and endless documentation searches
- Actually free - No monthly subscriptions, API costs, or usage caps to worry about
- Works with everything - Video, audio, images, subtitles - if FFmpeg can handle it, so can you
- Plays nice with AI tools - Built-in MCP server connects seamlessly with Claude and other AI agents
- Code when you want to - Python API available for when you need programmatic control
- Just works - Simple CLI that gets out of your way and lets you focus on creating
Installation
Prerequisites
| Component | Version | macOS | Linux |
|---|---|---|---|
| Python | 3.10+ | brew install python | sudo apt install python3 |
| FFmpeg | Latest | brew install ffmpeg | sudo apt install ffmpeg |
| Ollama | Latest | brew install ollama | curl -fsSL https://ollama.com/install.sh |
Install MediaLLM
# Install from PyPI
pip install mediallm
# Alternative: using uv (faster)
uv add mediallm
# Development installation
git clone https://github.com/iamarunbrahma/mediallm.git
cd mediallm
pip install -e .
Install MediaLLM MCP
# Install from PyPI
pip install mediallm-mcp
# Alternative: using uv (faster)
uv add mediallm-mcp
Quick Start
# 1. Start Ollama and pull a model
ollama serve
ollama pull llama3.1:latest
# 2. Convert media with natural language
mediallm "convert video.mp4 to MP3 audio"
mediallm "convert video.mov to MP4 format"
mediallm "extract audio from movie.mp4 as high quality MP3"
# 3. Preview commands before execution
mediallm --dry-run "compress large-video.mkv to smaller size"
Usage
CLI Commands
# Video Conversions
mediallm "convert video.mov to MP4 format"
mediallm "convert video.avi to MP4"
mediallm "convert video.flv to MP4 format"
mediallm "compress large-video.mp4 to smaller size"
# Audio Operations
mediallm "extract audio from movie.mp4 as high quality MP3"
mediallm "convert video.mp4 to MP3 audio"
# Image Operations
mediallm "extract thumbnail from video.mp4"
mediallm "convert image.jpg to PNG format"
# Trimming
mediallm "trim video.mp4 from start to 30 seconds"
Python API
import mediallm
# Initialize MediaLLM
ml = mediallm.MediaLLM()
# Scan workspace for media files
files = ml.scan_workspace()
print(f"Found {len(files['videos'])} videos")
# Generate commands from natural language
request = "convert video.mp4 to high-quality MP3"
commands = ml.generate_command(request)
# Execute generated commands
for cmd in commands:
print(f"Running: {' '.join(cmd)}")
# subprocess.run(cmd) # Execute the command
Configuration (Optional)
MediaLLM works out-of-the-box with sensible defaults. Customize only if needed:
Common Adjustments:
MEDIALLM_MODEL- Switch between different Ollama models (default: llama3.1:latest)MEDIALLM_OUTPUT_DIR- Change where converted files are saved (default: current directory)
Advanced Settings:
MEDIALLM_OLLAMA_HOST- Connect to Ollama on a different machine (default: http://localhost:11434)MEDIALLM_TIMEOUT- Increase for complex operations (default: 60s)MEDIALLM_DRY_RUN- Always preview commands without executing (default: false)
Set via environment variables or create a .env file in your project directory.
Architecture
βββββββββββββββββββββ βββββββββββββββββββββ βββββββββββββββββββββ βββββββββββββββββββββ
β Natural Language β β Local LLM β β FFmpeg Commands β β Media Output β
β "convert vid.mp4" β --> β (Ollama) β --> β ffmpeg -i ... β --> β output.mp4 β
β β β β β β β β
βββββββββββββββββββββ βββββββββββββββββββββ βββββββββββββββββββββ βββββββββββββββββββββ
MCP Server
MediaLLM includes an MCP (Model Context Protocol) server for integration with AI agents:
Usage
# Default: STDIO transport (for Claude Desktop, etc.)
mediallm-mcp
# SSE transport (for web integrations)
mediallm-mcp --sse --port 3001
# HTTP transport (for custom integrations)
mediallm-mcp --http --port 3001
Running in Docker
# Build the Docker image
cd packages/mediallm-mcp
docker build -t mediallm-mcp .
# Run with volume mounting and port mapping for HTTP access
docker run -it --rm \
-p 8080:8080 \
-v /path/to/your/media:/workspace \
mediallm-mcp
# MCP endpoint (default path): http://localhost:8080/mcp
# Customize path via CLI: mediallm-mcp --http --path /api/mcp
Claude Code
Add to .mcp.json in your project root:
{
"mcpServers": {
"mediallm-mcp": {
"command": "uvx",
"args": ["mediallm-mcp"]
}
}
}
Claude Desktop
Add to your claude_desktop_config.json:
Config file location:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"mediallm-mcp": {
"command": "uvx",
"args": ["mediallm-mcp"]
}
}
}
Cursor
Or manually create .cursor/mcp.json in your project (or edit the global ~/.cursor/mcp.json):
{
"mcpServers": {
"mediallm-mcp": {
"command": "uvx",
"args": ["mediallm-mcp"]
}
}
}
Environment Variables (Optional) for MCP configuration
MEDIALLM_WORKSPACE- Specify media directory (default: current working directory)MEDIALLM_MODEL- Override LLM model (default: llama3.1:latest)MEDIALLM_OLLAMA_HOST- Ollama server URL (default: http://localhost:11434)MEDIALLM_OUTPUT_DIR- Output directory (default: current working directory)
Available Tools:
generate_command- Convert natural language to FFmpeg commandsscan_workspace- Discover media files in directories
Debugging
# Enable verbose logging
mediallm-mcp --debug
# Test alternate transports with debug
mediallm-mcp --sse --port 3001 --debug
mediallm-mcp --http --port 3001 --debug
If the server is not detected:
- Ensure the command is available:
mediallm-mcp --help - Restart the client (Claude Desktop, Claude Code, or Cursor)
- Verify Ollama is running if using local LLMs
MCP Inspector Timeout
If you see "MCP error -32001: Request timed out" in MCP Inspector, set:
- Request Timeout - 300000
- Reset Timeout on Progress - True
- Maximum Total Timeout - 900000
Contributing
Help make MediaLLM better for everyone! Whether you're fixing bugs, adding features, or improving documentation, your contributions matter.
Get Started:
- Fork the repo and create a feature branch
- Check out CONTRIBUTING.md for development setup
- Run
make helpto see available development commands - Make your changes and add tests
- Submit a pull request
Have Ideas or Issues?
- Found a bug? Open an issue with details to reproduce
- Want a feature? Start a discussion to share your ideas
License
MIT License - use it, modify it, share it. See LICENSE for the fine print.
Made by Arun Brahma
