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.
Python agent-skillsai-agentscaptionsclaude-codeclaude-code-pluginclaude-skillscodexcursorexplainer-videoffmpegheadless-chromekokoro-ttslocal-firstmanimmcp-servermotion-graphicstext-to-speechvideovideo-editingvideo-generation
Adopted Python renders: frames drawn on a canvas (no black or late first frames on a busy machine)
Favio Vázquez954419d9d0de
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 78e66ca..3e4b537 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -49,6 +49,14 @@ through an HTTP proxy, `.env` files unreadable), plus a Windows race the push CIdimmed before it was spoken, was measured at that opacity (#e9b949 on #17120e came out at 2.98:1 instead of10.18:1). Caption words are judged at the caption's own opacity, and any text measured at partial opacity is namedwith it (`#e9b949 at 45% opacity (shows as #765d29) on #17120e`). Real low contrast still fails.+- **An adopted Python render could open on black frames, or show each frame late, on a busy machine.** Chrome+ puts a paused `<video>`'s seeked frame on screen through the video's own compositor submission and skips it while+ the previous one is still unacknowledged; the frame then goes out only at the next seek, so the capture showed the+ frame before (black for the first two frames on the Intel Mac runner). `seeked` and `requestVideoFrameCallback` both+ fire before that submission, so 0.3.4's wait could not see it. In renders the stage now draws a video's frame on a+ `<canvas data-st-video="ID">` and hides the video (a canvas is captured with the rest of the page), and `showtime+ adopt` writes its frames page that way (re-adopt, or `--refresh`, to update an existing one). `test_adopt` checks+ that every frame of the Python render shows its own time.- **A finished background run on Windows could show as "lost", with no id or command.** Windows refuses to open afile another process is replacing, so `status` and the run's supervisor could collide on `run.json`; thesupervisor's failed read then rewrote the file with only its new fields. Reads and replaces now retry for up to 2 s,diff --git a/skills/showtime/references/stage-api.md b/skills/showtime/references/stage-api.mdindex 3db2112..4a6c6e6 100644--- a/skills/showtime/references/stage-api.md+++ b/skills/showtime/references/stage-api.md@@ -40,11 +40,11 @@ a determinism, timing or seek problem.| Minimal page | 56-91 || Configuration | 93-109 || Clips: data-start / data-dur | 111-151 |-| API: Library helpers (built-in adapters), <video> in a page | 153-218 |-| Determinism: what the render mode does and what to avoid | 220-251 |-| Readiness | 253-258 |-| Preview mode | 260-272 |-| Scene transitions with shaders (layer protocol) | 274-280 |+| API: Library helpers (built-in adapters), <video> in a page | 153-224 |+| Determinism: what the render mode does and what to avoid | 226-257 |+| Readiness | 259-264 |+| Preview mode | 266-278 |+| Scene transitions with shaders (layer protocol) | 280-286 |## The one rule@@ -205,6 +205,12 @@ Every `<video>` is paused, muted and seeked to the middle of the right source frfps if it differs from the video's), `data-st="off"` (leave it alone). Its clock is its own`data-start`, else the nearest clip's.+A `<canvas data-st-video="ID">` styled like `<video id="ID">` (same box, same `object-fit`) gets that+video's frame drawn on it in renders, and the video is hidden; in the preview it stays empty. Use it+for a video that is the whole picture: on a busy or slow machine Chrome can put a paused video's+seeked frame on screen after the capture (the frame before, or nothing for the first one), while a+canvas is captured with the rest of the page. `showtime adopt` writes its pages this way.+- Use **VP9/WebM** (or AV1) for footage inside pages: Chromium builds without proprietary codecs(Playwright's Chromium, some Linux packages) cannot decode H.264. Convert with`showtime footage trim in.mp4 --webm --no-audio -o media/clip.webm` (never bare ffmpeg).diff --git a/skills/showtime/runtime/stage.js b/skills/showtime/runtime/stage.jsindex f87a822..5bcb410 100644--- a/skills/showtime/runtime/stage.js+++ b/skills/showtime/runtime/stage.js@@ -497,12 +497,37 @@continue;}if (!v.paused) v.pause();- if (Math.abs(v.currentTime - target) < 1e-4 && v.readyState >= 2 && !v.seeking) continue;+ if (Math.abs(v.currentTime - target) < 1e-4 && v.readyState >= 2 && !v.seeking) { drawVideoCanvas(v); continue; }if (MODE !== 'render') { v.currentTime = target; continue; }- waits.push(race(seekOne(v, t), 15000, 'video seek ' + key).catch(function (e) { diag.videos[key] = e.message; }));+ waits.push(seekVideo(v, t, key));}return waits;}+ function seekVideo(v, t, key) {+ return race(seekOne(v, t), 15000, 'video seek ' + key)+ .then(function () { drawVideoCanvas(v); }, function (e) { diag.videos[key] = e.message; });+ }+ // <canvas data-st-video="ID">: in render mode the frame of <video id="ID"> is drawn on this canvas+ // and the video is hidden. Chrome puts a paused video's new frame on screen through a compositor+ // submission of the video's own, and skips it while its previous one is still unacknowledged (a busy+ // or slow machine): the capture then shows the frame before, or nothing for the first one, although+ // 'seeked' and requestVideoFrameCallback have fired. A canvas is in the page's own frame, which the+ // capture waits for. For a video that is the whole picture (the page `showtime adopt` writes).+ function videoCanvas(v) {+ if (MODE !== 'render' || !v.id) return null;+ var cs = document.querySelectorAll('canvas[data-st-video]');+ for (var i = 0; i < cs.length; i++) if (cs[i].getAttribute('data-st-video') === v.id) return cs[i];+ return null;+ }+ function drawVideoCanvas(v) {+ var c = videoCanvas(v);+ if (!c || v.readyState < 2 || !v.videoWidth) return;+ try {+ if (c.width !== v.videoWidth || c.height !== v.videoHeight) { c.width = v.videoWidth; c.height = v.videoHeight; }+ c.getContext('2d').drawImage(v, 0, 0, c.width, c.height);+ if (v.style.visibility !== 'hidden') v.style.visibility = 'hidden';+ } catch (e) { reportError('video canvas #' + v.id, e); }+ }// A video that appeared after the page loaded (added by a handler, a new src) has no data yet: a// seek set then does nothing (no 'seeked' ever comes) and the frame shows nothing. Load it first.function videoData(v) {@@ -528,8 +553,11 @@// 'seeked' comes before the new frame reaches the compositor: a capture right after it can// still show the previous frame (black for the first one) on a slow machine. The wait also// takes the frame being presented (requestVideoFrameCallback, which fires after every seek of- // a file with a picture), or 500 ms after 'seeked' if it never comes.+ // a file with a picture), or 500 ms after 'seeked' if it never comes. It fires when the frame is+ // the player's current one, not when it is on screen (see data-st-video); a canvas draws the current+ // one, so a video drawn on a canvas waits for it longer.var seeked = false, shown = typeof v.requestVideoFrameCallback !== 'function' || !v.videoWidth, timer = null;+ var exact = !shown && !!videoCanvas(v);function end() {real.clearTimeout(timer);v.removeEventListener('seeked', done); v.removeEventListener('error', end); res();@@ -538,7 +566,8 @@function done() {if (v.seeking) return;seeked = true;- if (shown) end(); else if (!timer) timer = real.setTimeout(end, 500);+ // a canvas-drawn video waits longer (2 s) for its frame callback; never forever, in case a browser never calls it+ if (shown) end(); else if (!timer) timer = real.setTimeout(end, exact ? 2000 : 500);}if (!shown) v.requestVideoFrameCallback(function () { shown = true; if (seeked) end(); });v.addEventListener('seeked', done);diff --git a/skills/showtime/scripts/adopt.mjs b/skills/showtime/scripts/adopt.mjsindex 9d7e8f0..2fe2aa3 100644--- a/skills/showtime/scripts/adopt.mjs+++ b/skills/showtime/scripts/adopt.mjs@@ -812,9 +812,11 @@ async function adoptPython(ctx, kind) {<!-- written by \`showtime adopt\`: frames drawn by ${entry.replace(/--!?>/g, '')} (${mode === 'frames' ? `${fnName}()` : 'its own main'}), played frame-exactly --><html><head><meta charset="utf-8"><title>${escapeHtml(path.basename(entry))}</title><script src="/_st/stage.js"></script>-<style>html,body{margin:0;background:#000;overflow:hidden}#frames{position:absolute;inset:0;width:100%;height:100%;object-fit:contain}</style>+<style>html,body{margin:0;background:#000;overflow:hidden}#frames,#frames-still{position:absolute;inset:0;width:100%;height:100%;object-fit:contain}</style></head><body><video id="frames" src="media/frames.webm" data-start="0" muted playsinline preload="auto"></video>+<!-- renders draw each frame here (data-st-video): a paused video's own frame can reach the capture late -->+<canvas id="frames-still" data-st-video="frames"></canvas></body></html>`;fs.writeFileSync(path.join(dest, 'index.html'), index);diff --git a/skills/showtime/tests/test_adopt.py b/skills/showtime/tests/test_adopt.pyindex 17d8153..4a6e958 100644--- a/skills/showtime/tests/test_adopt.py+++ b/skills/showtime/tests/test_adopt.py@@ -11,9 +11,10 @@ Fixtures (tests/fixtures/adopt/), written the way a model writes them with no toFast (no browser): the Python harness (static scan, frame function pick, bytes frames, the two-orderhash that catches state kept between frames, the network guard) and the static page/driver scan.Full: every fixture adopted into a project; contract, size, fps and length as expected; the original-folder byte-identical afterwards; determinism measured; `check` clean; `render --from/--to`; `snap`-shows the injected data (setup script); `export html`; a nondeterministic page and a missing setup-fail with what/why/fix; `--refresh` picks up an edited original.+folder byte-identical afterwards; determinism measured; `check` clean; a Python render shows every+frame at its own time (none black, none late: renders draw the video on a canvas); `render --from/--to`;+`snap` shows the injected data (setup script); `export html`; a nondeterministic page and a missing+setup fail with what/why/fix; `--refresh` picks up an edited original.usage: python tests/test_adopt.py [--fast] [-v]"""@@ -49,6 +50,14 @@ def tearDownModule():shutil.rmtree(TMP, ignore_errors=True)+def video_rows(video, y, width=640):+ """Pixel row y of every frame of a video, as RGB bytes."""+ from st import ff+ raw = subprocess.run([ff.ffmpeg_path(), "-v", "error", "-i", str(video), "-vf", "format=rgb24,crop=%d:1:0:%d" % (width, y),+ "-f", "rawvideo", "-pix_fmt", "rgb24", "-"], stdout=subprocess.PIPE, check=True).stdout+ return [raw[i:i + 3 * width] for i in range(0, len(raw), 3 * width)]++def showtime(*args, check=True, cwd=None, timeout=900):cp = subprocess.run([sys.executable, str(LAUNCHER)] + [str(a) for a in args], env=ENV, cwd=cwd,stdout=subprocess.PIPE, stderr=subprocess.PIPE, encoding="utf-8",@@ -259,9 +268,18 @@ class Adopt(unittest.TestCase):self.assertEqual(rep["determinism"]["verdict"], "deterministic")self.assertTrue((out / "media" / "frames.webm").exists())self.assertFalse(list((FIX / "python-pil").glob("*.mp4")), "the original folder got a video")+ self.assertIn('<canvas id="frames-still" data-st-video="frames">', (out / "index.html").read_text())showtime("render", out, "-o", TMP / "pil.mp4")q = showtime("qa", TMP / "pil.mp4", "--project", out, "--json", check=False)self.assertIn(json.loads(q.stdout)["verdict"], ("PASS", "WARN"), q.stdout[-2000:])+ # every frame is the one drawn for its time, not the one before (or black): the progress bar is+ # 520 * t / 2 px long (10.8 px a frame) and the box crosses row 180 from frame 0+ bars = video_rows(TMP / "pil.mp4", 306)+ self.assertEqual(len(bars), 48)+ shown = [round(sum(1 for x in range(640) if r[3 * x + 1] > 120 and r[3 * x] < 120) / (520 / 48)) for r in bars]+ self.assertEqual(shown, list(range(48)), "frame k shows the bar of frame shown[k]")+ box = video_rows(TMP / "pil.mp4", 180)[0]+ self.assertGreater(sum(1 for x in range(640) if box[3 * x] > 200 and box[3 * x + 2] < 120), 80, "frame 0 has no box")def test_python_capture(self):cp, out, rep = self.adopt("python-capture")