videopython 0.26.9

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

Installation

1. Install FFmpeg

# macOS
brew install ffmpeg

# Ubuntu / Debian
sudo apt-get install ffmpeg

# Windows (Chocolatey)
choco install ffmpeg

2. Install videopython

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

Video editing

from videopython import Video
from videopython.base import FadeTransition

intro = Video.from_path("intro.mp4").resize(1080, 1920)
clip = Video.from_path("raw.mp4").cut(10, 25).resize(1080, 1920).resample_fps(30)
final = intro.transition_to(clip, FadeTransition(effect_time_seconds=0.5))
final = final.add_audio_from_file("music.mp3")
final.save("output.mp4")

JSON editing plans

Define multi-segment edits as JSON - useful for LLM-driven workflows. VideoEdit.json_schema() returns a schema for plan generation/validation.

from videopython.editing import VideoEdit

plan = {
    "segments": [{
        "source": "raw.mp4",
        "start": 10.0,
        "end": 20.0,
        "transforms": [
            {"op": "resize", "args": {"height": 1280}},
            {"op": "speed_change", "args": {"speed": 1.25}},
        ],
    }],
    "post_effects": [
        {"op": "fade", "args": {"mode": "in", "duration": 0.5}, "apply": {"start": 0.0, "stop": 0.5}},
    ],
}

edit = VideoEdit.from_dict(plan)
edit.validate()   # dry-run via metadata (no frame loading)
final = edit.run()
final.save("output.mp4")

AI generation

from videopython.ai import TextToImage, ImageToVideo, TextToSpeech

image = TextToImage().generate_image("A cinematic mountain sunrise")
video = ImageToVideo().generate_video(image=image).resize(1080, 1920)
audio = TextToSpeech().generate_audio("Welcome to videopython.")
video.add_audio(audio).save("ai_video.mp4")

LLM & AI Agent Integration

videopython is designed to be controlled by LLMs. Every video operation exposes a machine-readable spec with descriptions, parameter types, and value constraints - all available as JSON Schema at runtime.

Schema generation - VideoEdit.json_schema() returns a complete JSON Schema describing valid edit plans. Pass it directly as a tool schema or structured-output format to any LLM API:

from videopython.editing import VideoEdit

schema = VideoEdit.json_schema()
# Pass `schema` to your LLM as a function/tool definition or response format.
# The LLM generates a plan dict, then:

edit = VideoEdit.from_dict(plan)
edit.validate()   # dry-run: checks sources, time ranges, params - no frames loaded
final = edit.run()
final.save("output.mp4")

Operation discovery - the registry lets an LLM (or your code) inspect all available operations, their parameters, and constraints:

from videopython.base import get_operation_specs, get_specs_by_category, OperationCategory

all_ops = get_operation_specs()                                    # all registered operations
transforms = get_specs_by_category(OperationCategory.TRANSFORMATION)  # just transforms

spec = all_ops["color_adjust"]
print(spec.description)       # LLM-friendly docstring
print(spec.to_json_schema())  # {"brightness": {"type": "number", "minimum": -1, "maximum": 1}, ...}

Every operation has LLM-optimized descriptions and rich constraints (minimum, maximum, enum, exclusive_minimum, etc.) so models generate valid parameters on the first try.

Docs: Editing Plans | Operation Registry

Features

videopython.base - core editing (no AI dependencies)

Area	Highlights
Video I/O	Video, VideoMetadata, FrameIterator - load, save, inspect
Editing plans	VideoEdit, SegmentConfig - JSON/LLM-friendly multi-segment plans with full JSON Schema generation, dry-run validation, and operation registry
Multicam editing	MultiCamEdit, CutPoint - switch between synchronized camera angles with transitions, replace audio with external track
Transforms	Cut (time/frame), resize, crop, FPS resampling, speed change, picture-in-picture, reverse, freeze frame, silence removal
Transitions	FadeTransition, BlurTransition, InstantTransition
Effects	Blur, zoom, color grading, vignette, Ken Burns, image overlay, fade, text overlay, volume adjust
Audio	Load/save, overlay, concat, normalize, time-stretch, silence detection, segment classification
Text	Transcription data classes, TranscriptionOverlay for subtitle rendering
Scene detection	Histogram-based scene boundaries (detect, detect_streaming, detect_parallel)

API docs: Core | Video | Audio | Editing Plans | Transforms | Transitions | Effects | Text

videopython.ai - local AI features (install with [ai])

Area	Highlights
Generation	TextToVideo, ImageToVideo, TextToImage, TextToSpeech, TextToMusic
Understanding	AudioToText (transcription), AudioClassifier, SceneVLM (visual scene description), ActionRecognizer
Scene detection	SemanticSceneDetector (neural scene boundaries)
Video analysis	VideoAnalyzer - full-pipeline analysis combining multiple AI capabilities
Transforms	FaceTracker, FaceTrackingCrop, SplitScreenComposite
Dubbing	VideoDubber - voice cloning and revoicing with timing sync
Object swapping	ObjectSwapper - detect, segment, and inpaint objects in video

API docs: Generation | Understanding | Transforms | Dubbing | Object Swapping

Examples

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

Development

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