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
| 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.
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. Report vulnerabilities through the security policy.
For local setup, tests, documentation builds, and releases, see DEVELOPMENT.md.
1 maintainer
Metadata
1 maintainer
Release files for videopython 0.59.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| videopython-0.59.0.tar.gz | 1.1 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| videopython-0.59.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 2.3 MB
Release files / videopython-0.59.0.tar.gz
| Download URL | videopython-0.59.0.tar.gz |
|---|---|
| Size | 1.1 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
6b84c3f1b72f44f8cbdd44b99da89b50aab89edd643633b804f166612cc53034
|
|
BLAKE2b-256 checksum How to use checksums |
e94c73a56130a10a50bf93431f750a623188961d2b7b3ffe47d6bae249254a17
|
| Upload date | |
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 6, 2026.
Transparency logRelease files / videopython-0.59.0-py3-none-any.whl
| Download URL | videopython-0.59.0-py3-none-any.whl |
|---|---|
| Size | 1.2 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
4abbe29aebd4f9c56ac5f5ff565dde5429eede7780c77b58268643f06ab6cdcb
|
|
BLAKE2b-256 checksum How to use checksums |
c69fbe6942ff4a1b1bb2d3dc97150d94d7f39968906f43ad0448242500354314
|
| Upload date | |
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 6, 2026.
Transparency log
