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 Aug 2, 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 Aug 2, 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.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.54.1-py3-none-any.whl (1.2 MB view details)

Uploaded Python 3

File details

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

File metadata

  • Download URL: videopython-0.54.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.54.1.tar.gz
Algorithm Hash digest
SHA256 060a4a05f9014a33fb8ac29f5b0f7c19389e80f7e81b1027b15390df6817e1bc
MD5 cb27e2d46d799aab9226d76adb4d92f3
BLAKE2b-256 9e291e1d0f5bc5c3416d4bedd848c5c8433b9278d98b8300cb9b3aa49f77aa45

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: videopython-0.54.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.54.1-py3-none-any.whl
Algorithm Hash digest
SHA256 04fcec533b83926b8be6992d7b9d05f96334f2c369a79c713691c971877931a4
MD5 1e30b36975aebf95a3fbabcb57cf09ca
BLAKE2b-256 0d52f534fb4ae4e51e0172b003f1ca92894b7e6ec922c6ba32e3a299bdd99392

See more details on using hashes here.

Provenance

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

0.55.1

2 files

0.55.0

2 files

This release

0.54.1 This release

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