Local video editor for coding agents: 42 FFmpeg tools with a machine-readable contract and an MCP server, for Claude Code, Cursor and Codex. Cut, captions, reframe, loudness, platform exports. No cloud, no API keys.
Python agent-skillsai-agentsaudio-processingcaptionsclaude-codecodexcoding-agentcursorffmpegloudness-normalizationmcpmcp-servermodel-context-protocolpythonsubtitlestranscodingvideovideo-editingvideo-processingwhisper
docs: record the 2.0 design decisions (time grammar, encoder abstraction, Context) (#198)
claude[bot]7a46c22283a9
diff --git a/docs/design-decisions.md b/docs/design-decisions.mdindex 8b713d9..5b71aff 100644--- a/docs/design-decisions.md+++ b/docs/design-decisions.md@@ -118,3 +118,29 @@ exists. When a decision changes, edit the entry in the same PR.- **`retryable` is always `false` in failure documents.** No failure kind is distinguishabletoday from a deterministic one that would fail identically on a blind retry, so the field neverinvites a retry loop. Code: `_common.ERROR_RETRYABLE`.++## Decided for 2.0 (issue #189 B), recorded in 1.x so the code moves toward them++- **Time grammar: seconds, `mm:ss(.fff)`, `hh:mm:ss(.fff)` everywhere; four-part `hh:mm:ss:ff`+ is SMPTE at the source's frame rate, and a `@fps` suffix (e.g. `00:01:02:[email protected]`) names the+ rate explicitly.** The ambiguity today is only the four-part form (it needs an fps, and each+ tool found it its own way). 1.x: `time_arg()` is the single parser, every tool uses it, an+ unknown fps for a four-part value is `kind: input` naming `--fps`. 2.0: the `@fps` suffix is+ accepted by `time_arg()` and documented once in `references/scripts.md`; nothing else changes,+ so no CLI is removed. Rejected: "seconds only in single tools, composite input only in+ `render.py`" -- editors quote timecode, and refusing it moves the conversion onto the agent.+ Code: `_common.time_arg()`.+- **Encoder abstraction: `--codec h264|hevc|av1|prores` and `--quality N` on every+ re-encoding tool, resolved in one place.** `video_args()` already centralises x264 + the+ HDR/10-bit branch; 2.0 adds the two flags to `add_common()` for tools that re-encode, keeps+ `--crf`/`--preset` as aliases for one major, and maps `--quality` to CRF / `-b:v` / ProRes+ profile per codec. Until then every tool keeps its `x264 medium / crf 18` default; the+ `export.py` presets are the only place a non-x264 codec is chosen. Rejected: a per-tool+ `--codec` added piecemeal in 1.x (the audits found HDR fragility wherever encoder choice was+ duplicated; one more duplication is the wrong direction). Code: `_common.video_args()`.+- **Per-request Context: `STATE` stays process-global through 1.x; 2.0 passes a `Context`+ explicitly to `run()`/`emit()`/`die()`.** Today the MCP server spawns one subprocess per+ call, so the global is never shared between requests; the risk only appears if a future+ server runs tools in-process. 2.0 threads `ctx` through the three choke points (a signature+ change, hence major); tools that only call those keep working with a one-line change. Rejected:+ thread-locals (hides the dependency the reviews keep asking about). Code: `_common.Context`.