Skip to content

Installation

Prerequisites

videopython requires FFmpeg for video processing. Install it first:

# macOS
brew install ffmpeg

# Ubuntu/Debian
sudo apt-get install ffmpeg

# Windows (with Chocolatey)
choco install ffmpeg

Install videopython

Basic Installation

For basic video handling and processing:

pip install videopython

# Or with uv
uv add videopython

With AI Features

To use every AI-powered feature (generation, understanding, dubbing):

pip install "videopython[ai]"

# Or with uv
uv add videopython --extra ai

[ai] is the single extra and installs every AI capability — transcription, detection/scene/VLM understanding, source separation, translation, TTS, media generation, dubbing, and the LLM auto-editing planner. The heavy ML dependencies still load lazily at first use (no top-level imports under ai/), so importing videopython stays light even with [ai] installed.

With the MCP Server

To drive editing from an MCP-capable agent, add the [mcp] extra (it needs [ai] too):

pip install "videopython[ai,mcp]"

This installs the videopython-mcp console script (a stdio Model Context Protocol server). See the MCP Server guide.

Ollama is required for scene captioning, dubbing translation, and auto-editing

Scene captioning (SceneVLM, used by VideoAnalyzer), dubbing translation, and the AutoEditor / MCP planner run against a local Ollama server — there is no in-process fallback. Install Ollama, then pull the default model:

ollama serve            # start the local daemon
ollama pull qwen3.6:27b  # the default vision/translation model

The model must support Ollama's structured-output format. The default qwen3.6:27b is an Apache-2.0 vision model. Generation (image/video/speech/music), transcription, detection, and audio classification do not need Ollama.

Dubbing TTS

The dubbing pipeline synthesizes speech with a local Chatterbox TextToSpeech by default. To run synthesis out of process instead, inject your own SpeechBackend into VideoDubber (e.g. a remote synthesizer).

Hardware Requirements

Image and video generation (TextToImage, TextToVideo, ImageToVideo) require an NVIDIA CUDA GPU — these ~20–28B models raise on CPU/MPS rather than falling back. An NVIDIA A40 or better is recommended for video generation. Music generation (TextToMusic) runs on CUDA, Apple MPS, or CPU, and speech (TextToSpeech) on CUDA or CPU. Detection and understanding models run on CPU (GPU optional).

Local-Only AI Runtime

videopython.ai runs locally and does not use cloud backend/API key configuration.

Practical setup notes:

  • First AI run may download model weights.
  • Image/video generation require a CUDA GPU; other AI models prefer a GPU (cuda, or mps where supported) but run on CPU too.
  • Use the device argument where supported to force placement.
from videopython.ai import TextToSpeech, ImageToVideo

tts = TextToSpeech(device="cuda")
video_gen = ImageToVideo()