Metadata-Version: 2.5
Name: videopython
Version: 0.62.1
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: faster-whisper>=1.2.1; 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: pyannote-audio<4.1,>=4.0.7; 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.post2; extra == 'ai'
Provides-Extra: mcp
Requires-Dist: faster-whisper>=1.2.1; extra == 'mcp'
Requires-Dist: imagehash>=4.3; extra == 'mcp'
Requires-Dist: mcp<2,>=1.27; extra == 'mcp'
Requires-Dist: ollama>=0.5.0; 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)

Structured, local-first video editing for Python and AI agents.

Videopython represents an edit as a validated Python model or JSON plan. Whether the
plan comes from your code, an LLM, or an MCP client, it renders through the same
streaming engine with bounded frame buffers.

[Documentation](https://videopython.com) ·
[First edit](https://videopython.com/tutorials/first-edit/) ·
[API reference](https://videopython.com/reference/)

## Why videopython?

- **Structured edits** — segments and operations are Pydantic models with a generated
  JSON Schema.
- **Predictable rendering** — validate dimensions, timing, and operation constraints
  before decoding frames.
- **Bounded memory** — stream decode, effects, and encode without loading the full
  source into memory.
- **Local AI** — add transcription, scene understanding, generation, dubbing, and
  automatic editing without cloud inference APIs.
- **Agent-ready tools** — expose analysis, planning, validation, and rendering through
  the included MCP server.

## Installation

Install FFmpeg, then run `uv add videopython` (or `pip install videopython`).
The optional `ai` and `mcp` extras add model runtimes and the MCP server.
See the [installation guide](https://videopython.com/install/) for supported
Python versions, extras, FFmpeg features, and model setup.

## Quick start

Describe the edit, validate it without loading frames, then render it:

```python
from videopython.editing import VideoEdit

edit = VideoEdit.from_dict({
    "segments": [
        {
            "source": "input.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()
edit.run_to_file("output.mp4")
```

`run_to_file()` streams the source through FFmpeg and the operation pipeline, so frame buffers
stay bounded for long videos. Continue with
[Your first edit](https://videopython.com/tutorials/first-edit/).

## What you can build

| Area | Capabilities | Start here |
|---|---|---|
| Editing | Cuts, transforms, effects, overlays, subtitles, audio, and multi-segment plans | [Editing guides](https://videopython.com/how-to/) |
| AI workflows | Transcription, detection, scene understanding, generation, dubbing, and automatic editing | [Local AI](https://videopython.com/explanation/local-ai/) |
| LLM integrations | Generated schemas, structured validation, repair, and dimension normalization | [LLM plan guide](https://videopython.com/how-to/llm-plans/) |
| MCP agents | Local tools for media analysis, planning, validation, and rendering | [MCP guide](https://videopython.com/how-to/mcp-server/) |

Core editing does not install PyTorch or other model runtimes. AI dependencies load only
when you use an AI feature.

## Scope

Videopython is a library for programmatic editing. It does not provide a hosted
inference service, an interactive editing application, universal support for model
runtimes and FFmpeg builds, or a second in-memory operation engine.

## Project status

Videopython is pre-1.0, so public interfaces can still change. See the
[compatibility policy](docs/reference/compatibility.md) for public contracts and
versioning rules, and [release notes](RELEASE_NOTES.md)
for changes between versions. Report vulnerabilities through the [security
policy](SECURITY.md).

For local setup, tests, documentation builds, and releases, see
[DEVELOPMENT.md](DEVELOPMENT.md).
