Metadata-Version: 2.5
Name: videopython
Version: 0.58.0
Summary: LLM-friendly Python video editing with JSON plans, local AI, and MCP tools.
Project-URL: Homepage, https://videopython.com
Project-URL: Repository, https://github.com/bartwojtowicz/videopython/
Project-URL: Documentation, https://videopython.com
Author-email: Bartosz Wójtowicz <bartoszwojtowicz@outlook.com>, Bartosz Rudnikowicz <bartoszrudnikowicz840@gmail.com>, Piotr Pukisz <piotr.pukisz@gmail.com>
License: Apache-2.0
License-File: LICENSE
Keywords: ai,ai-agents,editing,ffmpeg,generation,llm,mcp,movie,ollama,opencv,python,shorts,video,video-editing,videopython
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: <3.15,>=3.11
Requires-Dist: numpy>=1.25.2
Requires-Dist: opencv-python-headless>=4.9.0.80
Requires-Dist: pillow>=12.1.1
Requires-Dist: pydantic>=2.8.0
Requires-Dist: resvg-py>=0.3.2
Requires-Dist: soxr>=0.5
Requires-Dist: tqdm>=4.66.3
Provides-Extra: ai
Requires-Dist: accelerate>=0.29.2; extra == 'ai'
Requires-Dist: demucs>=4.0.0; extra == 'ai'
Requires-Dist: diffusers>=0.35.0; extra == 'ai'
Requires-Dist: ftfy>=6.1; extra == 'ai'
Requires-Dist: imagehash>=4.3; extra == 'ai'
Requires-Dist: numba>=0.62; extra == 'ai'
Requires-Dist: ollama>=0.5.0; extra == 'ai'
Requires-Dist: openai-whisper>=20240930; extra == 'ai'
Requires-Dist: pyannote-audio>=4.0.0; extra == 'ai'
Requires-Dist: pyloudnorm>=0.1.1; extra == 'ai'
Requires-Dist: silero-vad>=5.1; extra == 'ai'
Requires-Dist: torch>=2.8.0; extra == 'ai'
Requires-Dist: torchaudio>=2.8.0; extra == 'ai'
Requires-Dist: torchcodec>=0.7.0; extra == 'ai'
Requires-Dist: torchvision>=0.23.0; extra == 'ai'
Requires-Dist: transformers>=5.2.0; extra == 'ai'
Requires-Dist: transnetv2-pytorch>=1.0.5; extra == 'ai'
Requires-Dist: videopython-chatterbox>=0.1.7.post1; extra == 'ai'
Provides-Extra: mcp
Requires-Dist: imagehash>=4.3; extra == 'mcp'
Requires-Dist: mcp<2,>=1.27; extra == 'mcp'
Requires-Dist: numba>=0.62; extra == 'mcp'
Requires-Dist: ollama>=0.5.0; extra == 'mcp'
Requires-Dist: openai-whisper>=20240930; extra == 'mcp'
Requires-Dist: torch>=2.8.0; extra == 'mcp'
Requires-Dist: torchvision>=0.23.0; extra == 'mcp'
Requires-Dist: transformers>=5.2.0; extra == 'mcp'
Requires-Dist: transnetv2-pytorch>=1.0.5; extra == 'mcp'
Description-Content-Type: text/markdown

# videopython

