videopython
Python library for structured, local-first video editing, processing, and AI workflows. Build edits as validated Python models or JSON plans, then render them through a bounded-memory streaming engine.
Full documentation: videopython.com
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
pip install "videopython[mcp]" # + MCP and its focused analysis/editing stack
[ai] and [mcp] are independent. Use [ai,mcp] when one environment needs every AI
capability and the MCP server.
Python >=3.11, <3.14. AI features run locally without cloud inference APIs, but model
weights are downloaded on first use. LLM-driven editing and scene captioning use a local
Ollama server (ollama pull qwen3.6:27b). Image and video
generation require an NVIDIA CUDA GPU. See the install guide
for FFmpeg, Ollama, model downloads, and hardware details.
Videopython is pre-1.0. Public interfaces can still change before the stable release; see the roadmap for the stability criteria.
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.
A reproducible eight-second edit rendered from a JSON plan. View the plan, source, and replay script in the demo.
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
Image and video generation use large CUDA-only models. Speech generation can run on CPU or CUDA.
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")
Structured plans and automation
The same validation and rendering path works whether a plan is written directly, loaded from JSON, produced by a model, or submitted through MCP:
- Python or JSON — construct
VideoEditdirectly, as in the quick start. - Your own LLM — use the generated JSON Schema and structured refine loop. Guide
AutoEditor— use a local Ollama vision model to select and order scenes. Guide- MCP — expose analysis, planning, validation, and rendering tools to any compatible client. Guide
For schema-driven integrations, every operation is a Pydantic model whose fields are the
JSON wire format. VideoEdit.json_schema() returns a discriminated union over every
exposed operation; pass strict=True for provider grammar modes. Plans parse
permissively and report numeric bounds during validation, so a refine loop can use:
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,FaceShotTracker,FaceSmoothingTracker,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[mcp]) —videopython-mcp, an MCP stdio server exposing the auto-edit pipeline to compatible clients. The extra includes the analysis and AI editing dependencies, but not generation, dubbing, diarization, source separation, or TTS.
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.
See ROADMAP.md for project direction and the criteria for 1.0.
1 maintainer
Metadata
1 maintainer
Release files for videopython 0.57.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.57.0.tar.gz | 1.1 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| videopython-0.57.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 2.3 MB
Release files / videopython-0.57.0.tar.gz
| Download URL | videopython-0.57.0.tar.gz |
|---|---|
| Size | 1.1 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
6aa4621ebdc1046978d559735dc72f571abe082518df033981f37adeeb044026
|
|
BLAKE2b-256 checksum How to use checksums |
900b1594418bc6b96dcf285f0b4c6e324f6eff9c57cef49e4cc596d9aaa5b1f5
|
| 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.57.0-py3-none-any.whl
| Download URL | videopython-0.57.0-py3-none-any.whl |
|---|---|
| Size | 1.2 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
59cf75bb7f68d867857d1da0d1a777713a07241f1d5a3f70ce5c8f7336e12bc3
|
|
BLAKE2b-256 checksum How to use checksums |
efb3147dca386c6c8d6bce198b03944a49bb17e9969e96fd0030f3eb7338f97b
|
| 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
