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
GitHub Pages: a project site generated from the repo's own Markdown (#363)
Shogo Kajiyama36d023ec9a71
diff --git a/.github/scripts/build_pages.py b/.github/scripts/build_pages.pynew file mode 100644index 0000000..4b60931--- /dev/null+++ b/.github/scripts/build_pages.py@@ -0,0 +1,146 @@+#!/usr/bin/env python3+"""Assemble the GitHub Pages site from the repository's own Markdown, so the site never says+anything the repo doesn't. Nothing here is hand-written copy: each page is a published+document with Jekyll front matter added and its relative links rewritten.++ python3 .github/scripts/build_pages.py [OUT] # default OUT: _pages++- A link to another published document becomes a link to its page (README.md -> index.html).+- A link to any other file or folder in the repo becomes a link to it on github.com.+- An image or other asset the pages reference is copied next to the page that uses it.+- A relative link whose target does not exist is an error: the build fails rather than+ publish a dead link.++pages.yml runs this and hands OUT to actions/jekyll-build-pages; tests/test_contract.py runs+it too, so a broken link fails CI before it reaches the site.+"""+import re+import shutil+import sys+from pathlib import Path+from urllib.parse import quote++ROOT = Path(__file__).resolve().parents[2]+REPO_URL = "https://github.com/kajisho5/ffmpeg-skill"++# repo path -> (site path, page title). The site keeps the repo's layout, so a relative link+# between two published documents stays relative.+PAGES = {+ "README.md": ("index.md", "ffmpeg-skill"),+ "docs/demos.md": ("docs/demos.md", "Demo gallery"),+ "docs/contract.md": ("docs/contract.md", "Contract"),+ "docs/design-decisions.md": ("docs/design-decisions.md", "Design decisions"),+ "docs/roadmap.md": ("docs/roadmap.md", "Roadmap"),+ "CHANGELOG.md": ("CHANGELOG.md", "Changelog"),+}++# ](target) in Markdown, and src= / href= / srcset= in the inline HTML the README uses.+MD_LINK = re.compile(r"""(\]\()([^)\s]+)((?:\s+(?:"[^"]*"|'[^']*'))?\))""") # also [t](url "title")+CODE_SPAN = re.compile(r"(``[^\n]*?``|`[^`\n]*`)")+HTML_ATTR = re.compile(r"""(\b(?:src|href|srcset)=")([^"]+)(")""")+EXTERNAL = re.compile(r"^(?:[a-z][a-z0-9+.-]*:|#|//)", re.I)+++class DeadLink(Exception):+ pass+++def _rewrite(target: str, page_repo: str, assets: set) -> str:+ """Map one relative `target`, written in the repo document `page_repo`, to its URL on the+ published page (which sits at the same relative place in the site)."""+ if EXTERNAL.match(target):+ return target+ path, _, frag = target.partition("#")+ if not path:+ return target+ resolved = (ROOT / Path(page_repo).parent / path).resolve()+ try:+ rel = resolved.relative_to(ROOT).as_posix()+ except ValueError:+ raise DeadLink(f"{page_repo}: {target} points outside the repository")+ if not resolved.exists():+ raise DeadLink(f"{page_repo}: {target} does not exist ({rel})")+ anchor = f"#{frag}" if frag else ""+ page_dir = Path(PAGES[page_repo][0]).parent+ if rel in PAGES:+ site = Path(PAGES[rel][0]).with_suffix(".html")+ return _relative(site, page_dir) + anchor+ if resolved.is_file() and resolved.suffix.lower() in {".png", ".gif", ".svg", ".jpg", ".jpeg", ".webp"}:+ assets.add(rel)+ return _relative(Path(rel), page_dir) + anchor+ kind = "tree" if resolved.is_dir() else "blob"+ return f"{REPO_URL}/{kind}/main/{quote(rel)}{anchor}"+++def _relative(target: Path, from_dir: Path) -> str:+ up = [".."] * len(from_dir.parts)+ return "/".join(up + list(target.parts)) or "."+++def _rewrite_prose(text: str, page_repo: str, assets: set) -> str:+ def md(m):+ return m.group(1) + _rewrite(m.group(2), page_repo, assets) + m.group(3)++ def attr(m):+ if not m.group(1).startswith("srcset"):+ return md(m)+ # srcset="a.png, b.png 2x": rewrite each URL, keep its descriptor+ parts = []+ for candidate in m.group(2).split(","):+ url, *descriptor = candidate.split()+ parts.append(" ".join([_rewrite(url, page_repo, assets)] + descriptor))+ return m.group(1) + ", ".join(parts) + m.group(3)++ # an inline code span is shown as written, like a fenced block+ chunks = CODE_SPAN.split(text)+ return "".join(c if i % 2 else HTML_ATTR.sub(attr, MD_LINK.sub(md, c)) for i, c in enumerate(chunks))+++def render(page_repo: str, assets: set) -> str:+ text = (ROOT / page_repo).read_text(encoding="utf-8")+ # fenced code blocks are shown as written: a `](x)` inside one is code, not a link+ chunks = re.split(r"(^```.*?^```[^\n]*$)", text, flags=re.M | re.S)+ text = "".join(c if i % 2 else _rewrite_prose(c, page_repo, assets) for i, c in enumerate(chunks))+ title = PAGES[page_repo][1]+ # {% raw %} keeps Liquid from reading a `{{` or `{%` that a code sample may contain.+ return f"---\nlayout: default\ntitle: {title}\n---\n{{% raw %}}\n{text}\n{{% endraw %}}\n"+++def build(out: Path) -> "list[str]":+ if out.exists():+ shutil.rmtree(out)+ assets: set = set()+ for repo, (site, _title) in PAGES.items():+ dest = out / site+ dest.parent.mkdir(parents=True, exist_ok=True)+ dest.write_text(render(repo, assets), encoding="utf-8")+ for rel in sorted(assets):+ dest = out / rel+ dest.parent.mkdir(parents=True, exist_ok=True)+ shutil.copy2(ROOT / rel, dest)+ (out / "_config.yml").write_text(+ "title: ffmpeg-skill\n"+ "description: Give your coding agent a video editor. Local FFmpeg, no cloud, no API keys.\n"+ "repository: kajisho5/ffmpeg-skill\n"+ "markdown: kramdown\n"+ "kramdown:\n input: GFM\n hard_wrap: false\n", encoding="utf-8")+ # The site's own layout, not a theme: a theme pulls in GitHub-API metadata the build+ # does not need, and this one page of HTML is the only design the site has.+ (out / "_layouts").mkdir()+ shutil.copy2(Path(__file__).with_name("pages_layout.html"), out / "_layouts" / "default.html")+ return sorted(assets)+++def main(argv: "list[str]") -> int:+ out = Path(argv[1]) if len(argv) > 1 else ROOT / "_pages"+ try:+ assets = build(out)+ except DeadLink as e:+ print(f"build_pages: dead link: {e}", file=sys.stderr)+ return 1+ print(f"build_pages: {len(PAGES)} pages, {len(assets)} assets -> {out}")+ return 0+++if __name__ == "__main__":+ sys.exit(main(sys.argv))diff --git a/.github/scripts/pages_layout.html b/.github/scripts/pages_layout.htmlnew file mode 100644index 0000000..825d155--- /dev/null+++ b/.github/scripts/pages_layout.html@@ -0,0 +1,69 @@+<!doctype html>+<html lang="en">+<head>+<meta charset="utf-8">+<meta name="viewport" content="width=device-width, initial-scale=1">+<title>{% if page.title and page.title != site.title %}{{ page.title }} · {% endif %}{{ site.title }}</title>+<meta name="description" content="{{ site.description }}">+<meta property="og:title" content="{{ page.title | default: site.title }}">+<meta property="og:description" content="{{ site.description }}">+<meta property="og:image" content="https://raw.githubusercontent.com/kajisho5/ffmpeg-skill/main/assets/social-preview.png">+<link rel="icon" href="{{ '/brand/app-icon.png' | relative_url }}">+<style>+:root {+ --bg: #ffffff; --fg: #1f2328; --muted: #59636e; --line: #d1d9e0;+ --link: #0969da; --code-bg: #f6f8fa; --nav-bg: #f6f8fa;+}+@media (prefers-color-scheme: dark) {+ :root {+ --bg: #0d1117; --fg: #e6edf3; --muted: #9198a1; --line: #3d444d;+ --link: #4493f8; --code-bg: #151b23; --nav-bg: #151b23;+ }+}+* { box-sizing: border-box; }+body {+ margin: 0; background: var(--bg); color: var(--fg);+ font: 16px/1.6 -apple-system, BlinkMacSystemFont, "Segoe UI", "Noto Sans", Helvetica, Arial, sans-serif;+}+a { color: var(--link); text-decoration: none; }+a:hover { text-decoration: underline; }+nav {+ position: sticky; top: 0; z-index: 1; background: var(--nav-bg);+ border-bottom: 1px solid var(--line);+}+nav .in {+ max-width: 980px; margin: 0 auto; padding: 10px 16px;+ display: flex; flex-wrap: wrap; gap: 6px 18px; align-items: center;+}+nav .brand { font-weight: 600; color: var(--fg); margin-right: auto; }+main { max-width: 980px; margin: 0 auto; padding: 24px 16px 64px; overflow-wrap: anywhere; }+h1, h2, h3 { line-height: 1.25; margin: 1.6em 0 .6em; }+h1, h2 { padding-bottom: .3em; border-bottom: 1px solid var(--line); }+img { max-width: 100%; }+img:not([height]) { height: auto; }+code, pre { font: 85%/1.45 ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; }+code { background: var(--code-bg); padding: .15em .35em; border-radius: 6px; }+pre { background: var(--code-bg); padding: 14px 16px; border-radius: 6px; overflow-x: auto; }+pre code { background: none; padding: 0; }+table { border-collapse: collapse; display: block; overflow-x: auto; max-width: 100%; }+th, td { border: 1px solid var(--line); padding: 6px 12px; vertical-align: top; }+blockquote { margin: 0; padding: 0 1em; color: var(--muted); border-left: 4px solid var(--line); }+hr { border: 0; border-top: 1px solid var(--line); }+footer { max-width: 980px; margin: 0 auto; padding: 0 16px 40px; color: var(--muted); font-size: 14px; }+</style>+</head>+<body>+<nav><div class="in">+ <a class="brand" href="{{ '/' | relative_url }}">ffmpeg-skill</a>+ <a href="{{ '/docs/demos.html' | relative_url }}">Demos</a>+ <a href="{{ '/docs/contract.html' | relative_url }}">Contract</a>+ <a href="{{ '/docs/design-decisions.html' | relative_url }}">Design decisions</a>+ <a href="{{ '/CHANGELOG.html' | relative_url }}">Changelog</a>+ <a href="https://github.com/kajisho5/ffmpeg-skill">GitHub</a>+</div></nav>+<main>+{{ content }}+</main>+<footer>Generated from the repository's own Markdown by <code>.github/scripts/build_pages.py</code>. Source: <a href="https://github.com/kajisho5/ffmpeg-skill">kajisho5/ffmpeg-skill</a> · MIT</footer>+</body>+</html>diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.ymlnew file mode 100644index 0000000..e80df54--- /dev/null+++ b/.github/workflows/pages.yml@@ -0,0 +1,51 @@+# Publishes https://kajisho5.github.io/ffmpeg-skill/ from the repository's own Markdown.+# .github/scripts/build_pages.py assembles the pages (README -> index, docs/*.md, CHANGELOG)+# with their relative links rewritten; nothing on the site is written by hand. The repo's+# Settings -> Pages -> Source must be "GitHub Actions".+name: pages++on:+ push:+ branches: [main]+ paths:+ - "README.md"+ - "CHANGELOG.md"+ - "docs/**"+ - "brand/**"+ - ".github/scripts/build_pages.py"+ - ".github/scripts/pages_layout.html"+ - ".github/workflows/pages.yml"+ workflow_dispatch:++permissions:+ contents: read+ pages: write+ id-token: write++concurrency:+ group: pages+ cancel-in-progress: true++jobs:+ build:+ runs-on: ubuntu-latest+ steps:+ - uses: actions/checkout@v7+ - name: Assemble the site+ run: python3 .github/scripts/build_pages.py _pages+ - uses: actions/configure-pages@v6+ - uses: actions/jekyll-build-pages@v1+ with:+ source: _pages+ destination: _site+ - uses: actions/upload-pages-artifact@v5++ deploy:+ needs: build+ runs-on: ubuntu-latest+ environment:+ name: github-pages+ url: ${{ steps.deployment.outputs.page_url }}+ steps:+ - id: deployment+ uses: actions/deploy-pages@v5diff --git a/.gitignore b/.gitignoreindex eb24beb..25f4f41 100644--- a/.gitignore+++ b/.gitignore@@ -22,3 +22,7 @@ tests/corpus/# eval staging (fixtures, prompts, per-run outputs) -- not part of the reposcratchpad/++# GitHub Pages build (.github/scripts/build_pages.py)+_pages/+_site/diff --git a/CHANGELOG.md b/CHANGELOG.mdindex cb89af7..3b8ea9c 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -6,6 +6,7 @@### Documentation+- **A project site on GitHub Pages.** `pages.yml` publishes https://kajisho5.github.io/ffmpeg-skill/ on every push to `main` that touches the docs. `.github/scripts/build_pages.py` assembles the site from the repository's own Markdown: the README, the demo gallery, the contract, the design decisions, the roadmap and this changelog. It rewrites relative links and copies the images they use, so nothing on the site is written by hand. A relative link to a file that does not exist fails the build, and `test_pages_site_builds_with_no_dead_links` runs the same build in CI.- **Measured on a one-hour recording.** README § "A one-hour recording" times the main tools on a 60-minute 1080p30 file. Every analysis tool and the stream-copy cut finished, the slowest being `check.py --content` at 308 s. A whole-hour `export.py --preset youtube` at the default preset hit the default 1800 s `--timeout` and failed cleanly with `kind: timeout`. The README's gotchas and SKILL.md's shared-flags line now say to pass `--timeout 0` or `--fast` for an hour-long re-encode.## 2.17.1diff --git a/tests/test_contract.py b/tests/test_contract.pyindex ef932ba..612380a 100644--- a/tests/test_contract.py+++ b/tests/test_contract.py@@ -232,6 +232,34 @@ class ContractTests(unittest.TestCase):self.assertTrue(set(manifest) <= {"name", "version", "description", "author", "homepage", "repository", "license", "keywords"}, sorted(manifest))self.assertTrue(re.fullmatch(r"[a-z0-9-]+", manifest["name"]))+ def test_pages_site_builds_with_no_dead_links(self):+ """The GitHub Pages site (pages.yml) is assembled from the repo's own Markdown by+ .github/scripts/build_pages.py, which refuses a relative link whose target does not+ exist. Running it here means a renamed doc or a moved GIF fails CI instead of+ publishing a dead link, and every image a page points to was copied next to it."""+ with tempfile.TemporaryDirectory() as tmp:+ out = Path(tmp) / "site"+ proc = subprocess.run([sys.executable, str(ROOT / ".github" / "scripts" / "build_pages.py"), str(out)],+ capture_output=True, text=True)+ self.assertEqual(proc.returncode, 0, proc.stderr)+ self.assertTrue((out / "index.md").is_file())+ # a titled link is rewritten; a link-shaped inline code span is left as written+ sys.path.insert(0, str(ROOT / ".github" / "scripts"))+ try:+ import build_pages+ finally:+ sys.path.pop(0)+ self.assertEqual(build_pages._rewrite_prose('[c](docs/contract.md "API") `](no.png)`', "README.md", set()),+ '[c](docs/contract.html "API") `](no.png)`')+ self.assertTrue((out / "_layouts" / "default.html").is_file())+ for page in out.rglob("*.md"):+ text = page.read_text(encoding="utf-8")+ self.assertTrue(text.startswith("---\nlayout: default\n"), page)+ for src in re.findall(r'(?:src|srcset)="([^"]+)"|!\[[^\]]*\]\(([^)\s]+)\)', text):+ url = (src[0] or src[1]).split()[0]+ if not re.match(r"^[a-z]+:", url):+ self.assertTrue((page.parent / url).is_file(), f"{page.relative_to(out)}: {url}")+def test_claude_plugin_marketplace_lists_the_plugin_at_the_repo_root(self):"""Without .claude-plugin/marketplace.json, `claude plugin install` and `claude pluginmarketplace add kajisho5/ffmpeg-skill` both fail ("not found in any configured