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.

Metadata

Release files for videopython 0.62.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for videopython 0.62.0
File	Size	Uploaded
videopython-0.62.0.tar.gz	1.1 MB	Sep 9, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for videopython 0.62.0
File	Interpreter	ABI	Platform	Reset
videopython-0.62.0-py3-none-any.whl 1.2 MB Sep 9, 2026	Python 3	none	any	Details

Total release size: 2.3 MB

Release files / videopython-0.62.0.tar.gz

Download URL	videopython-0.62.0.tar.gz
Size	1.1 MB
Tags	Source
SHA-256 checksum How to use checksums	`aea6b52495912cfa159178c3886e5831d2cd98835c08cd61bdb75dffc816bf5c`
BLAKE2b-256 checksum How to use checksums	`bba09f95e83f76e03cd66634a027382b108c82ab49d66fbf20c3722a523c0487`
Upload date	Sep 9, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/BartWojtowicz/videopython
Publishing commit: github.com/BartWojtowicz/videopython/tree/a68174c067418e7518c95d37bc3a32c0f497cc56

Workflow

Publishing configuration: github.com/BartWojtowicz/videopython/blob/a68174c067418e7518c95d37bc3a32c0f497cc56/.github/workflows/publish.yml
Publishing logs: github.com/BartWojtowicz/videopython/actions/runs/34398555516/attempts/1

Artifact

Subject: videopython-0.62.0.tar.gz
SHA-256 checksum: aea6b52495912cfa159178c3886e5831d2cd98835c08cd61bdb75dffc816bf5c Verifying attestations

Release files / videopython-0.62.0-py3-none-any.whl

Download URL	videopython-0.62.0-py3-none-any.whl
Size	1.2 MB
Tags	Python 3
SHA-256 checksum How to use checksums	`bd35fb8e442a2e14b08449ab41bdc927c1a29c0ccea4ff0862b134c3f22da732`
BLAKE2b-256 checksum How to use checksums	`0221b63ab5939634b35cf0b0326965cca9c4bc1d9235d987bbb5197dd6a2c511`
Upload date	Sep 9, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/BartWojtowicz/videopython
Publishing commit: github.com/BartWojtowicz/videopython/tree/a68174c067418e7518c95d37bc3a32c0f497cc56

Workflow

Publishing configuration: github.com/BartWojtowicz/videopython/blob/a68174c067418e7518c95d37bc3a32c0f497cc56/.github/workflows/publish.yml
Publishing logs: github.com/BartWojtowicz/videopython/actions/runs/34398555516/attempts/1

Artifact

Subject: videopython-0.62.0-py3-none-any.whl
SHA-256 checksum: bd35fb8e442a2e14b08449ab41bdc927c1a29c0ccea4ff0862b134c3f22da732 Verifying attestations