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 four subpackages, 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-only AI

Why every model runs on your machine, what that costs, and which parts depend on a local Ollama server.