:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
feat(skills): zoom demo videos, fix truncation and draw a real pointer (#119415)
Harley Alexanderd7707260780f
diff --git a/.agents/skills/recording-demo-videos/SKILL.md b/.agents/skills/recording-demo-videos/SKILL.mdindex a8ddc6423722..871792a6802d 100644--- a/.agents/skills/recording-demo-videos/SKILL.md+++ b/.agents/skills/recording-demo-videos/SKILL.md@@ -5,10 +5,10 @@ description: >PostHog stack, for a Loom, a Slack demo, or a PR. Use when asked to record a video, demo,walkthrough, or Loom of a change end to end, including flows that leave the app, such as an APIcall shown as a terminal card or an email arriving in the local inbox. The recorder drives the- real app with Playwright, adds RoundHog captions, a cursor, hedgehog stickers, and an optional- ElevenLabs voiceover and music bed, frames the video with title and end cards that carry the logo and a hedgehog- from @posthog/brand, and cuts loading time out. For a short animated WebP of one interaction in a- PR description, use the reel mode of qa-frontend.+ real app, zooms in on the beats the storyboard marks, adds RoundHog+ captions, a pointer, hedgehog stickers, and an optional ElevenLabs voiceover and music bed, and+ frames the video with title and end cards that carry the logo and a hedgehog from @posthog/brand.+ For a short animated WebP of one interaction in a PR description, use the reel mode of qa-frontend.---# Recording demo videos@@ -17,12 +17,14 @@ A demo video shows a feature working, from the first click to the proof that itThe recorder drives the real app on the local stack, so what the viewer sees is what the code does.It writes a short MP4, usually under a minute, a contact sheet of frames to review, and a log.-The output looks like this: a title card with the logo and a hedgehog, the app with a caption bar and a cursor for each step, terminal cards for API calls, and an end card.-Waits for page loads and data are cut, so the video moves at reading speed.+The output looks like this: a title card with the logo and a hedgehog, the app with a caption bar and a pointer that glides to each click, terminal cards for API calls, and an end card.+Page loads stay out of the video, so it moves at reading speed.+A step can also zoom in on the button it clicks or on the detail it proves.A voiceover can read the captions, a music bed can sit under it, and a step can pop in a hedgehog sticker with a short sound.Use [qa-frontend](../qa-frontend/SKILL.md) instead for a reel: a short animated WebP of one interaction, made from stills, for a PR description.For a narrated or musical promo video, see [hogreel](references/branding.md#promo-videos).+For a raw take with no captions or narration, frame-perfect at 60 fps, PostHog staff can use `recording-web-demos` from the team skills store (`skill-get` in the PostHog MCP). It steps the page clock frame by frame, so it never judders.## Workflow@@ -78,6 +80,7 @@ A demo that drags loses the viewer. Keep it short, and keep it moving.- Keep captions under ten words. A long caption holds its step longer, and a long voiceover line holds it longer still.- Leave `hold` unset. The defaults hold a caption for about a quarter of a second per word, at least one and a half seconds. With a voiceover, a step waits for its line to finish.- Set `hold` only to give a sticker time to land or to make a navigation step shorter. Keep it at two seconds or less.+- Zoom on the two to five beats that matter: the key click, and the detail that proves it worked. A zoom on every step makes the video seasick.For a voiceover or music, add `voiceover` or `music` to the storyboard.They need an ElevenLabs API key in `ELEVENLABS_API_KEY`. Do not ask the developer to paste the key into the chat.@@ -95,7 +98,7 @@ uv run python .agents/skills/recording-demo-videos/scripts/record_demo.py path/tThe script logs in, loads every page once to warm the dev server, then records.It writes `<output>.mp4`, `<output>.sheet.png` and `<output>.log.json` next to the storyboard.-When a step fails, it writes `<output>.error.png` and `<output>.failed.webm` instead and exits non-zero. The log names the step.+When a step fails, it writes `<output>.error.png` and exits non-zero. The log names the step.### 5. Review, then record againdiff --git a/.agents/skills/recording-demo-videos/references/branding.md b/.agents/skills/recording-demo-videos/references/branding.mdindex 30eee438a20c..96fa6fd78122 100644--- a/.agents/skills/recording-demo-videos/references/branding.md+++ b/.agents/skills/recording-demo-videos/references/branding.md@@ -21,7 +21,7 @@ Use them in PostHog's own videos only.These come from brand.posthog.com and the brand handbook. The recorder follows them. Keep to them when you write a storyboard.- **Logo**: the full-color logo goes on light backgrounds only, and the white logo on dark ones. Do not recolor, stretch or animate it, and never set "PostHog" in text next to the logomark.-- **Colors**: tangerine (`#FF5C1C`) is the accent, on the card bar, the caption edge and the cursor. A scene leans on two or three colors. Stage backgrounds are solid: cream (`#F4F3EE`) or dark (`#1D1F27`).+- **Colors**: tangerine (`#FF5C1C`) is the accent, on the card bar, the caption edge and the click ring. A scene leans on two or three colors. Stage backgrounds are solid: cream (`#F4F3EE`) or dark (`#1D1F27`).- **Type**: RoundHog in its brand weights: 500 Medium, 700 SemiBold, 800 Bold. There is no 600. Headings are sentence case.- **Hedgehogs**: official art only. Never use AI-generated hedgehogs, and never edit one. Pick a hog that makes the card's point, not one that only fills space.diff --git a/.agents/skills/recording-demo-videos/references/storyboard.md b/.agents/skills/recording-demo-videos/references/storyboard.mdindex 896b21279430..503e27245fc7 100644--- a/.agents/skills/recording-demo-videos/references/storyboard.md+++ b/.agents/skills/recording-demo-videos/references/storyboard.md@@ -50,6 +50,7 @@ A `card` or `http` step does only that.| `wait_for` | A target that must be visible. In a `goto` step it waits after the load, otherwise after the action. The wait is cut from the video, so wait on real content, not on a fixed time || `say` | The voiceover line for the step, when it should differ from the caption. `""` keeps the step silent || `sticker` | A hedgehog that pops in once the action is done: `{ "hog": "mailbox", "text": "You've got mail", "position": "bottom-right", "seconds": 3 }`. Positions: `bottom-right`, `bottom-left`, `top-right`, `top-left` |+| `zoom` | `true` frames the clicked or typed-in target until just after the action. `{ "target": …, "level": 1.6 }` frames a detail once it is on screen, for the rest of the step. See [Zoom](#zoom) || `hold` | Seconds to stay on the result. Default: a quarter of a second per caption word, at least 1.5. With a voiceover, half a second, and the step always waits for its line to finish. Usually leave it unset || `card` | A full-screen card mid-video, with the same fields as `title` || `http` | A terminal card that types out a curl command, sends the request, and shows the response. See below |@@ -90,6 +91,18 @@ The video masks secret values in all the text it shows, including the response bIt cannot mask what a `type` step types into the app or what the app itself shows, so never type a secret in a demo.With `expect_status`, any other status fails the recording, so a broken call never ends up in a finished video.+## Zoom++A step with `zoom` moves the camera in, and the camera eases back out when the step ends.+Captions, stickers and cards stay put, because they are drawn over the zoomed frame.+A zoom upscales the recorded page, so zoomed text is a little soft. Keep zooms to about 1.5x when text has to be read.++- `"zoom": true` frames what the step clicks or types into, from the moment the pointer heads for it until about half a second after the action. The page usually changes after a click, so the camera does not stay.+- `"zoom": { "target": { "selector": "[data-attr=draft-tag]" }, "level": 1.8 }` frames something the step produced, such as a new tag, a count or a table row, from when it is on screen to the end of the step.++Without `level`, the zoom fills about half the view with the target, between 1.25x and 2x.+Pick two to five beats in a video. The key click and the proof are usually enough.+## Voiceover`voiceover` narrates the video with ElevenLabs.diff --git a/.agents/skills/recording-demo-videos/scripts/layers.py b/.agents/skills/recording-demo-videos/scripts/layers.pynew file mode 100644index 000000000000..a1394d021c87--- /dev/null+++ b/.agents/skills/recording-demo-videos/scripts/layers.py@@ -0,0 +1,183 @@+"""The camera and overlay pass for a storyboard with zooms.++The page is recorded without captions or stickers. This pass zooms the camera toward the steps that ask for it, then+draws the captions and stickers over the zoomed frame, so they stay put while the page moves under them.+Every time in the timeline is in seconds of the recording clock.+"""++import io+import math+import subprocess+from collections.abc import Iterable+from pathlib import Path+from types import ModuleType+from typing import Any++from PIL import Image+from playwright.sync_api import sync_playwright++# A zoom frames its target to fill about this share of the view, within these levels.+ZOOM_FILL = 0.55+ZOOM_MIN, ZOOM_MAX = 1.25, 2.0+# The camera eases toward its target with this time constant, in seconds.+CAMERA_EASE = 0.45+# A click zoom stays this long after the action. The page usually changes after a click.+ZOOM_AFTER_ACTION = 0.6+++def render_overlays(+ rd: ModuleType, brand: Any, timeline: dict[str, Any], viewport: dict[str, int], out_width: int+) -> tuple[dict[str, tuple[Image.Image, tuple[int, int]]], list[dict[str, Any]]]:+ """Caption and sticker images at the output size, from the same HTML and CSS as the in-page overlay."""+ scale = out_width / viewport["width"]+ dark, cream, accent = brand.colors["dark"], brand.colors["cream"], brand.colors["tangerine"]+ captions: dict[str, tuple[Image.Image, tuple[int, int]]] = {}+ stickers: list[dict[str, Any]] = []+ with sync_playwright() as pw:+ browser = pw.chromium.launch()+ page = browser.new_page(viewport=viewport, device_scale_factor=scale)+ for caption in timeline["captions"]:+ text = caption["text"]+ if not text or text in captions:+ continue+ page.set_content(+ f"""<!doctype html><html><head><style>{brand.font_css} html,body{{margin:0;background:transparent}}+#c{{position:fixed;left:50%;bottom:32px;transform:translateX(-50%);max-width:1080px;padding:14px 24px;border-radius:10px;+border-left:6px solid {accent};background:{dark}ee;color:{cream};font:700 21px/1.35 RoundHog,-apple-system,Inter,sans-serif;+box-shadow:0 10px 30px rgba(0,0,0,.25)}}</style></head><body><div id="c"></div></body></html>"""+ )+ page.evaluate("t => { document.getElementById('c').textContent = t }", text)+ page.evaluate("document.fonts.ready")+ image = Image.open(io.BytesIO(page.screenshot(omit_background=True))).convert("RGBA")+ box = image.getbbox()+ if box:+ captions[text] = (image.crop(box), (box[0], box[1]))+ for sticker in timeline["stickers"]:+ position = rd.STICKER_POSITIONS.get(+ sticker.get("position", "bottom-right"), rd.STICKER_POSITIONS["bottom-right"]+ )+ label = (+ f'<div id="l" style="background:{accent};color:#fff;font:800 22px RoundHog,-apple-system,sans-serif;'+ 'padding:6px 16px;border-radius:999px;transform:rotate(-4deg);box-shadow:0 6px 16px rgba(0,0,0,.2)"></div>'+ if sticker.get("text")+ else ""+ )+ page.set_content(+ f"""<!doctype html><html><head><style>{brand.font_css} html,body{{margin:0;background:transparent}}</style>+</head><body><div id="s" style="position:fixed;{position};display:flex;flex-direction:column;align-items:center;gap:6px;+padding:16px"><img src="{brand.hog(sticker.get("hog", "star"))}" style="width:190px;height:190px;object-fit:contain;+filter:drop-shadow(0 8px 14px rgba(0,0,0,.22))">{label}</div></body></html>"""+ )+ if sticker.get("text"):+ page.evaluate("t => { document.getElementById('l').textContent = t }", sticker["text"])+ page.evaluate("document.fonts.ready")+ element = page.locator("#s")+ box = element.bounding_box() or {"x": 0, "y": 0, "width": 0, "height": 0}+ stickers.append(+ {+ **sticker,+ "image": Image.open(io.BytesIO(element.screenshot(omit_background=True))).convert("RGBA"),+ "cx": (box["x"] + box["width"] / 2) * scale,+ "cy": (box["y"] + box["height"] / 2) * scale,+ }+ )+ browser.close()+ return captions, stickers+++def _ease_out_back(t: float, s: float = 1.7) -> float:+ t -= 1+ return t * t * ((s + 1) * t + s) + 1+++def _sticker_frame(sticker: dict[str, Any], t: float) -> tuple[Image.Image, int, int] | None:+ """The sticker at time t: it pops in, holds, then shrinks away. Matches the in-page sticker."""+ u = t - sticker["at"]+ seconds = sticker.get("seconds", 3)+ if u < 0 or u > seconds + 0.35:+ return None+ if u < 0.42:+ k = _ease_out_back(u / 0.42)+ scale, angle, alpha = 0.2 + 0.8 * k, -14 + 19 * k, min(u / 0.2, 1)+ elif u < seconds:+ scale, angle, alpha = 1.0, 5.0, 1.0+ else:+ k = (u - seconds) / 0.3+ scale, angle, alpha = 1 - 0.4 * k, 5 + 7 * k, max(1 - k, 0)+ image = sticker["image"]+ resized = image.resize((max(int(image.width * scale), 1), max(int(image.height * scale), 1)), Image.BICUBIC)+ rotated = resized.rotate(-angle, Image.BICUBIC, expand=True)+ if alpha < 1:+ rotated.putalpha(rotated.getchannel("A").point(lambda value: int(value * alpha)))+ return rotated, int(sticker["cx"] - rotated.width / 2), int(sticker["cy"] - rotated.height / 2)+++def compose(+ rd: ModuleType,+ brand: Any,+ frames: Iterable[tuple[float, Image.Image]],+ timeline: dict[str, Any],+ viewport: dict[str, int],+ out_width: int,+ fps: int,+ output: Path,+) -> None:+ """Zoom, then draw the overlays, frame by frame, and encode the result.++ `frames` gives the time of each frame that goes into the video and the frame itself, in page coordinates at any+ scale. The camera moves only on these frames, so a zoom never finishes inside a cut and jumps.+ """+ vw, vh = viewport["width"], viewport["height"]+ out_h = round(out_width * vh / vw / 2) * 2+ captions, stickers = render_overlays(rd, brand, timeline, viewport, out_width)+ encoder = subprocess.Popen(+ ["ffmpeg", "-y", "-loglevel", "error", "-f", "rawvideo", "-pix_fmt", "rgb24", "-s", f"{out_width}x{out_h}",+ "-r", str(fps), "-i", "-", "-c:v", "libx264", "-preset", "medium", "-crf", "18", "-pix_fmt", "yuv420p",+ "-movflags", "+faststart", str(output)],+ stdin=subprocess.PIPE,+ ) # fmt: skip+ assert encoder.stdin is not None+ cards, zooms = timeline["cards"], timeline["zooms"]+ caption_events = timeline["captions"]+ ease = 1 - math.exp(-(1 / fps) / CAMERA_EASE)+ z, cx, cy = 1.0, vw / 2, vh / 2+ for t, frame in frames:+ on_card = any(card["from"] <= t < card["to"] for card in cards)+ active = next((zoom for zoom in zooms if zoom["from"] <= t <= zoom["to"]), None)+ if active and not on_card:+ box = active["box"]+ fill = min(vw * ZOOM_FILL / max(box["width"], 1), vh * ZOOM_FILL / max(box["height"], 1))+ target_z = active["level"] or min(max(fill, ZOOM_MIN), ZOOM_MAX)+ tx, ty = box["x"] + box["width"] / 2, box["y"] + box["height"] / 2+ else:+ target_z, tx, ty = 1.0, vw / 2, vh / 2+ z += (target_z - z) * ease+ cx += (tx - cx) * ease+ cy += (ty - cy) * ease+ if on_card:+ # A card is a scene change, so the next page starts from the full view.+ z, cx, cy = 1.0, vw / 2, vh / 2+ w, h = vw / z, vh / z+ left = min(max(cx - w / 2, 0), vw - w)+ top = min(max(cy - h / 2, 0), vh - h)+ k = frame.width / vw+ if z > 1.001 or frame.size != (out_width, out_h):+ # A fractional box resamples the frame, so a slow zoom or pan never steps by whole pixels. Outside a zoom,+ # a frame already at the output size needs no resampling, which keeps the pass quick.+ box = (left * k, top * k, (left + w) * k, (top + h) * k)+ frame = frame.resize((out_width, out_h), Image.LANCZOS, box=box)+ shown = [event for event in caption_events if event["at"] <= t]+ if shown and shown[-1]["text"] in captions and not on_card:+ image, at = captions[shown[-1]["text"]]+ fade = min((t - shown[-1]["at"]) / 0.15, 1)+ if fade < 1:+ image = image.copy()+ image.putalpha(image.getchannel("A").point(lambda value, f=fade: int(value * f)))+ frame.paste(image, at, image)+ for sticker in stickers:+ drawn = _sticker_frame(sticker, t)+ if drawn:+ frame.paste(drawn[0], (drawn[1], drawn[2]), drawn[0])+ encoder.stdin.write(frame.tobytes())+ encoder.stdin.close()+ encoder.wait()diff --git a/.agents/skills/recording-demo-videos/scripts/record_demo.py b/.agents/skills/recording-demo-videos/scripts/record_demo.pyindex 8637b596368e..2f1941d45380 100644--- a/.agents/skills/recording-demo-videos/scripts/record_demo.py+++ b/.agents/skills/recording-demo-videos/scripts/record_demo.py@@ -12,6 +12,7 @@ import osimport reimport sysimport json+import mathimport timeimport base64import shutil@@ -19,11 +20,14 @@ import asyncioimport hashlibimport tempfileimport subprocess+from collections.abc import Iteratorfrom pathlib import Pathfrom typing import Any+import layersimport requests-from playwright.async_api import BrowserContext, Locator, Page, async_playwright+from PIL import Image+from playwright.async_api import BrowserContext, FloatRect, Locator, Page, async_playwrightDEFAULT_VIEWPORT = {"width": 1440, "height": 900}FIRST_LOAD_TIMEOUT_MS = 300_000@@ -160,7 +164,7 @@ def overlay_script(brand: Brand, hide_selectors: list[str], hide_text: list[str]"hideText": hide_text,}return (- "(() => { const C = "+ "(() => { if (window.top !== window) return; const C = "+ json.dumps(config)+ r""";// Hidden from the first frame of every page, before the app renders them.@@ -174,10 +178,13 @@ def overlay_script(brand: Brand, hide_selectors: list[str], hide_text: list[str]const ensure = () => {if (!document.body || document.getElementById('__demo_cursor')) return;if (C.fontCss) { const s = document.createElement('style'); s.textContent = C.fontCss; document.head.appendChild(s); }+ // A pointer arrow drawn larger than life, so it reads in a scaled-down video. The tip is the hotspot.const cursor = document.createElement('div'); cursor.id = '__demo_cursor';- cursor.style.cssText = 'position:fixed;left:0;top:0;width:22px;height:22px;margin:-11px 0 0 -11px;border-radius:50%;'- + 'background:' + C.accent + '55;border:2px solid ' + C.accent + ';z-index:2147483647;pointer-events:none;'- + 'transition:transform .08s;transform:translate(-100px,-100px)';+ cursor.style.cssText = 'position:fixed;left:0;top:0;width:34px;height:34px;margin:-3px 0 0 -6px;z-index:2147483647;'+ + 'pointer-events:none;transform-origin:6px 3px;transition:transform .08s;transform:translate(-100px,-100px)';+ cursor.innerHTML = '<svg viewBox="0 0 24 24" width="34" height="34" style="filter:drop-shadow(0 2px 3px rgba(0,0,0,.35))">'+ + '<path d="M5.5 3.2v16.1l4.2-4.1 2.7 6.2 2.6-1.1-2.7-6.1h5.9z" fill="#111" stroke="#fff" stroke-width="1.6" '+ + 'stroke-linejoin="round"/></svg>';document.body.appendChild(cursor);const cap = document.createElement('div'); cap.id = '__demo_caption';cap.style.cssText = 'position:fixed;left:50%;bottom:32px;transform:translateX(-50%);max-width:1080px;padding:14px 24px;'@@ -185,11 +192,22 @@ def overlay_script(brand: Brand, hide_selectors: list[str], hide_text: list[str]+ 'font:700 21px/1.35 RoundHog,-apple-system,Inter,sans-serif;z-index:2147483646;pointer-events:none;'+ 'text-align:left;box-shadow:0 10px 30px rgba(0,0,0,.25);display:none';document.body.appendChild(cap);- let x = -100, y = -100, s = 1;+ let x = window.__demoCursorAt ? window.__demoCursorAt[0] : -100;+ let y = window.__demoCursorAt ? window.__demoCursorAt[1] : -100;+ let s = 1;const paint = () => { cursor.style.transform = `translate(${x}px,${y}px) scale(${s})`; };- document.addEventListener('mousemove', e => { x = e.clientX; y = e.clientY; paint(); }, true);- document.addEventListener('mousedown', () => { s = 0.7; paint(); }, true);- document.addEventListener('mouseup', () => { s = 1; paint(); }, true);+ paint();+ window.__demoMoveCursor = (nx, ny) => { x = nx; y = ny; paint(); };+ window.__demoClick = (cx, cy) => {+ s = 0.85; paint(); setTimeout(() => { s = 1; paint(); }, 140);+ const ring = document.createElement('div');+ ring.style.cssText = 'position:fixed;left:' + cx + 'px;top:' + cy + 'px;width:40px;height:40px;'+ + 'margin:-20px 0 0 -20px;border-radius:50%;border:3px solid ' + C.accent + ';z-index:2147483646;pointer-events:none;'+ + 'transform:scale(.3);opacity:.9;transition:transform .45s ease-out,opacity .45s ease-out';+ document.body.appendChild(ring);+ requestAnimationFrame(() => requestAnimationFrame(() => { ring.style.transform = 'scale(1.4)'; ring.style.opacity = '0'; }));+ setTimeout(() => ring.remove(), 500);+ };};const hide = () => {for (const sel of C.hideSelectors) document.querySelectorAll(sel).forEach(el => { el.style.display = 'none'; });@@ -231,6 +249,7 @@ def card_html(brand: Brand, heading: str, subheading: str, hog: str, dark: boollogo = brand.logos.get("white" if dark else "color", "")hog_img = f'<img src="{hog}" style="width:340px;height:340px;object-fit:contain">' if hog else ""return f"""<!doctype html><html><head><style>{brand.font_css}+#__demo_cursor{{display:none!important}}body{{margin:0;height:100vh;background:{bg};color:{fg};font-family:RoundHog,-apple-system,Inter,sans-serif;display:flex;align-items:center;justify-content:center;overflow:hidden}}.logo{{position:absolute;top:44px;left:56px;width:180px}}@@ -244,6 +263,7 @@ p{{font-weight:500;font-size:28px;line-height:1.35;margin:0;opacity:.8}}def terminal_html(brand: Brand, title: str) -> str:return f"""<!doctype html><html><head><style>{brand.font_css}+#__demo_cursor{{display:none!important}}body{{margin:0;height:100vh;background:{brand.colors["dark"]};color:#d4d4d4;font:17px/1.6 Menlo,Consolas,monospace}}.logo{{position:absolute;top:36px;right:48px;width:140px;opacity:.9}}.title{{font:700 26px RoundHog,-apple-system,sans-serif;color:{brand.colors["cream"]};margin-bottom:24px}}@@ -414,6 +434,11 @@ class Recorder:self.pop: Path | None = Noneself.voice_log: list[dict[str, Any]] = []self.base = Path(".")+ self.mouse: tuple[float, float] = (720.0, 450.0)+ # With a zoom in the storyboard, captions and stickers are drawn after the camera pass, so they don't zoom.+ self.layered = any("zoom" in step for step in storyboard["steps"])+ self.timeline: dict[str, list[dict[str, Any]]] = {"captions": [], "stickers": [], "cards": [], "zooms": []}+ self.last_box: FloatRect | None = Nonedef now(self) -> float:return time.monotonic() - self.t0@@ -436,6 +461,11 @@ class Recorder:await asyncio.sleep(0.1)async def sticker(self, page: Page, spec: dict[str, Any]) -> None:+ if self.layered:+ self.timeline["stickers"].append({**spec, "at": self.now(), "text": self.vars.shown(spec.get("text", ""))})+ if self.pop:+ self.sounds.append((self.video_now() + 0.05, self.pop))+ returnposition = STICKER_POSITIONS.get(spec.get("position", "bottom-right"), STICKER_POSITIONS["bottom-right"])await page.evaluate("([src, label, pos, seconds]) => window.__sticker && window.__sticker(src, label, pos, seconds)",@@ -449,12 +479,18 @@ class Recorder:if self.pop:self.sounds.append((self.video_now() + 0.05, self.pop))- async def waited(self, coro: Any, keep: float = CUT_KEEP_SECONDS) -> None:+ async def show(self, page: Page, html: str) -> None:+ await page.set_content(html)+ await page.evaluate(+ "document.fonts.ready.then(() => new Promise(r => requestAnimationFrame(() => requestAnimationFrame(r))))"+ )++ async def waited(self, coro: Any, keep: float = CUT_KEEP_SECONDS, shortest: float = 0.4, tail: float = 0.2) -> None:start = self.now()await coroend = self.now()- if end - start > keep + 0.4:- self.cuts.append((round(start + keep, 2), round(end - 0.2, 2)))+ if end - start > keep + shortest:+ self.cuts.append((round(start + keep, 2), round(end - tail, 2)))def url(self, path: str) -> str:path = self.vars.real(path)@@ -476,15 +512,48 @@ class Recorder:return loc.nth(target.get("nth", 0))async def caption(self, page: Page, text: str) -> None:+ if self.layered:+ self.timeline["captions"].append({"at": self.now(), "text": self.vars.shown(text)})+ returnawait page.evaluate("t => window.__caption && window.__caption(t)", self.vars.shown(text))async def glide(self, page: Page, loc: Locator) -> None:await loc.wait_for(state="visible", timeout=STEP_TIMEOUT_MS)await loc.scroll_into_view_if_needed()box = await loc.bounding_box()+ self.last_box = boxif box:- await page.mouse.move(box["x"] + box["width"] / 2, box["y"] + box["height"] / 2, steps=25)- await asyncio.sleep(0.25)+ await self.move_mouse(page, box["x"] + box["width"] / 2, box["y"] + box["height"] / 2)+ await asyncio.sleep(0.2)++ async def move_mouse(self, page: Page, x: float, y: float) -> None:+ # Ease in and out along a slight arc, over a time that grows with the distance, like a hand moves.+ x0, y0 = self.mouse+ distance = math.hypot(x - x0, y - y0)+ frames = max(8, min(36, int(distance / 28)))+ bend = min(distance * 0.08, 40)+ for i in range(1, frames + 1):+ t = i / frames+ eased = 4 * t**3 if t < 0.5 else 1 - (-2 * t + 2) ** 3 / 2+ arc = math.sin(math.pi * eased) * bend+ await page.mouse.move(x0 + (x - x0) * eased, y0 + (y - y0) * eased - arc)+ await page.evaluate(+ "([x, y]) => window.__demoMoveCursor && window.__demoMoveCursor(x, y)",+ [x0 + (x - x0) * eased, y0 + (y - y0) * eased - arc],+ )+ await asyncio.sleep(1 / FPS)+ self.mouse = (x, y)++ async def click_effect(self, page: Page) -> None:+ await page.evaluate("([x, y]) => window.__demoClick && window.__demoClick(x, y)", list(self.mouse))++ async def restore_cursor(self, page: Page) -> None:+ # A new page starts without a pointer. Put it back where it was, so it does not jump in from a corner.+ x, y = self.mouse+ await page.evaluate(+ "([x, y]) => { window.__demoCursorAt = [x, y]; window.__demoMoveCursor && window.__demoMoveCursor(x, y); }",+ [x, y],+ )async def log_in(self, context: BrowserContext) -> None:login = self.sb.get("login", {"email": "[email protected]", "password": "12345678"})@@ -506,6 +575,11 @@ class Recorder:await page.close()async def card(self, page: Page, spec: dict[str, Any], key: str, dark: bool = False) -> None:+ start = self.now()+ await self._card(page, spec, key, dark)+ self.timeline["cards"].append({"from": start, "to": self.now()})++ async def _card(self, page: Page, spec: dict[str, Any], key: str, dark: bool = False) -> None:html = card_html(self.brand,self.vars.shown(spec.get("heading", "")),@@ -513,12 +587,18 @@ class Recorder:self.brand.hog(spec.get("hog")),dark=dark,)- await page.set_content(html)+ # The video runs a little behind the clock, so the cut runs past the moment the card is ready.+ await self.waited(self.show(page, html), keep=0, shortest=0.05, tail=-0.3)self.speak(key)await asyncio.sleep(spec.get("hold", 1.0 if self.voice else 2.5))await self.finish_speaking()async def http(self, page: Page, spec: dict[str, Any], key: str) -> None:+ start = self.now()+ await self._http(page, spec, key)+ self.timeline["cards"].append({"from": start, "to": self.now()})++ async def _http(self, page: Page, spec: dict[str, Any], key: str) -> None:method = spec.get("method", "POST").upper()shown_url, real_url = self.url(self.vars.shown(spec["url"])), self.url(spec["url"])headers = spec.get("headers", {})@@ -530,7 +610,12 @@ class Recorder:lines.append(' -H "Content-Type: application/json" \\')lines.append(f" -d '{json.dumps(self.vars.shown(body), indent=2)}'")command = "\n".join(lines).rstrip(" \\")- await page.set_content(terminal_html(self.brand, self.vars.shown(spec.get("title", ""))))+ await self.waited(+ self.show(page, terminal_html(self.brand, self.vars.shown(spec.get("title", "")))),+ keep=0,+ shortest=0.05,+ tail=-0.3,+ )self.speak(key)await page.evaluate("""async (t) => { const el = document.getElementById('cmd');@@ -561,6 +646,11 @@ class Recorder:await asyncio.sleep(spec.get("hold", 1.5 if self.voice else 3))await self.finish_speaking()+ async def load(self, page: Page, step: dict[str, Any]) -> None:+ await page.goto(self.url(step["goto"]), timeout=FIRST_LOAD_TIMEOUT_MS)+ if "wait_for" in step:+ await self.locate(page, step["wait_for"]).wait_for(timeout=STEP_TIMEOUT_MS)+async def step(self, page: Page, step: dict[str, Any], key: str) -> None:if "card" in step:await self.card(page, step["card"], key)@@ -569,12 +659,13 @@ class Recorder:await self.http(page, step["http"], key)returnif "goto" in step:- await self.waited(page.goto(self.url(step["goto"]), timeout=FIRST_LOAD_TIMEOUT_MS), keep=0.2)- if "wait_for" in step and "goto" in step:- await self.waited(self.locate(page, step["wait_for"]).wait_for(timeout=STEP_TIMEOUT_MS), keep=0.2)+ await self.waited(self.load(page, step), keep=0)+ await self.restore_cursor(page)if "caption" in step:await self.caption(page, step["caption"])self.speak(key)+ self.last_box = None+ acting = self.now()if "scroll" in step:await page.mouse.wheel(0, step["scroll"])await asyncio.sleep(0.6)@@ -583,25 +674,39 @@ class Recorder:if "click" in step:loc = self.locate(page, step["click"])await self.glide(page, loc)+ await self.click_effect(page)await loc.click()if "type" in step:spec = step["type"]if "target" in spec:loc = self.locate(page, spec["target"])await self.glide(page, loc)+ await self.click_effect(page)await loc.click()for key in spec.get("keys", []):name, _, times = key.partition(" x")for _ in range(int(times or 1)):await page.keyboard.press(name)await page.keyboard.type(self.vars.real(spec.get("text", "")), delay=spec.get("delay_ms", 80))+ acted = self.now()if "wait_for" in step and "goto" not in step:await self.waited(self.locate(page, step["wait_for"]).wait_for(timeout=STEP_TIMEOUT_MS))+ zoom = step.get("zoom")+ detail = None+ if zoom is True and self.last_box:+ box, until = self.last_box, acted + layers.ZOOM_AFTER_ACTION+ self.timeline["zooms"].append({"from": acting, "to": until, "box": box, "level": None})+ elif isinstance(zoom, dict) and "target" in zoom:+ target = self.locate(page, zoom["target"])+ await self.waited(target.wait_for(state="visible", timeout=STEP_TIMEOUT_MS))+ detail = {"from": self.now(), "box": await target.bounding_box(), "level": zoom.get("level")}if "sticker" in step:await self.sticker(page, step["sticker"])default_hold = 0.5 if self.voice else max(1.5, len(step.get("caption", "").split()) * 0.25)await asyncio.sleep(step.get("hold", default_hold))await self.finish_speaking()+ if detail and detail["box"]:+ self.timeline["zooms"].append({**detail, "to": self.now()})async def run(self, output: Path) -> dict[str, Any]:viewport = self.sb.get("viewport", DEFAULT_VIEWPORT)@@ -657,15 +762,36 @@ class Recorder:if self.voice_log:log["voice"] = self.voice_logif raw_video and "error" not in log:+ source, cuts, duration = raw_video, self.cuts, log["duration"]+ if self.layered:+ # The camera and overlay pass cuts the video itself, so the encode below only adds the sound.+ source = output.with_suffix(".camera.mp4")+ frames = _kept_frames(raw_video, self.cuts, duration, viewport)+ # The overlay pass renders with Playwright's sync API, which can't run inside this event loop.+ await asyncio.to_thread(+ layers.compose,+ sys.modules[__name__],+ self.brand,+ frames,+ self.timeline,+ viewport,+ viewport["width"],+ FPS,+ source,+ )+ cuts, duration = [], duration_of(source)+ log["zooms"] = len(self.timeline["zooms"])encode(- raw_video,+ source,output,- self.cuts,- log["duration"],+ cuts,+ duration,self.sounds,self.sb["music"] if "music" in self.sb else None,self.base,)+ if source != raw_video:+ source.unlink()contact_sheet(output)elif raw_video:shutil.copy(raw_video, output.with_suffix(".failed.webm"))@@ -673,6 +799,32 @@ class Recorder:return log+def _kept_frames(+ raw: Path, cuts: list[tuple[float, float]], duration: float, viewport: dict[str, int]+) -> Iterator[tuple[float, Image.Image]]:+ """The frames of the raw take that stay in the video, with their time on the recording clock."""+ width, height = viewport["width"], viewport["height"]+ decode = subprocess.Popen(+ ["ffmpeg", "-loglevel", "error", "-i", str(raw), "-vf", f"fps={FPS},scale={width}:{height}",+ "-f", "rawvideo", "-pix_fmt", "rgb24", "-"],+ stdout=subprocess.PIPE,+ ) # fmt: skip+ assert decode.stdout is not None+ size = width * height * 3+ index = 0+ while chunk := decode.stdout.read(size):+ if len(chunk) < size:+ break+ t = index / FPS+ index += 1+ if t > duration + 0.5:+ break+ if not any(start <= t <= end for start, end in cuts):+ yield t, Image.frombytes("RGB", (width, height), chunk)+ decode.stdout.close()+ decode.wait()++def music_track(spec: dict[str, Any], seconds: float, base: Path) -> Path:"""A music bed at least `seconds` long: a file from the storyboard, or one generated by ElevenLabs Music."""if "file" in spec:@@ -751,7 +903,8 @@ def encode(else:chains.append("[front]anull[mixed]")# -16 LUFS, the usual level for web video, so it plays as loud as other videos in Slack or Loom.- chains.append("[mixed]loudnorm=I=-16:TP=-1.5:LRA=11[aout]")+ # apad keeps the audio running to the end of the video, so -shortest never cuts the video short.+ chains.append("[mixed]loudnorm=I=-16:TP=-1.5:LRA=11,apad[aout]")graph = ";".join(chains)subprocess.run([@@ -816,7 +969,9 @@ def main() -> None:output = (storyboard_path.parent / storyboard.get("output", "demo.mp4")).resolve()output.parent.mkdir(parents=True, exist_ok=True)values = {**os.environ, **storyboard.get("vars", {})}- recorder = Recorder(storyboard, Brand(repo_root), Vars(values, storyboard.get("secrets", [])))+ variables = Vars(values, storyboard.get("secrets", []))+ brand = Brand(repo_root)+ recorder = Recorder(storyboard, brand, variables)recorder.base = storyboard_path.parentlog = asyncio.run(recorder.run(output))if skipped: