The command-line workflow is a pipeline with three durable boundaries:
- Ingest converts source media into
words.jsonand an initialedit.md. All expensive media analysis happens here and is persisted. - Editing turns
edit.mdinto validated decisions: curation marks likely restarts, and planning may select, reorder, drop, and assign zoom emphasis. - Render treats
words.json,edit.md, and project configuration as its complete input. It constructs a deterministic output timeline and one FFmpeg graph without re-analyzing source audio.
| Module | Responsibility |
|---|---|
core.py |
Shared constants, external-tool resolution, small text/process helpers |
ingest.py |
Audio extraction, Whisper parsing, energy timing, face detection |
transcript.py |
Sentence grouping and delivery annotations |
curate.py |
Conservative false-start and restart detection |
planning.py |
Backend calls, plan validation, and edit.md rewriting |
cuts.py |
Edit matching, cut-list construction, clamping, and zoom assignment |
framing.py |
Face-aware crop solver and per-take framing overrides |
config.py |
Parsing and validation of the flat YAML-like configuration files |
overlays.py |
Phrase/time anchor resolution for still-image overlays |
captions.py |
Caption timing, grouping, layout, and ASS generation |
ffmpeg.py |
Resolution probing and the single-pass FFmpeg filter graph |
setup.py |
Dependency doctor and consent-gated installer (vlogcut setup) |
cli.py |
Subcommands and workflow orchestration |
vlogcut.py is only a compatibility launcher. The installed vlogcut
command and python -m vlogcut both call vlogcut.cli:main.
words.jsonis the timing and analysis source of truth.edit.mdtext must continue matching transcript sentences verbatim; markup such asx,~~strike~~,{zoom}, and comments is explicitly parsed.- Planning may select and reorder spoken lines, but never invent transcript text. A plan is applied only after complete validation.
- Rendering must remain a pure derivation from project artifacts and config.
- Refactors must preserve the computed cut list, generated ASS, and FFmpeg
graph. Run
python3 tests/run_checks.pyafter changes.