Show HN: Videopython – local-first video processing, editing and AI workflows

Notifications You must be signed in to change notification settings

Fork 0

Star 16

BranchesTags

Open more actions menu

Folders and files

NameName

Last commit message

Last commit date

Latest commit

History

253 Commits

253 Commits

.github/workflows

.github/workflows

docs

docs

src

src

.gitignore

.gitignore

.pre-commit-config.yaml

.pre-commit-config.yaml

DEVELOPMENT.md

DEVELOPMENT.md

LICENSE

LICENSE

README.md

README.md

RELEASE_NOTES.md

RELEASE_NOTES.md

mkdocs.yml

mkdocs.yml

pyproject.toml

pyproject.toml

uv.lock

uv.lock

Repository files navigation

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 gemma3:27b).

Quick Start

JSON editing plans

A VideoEdit is a multi-segment plan, defined as 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 ffmpeg decode → per-frame effects → encode, so memory stays bounded even for hour-long sources. If you need the frames back in memory, load the rendered file: Video.from_path(str(edit.run_to_file("output.mp4"))).

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="gemma3:27b")) # ollama pull gemma3: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 the Automatic Editing Guide.

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:

Bring your own LLM — videopython gives your model the JSON Schema and a structured refine loop; your model authors the plans (details below).

AutoEditor — a local Ollama vision model is the planner (see Automatic editing above).

MCP server — videopython-mcp exposes the pipeline as Model Context Protocol tools, so an agent like Claude drives editing with its own model. Install [ai,mcp], run videopython-mcp, and point your MCP client at it. See the MCP Server 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 first

edit.repair(meta) — auto-clamp mechanical violations (overruns, negatives) with a changelog

edit.normalize_dimensions(meta, target) — make heterogeneous segments concat-compatible

See the LLM Integration Guide for end-to-end examples (Anthropic / OpenAI tool use), the refine loop, and operation discovery.

Features

videopython.base — Video, VideoMetadata, FrameIterator, Transcription, and shared result types (BoundingBox, FaceTrack, SceneBoundary, ...). No AI dependencies.

videopython.audio — Audio with overlay, concat, normalize, time-stretch, silence detection, segment classification.

videopython.editing — Operation/Effect foundation, VideoEdit plan 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), the FaceTrackingCrop transform, the ObjectDetectionOverlay effect (per-frame bounding boxes + labels), and the full-pipeline VideoAnalyzer. Scene captioning and dub translation run on a local Ollama model.

videopython.ai.auto_edit — AutoEditor + OllamaVisionLLM: plan and render an edit from sources + a one-line brief, with a local LLM selecting scenes by id from an auto-built catalog.

videopython.ai.dubbing — VideoDubber for voice-cloned revoicing with timing sync.

videopython.mcp (install with [mcp]) — videopython-mcp, an MCP stdio server exposing the auto-edit pipeline (analyze → catalog → validate/repair/run) so an agent drives editing.

Examples

Social Media Clip

AI-Generated Video

Auto-Subtitles

Processing Large Videos

Development

See DEVELOPMENT.md for local setup, testing, and contribution workflow.

About

Video generation and processing library.

videopython.com/

Topics

python

video

ffmpeg

video-processing

video-generation

Resources

Readme

License

Apache-2.0 license

Uh oh!

There was an error while loading. Please reload this page.

Activity

Stars

16 stars

Watchers

2 watching

Forks

0 forks

Report repository

Releases 147

v0.52.1

Latest

Jun 22, 2026

+ 146 releases

Uh oh!

There was an error while loading. Please reload this page.

Contributors

Uh oh!

There was an error while loading. Please reload this page.

Languages

Python 100.0%