Skip to content

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.

docs: README FAQ for Remotion and filter-graph checks (#345)

Shogo Kajiyama4334225e4a61
diff --git a/CHANGELOG.md b/CHANGELOG.md
index eba525b..0b5e54c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,7 +4,9 @@
## Unreleased
-(nothing yet)
+### Added
+
+- **README FAQ.** How ffmpeg-skill compares with Remotion: it edits existing footage locally with FFmpeg tools and a machine-readable contract; Remotion renders from React; a file Remotion or HyperFrames writes is an ordinary input here. Whether the filter graph is validated before a run: no. `--dry-run` prints a writing tool's ffmpeg command and does not start ffmpeg. `--plan` records that dry run and fingerprints inputs; `render.py` re-runs the tool later, it does not ask ffmpeg to parse the graph. `doctor` checks capability names against `ffmpeg -filters`, `-encoders` and `-bsfs`.
## 2.10.7
diff --git a/README.md b/README.md
index 5022ddd..158367d 100644
--- a/README.md
+++ b/README.md
@@ -395,9 +395,13 @@ The short list for humans. The agent-facing version, with the reasoning, is the
Each operation is a script whose flags are its argparse parser, and that parser is what `contract --json` and the MCP `inputSchema` are built from. CI fails the build when those drift from the scripts. A caller-supplied filter graph, `-vf` string, or other ffmpeg option is not an argument any script accepts. `doctor` reads `ffmpeg -filters` (and `-encoders`, `-bsfs`) and reports a filter a tool needs before a job runs into it. MCP does accept an `argv` array, and that array is the named script's own CLI flags, still bound to that script: the script's flags, never an ffmpeg command line and never a shell.
-### How does this differ from Remotion or HyperFrames? Can they be used together?
+### How does ffmpeg-skill compare with Remotion?
-Remotion renders a video from React components. HyperFrames renders one from HTML. This repository does neither, and it does not call either of them. It edits a media file you already have, on the machine, with ffmpeg and ffprobe, then probes the file it wrote. A render from either tool is an ordinary input: `probe.py`, `cut.py`, `fit.py`, `export.py` and `check.py` take the file the same way they take any other clip.
+ffmpeg-skill edits footage you already have, on this machine, with FFmpeg tools whose flags are a machine-readable contract (`contract --json`). Remotion renders a video from React components. They complement each other: this repository does not call Remotion, and a file Remotion writes is an ordinary input (`probe.py`, `cut.py`, `fit.py`, `export.py`, `check.py`). HyperFrames renders a video from HTML and is the same kind of neighbour: a file it writes is an ordinary input too.
+
+### Does it validate the filter graph before running?
+
+No. `--dry-run` prints the ffmpeg command a writing tool would run and does not start ffmpeg, so ffmpeg never parses that filter graph. ffprobe still runs when the tool probes an input that exists. Unless `--overwrite` is passed, an existing output is refused (`kind: input`) before ffmpeg. An output that is the same file as an input is refused either way. No media file is written, and `verified` is false; `--plan FILE` does write the plan JSON. A path that is not on disk yet is not measured: the probe is a stub (0×0, duration 0), so a number taken from it is not a measurement. The measuring tools (`probe`, `check`, `sync`, `multicam`, `scenes`, `cropdetect`, `report`, `silence`, `loudness`, `stabilize`) still run their measurements; only the artifact is skipped, and `silence` with `--filler --transcribe` also runs the speech engine, which may download a model. `verify` accepts `--dry-run` and ignores it: its steps run. `--plan FILE` is that dry run written down — the planned argv, the command lines, and a fingerprint of each existing input (size, plus a sha256 of the first and last 8 MiB). `render.py` and `verify.py` refuse `--plan`. `render.py FILE` runs a plan only when those fingerprints still match, by running the tool again with the planned argv, not by executing the recorded ffmpeg lines; `--dry-run` on that run only prints them. `doctor` reports whether the filters, encoders and bitstream filters the contract names are in this build (`ffmpeg -filters`, `-encoders`, `-bsfs`) and which fonts are installed. A name in that listing is not a check of the graph this command would build, and a listed GPU encoder is not a successful encode.
### Can it remove burned-in subtitles or logos?
diff --git a/tests/test_contract.py b/tests/test_contract.py
index 1ba11c1..9a6b7a9 100644
--- a/tests/test_contract.py
+++ b/tests/test_contract.py
@@ -645,7 +645,8 @@ class ContractTests(unittest.TestCase):
see _contract.py's DRY_RUN_ANALYSIS) and for verify (accepts the flag but ignores it).
Pin the doc text naming those exact tools against the real exception set so a future
tool gaining/losing an analysis-only dry-run mode is caught here instead of the docs
- silently drifting out of sync with _contract.py again (issue #82)."""
+ silently drifting out of sync with _contract.py again (issue #82). README's FAQ states
+ the same list."""
analysis_tools = set(_contract.DRY_RUN_ANALYSIS.keys())
self.assertEqual(analysis_tools, {"sync", "multicam", "scenes", "report", "cropdetect", "silence", "loudness", "check", "stabilize"},
"the analysis-only dry-run tool set changed -- update SKILL.md/references/scripts.md's exception list to match")
@@ -653,7 +654,7 @@ class ContractTests(unittest.TestCase):
# request table anyway, so the list drifted twice (#176 -> #179) with this test green.
# Pin the sentence that states the exception: the one naming `verify` and `--dry-run`.
docs = {"SKILL.md": ROOT / "SKILL.md", "references/scripts.md": ROOT / "references" / "scripts.md",
- "docs/contract.md": ROOT / "docs" / "contract.md"}
+ "docs/contract.md": ROOT / "docs" / "contract.md", "README.md": ROOT / "README.md"}
for label, path in docs.items():
text = path.read_text(encoding="utf-8")
paragraphs = [p for p in text.split("\n\n") if "verify" in p and "dry-run" in p and "multicam" in p]