Skip to content

A local video studio for your coding agent. Describe a video in one sentence: your agent directs, your machine renders. Claude Code, Codex, Cursor, Devin and more. No API keys, no uploads.

Guides: tutorial pictures at 2x, and each tutorial's clip as a short film (#83)

Favio Vázquezf01a4500e0bd
diff --git a/assets/readme/tutorials/first-video/01-terminal-job.webp b/assets/readme/tutorials/first-video/01-terminal-job.webp
index 497f435..9d4ba10 100644
Binary files a/assets/readme/tutorials/first-video/01-terminal-job.webp and b/assets/readme/tutorials/first-video/01-terminal-job.webp differ
diff --git a/assets/readme/tutorials/first-video/02-terminal-check.webp b/assets/readme/tutorials/first-video/02-terminal-check.webp
index a1c06b4..cc17e23 100644
Binary files a/assets/readme/tutorials/first-video/02-terminal-check.webp and b/assets/readme/tutorials/first-video/02-terminal-check.webp differ
diff --git a/assets/readme/tutorials/first-video/03-look.webp b/assets/readme/tutorials/first-video/03-look.webp
index 737233f..7cc5d66 100644
Binary files a/assets/readme/tutorials/first-video/03-look.webp and b/assets/readme/tutorials/first-video/03-look.webp differ
diff --git a/assets/readme/tutorials/first-video/04-terminal-render-qa.webp b/assets/readme/tutorials/first-video/04-terminal-render-qa.webp
index 5a4bd11..26da373 100644
Binary files a/assets/readme/tutorials/first-video/04-terminal-render-qa.webp and b/assets/readme/tutorials/first-video/04-terminal-render-qa.webp differ
diff --git a/assets/readme/tutorials/first-video/05-fix-and-pass.webp b/assets/readme/tutorials/first-video/05-fix-and-pass.webp
index 01743ad..3a99631 100644
Binary files a/assets/readme/tutorials/first-video/05-fix-and-pass.webp and b/assets/readme/tutorials/first-video/05-fix-and-pass.webp differ
diff --git a/assets/readme/tutorials/first-video/06-final.webp b/assets/readme/tutorials/first-video/06-final.webp
index 27e4bc3..0f20849 100644
Binary files a/assets/readme/tutorials/first-video/06-final.webp and b/assets/readme/tutorials/first-video/06-final.webp differ
diff --git a/assets/readme/tutorials/first-video/07-terminal-review-pack.webp b/assets/readme/tutorials/first-video/07-terminal-review-pack.webp
index 6123395..ff7fba7 100644
Binary files a/assets/readme/tutorials/first-video/07-terminal-review-pack.webp and b/assets/readme/tutorials/first-video/07-terminal-review-pack.webp differ
diff --git a/assets/readme/tutorials/first-video/08-review-sheet.webp b/assets/readme/tutorials/first-video/08-review-sheet.webp
index 6a53a14..7bac874 100644
Binary files a/assets/readme/tutorials/first-video/08-review-sheet.webp and b/assets/readme/tutorials/first-video/08-review-sheet.webp differ
diff --git a/assets/readme/tutorials/first-video/09-findings.webp b/assets/readme/tutorials/first-video/09-findings.webp
index 9bbd3ac..9433290 100644
Binary files a/assets/readme/tutorials/first-video/09-findings.webp and b/assets/readme/tutorials/first-video/09-findings.webp differ
diff --git a/assets/readme/tutorials/first-video/10-terminal-waive.webp b/assets/readme/tutorials/first-video/10-terminal-waive.webp
index 9707879..c40674a 100644
Binary files a/assets/readme/tutorials/first-video/10-terminal-waive.webp and b/assets/readme/tutorials/first-video/10-terminal-waive.webp differ
diff --git a/assets/readme/tutorials/first-video/11-receipt.webp b/assets/readme/tutorials/first-video/11-receipt.webp
index b6bf058..c29a053 100644
Binary files a/assets/readme/tutorials/first-video/11-receipt.webp and b/assets/readme/tutorials/first-video/11-receipt.webp differ
diff --git a/assets/readme/tutorials/first-video/clip.webp b/assets/readme/tutorials/first-video/clip.webp
deleted file mode 100644
index 75acd1e..0000000
Binary files a/assets/readme/tutorials/first-video/clip.webp and /dev/null differ
diff --git a/assets/readme/tutorials/studio/01-terminal-board.webp b/assets/readme/tutorials/studio/01-terminal-board.webp
index a96c4e7..098473e 100644
Binary files a/assets/readme/tutorials/studio/01-terminal-board.webp and b/assets/readme/tutorials/studio/01-terminal-board.webp differ
diff --git a/assets/readme/tutorials/studio/02-board.webp b/assets/readme/tutorials/studio/02-board.webp
index 120a7e7..9a11d0a 100644
Binary files a/assets/readme/tutorials/studio/02-board.webp and b/assets/readme/tutorials/studio/02-board.webp differ
diff --git a/assets/readme/tutorials/studio/03-compare.webp b/assets/readme/tutorials/studio/03-compare.webp
index d4906b3..b61bda9 100644
Binary files a/assets/readme/tutorials/studio/03-compare.webp and b/assets/readme/tutorials/studio/03-compare.webp differ
diff --git a/assets/readme/tutorials/studio/04-comment.webp b/assets/readme/tutorials/studio/04-comment.webp
index 3c8b28f..dab90ca 100644
Binary files a/assets/readme/tutorials/studio/04-comment.webp and b/assets/readme/tutorials/studio/04-comment.webp differ
diff --git a/assets/readme/tutorials/studio/05-feedback.webp b/assets/readme/tutorials/studio/05-feedback.webp
index b7439a1..fd90876 100644
Binary files a/assets/readme/tutorials/studio/05-feedback.webp and b/assets/readme/tutorials/studio/05-feedback.webp differ
diff --git a/assets/readme/tutorials/studio/06-terminal-digest.webp b/assets/readme/tutorials/studio/06-terminal-digest.webp
index 6f51d2e..7765612 100644
Binary files a/assets/readme/tutorials/studio/06-terminal-digest.webp and b/assets/readme/tutorials/studio/06-terminal-digest.webp differ
diff --git a/assets/readme/tutorials/studio/07-storyboard.webp b/assets/readme/tutorials/studio/07-storyboard.webp
index 2bb6902..0d6c8ff 100644
Binary files a/assets/readme/tutorials/studio/07-storyboard.webp and b/assets/readme/tutorials/studio/07-storyboard.webp differ
diff --git a/assets/readme/tutorials/studio/08-shot-note.webp b/assets/readme/tutorials/studio/08-shot-note.webp
index 909827f..e86ca69 100644
Binary files a/assets/readme/tutorials/studio/08-shot-note.webp and b/assets/readme/tutorials/studio/08-shot-note.webp differ
diff --git a/assets/readme/tutorials/studio/09-approve.webp b/assets/readme/tutorials/studio/09-approve.webp
index a0d60f9..f7402b2 100644
Binary files a/assets/readme/tutorials/studio/09-approve.webp and b/assets/readme/tutorials/studio/09-approve.webp differ
diff --git a/assets/readme/tutorials/studio/10-terminal-storyboard.webp b/assets/readme/tutorials/studio/10-terminal-storyboard.webp
index 3d997d6..c5f37cc 100644
Binary files a/assets/readme/tutorials/studio/10-terminal-storyboard.webp and b/assets/readme/tutorials/studio/10-terminal-storyboard.webp differ
diff --git a/assets/readme/tutorials/studio/11-final.webp b/assets/readme/tutorials/studio/11-final.webp
index c17ffb8..e923207 100644
Binary files a/assets/readme/tutorials/studio/11-final.webp and b/assets/readme/tutorials/studio/11-final.webp differ
diff --git a/assets/readme/tutorials/studio/clip.webp b/assets/readme/tutorials/studio/clip.webp
deleted file mode 100644
index 09bcfde..0000000
Binary files a/assets/readme/tutorials/studio/clip.webp and /dev/null differ
diff --git a/docs/guides/README.md b/docs/guides/README.md
index 6305563..0129116 100644
--- a/docs/guides/README.md
+++ b/docs/guides/README.md
@@ -2,7 +2,7 @@
Task guides for people. Each one says what to tell your coding agent, the commands it runs, the files you get,
how long it took on a named machine, the phrases that change the result, the honest limits, and an example to
-look at. A few guides are tutorials: one real run as numbered steps, a screenshot at each and a short clip at the top, then the same closing sections. The references in `skills/showtime/references/` are written for your agent; these are written for you.
+look at. A few guides are tutorials: one real run as numbered steps, a screenshot at each and a short silent film of the whole run at the top (made with showtime), then the same closing sections. The references in `skills/showtime/references/` are written for your agent; these are written for you.
| Guide | When you want |
|---|---|
diff --git a/docs/guides/first-video.md b/docs/guides/first-video.md
index 926195f..7672716 100644
--- a/docs/guides/first-video.md
+++ b/docs/guides/first-video.md
@@ -6,7 +6,8 @@ Start here if you have never used showtime. Ask for a 5-second test video: your
the video on your computer, checks it and has it reviewed. You learn that the install works, and you see every step a
bigger video goes through. This guide follows one real run, with a screenshot of each step.
-![The whole run in 23 seconds: the terminal as the job is made, the check and the first look, the first render and its qa warning, the fixed render, the finished 5-second video, the review sheet and the receipt.](../../assets/readme/tutorials/first-video/clip.webp)
+<!-- video: examples/_tutorials/first-video/clip.mp4 -->
+[![The whole run in 18 seconds, one step at a time: the terminal as the job is made, the check and the first look, the first render and its qa warning, the fixed render, the finished 5-second video, the review sheet, the findings answered and the receipt.](https://github.com/FavioVazquez/showtime-examples/raw/main/examples/_tutorials/first-video/clip.jpg)](https://faviovazquez.github.io/showtime/docs/guides/first-video.html)
## Say this
@@ -137,7 +138,9 @@ top and were not timed. More numbers: [render § Speed](../../skills/showtime/re
a video needs them, with their size shown first. The test video downloads nothing more.
- The qa output in steps 3 and 4 was printed again on the saved files for the screenshots, after the silent-film line
was in `showtime.json`, so it shows the still-hold warning only. The findings in step 7 are shortened from the
- critic's reply. Something failed? Ask your agent to run `showtime doctor`, then see [Troubleshooting](../troubleshooting.md).
+ critic's reply. The look image and the review sheet were made again at twice their size for this page: the look
+ from the finished project (the glow's drift is the only change), the sheet from the same six frames of
+ `final-3.mp4`. Something failed? Ask your agent to run `showtime doctor`, then see [Troubleshooting](../troubleshooting.md).
## The example
diff --git a/docs/guides/studio-concepts-to-final.md b/docs/guides/studio-concepts-to-final.md
index 96b126e..e849321 100644
--- a/docs/guides/studio-concepts-to-final.md
+++ b/docs/guides/studio-concepts-to-final.md
@@ -7,7 +7,8 @@ storyboard, and only then does the film get built. This guide walks through one
screenshot of each step. The video is a 20-second trailer for Tidepool, a fictional notes app that ships with showtime
as sample material.
-![The whole run in 22 seconds: the board with four concepts, a wipe between two of them, a pick and a comment, the storyboard, the approval and the finished trailer.](../../assets/readme/tutorials/studio/clip.webp)
+<!-- video: examples/_tutorials/studio/clip.mp4 -->
+[![The whole run in 18 seconds, one step at a time: the terminal as the board is built, the board with four concepts, a wipe between two of them, a comment, your agent's answer, the storyboard, the approval, then the first and last seconds of the finished trailer.](https://github.com/FavioVazquez/showtime-examples/raw/main/examples/_tutorials/studio/clip.jpg)](https://faviovazquez.github.io/showtime/docs/guides/studio-concepts-to-final.html)
## Say this
@@ -38,7 +39,7 @@ One concept is marked **Recommended**, with the reason.
The **Compare** tab puts any two concepts on one frame. Drag across it to wipe from one to the other.
-![The Compare tab: a frame split down the middle, C1 Low tide on the left with its wave line and C2 Macro on the right with the words "Sync: local only".](../../assets/readme/tutorials/studio/03-compare.webp)
+![The Compare tab: one frame split by the wipe line, C1 Low tide on the left with its wave line and the words "Q4 planning draft", and C3 Keystrokes on the right with the app's command palette.](../../assets/readme/tutorials/studio/03-compare.webp)
## 4. Pick, like and comment
@@ -66,7 +67,7 @@ Round 2 is the storyboard of the concept you picked: every shot with its time ra
how it moves. The thumbnails are rendered from the draft project at those moments. Open the **Storyboard** tab, and
use **Note** under a shot to say what to change.
-![The Storyboard tab: shot cards C2.1 to C2.5, with a sixth cut off at the right edge, each with a thumbnail, a time range such as 0:00.0 to 0:02.5, what is on screen and a Note button.](../../assets/readme/tutorials/studio/07-storyboard.webp)
+![The Storyboard tab: the first three shot cards, C2.1 to C2.3, each with a thumbnail, a time range such as 0:00.0 to 0:02.5, what is on screen, how it moves and a Note button.](../../assets/readme/tutorials/studio/07-storyboard.webp)
![A comment box on shot C2.1: Hold the first shot a beat longer.](../../assets/readme/tutorials/studio/08-shot-note.webp)
@@ -121,6 +122,7 @@ Your agent's writing of the concepts and your own time on the board come on top
- Music beds and voice samples also go on the board; this run skipped them to stay short.
- To keep the run short, the project that was rendered in step 8 is the finished project of example 09, copied to a plain
folder; the storyboard thumbnails and the final film come from it. The clicks on the board were made with a headless
- browser, the way a reviewer would make them.
+ browser, the way a reviewer would make them. The board pictures were captured again later from the same job at a
+ higher resolution, with the board and its feedback put back to each round as it was.
- The commands behind each step: [Studio mode](../../skills/showtime/references/studio.md); the board file:
[Board format](../../skills/showtime/references/boards.md).
diff --git a/site/build.py b/site/build.py
index 040eda7..303f586 100644
--- a/site/build.py
+++ b/site/build.py
@@ -469,6 +469,22 @@ class Site:
out = re.sub(r'(<(?:img|source)\b[^>]*?(?:src|srcset)="[^"]*-(?:light|dark)\.svg")', r'\1 data-themed', out)
return out
+ def guide_videos(self, body: str, page: str) -> str:
+ """A guide's film: `<!-- video: examples/....mp4 -->` over a linked poster picture (on GitHub the poster
+ links to the site page). Here the pair becomes a <video> with that poster; without the film in this build
+ the poster stays, linked to the film's own address."""
+ def video(m: "re.Match[str]") -> str:
+ local, fallback = self.media(m.group(1), m.group(1).split("/")[1])
+ poster, alt = m.group(3), m.group(4)
+ if not local:
+ return '<p><a href="%s"><img src="%s" alt="%s"></a></p>' % (esc(fallback or m.group(2)), poster, alt)
+ src = esc(rel(page, local)) # a browser that plays no video shows a link to the file instead
+ return ('<figure class="guide-video"><video controls muted loop playsinline preload="metadata" poster="%s" '
+ 'aria-label="%s"><source src="%s" type="video/mp4"><a href="%s">Watch the film (MP4)</a></video></figure>'
+ % (poster, alt, src, src))
+ return re.sub(r'<!-- video: (examples/[^ ]+\.mp4) -->\s*<p><a href="([^"]*)"><img src="([^"]*)" alt="([^"]*)"\s*/?></a></p>',
+ video, body)
+
def render_md(self, text: str, src: Path, page: str, drop_h1: bool = False) -> Tuple[str, str, List[Tuple[str, str, int]]]:
"""Markdown -> (html, title, headings[(text, id, level)])."""
env: dict = {}
@@ -493,6 +509,7 @@ class Site:
body = re.sub(r"<blockquote>\s*<p>\[!(NOTE|TIP|IMPORTANT|WARNING|CAUTION)\]\s*",
lambda m: '<blockquote class="alert"><p class="alert-title">%s</p><p>' % m.group(1).title(), body)
body = self.rewrite(body, src, page)
+ body = self.guide_videos(body, page)
body = mark_url_links(body)
body = keep_flags_whole(body)
return body, title, heads
diff --git a/site/static/style.css b/site/static/style.css
index f99c8a9..8f7963e 100644
--- a/site/static/style.css
+++ b/site/static/style.css
@@ -271,6 +271,8 @@ p{margin:0}
.prose blockquote > * + *{margin-top:.6em}
.prose .alert-title{font-size:.8rem;font-weight:600;letter-spacing:.04em;color:var(--ink);text-transform:uppercase}
.prose img{border-radius:8px;max-height:72vh;width:auto}
+.prose .guide-video{margin:1.2em 0}
+.prose .guide-video video{display:block;width:100%;height:auto;aspect-ratio:16/9;border-radius:8px;background:#15110e}
.prose picture img{border-radius:0}
.prose pre{font-size:.83rem}
.crumbs{font-size:.84rem;color:var(--muted);margin-bottom:18px}
diff --git a/skills/showtime/tests/test_site_build.py b/skills/showtime/tests/test_site_build.py
index b8de64c..7fbd57d 100644
--- a/skills/showtime/tests/test_site_build.py
+++ b/skills/showtime/tests/test_site_build.py
@@ -28,6 +28,33 @@ TESTS_DIR = Path(__file__).resolve().parent
REPO = TESTS_DIR.parents[2]
BUILD = REPO / "site" / "build.py"
+
+def image_size(p: Path) -> "tuple[int, int]":
+ """(width, height) of a WebP, JPEG or PNG file, read from its header (no imaging library needed)."""
+ b = p.read_bytes()
+ if b[:4] == b"RIFF" and b[8:12] == b"WEBP":
+ kind = b[12:16]
+ if kind == b"VP8X":
+ return 1 + int.from_bytes(b[24:27], "little"), 1 + int.from_bytes(b[27:30], "little")
+ if kind == b"VP8L":
+ bits = int.from_bytes(b[21:25], "little")
+ return 1 + (bits & 0x3FFF), 1 + ((bits >> 14) & 0x3FFF)
+ if kind == b"VP8 ":
+ return int.from_bytes(b[26:28], "little") & 0x3FFF, int.from_bytes(b[28:30], "little") & 0x3FFF
+ if b[:8] == b"\x89PNG\r\n\x1a\n":
+ return int.from_bytes(b[16:20], "big"), int.from_bytes(b[20:24], "big")
+ if b[:2] == b"\xff\xd8":
+ i = 2
+ while i < len(b) - 9:
+ if b[i] != 0xFF:
+ i += 1
+ continue
+ marker, size = b[i + 1], int.from_bytes(b[i + 2:i + 4], "big")
+ if marker in (0xC0, 0xC1, 0xC2):
+ return int.from_bytes(b[i + 7:i + 9], "big"), int.from_bytes(b[i + 5:i + 7], "big")
+ i += 2 + size
+ raise ValueError("%s: not a WebP, PNG or JPEG file" % p)
+
try:
import markdown_it # noqa: F401
spec = importlib.util.spec_from_file_location("site_build", BUILD)
@@ -256,7 +283,8 @@ class OneVersion(unittest.TestCase):
def test_tutorials_have_a_picture_for_every_step(self):
# a tutorial is a walk through one run: every numbered step has a picture with real alt text, no file is
- # missing, the clip at the top stays small, and nothing on the page names a private folder
+ # missing, every picture is sharp on a 2x screen, the film at the top is an mp4 with a poster, and nothing on
+ # the page names a private folder
guides = [p for p in sorted((REPO / "docs" / "guides").glob("*.md")) if "<!-- tutorial:" in p.read_text(encoding="utf-8")]
self.assertTrue(guides)
for guide in guides:
@@ -265,10 +293,30 @@ class OneVersion(unittest.TestCase):
self.assertGreaterEqual(len(pics), 10, guide.name)
for alt, src in pics:
self.assertGreater(len(alt), 20, src)
+ if "/examples/_tutorials/" in src:
+ continue # the film's poster lives with the examples (another repository when published)
self.assertTrue((guide.parent / src).is_file(), src)
- clip = [src for _a, src in pics if src.endswith("clip.webp")]
- self.assertEqual(len(clip), 1, guide.name)
- self.assertLess((guide.parent / clip[0]).stat().st_size, 3 * 1024 * 1024)
+ w, h = image_size(guide.parent / src)
+ # the docs column is 44rem (704 px) and a picture is at most 72% of the screen's height: on a 2x
+ # screen up to 1200 px tall it needs twice the width it is shown at; a full-column picture 2048 px
+ shown = min(704.0, 0.72 * 1200 * w / h)
+ self.assertTrue(w >= 2048 or w >= 2 * shown, "%s is %dx%d, shown up to %d px wide" % (src, w, h, shown))
+ self.assertNotIn("clip.webp", text, guide.name)
+ terms = [src for _, src in pics if "terminal" in src.rsplit("/", 1)[-1]]
+ self.assertTrue(terms, guide.name)
+ for src in terms: # terminal text stays exact: no lossy compression
+ self.assertTrue(src.endswith(".webp") and webp_is_lossless(guide.parent / src), "%s is not lossless WebP" % src)
+ film = re.findall(r"<!-- video: (examples/_tutorials/([^/]+)/clip\.mp4) -->\n\[!\[[^\]]{20,}\]\(([^)]+)\)\]\(([^)]+)\)", text)
+ self.assertEqual(len(film), 1, "%s: one film marker over its linked poster" % guide.name)
+ mp4, folder, poster, link = film[0]
+ self.assertTrue(poster.endswith("examples/_tutorials/%s/clip.jpg" % folder), poster)
+ self.assertEqual(link, "https://faviovazquez.github.io/showtime/docs/guides/%s.html" % guide.stem)
+ if (REPO / "examples").is_dir(): # the checkout that has the examples (not the published main repo)
+ clip, still = REPO / mp4, REPO / (mp4[:-len(".mp4")] + ".jpg")
+ self.assertTrue(clip.is_file() and still.is_file(), mp4)
+ self.assertEqual(clip.read_bytes()[4:8], b"ftyp", mp4)
+ self.assertEqual(clip_problems(clip), [], mp4)
+ self.assertGreaterEqual(image_size(still)[0], 2048, still.name)
for marker in ("/Users/", "/home/", "C:\\Users\\", "~/Projects"):
self.assertNotIn(marker, text, guide.name)
sections = re.split(r"^## ", text, flags=re.M)[1:]
@@ -278,6 +326,73 @@ class OneVersion(unittest.TestCase):
self.assertRegex(sec, r"!\[[^\]]{20,}\]\(", "%s: step '%s' has no picture" % (guide.name, sec.splitlines()[0]))
self.assertIn("(%s)" % guide.name, (guide.parent / "README.md").read_text(encoding="utf-8") if guide.name != "first-video.md" else "(first-video.md)")
+ def test_image_size_reads_webp_jpeg_and_png(self):
+ out = Path(tempfile.mkdtemp(prefix="st-imgsize-"))
+ try:
+ vp8l = b"RIFF" + (21).to_bytes(4, "little") + b"WEBPVP8L" + (9).to_bytes(4, "little") + b"\x2f" + \
+ ((2999) | (1999 << 14)).to_bytes(4, "little") + b"\0" * 4
+ (out / "a.webp").write_bytes(vp8l)
+ (out / "b.jpg").write_bytes(b"\xff\xd8\xff\xe0\x00\x04ab\xff\xc0\x00\x11\x08" + (1080).to_bytes(2, "big") + (1920).to_bytes(2, "big") + b"\x03")
+ (out / "c.png").write_bytes(b"\x89PNG\r\n\x1a\n\x00\x00\x00\x0dIHDR" + (640).to_bytes(4, "big") + (360).to_bytes(4, "big"))
+ self.assertEqual(image_size(out / "a.webp"), (3000, 2000))
+ self.assertEqual(image_size(out / "b.jpg"), (1920, 1080))
+ self.assertEqual(image_size(out / "c.png"), (640, 360))
+ finally:
+ shutil.rmtree(out, ignore_errors=True)
+
+ def test_the_spec_checks_catch_a_lossy_terminal_and_an_off_spec_film(self):
+ # synthetic files: a film that meets the spec passes; 720p, an audio track, 24 fps, 25 s and a lossy
+ # terminal picture each fail
+ out = Path(tempfile.mkdtemp(prefix="st-spec-"))
+
+ def box(kind: bytes, payload: bytes) -> bytes:
+ return (8 + len(payload)).to_bytes(4, "big") + kind + payload
+
+ def trak(handler: bytes, w: int, h: int, scale: int, frames: int, delta: int) -> bytes:
+ tkhd = b"\0" * 76 + (w << 16).to_bytes(4, "big") + (h << 16).to_bytes(4, "big")
+ mdhd = b"\0" * 12 + scale.to_bytes(4, "big") + (frames * delta).to_bytes(4, "big") + b"\0" * 4
+ hdlr = b"\0" * 8 + handler + b"\0" * 13
+ stts = b"\0" * 4 + (1).to_bytes(4, "big") + frames.to_bytes(4, "big") + delta.to_bytes(4, "big")
+ return box(b"trak", box(b"tkhd", tkhd) + box(b"mdia", box(b"mdhd", mdhd) + box(b"hdlr", hdlr)
+ + box(b"minf", box(b"stbl", box(b"stts", stts)))))
+
+ def mp4(name: str, *traks: bytes) -> Path:
+ (out / name).write_bytes(box(b"ftyp", b"isom" + b"\0" * 4) + box(b"moov", b"".join(traks)))
+ return out / name
+ try:
+ good = trak(b"vide", 1920, 1080, 15360, 540, 512)
+ self.assertEqual(clip_problems(mp4("good.mp4", good)), [])
+ self.assertEqual(clip_problems(mp4("720.mp4", trak(b"vide", 1280, 720, 15360, 540, 512))), ["is 1280x720, not 1920x1080"])
+ self.assertEqual(clip_problems(mp4("audio.mp4", good, trak(b"soun", 0, 0, 48000, 846, 1024))), ["has an audio track"])
+ self.assertEqual(clip_problems(mp4("24.mp4", trak(b"vide", 1920, 1080, 12288, 432, 512))), ["runs at 24.00 fps, not 30"])
+ self.assertEqual(clip_problems(mp4("25s.mp4", trak(b"vide", 1920, 1080, 15360, 750, 512))), ["lasts 25.0 s, not 15-20 s"])
+ chunk = lambda kind, data: kind + len(data).to_bytes(4, "little") + data + b"\0" * (len(data) & 1)
+ riff = lambda body: b"RIFF" + (4 + len(body)).to_bytes(4, "little") + b"WEBP" + body
+ (out / "l.webp").write_bytes(riff(chunk(b"VP8L", b"\x2f" + b"\0" * 8)))
+ (out / "x.webp").write_bytes(riff(chunk(b"VP8X", b"\0" * 10) + chunk(b"VP8L", b"\x2f" + b"\0" * 8)))
+ (out / "q.webp").write_bytes(riff(chunk(b"VP8 ", b"\0" * 10)))
+ self.assertTrue(webp_is_lossless(out / "l.webp"))
+ self.assertTrue(webp_is_lossless(out / "x.webp"))
+ self.assertFalse(webp_is_lossless(out / "q.webp"))
+ finally:
+ shutil.rmtree(out, ignore_errors=True)
+
+ def test_a_guide_film_becomes_a_video_with_its_poster(self):
+ # the marker over a linked poster becomes a <video> when the film is in the build, else the poster stays
+ site = build.Site.__new__(build.Site)
+ html_in = ('<!-- video: examples/_tutorials/t/clip.mp4 -->\n<p><a href="https://example.org/t.html">'
+ '<img src="../../a/examples/_tutorials/t/clip.jpg" alt="The whole run"></a></p>\n<p>next</p>')
+ site.media = lambda repo_rel, folder: ("media/_tutorials/t/clip.mp4", "https://github.com/x/y/blob/main/" + repo_rel)
+ got = site.guide_videos(html_in, "docs/guides/t.html")
+ self.assertIn('<video controls muted loop playsinline preload="metadata" poster="../../a/examples/_tutorials/t/clip.jpg" '
+ 'aria-label="The whole run"><source src="../../media/_tutorials/t/clip.mp4" type="video/mp4">'
+ '<a href="../../media/_tutorials/t/clip.mp4">Watch the film (MP4)</a></video>', got)
+ self.assertIn("<p>next</p>", got)
+ site.media = lambda repo_rel, folder: (None, "https://github.com/x/y/blob/main/" + repo_rel)
+ got = site.guide_videos(html_in, "docs/guides/t.html")
+ self.assertNotIn("<video", got)
+ self.assertIn('<a href="https://github.com/x/y/blob/main/examples/_tutorials/t/clip.mp4"><img src="../../a/examples/_tutorials/t/clip.jpg"', got)
+
def test_landing_anchors_are_of_open_sections(self):
# a heading is linked to the section it is in, never to one that closed before it
out = Path(tempfile.mkdtemp(prefix="st-anchor-"))
@@ -293,6 +408,84 @@ class OneVersion(unittest.TestCase):
shutil.rmtree(out, ignore_errors=True)
+def webp_is_lossless(p: Path) -> bool:
+ """True when a WebP holds its picture as VP8L (lossless) and has no lossy VP8 chunk."""
+ b, ids, i = p.read_bytes(), [], 12
+ if b[:4] != b"RIFF" or b[8:12] != b"WEBP":
+ return False
+ while i + 8 <= len(b):
+ n = int.from_bytes(b[i + 4:i + 8], "little")
+ ids.append(b[i:i + 4])
+ i += 8 + n + (n & 1)
+ return b"VP8L" in ids and b"VP8 " not in ids
+
+
+def mp4_tracks(p: Path) -> "list[dict]":
+ """Each track of an MP4 file: its handler (vide, soun), width and height (tkhd), timescale and duration (mdhd)
+ and frame count and ticks (stts), read from the boxes with no media tool."""
+ b, tracks = p.read_bytes(), []
+
+ def boxes(lo: int, hi: int):
+ while lo + 8 <= hi:
+ n, kind, head = int.from_bytes(b[lo:lo + 4], "big"), b[lo + 4:lo + 8], 8
+ if n == 1:
+ n, head = int.from_bytes(b[lo + 8:lo + 16], "big"), 16
+ elif n == 0:
+ n = hi - lo
+ if n < head:
+ return
+ yield kind, lo + head, lo + n
+ lo += n
+
+ def walk(lo: int, hi: int, t: dict) -> None:
+ for kind, s, e in boxes(lo, hi):
+ v = b[s]
+ if kind == b"trak":
+ tracks.append({})
+ walk(s, e, tracks[-1])
+ elif kind in (b"moov", b"mdia", b"minf", b"stbl"):
+ walk(s, e, t)
+ elif kind == b"tkhd":
+ o = s + (88 if v == 1 else 76)
+ t["w"], t["h"] = int.from_bytes(b[o:o + 4], "big") >> 16, int.from_bytes(b[o + 4:o + 8], "big") >> 16
+ elif kind == b"mdhd":
+ o = s + (20 if v == 1 else 12)
+ n = 8 if v == 1 else 4
+ t["timescale"], t["duration"] = int.from_bytes(b[o:o + 4], "big"), int.from_bytes(b[o + 4:o + 4 + n], "big")
+ elif kind == b"hdlr":
+ t["handler"] = b[s + 8:s + 12].decode("latin-1")
+ elif kind == b"stts":
+ pairs = [(int.from_bytes(b[s + 8 + 8 * k:s + 12 + 8 * k], "big"), int.from_bytes(b[s + 12 + 8 * k:s + 16 + 8 * k], "big"))
+ for k in range(int.from_bytes(b[s + 4:s + 8], "big"))]
+ t["frames"], t["ticks"] = sum(c for c, _ in pairs), sum(c * d for c, d in pairs)
+
+ walk(0, len(b), {})
+ return tracks
+
+
+def clip_problems(p: Path) -> "list[str]":
+ """What keeps a tutorial film from the media spec: one 1920x1080 video track at about 30 fps, no audio,
+ 15-20 s long, under 8 MiB. Empty when it meets it."""
+ out, tracks = [], mp4_tracks(p)
+ vids = [t for t in tracks if t.get("handler") == "vide"]
+ if any(t.get("handler") == "soun" for t in tracks):
+ out.append("has an audio track")
+ if len(vids) != 1:
+ return out + ["has %d video tracks" % len(vids)]
+ v = vids[0]
+ if (v.get("w"), v.get("h")) != (1920, 1080):
+ out.append("is %sx%s, not 1920x1080" % (v.get("w"), v.get("h")))
+ fps = v["timescale"] * v["frames"] / v["ticks"] if v.get("ticks") else 0
+ if abs(fps - 30) > 0.5:
+ out.append("runs at %.2f fps, not 30" % fps)
+ secs = v["duration"] / v["timescale"] if v.get("timescale") else 0
+ if not 15 <= secs <= 20:
+ out.append("lasts %.1f s, not 15-20 s" % secs)
+ if p.stat().st_size >= 8 * 1024 * 1024:
+ out.append("is %.1f MiB, not under 8" % (p.stat().st_size / 1048576))
+ return out
+
+
class PeoplePages(unittest.TestCase):
"""The pages written for people (What's new, the FAQ), the counts, and links to examples without a card."""