Mediallm

Natural language to FFmpeg, instantly and privately

Privacy-First • Local LLM • FFmpeg made effortless

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

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 commands
• scan_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 help to 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

⭐ Star on GitHub • 🐛 Report Issues