Explanation

Background on why videopython is shaped the way it is. Nothing here is needed to get work done — it is here so that when the library behaves in a way that surprises you, the behavior has a reason you can find.

Architecture

The library layers and MCP server, the dependency layering that keeps AI optional, and why importing videopython stays fast with [ai] installed.

The streaming engine

Why run_to_file() is the only execution path, how an operation becomes either an FFmpeg filter or a per-frame function, and which plan shapes cannot stream.

The plan lifecycle

Parse, validate, check, repair, normalize — what each stage owns, and why numeric bounds are deliberately not enforced at parse time.

LLM-first design

Why every operation is a Pydantic model, what llm_exposed and llm_hidden are for, and why the auto-editor makes the model select scenes by id.

Local AI

Why inference stays under your control, what that costs, and which parts depend on Ollama.

The dubbing pipeline

Why source turns, translation phrases, and generated speech use different units.

MCP security boundary

What the local MCP process can read, write, execute, and send to its client or Ollama host.