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).

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="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 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:

  1. Bring your own LLM — videopython gives your model the JSON Schema and a structured refine loop; your model authors the plans (details below).
  2. AutoEditor — a local Ollama vision model is the planner (see Automatic editing above).
  3. 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

Development

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

Project links

Data verified by PyPI on Jul 9, 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:
Newer release available (0.55.1)

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 Jul 9, 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.54.0.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.54.0-py3-none-any.whl (1.2 MB view details)

Uploaded Python 3

File details

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

File metadata

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

File hashes

Hashes for videopython-0.54.0.tar.gz
Algorithm Hash digest
SHA256 9a68e4b0be299b90b9a9dd438ff67911626103bb8b9326b4c0dd87c988b8e217
MD5 5ad53cfb949a5753058f75a36b2fafc7
BLAKE2b-256 e7dd9f6f32a4031890676c44df73f24b519067c6b026030a8b6de2a08f4de0b7

See more details on using hashes here.

Provenance

The following attestation bundles were made for videopython-0.54.0.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.54.0-py3-none-any.whl.

File metadata

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

File hashes

Hashes for videopython-0.54.0-py3-none-any.whl
Algorithm Hash digest
SHA256 c93814660d1db97299334f36c0911da3192d31ac44b4526c3f81503f7e05a880
MD5 8075439cb96721e07a9289c2f97547d1
BLAKE2b-256 5ecb89cb2a8cb26473dc933d9a012830fbf2bc415c85dcbae216dd6113d6db92

See more details on using hashes here.

Provenance

The following attestation bundles were made for videopython-0.54.0-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

0.55.1

2 files

0.55.0

2 files

0.54.1

2 files

This release

0.54.0 This release

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