videopython 0.34.0

Minimal video generation and processing library.

videopython

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]"    # + local AI features (GPU recommended)

Python >=3.10, <3.14. AI features run locally — no cloud API keys required, but model weights are downloaded on first use.

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. Use edit.run() to get a Video back in memory instead.

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

Every operation is a Pydantic model whose fields ARE the JSON wire format. VideoEdit.json_schema() returns a JSON Schema with a discriminated union over every registered Operation — pass it straight to Anthropic tool use, OpenAI function calling, or any structured-output API. Then edit.validate() dry-runs the plan via metadata before any frames are loaded, so a failed LLM output can be fed back as an error and retried cheaply.

See the LLM Integration Guide for end-to-end examples, validation error loops, and operation discovery patterns.

Features

• videopython.base — Video, VideoMetadata, FrameIterator, ImageText, 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 (cut, resize, crop, fps, speed, reverse, freeze, silence removal) 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, SemanticSceneDetector), FaceTrackingCrop transform, and the full-pipeline VideoAnalyzer.
• videopython.ai.dubbing — VideoDubber for voice-cloned revoicing with timing sync.

Examples

• Social Media Clip
• AI-Generated Video
• Auto-Subtitles
• Processing Large Videos

Development

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