We set one rule for the EventConductor video series — nothing on screen may be drawn by hand — and that rule turned every chapter into a test of the real product. Recording 14 short chapters surfaced more than a dozen real defects, including one that wasn't a bug in the code at all, but in the story our examples told.

The rule: nothing drawn by hand

EventConductor is an open-source engine for business processes in Java/Spring: you declare the steps in YAML, and it handles retries, compensation, waiting for people, timers and operations. It does a lot, and a single promo video can't show it. So we made EventConductor in N minutes: 14 chapters of 2–4 minutes, one aspect each.

The series had three production rules:

  • Every screen is the product running. The admin console is recorded with Playwright; terminals show real commands with their real output; the IDE is real VS Code with the published extension.
  • Every snippet on screen compiles and is the code that produces the screen next to it. A script checks each chapter's excerpts against the repository before rendering.
  • Claims match the product. Opt-in features are called opt-in, stand-ins (a fake hotel, a demo language model) are labelled on screen, and nothing unreleased is shown as available.

The consequence we didn't plan for: if a chapter can't be recorded, something is broken. Every chapter became an end-to-end test that a human would actually watch.

What the camera caught

The recordings found real defects in the engine, the console and the IDE plugin. None of them showed up in our test suites, because each needed a person looking at the screen to notice.

Found while recording Where What was wrong Fix
An XOR join after a CHOICE Engine A step fed by a CHOICE ignored its other incoming links; the process finished silently, skipping everything after the join Every link judged on its own rule
compensateLosers race Engine If both branches finished before the join, both were winners and nothing was undone Exactly one winner, first to finish
Start right after boot Engine The REST API answered before definitions were imported, so a start returned 404 Definitions load before the web server opens
Graph editor VS Code plugin One drag on the canvas rewrote the whole YAML file, dropping comments Targeted, comment-preserving edits
Migrate dialog Console Taller than the screen: the mandatory Reason and the Preview button were below the fold Dialogs fit 720 px; dry run shown inline
Task inbox Console The Run button sat past the right edge of a 1920 px page Action column first
Operations tab Console It only appeared after a manual page reload Appears live with the first operation
Process page redraw Console After an operation the back arrow vanished and buttons reordered Redraw renders exactly like a fresh load
Help text Console "Recorded with your name" — but without a login the audit says anonymous Copy that is always true
Compensation rows, attempts, timeout routes Console item 0 instead of Room 101; retries invisible; a timeout route drawn as a false guard Labels, an Attempts column, a real timeout edge

Two more were in the shared UI framework underneath, Mateu: a page-layout cache that leaked between apps on the same port (fixed and released) and icon-only buttons with no accessible name (filed).

The worst bug was in the story

Our flagship example is a hotel booking: approve, book each room, tell the guest. To show sagas, room 900 is always sold out — and the process then cancelled the two rooms it had already booked. Automatically. That is how compensation demos usually go.

Watching it on screen, it was obviously wrong. No hotel cancels a guest's confirmed rooms because a third one is full. It tells the guest, offers an alternative, and cancels only if the guest says so. An example that undoes a customer's booking on its own doesn't sell a saga engine; it makes people afraid of one.

So the example changed, and the engine gained what it needed to tell the realistic story:

  1. The rooms step keeps what it booked when one room fails (onIterationFailure: continue).
  2. The process fetches alternatives from the hotel and asks the guest.
  3. It waits for the answer with a deadline. No answer means a reminder, then the front desk — never a cancellation.
  4. Only when the guest (or the front desk) cancels does an END with the new compensate: true undo every booked room, newest first.
- id: cancelled-by-guest type: END name: Cancelled by the guest compensate: true # undo what was booked — because the guest decided 

Compensation is the mechanism; who decides to trigger it is your business rule. Automatic all-or-nothing compensation is still there for what really is one technical unit. The same review later caught a payment-deadline example that released an unpaid room on its own; it now goes to the front desk too.

How the pipeline works

Everything lives in the repository under media/video-series, and one command renders a chapter. It is deterministic, so a script change re-renders the chapter.

  1. Narration first. Each chapter is a script of scenes with English narration. The length of each scene comes from its narration, not the other way round.
  2. Local, free voice. Kokoro runs offline with one fixed voice for the whole series. Subtitles (.srt) are generated from the same timings, in English and Spanish.
  3. Frame-by-frame capture. Playwright drives the real console with the page clock paused (clock.install + clock.pauseAt), CSS animations slowed through CDP, and one screenshot per frame at 1920×1080. ffmpeg assembles at 30 fps. No screen recorder, no dropped frames, no timing luck.
  4. Title and diagram scenes are plain HTML, rendered the same way.
  5. Source checks. Before rendering, a script verifies that every code excerpt still matches the file it claims to come from.
  6. Contact sheets. Every master is reviewed as a grid of stills before upload: cut-off content, unreadable text, blank frames, and anything that contradicts the product.

The apps run offline against a locally built engine, so what is filmed is exactly the code in the repository.

If you make product videos

  • Ban mock-ups. A drawn screen can't fail. A real one fails exactly where your users would trip.
  • Treat "can't record it" as a bug report. We never worked around the product in a video; we fixed the product and re-recorded.
  • Read your examples as a customer would. Our worst finding wasn't in the code: it was a demo that did something no business would accept.
  • Make it reproducible. A paused clock and frame-by-frame capture turn a video into a build artefact: change a line, re-render, compare.
  • Say what's a stand-in. A label on screen ("fake hotel: local stand-in", "MCP server: opt-in") costs nothing and keeps the video honest.

Most of the time on this series went into fixing the product, not into making videos. Two releases (2.42.0 and 2.42.1) shipped what the camera found.

Watch and try it