[![PyPI](https://img.shields.io/pypi/v/videopython)](https://pypi.org/project/videopython/)
[![Python](https://img.shields.io/pypi/pyversions/videopython)](https://pypi.org/project/videopython/)
[![License](https://img.shields.io/github/license/BartWojtowicz/videopython)](LICENSE)
[![CI](https://github.com/BartWojtowicz/videopython/actions/workflows/ci.yml/badge.svg)](https://github.com/BartWojtowicz/videopython/actions/workflows/ci.yml)

Python library for structured, local-first video editing, processing, and AI workflows.
Build edits as validated Python models or JSON plans, then render them through a
bounded-memory streaming engine.

Full documentation: [videopython.com](https://videopython.com)

## Installation

```bash
# Install FFmpeg first (macOS: brew install ffmpeg-full | Debian: apt-get install ffmpeg)
pip install videopython              # core video/audio editing
pip install "videopython[ai]"        # + all local AI features
pip install "videopython[mcp]"       # + MCP and its focused analysis/editing stack
```

`[ai]` and `[mcp]` are independent. Use `[ai,mcp]` when one environment needs every AI
capability and the MCP server.

Python `>=3.11, <3.15`. AI features run locally without cloud inference APIs, but model
weights are downloaded on first use. LLM-driven editing and scene captioning use a local
[Ollama](https://ollama.com) server (`ollama pull qwen3.6:27b`). Image and video
generation require an NVIDIA CUDA GPU. See the [install guide](https://videopython.com/install/)
for FFmpeg, Ollama, model downloads, and hardware details.

Videopython is pre-1.0. Public interfaces can still change before the stable release;
see the [roadmap](ROADMAP.md) for the stability criteria.

## Quick start

An edit is a plan — a dict (or JSON) validated and executed against the source files:

```python
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](https://videopython.com/tutorials/first-edit/).

[![A vertical clip rendered from a videopython JSON plan](https://videopython.com/assets/edit-plan-demo-poster.jpg)](https://videopython.com/how-to/agent-edit-demo/)

*A reproducible eight-second edit rendered from a JSON plan. View the plan, source, and
replay script in the [demo](https://videopython.com/how-to/agent-edit-demo/).*

### 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`:

```python
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](https://videopython.com/how-to/auto-editing/).

### AI generation

Image and video generation use large CUDA-only models. Speech generation can run on CPU
or CUDA.

```python
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")
```

## Structured plans and automation

The same validation and rendering path works whether a plan is written directly, loaded
from JSON, produced by a model, or submitted through MCP:

1. **Python or JSON** — construct `VideoEdit` directly, as in the quick start.
2. **Your own LLM** — use the generated JSON Schema and structured refine loop. [Guide](https://videopython.com/how-to/llm-plans/)
3. **`AutoEditor`** — use a local Ollama vision model to select and order scenes. [Guide](https://videopython.com/how-to/auto-editing/)
4. **MCP** — expose analysis, planning, validation, and rendering tools to any compatible client. [Guide](https://videopython.com/how-to/mcp-server/)

For schema-driven integrations, every operation is a Pydantic model whose fields are the
JSON wire format. `VideoEdit.json_schema()` returns a discriminated union over every
exposed operation; pass `strict=True` for provider grammar modes. Plans parse
permissively and report numeric bounds during validation, so a refine loop can use:

- **`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](https://videopython.com/explanation/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`, `FaceShotTracker`, `FaceSmoothingTracker`, `ObjectDetector`, `SemanticSceneDetector`), the `FaceTrackingCrop` transform, the `ObjectDetectionOverlay` effect, and the full-pipeline `VideoAnalyzer`. Scene captioning and dubbing translation run on a local [Ollama](https://ollama.com) 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 `[mcp]`)* — `videopython-mcp`, an MCP stdio server exposing the auto-edit pipeline to compatible clients. The extra includes the analysis and AI editing dependencies, but not generation, dubbing, diarization, source separation, or TTS.

## Documentation

The docs follow [Diátaxis](https://diataxis.fr): four sections, each answering a different kind of question.

| | |
|---|---|
| [Tutorials](https://videopython.com/tutorials/) | Learn by doing — start here if you are new |
| [How-to guides](https://videopython.com/how-to/) | Recipes for a specific goal |
| [Reference](https://videopython.com/reference/) | Classes, operations, parameters, wire format |
| [Explanation](https://videopython.com/explanation/) | Why the library is shaped the way it is |

## Development

See [`DEVELOPMENT.md`](DEVELOPMENT.md) for local setup, testing, docs, and the release workflow.
See [`ROADMAP.md`](ROADMAP.md) for project direction and the criteria for 1.0.
