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:
- The rooms step keeps what it booked when one room fails (
onIterationFailure: continue). - The process fetches alternatives from the hotel and asks the guest.
- It waits for the answer with a deadline. No answer means a reminder, then the front desk — never a cancellation.
- Only when the guest (or the front desk) cancels does an
ENDwith the newcompensate: trueundo 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.
- 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.
- 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. - 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. - Title and diagram scenes are plain HTML, rendered the same way.
- Source checks. Before rendering, a script verifies that every code excerpt still matches the file it claims to come from.
- 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
- The series: EventConductor in N minutes — 14 chapters, English, subtitles in English and Spanish
- Start with Chapter 1: EventConductor in 3 minutes or the saga chapter, When a room can't be booked: the guest decides
- Docs and the hands-on workshop: eventconductor.mateu.io
- Code (open source, MIT): github.com/miguelperezcolom/eventconductor — the video pipeline is in
media/video-series - Latest release: v2.42.1