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 streaming engine with bounded frame buffers.

Documentation · First edit · API reference

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 run uv add videopython (or pip install videopython). The optional ai and mcp extras add model runtimes and the MCP server. See the installation guide for supported Python versions, extras, FFmpeg features, and model setup.

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 frame buffers stay bounded for long videos. Continue with Your first edit.

What you can build

Area	Capabilities	Start here
Editing	Cuts, transforms, effects, overlays, subtitles, audio, and multi-segment plans	Editing guides
AI workflows	Transcription, detection, scene understanding, generation, dubbing, and automatic editing	Local AI
LLM integrations	Generated schemas, structured validation, repair, and dimension normalization	LLM plan guide
MCP agents	Local tools for media analysis, planning, validation, and rendering	MCP guide

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

Scope

Videopython is a library for programmatic editing. It does not provide a hosted inference service, an interactive editing application, universal support for model runtimes and FFmpeg builds, or a second in-memory operation engine.

Project status

Videopython is pre-1.0, so public interfaces can still change. See the compatibility policy for public contracts and versioning rules, and release notes for changes between versions. Report vulnerabilities through the security policy.

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