videopython

PyPI Python License

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:

  1. Bring your own LLM — videopython gives your model the JSON Schema and a structured refine loop; your model authors the plans. Guide
  2. AutoEditor — a local Ollama vision model is the planner. Guide
  3. MCP server — videopython-mcp exposes 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 first
  • edit.repair(meta) — auto-clamp mechanical violations (overruns, negatives) with a changelog
  • edit.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 — 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, and the full-pipeline VideoAnalyzer. 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 — VideoDubber for 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.

Project links

Data verified by PyPI on Aug 25, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for bartwojtowicz from gravatar.com bartwojtowicz

Credits

Author: Bartosz Wójtowicz

GitHub Statistics

Data verified by PyPI on Aug 25, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

Apache Software License (Apache-2.0)

Requires

Python <3.14, >=3.11

Provides Extra

ai mcp

Tags

ai editing generation movie opencv python shorts video videopython

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

videopython-0.55.1.tar.gz (1.1 MB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

videopython-0.55.1-py3-none-any.whl (1.2 MB view details)

Uploaded Python 3

File details

Details for the file videopython-0.55.1.tar.gz.

File metadata

  • Download URL: videopython-0.55.1.tar.gz
  • Upload date:
  • Size: 1.1 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for videopython-0.55.1.tar.gz
Algorithm Hash digest
SHA256 145f2b49eda06497845da22ba8c2cc3714f28eef0e377157d34e81128376816b
MD5 beaf0b5e7b1268fe115e1b084cc00121
BLAKE2b-256 2a061dcfc3dee4f2d62b3113c490d09af168df13c9e6111f7520771f8d423181

See more details on using hashes here.

Provenance

The following attestation bundles were made for videopython-0.55.1.tar.gz:

Publisher: publish.yml on BartWojtowicz/videopython

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file videopython-0.55.1-py3-none-any.whl.

File metadata

  • Download URL: videopython-0.55.1-py3-none-any.whl
  • Upload date:
  • Size: 1.2 MB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for videopython-0.55.1-py3-none-any.whl
Algorithm Hash digest
SHA256 706c0f110b48921009a8718ca3f5153af00383f856aca60e82f80cdf2eaf023c
MD5 a84d106c3b0dcf710c34a14ba9c8a1e7
BLAKE2b-256 9dba06cfb65c3cd7c68d484fdf91d53e871bcdc4c965c21bbb4d66b70f721d02

See more details on using hashes here.

Provenance

The following attestation bundles were made for videopython-0.55.1-py3-none-any.whl:

Publisher: publish.yml on BartWojtowicz/videopython

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

0.55.1 This release

2 files

0.55.0

2 files

0.54.1

2 files

0.54.0

2 files

0.53.0

2 files

0.52.1

2 files

0.52.0

2 files

0.51.0

2 files

0.50.1

2 files

0.50.0

2 files

0.49.0

2 files

0.48.0

2 files

0.47.0

2 files

0.46.0

2 files

0.45.0

2 files

0.44.1

2 files

0.44.0

2 files

0.43.1

2 files

0.43.0

2 files

0.42.0

2 files

0.41.0

2 files

0.40.0

2 files

0.39.0

2 files

0.38.0

2 files

0.37.0

2 files

0.36.1

2 files

0.36.0

2 files

0.35.1

2 files

0.35.0

2 files

0.34.1

2 files

0.34.0

2 files

0.33.5

2 files

0.33.4

2 files

0.33.3

2 files

0.33.2

2 files

0.33.1

2 files

0.33.0

2 files

0.32.0

2 files

0.31.3

2 files

0.31.2

2 files

0.31.1

2 files

0.31.0

2 files

0.30.0

2 files

0.29.1

2 files

0.29.0

2 files

0.28.3

2 files

0.28.2

2 files

0.28.1

2 files

0.28.0

2 files

0.27.2

2 files

0.27.1

2 files

0.27.0

2 files

0.26.10

2 files

0.26.9

2 files

0.26.8

2 files

0.26.7

2 files

0.26.6

2 files

0.26.5

2 files

0.26.4

2 files

0.26.3

2 files

0.26.2

2 files

0.26.1

2 files

0.26.0

2 files

0.25.8

2 files

0.25.7

2 files

0.25.6

2 files

0.25.5

2 files

0.25.4

2 files

0.25.3

2 files

0.25.2

2 files

0.25.1

2 files

0.25.0

2 files

0.24.2

2 files

0.24.1

2 files

0.24.0

2 files

0.23.3

2 files

0.23.2

2 files

0.23.1

2 files

0.23.0

2 files

0.22.8

2 files

0.22.7

2 files

0.22.6

2 files

0.22.5

2 files

0.22.4

2 files

0.22.3

2 files

0.22.2

2 files

0.22.1

2 files

0.22.0

2 files

0.21.6

2 files

0.21.5

2 files

0.21.4

2 files

0.21.3

2 files

0.21.2

2 files

0.21.1

2 files

0.21.0

2 files

0.20.5

2 files

0.20.4

2 files

0.20.3

2 files

0.20.2

2 files

0.20.1

2 files

0.20.0

2 files

0.19.0

2 files

0.18.3

2 files

0.18.2

2 files

0.18.1

2 files

0.18.0

2 files

0.17.0

2 files

0.16.6

2 files

0.16.5

2 files

0.16.4

2 files

0.16.3

2 files

0.16.2

2 files

0.16.1

2 files

0.16.0

2 files

0.15.6

2 files

0.15.5

2 files

0.15.4

2 files

0.15.3

2 files

0.15.2

2 files

0.15.1

2 files

0.15.0

2 files

0.14.1

2 files

0.14.0

2 files

0.13.0

2 files

0.12.0

2 files

0.11.1

2 files

0.11.0

2 files

0.10.0

2 files

0.9.1

2 files

0.8.3

2 files

0.8.2

2 files

0.8.1

2 files

0.8.0

2 files

0.7.4

2 files

0.7.3

2 files

0.7.2

2 files

0.7.1

2 files

0.7.0

2 files

0.6.3

2 files

0.6.2

2 files

0.6.1

2 files

0.6.0

2 files

0.5.5

2 files

0.5.4

2 files

0.5.3

2 files

0.5.2

2 files

0.5.1

2 files

0.5.0

2 files

0.4.1

2 files

0.4.0

2 files

0.3.0

2 files

0.2.1

2 files

0.2.0

2 files

0.1.41

2 files

0.1.4

2 files

0.1.3

2 files

0.1.2

2 files

0.1.1

2 files

0.1.0

2 files

0.0.1

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page