videopython

Structured, local-first video editing for Python and AI agents.

Videopython represents an edit as a validated Python model or JSON plan. Whether the plan comes from your code, an LLM, or an MCP client, it renders through the same bounded-memory streaming engine.

Documentation · First edit · API reference · Roadmap

Why videopython?

• Structured edits — segments and operations are Pydantic models with a generated JSON Schema.
• Predictable rendering — validate dimensions, timing, and operation constraints before decoding frames.
• Bounded memory — stream decode, effects, and encode without loading the full source into memory.
• Local AI — add transcription, scene understanding, generation, dubbing, and automatic editing without cloud inference APIs.
• Agent-ready tools — expose analysis, planning, validation, and rendering through the included MCP server.

Installation

Install FFmpeg, then choose the package extras you need:

pip install videopython              # core video and audio editing
pip install "videopython[ai]"        # all local AI features
pip install "videopython[mcp]"       # MCP and its focused analysis stack

Videopython supports Python >=3.11, <3.15. The ai and mcp extras are independent; install videopython[ai,mcp] if you need both. See the installation guide for FFmpeg features, model downloads, Ollama setup, and hardware requirements.

Quick start

Describe the edit, validate it without loading frames, then render it:

from videopython.editing import VideoEdit

edit = VideoEdit.from_dict({
    "segments": [
        {
            "source": "input.mp4",
            "start": 10.0,
            "end": 20.0,
            "operations": [
                {"op": "resize", "width": 1080, "height": 1920},
                {"op": "color_adjust", "saturation": 1.15, "contrast": 1.05},
                {"op": "fade", "mode": "in", "duration": 0.5},
            ],
        }
    ]
})

edit.validate()
edit.run_to_file("output.mp4")

run_to_file() streams the source through FFmpeg and the operation pipeline, so memory use stays bounded for long videos. Continue with Your first edit.

What you can build

Core editing does not install PyTorch or other model runtimes. AI dependencies load only when you use an AI feature.

Documentation

The documentation follows Diataxis:

• Tutorials teach the library through complete examples.
• How-to guides cover specific editing and AI tasks.
• Reference documents the API, operations, and JSON wire format.
• Explanation covers the streaming engine, plan lifecycle, architecture, and LLM-first design.

Project status

Videopython is pre-1.0, so public interfaces can still change. See the roadmap for the stability criteria and release notes for changes between versions.

For local setup, tests, documentation builds, and releases, see DEVELOPMENT.md.