videopython
Minimal, LLM-friendly Python library for programmatic video editing, processing, and AI video workflows.
Full documentation: videopython.com
Disclaimer: This project started as a hand-written hobby project, but most of the code is now produced by LLM agents. Humans still drive direction, approve changes, and own design decisions.
Installation
# Install FFmpeg first (macOS: brew install ffmpeg | Debian: apt-get install ffmpeg)
pip install videopython # core video/audio editing
pip install "videopython[ai]" # + ALL local AI features (GPU recommended)
pip install "videopython[ai,mcp]" # + MCP server for agent-driven editing
Python >=3.11, <3.14. AI features run locally — no cloud API keys required, but model weights are downloaded on first use. LLM-driven editing and scene captioning use a local Ollama server (ollama pull qwen3.6:27b). See the install guide for FFmpeg, Ollama, and hardware details.
Quick start
An edit is a plan — a dict (or JSON) validated and executed against the source files:
from videopython.editing import VideoEdit
edit = VideoEdit.from_dict({
"segments": [{
"source": "raw.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() # dry-run via metadata, no frames loaded
edit.run_to_file("output.mp4") # streams ffmpeg decode → effects → encode
run_to_file() streams, so memory stays bounded even for hour-long sources. Walk through it in Tutorial 1.
Automatic editing (local LLM)
Give AutoEditor your clips and a brief; a local Ollama vision model selects and orders the shots, and you get back a runnable VideoEdit:
from videopython.ai import AutoEditor, OllamaVisionLLM
editor = AutoEditor(planner=OllamaVisionLLM(model="qwen3.6:27b")) # ollama pull qwen3.6:27b
edit = editor.edit(
["clip_a.mp4", "clip_b.mp4", "clip_c.mp4"],
brief="A punchy 15-second teaser; lead with the most dynamic shot.",
)
edit.run_to_file("teaser.mp4")
The model picks scenes by id from a catalog built from scene detection + captions, so its temporal imprecision never reaches the render. See Let a local LLM edit for you.
AI generation
from videopython.ai import TextToImage, ImageToVideo, TextToSpeech
image = TextToImage().generate_image("A cinematic mountain sunrise")
video = ImageToVideo().generate_video(image=image)
audio = TextToSpeech().generate_audio("Welcome to videopython.")
video.add_audio(audio).save("ai_video.mp4")
LLM & AI agent integration
Putting an LLM in the loop works three ways, differing in who owns the model:
- Bring your own LLM — videopython gives your model the JSON Schema and a structured refine loop; your model authors the plans. Guide
AutoEditor— a local Ollama vision model is the planner. Guide- MCP server —
videopython-mcpexposes the pipeline as Model Context Protocol tools, so an agent like Claude drives editing with its own model. Guide
Mode 1 in brief: every operation is a Pydantic model whose fields are the JSON wire format, so VideoEdit.json_schema() hands your model a ready-made tool schema — a discriminated union over every LLM-exposed op (pass strict=True for provider grammar modes). Plans parse permissively and own their numeric bounds at validation, so a refine loop converges fast:
edit.check(meta)— collect every structured error in one pass, not just the firstedit.repair(meta)— auto-clamp mechanical violations (overruns, negatives) with a changelogedit.normalize_dimensions(meta, target)— make heterogeneous segments concat-compatible
Why it is built this way: LLM-first design.
Features
videopython.base—Video,VideoMetadata,FrameIterator,Transcription, and shared result types (BoundingBox,FaceTrack,SceneBoundary, ...). No AI dependencies.videopython.audio—Audiowith overlay, concat, normalize, time-stretch, silence detection, segment classification.videopython.editing—Operation/Effectfoundation,VideoEditplan runner with JSON Schema + streaming execution. Transforms (resize, crop, fps, speed, freeze, silence removal; cutting is the segment's own start/end) and effects (blur, zoom, color grading, vignette, Ken Burns, fade, overlays, animated subtitles).videopython.ai(install with[ai]) — generation (TextToVideo,ImageToVideo,TextToImage,TextToSpeech,TextToMusic), understanding (AudioToText,AudioClassifier,SceneVLM,FaceTracker,ObjectDetector,SemanticSceneDetector), theFaceTrackingCroptransform, theObjectDetectionOverlayeffect, and the full-pipelineVideoAnalyzer. Scene captioning and dubbing translation run on a local Ollama model.videopython.ai.auto_edit—AutoEditor+OllamaVisionLLM: plan and render an edit from sources + a one-line brief.videopython.ai.dubbing—VideoDubberfor voice-cloned revoicing with timing sync.videopython.mcp(install with[ai,mcp]) —videopython-mcp, an MCP stdio server exposing the auto-edit pipeline so an agent drives editing.
Documentation
The docs follow Diátaxis: four sections, each answering a different kind of question.
| Tutorials | Learn by doing — start here if you are new |
| How-to guides | Recipes for a specific goal |
| Reference | Classes, operations, parameters, wire format |
| Explanation | Why the library is shaped the way it is |
Development
See DEVELOPMENT.md for local setup, testing, docs, and the release workflow.
1 maintainer
Metadata
1 maintainer
Release files for videopython 0.55.2
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.55.2.tar.gz | 1.1 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| videopython-0.55.2-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 2.3 MB
Release files / videopython-0.55.2.tar.gz
| Download URL | videopython-0.55.2.tar.gz |
|---|---|
| Size | 1.1 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
75542fcd0904cb84f12a8e3c5a8da46b4ab88e487504782ffe87df8e1965a966
|
|
BLAKE2b-256 checksum How to use checksums |
e236e76fa9762aabea421bdc059a02e9bafe6e44867c2e22afbcfcec9a2e81ca
|
| 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 2, 2026.
Transparency logRelease files / videopython-0.55.2-py3-none-any.whl
| Download URL | videopython-0.55.2-py3-none-any.whl |
|---|---|
| Size | 1.2 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
d0880002d2f93baae9ec7b94c3570fc0695cebd71c636a535acf4c31b2ac2f79
|
|
BLAKE2b-256 checksum How to use checksums |
9a1f171de5be4d0ff160aebe0aa5312d327be4d27c6fd18d32853b3dfc1aa47d
|
| 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 2, 2026.
Transparency log
