Record a demo

A demo shows the screen behavior for each acceptance criterion as its own chapter. A spoken line says what happens. The chapter lists the checks the recording ran. Each chapter is an ordinary video artifact. It is the video proof for its criterion, so no proof rule changes. A chapter with a failed check is never bound to its criterion. You record the demo in three steps:

Write a Playwright test with @outerlayer/playwright.
Run the test. It writes a video and a manifest.
Run outerlayer emit demo on the manifest.

Demos cover browser apps. A runner build image has everything the command needs. On your own machine, install ffmpeg and espeak-ng first.

Write the test

Install the package next to your Playwright setup. It needs @playwright/test 1.50 or later.

npm install --save-dev @outerlayer/playwright

Import test and expect from the package, not from @playwright/test. Add one demo.chapter for each criterion.

import { expect, test } from "@outerlayer/playwright";

test("a member signs in", async ({ page, demo }) => {
  await page.goto("/login");

  await demo.chapter("LOGIN-01", "Sign in", "The member signs in and lands on the dashboard.", async () => {
    await page.getByLabel("Email").fill("member@example.com");
    await page.getByRole("button", { name: "Sign in" }).click();
    await expect(page.getByRole("heading", { name: "Dashboard" })).toBeVisible();
  });
});

demo.chapter(criterionId, title, narration, body) takes these arguments:

Argument	Meaning
`criterionId`	The id of a recorded criterion. Use `null` for an opening scene.
`title`	A short name for the chapter.
`narration`	The line spoken over the chapter. Use an empty string for no speech.
`body`	The steps of the chapter.

The chapter starts when body starts and ends when body ends. Each expect that runs inside body is recorded as a check of the chapter. A failed expect fails the test, as it does without this package. The failed check is still in the manifest. Follow these rules for chapters:

Give each criterion one chapter.
Put a chapter with no criterion first. Only the first chapter may have none.
Keep the narration short. The speech must end before its chapter does. See Fit the narration.
Do not use a viewport larger than you need. A clip over 8 MiB is refused.

Run the test

Run the test as usual.

npx playwright test

The package turns video recording on. When the test ends, its output folder holds a demo folder with two files:

File	Content
`video.webm`	The recording of the whole test.
`manifest.json`	The chapters, in order. Each has its criterion, start and end in seconds, title, narration and checks.

Emit the demo

Run the command on the manifest.

outerlayer emit demo test-results/<test folder>/demo/manifest.json --item 412

The command does these steps:

It checks the manifest, the video and the programs it needs. It refuses here, before it uploads anything.
It turns each narration line into speech on your machine.
It cuts the video into one clip for each chapter. Each clip is WebM with VP9 video and Opus audio.
It emits each clip as a video artifact.
It emits the manifest as the demo record, with the artifact id of each clip added.

A chapter whose checks all passed is bound to its criterion. A chapter with a failed check, and a chapter with no criterion, is stored with no criterion bound. When a chapter has a failed check, the command stores everything and then exits 1. It names the chapter and the failed check. Fix the app, record again and run the command again. You can run the command again with the same manifest, video, item and pull request. This also applies after an upload failed part way. A clip that is already stored keeps its artifact id, and the command does not store it a second time. Inside a recorded session, the clips and the record are queued. They upload on the next outerlayer sync. Outside a session they upload at once. The full flags are in outerlayer emit demo.

Fit the narration

Speech starts 0.2 seconds into its chapter and ends at least 0.2 seconds before the chapter ends. Speech that is too long for its chapter is sped up, to at most 1.3 times. Speech that is still too long makes the command refuse. It names the chapter and says by how many seconds the line is too long. To fix a refusal, shorten the line or lengthen the chapter. The command never stretches the video.

Install the programs

The command runs ffmpeg and espeak-ng as separate programs. ffprobe comes with ffmpeg. A narrated run needs both. A run with --no-narration needs only ffmpeg.

Linux

Use your package manager.

# Debian and Ubuntu
sudo apt-get install ffmpeg espeak-ng

# Fedora
sudo dnf install ffmpeg espeak-ng

# Alpine
sudo apk add ffmpeg espeak-ng

On Fedora, ffmpeg comes from the RPM Fusion repository. See the Fedora documentation to enable it.

macOS

Use Homebrew.

brew install ffmpeg espeak-ng

Windows

Install ffmpeg with winget, then install eSpeak NG from its Windows installer.

winget install Gyan.FFmpeg

Download the eSpeak NG installer from the eSpeak NG releases page. Open a new terminal after both installs. Then check that each program is on PATH.

ffmpeg -version
espeak-ng --version

If a command is not found, add its folder to PATH. The ffmpeg folder is the bin folder of the winget package. The eSpeak NG folder is C:\Program Files\eSpeak NG.

Download the voice pack

The first narrated run downloads the voice pack to ~/.outerlayer/voice/. It is about 400 MB. It holds the Kokoro-82M speech model, one voice and the ONNX Runtime that runs the model. The command shows progress and resumes a broken download. The command checks every file of the pack against a pinned sha256 on each narrated run. When a file does not match, the command refuses and names the file. Delete that file to download it again. After the first run, narration needs no network, no account and no key. To work offline from the start, set OUTERLAYER_VOICE_MIRROR to the address of a server that holds the pack files. The pinned hashes still apply to every file the mirror serves.

Skip the narration

Pass --no-narration to store silent clips.

outerlayer emit demo test-results/<test folder>/demo/manifest.json --no-narration

This needs no espeak-ng and no voice pack. It downloads nothing.

Run in a build

The runner build image holds ffmpeg, espeak-ng and the voice pack. A build records and narrates a demo with no network and nothing else to install. The evidence skill tells an agent to record a demo for the criteria whose behavior shows on screen. See also: Prove the work, outerlayer emit demo.

Get started

Connect

Work on an item

Configure a repository

Run builds

Security and privacy

Operate

Write the test

Run the test

Emit the demo

Fit the narration

Install the programs

Linux

macOS

Windows

Download the voice pack

Skip the narration

Run in a build

​Write the test

​Run the test

​Emit the demo

​Fit the narration

​Install the programs

​Linux

​macOS

​Windows

​Download the voice pack

​Skip the narration

​Run in a build

Write the test

Run the test

Emit the demo

Fit the narration

Install the programs

Linux

macOS

Windows

Download the voice pack

Skip the narration

Run in a build