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.

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.md
index 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 CI
dimmed before it was spoken, was measured at that opacity (#e9b949 on #17120e came out at 2.98:1 instead of
10.18:1). Caption words are judged at the caption's own opacity, and any text measured at partial opacity is named
with 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 a
file another process is replacing, so `status` and the run's supervisor could collide on `run.json`; the
supervisor'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.md
index 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 fr
fps 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.js
index 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.mjs
index 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.py
index 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 to
Fast (no browser): the Python harness (static scan, frame function pick, bytes frames, the two-order
hash 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")