Demo Videos

View saved version →

---
name: capture-demo-video
description: Record an app or screen for a product demo, with action timing when available for cursor animations or input badges.
---

# Capture a demo video

Choose a recorder that works with the app, machine, and available permissions. For a
local screen or window, use the bundled Cirro recorder or an existing setup. For
synchronized pointer events in a supported Chromium app, use the bundled Chromium
helper. See [recorder options](references/recorders.md) for commands, platform limits,
and alternatives.

For Cirro recording, follow [Set up Cirro](../setup/SKILL.md) to prepare its launcher.

For existing footage, continue with [Create Demo Video](../create-demo-video/SKILL.md).

## Choose how to record

Try to capture action timing by default using the available recorder or input tool
journal. Read [action timing](references/action-timing.md) before recording. Include
clicks, typing, shortcuts, scrolling, and dragging when supported; pointer movement
alone does not describe those actions. Keep partial logs and note what is missing.
If logging is unavailable, continue with the recording rather than blocking the task.
Never invent events or precise timestamps.

- **Keep the original cursor:** record it as part of the video. Captions, zooms, masks,
  and speed changes do not need an event log.
- **Animate the cursor:** record without the cursor and capture synchronized pointer
  events. Use input badges only for actual keyboard events.

If reliable event timing is unavailable, keep the original recording and edit without
those effects.

## Record the story

Choose the task and result you want to show. For a before-and-after comparison, perform
the same task on both versions with comparable app state and recording settings.

Before performing the walkthrough, make a short test recording and inspect it for
permission errors, black frames, and cursor visibility. Check input permissions too
when the walkthrough needs desktop control. If access is denied, use an available
permitted alternative or tell the user which app needs which permission and where to
enable it. After access changes, repeat the test before recording the full walkthrough.

On macOS, native screen or window recording may need approved execution outside
Codex's sandbox, even when Screen Recording consent is already granted. Follow the
[macOS permission guidance](references/recorders.md#macos-permissions-and-sandboxing)
and keep the exception limited to capture commands.

Keep the recording region and scale stable. Show a readable starting
state, perform the task, and leave the result on screen long enough to understand it.
Keep failed attempts and describe what happened.

When collecting events, start logging before the first interaction and align the log
with the video. Record timing uncertainty and protect sensitive input as described in
the timing reference.

Stop and finalize the recording. Stop only processes created for it and restore
temporary settings. Check the footage for missing frames, clipped UI, and private
content.

## Hand off to editing

Keep the original video with the recording settings, task, outcome, and version under
test. Include raw logs and clock and coordinate mappings when collected. Continue with
[Create Demo Video](../create-demo-video/SKILL.md), passing only trustworthy events in
the screenplay.

Referenced files: 4

View saved version →

---
name: create-demo-video
description: Create a demo from new or existing footage, with captions, zooms, privacy masks, and optional cursor animations or input badges.
---

# Create a demo video

Use Cirro to turn a recording into a product demo. Keep the original recording and write
generated files outside tracked repository paths.

When footage is needed, use [Capture Demo Video](../capture-demo-video/SKILL.md).

Follow [Set up Cirro](../setup/SKILL.md) to prepare its launcher before editing. The
examples use the macOS/Linux launcher; pass the same arguments on Windows.
If setup fails, report the blocker; do not substitute another editing pipeline.
Use Cirro to validate and render the final screenplay, fixing validation errors
before delivering the video.

## Inspect the recording

Cirro produces VP9/WebM video without audio and can also read supported MP4 recordings.

```sh
sh /absolute/path/to/setup/scripts/cirro.sh schema
sh /absolute/path/to/setup/scripts/cirro.sh inspect /absolute/path/recording.webm --json
```

Read the schema and [editing guide](references/screenplay-contract.md). Check the
recording's dimensions, duration, interface states, and frames around important
transitions. Before choosing the trim, identify the outcomes the user's request or
session summary says the demo should show, then locate their evidence in the footage.
Keep the setup and result for those outcomes. A short demo can compress pauses without
reducing a multi-step walkthrough to its last interaction. For a failure and retry,
let the viewer recognize the failure, retained work, and eventual result.

Show the starting state, interaction, response, and result. Use short captions to
explain what's happening.

For cursor animations and input badges, use actual event logs with coordinates in
recording pixels and timestamps in milliseconds from the first video frame. Keep drag
endpoints and button metadata; map tool names only when their meaning is known.

Omit `recording.events` when logs are unavailable. The renderer then keeps any cursor in
the recording and adds no cursor animation or input badges. If the recording already has
a cursor, omit pointer events to avoid drawing a second one; reliable keyboard events
can still produce input badges. Use cursor-free footage when supplying pointer events.
Never invent events from screenshots.

Summarize ordinary typing by count. Protected typing must contain neither its value nor
its length. Review the visible interactions as well as the finished file.

## Edit the video

Keep one continuous section of the recording. Trim the beginning or end and speed up
idle time instead of adding gaps, repeats, freezes, or invented actions. Keep enough of
the opening to establish where the viewer is and what will change. Keep important
actions and their visible results, including the final success or failure, readable.
Compress idle waits aggressively, but preserve time to recognize each new state.
The renderer shows a double-chevron icon during
fast-forward and adds elapsed source time after ten seconds.

Start at full-frame zoom 1. Use a zoom only when it reveals a detail the viewer would
otherwise miss. Use a short, deliberate transition, then hold the same framing through
the action and result. Avoid a slow zoom throughout a scene or an immediate zoom-out
that competes with the action. Keep the cursor, target, and relevant result inside the
frame; show enough context to follow scrolling and movement between controls.

Highlight visible results sparingly. Inspect the target's bounds in the actual frame;
use balanced padding that separates the annotation from the UI without covering nearby
controls. Start the highlight after its target appears and end it before the target
moves or disappears. Map source times through speed changes before timing overlays.

Use ASD-STE100-inspired language for captions: short sentences, active voice, familiar
words, and one idea per caption. Explain the action or result and give each caption
enough reading time. Keep captions and input badges from overlapping each other or the important UI;
omit redundant annotations. If annotations obscure the evidence, simplify or remove
them before adding camera motion to make room. A clear, complete static edit is a
better starting point than a decorated edit that needs repeated repairs.
Recorded click events animate the cursor. Use
`edit.style.reduced_motion` when requested.

Set `edit.style.accent` to `#4a8fff` for an ordinary demonstration, `#ef6b73`
for a bug reproduction, or `#58c98a` for a verified fix. Use the video's actual
outcome to choose the color; an unresolved bug is not a verified fix.

Use `edit.cover.at_ms` to choose a frame that shows what the viewer should notice. The
cover is the first video frame; the complete story follows. Overlay and camera times
refer to the story, so do not offset them for the cover. Derive duration from clip
ranges and speeds; validate to get the exact mapped event times.

Cover private information with opaque masks in every affected frame, including the cover
and zooms. If masks would hide the behavior being demonstrated, request a clean
recording instead of sharing it.

## Validate and render

```sh
sh /absolute/path/to/setup/scripts/cirro.sh validate /absolute/path/screenplay.json --json
sh /absolute/path/to/setup/scripts/cirro.sh render /absolute/path/screenplay.json -o /absolute/path/demo.webm --json
sh /absolute/path/to/setup/scripts/cirro.sh frame /absolute/path/screenplay.json --at-ms 2000 -o /absolute/path/review.png
```

Start with 60 fps and a width near 1440 pixels, adjusted for the source dimensions and
aspect ratio. Upscaling does not add source detail. Wait for encoding to finish.

## Verify and deliver

Watch the finished video. Check that the actions and results are easy to follow. Check
frames around clicks, zooms, speed changes, masks, and the final result. Watch the opening
and ending without relying on the prompt: the viewer should understand the setup and
see the outcome, not just the last click. Make sure the cover and captions match what happened and private content stays covered. The renderer
decodes the output to check VP9/yuv420p WebM, dimensions, frame count, and timing. That
does not establish that the demo shows the task or is easy to follow.

When the user is working on a pull request, include the video in that PR using
[Share Demo Video](../share-demo-video/SKILL.md). Otherwise, show the final video using
its absolute file path. Mention any limitations in the footage.

Referenced files: 3

View saved version →

---
name: setup
description: Set up Cirro for recording or editing demo videos. Use when a demo-videos workflow needs the bundled Cirro launcher.
---

# Set up Cirro

Cirro is a command-line tool for recording screens and windows and editing recordings
into demo videos.

Use this skill's launcher. On macOS/Linux, run
`sh "/absolute/path/to/setup/scripts/cirro.sh" <command> ...`. In Windows PowerShell,
run `& "C:\absolute\path\to\setup\scripts\cirro.cmd" <command> ...`. Pass the same Cirro
arguments on either platform.

Choose one absolute path for `DEMO_VIDEOS_CACHE` from the current task's writable paths,
in this order:

1. A shared cache root, when the sandbox allows writing it (for example,
   `$XDG_CACHE_HOME`, `~/.cache`, `~/Library/Caches`, or `%LOCALAPPDATA%`).
2. An allowed temporary root, such as `$TMPDIR`, `/tmp`, or `%TEMP%`.
3. The task's writable working directory.

Use a `demo-videos-cache` subdirectory of the chosen root. On macOS/Linux set
`export DEMO_VIDEOS_CACHE="/absolute/chosen/path/demo-videos-cache"`; in PowerShell set
`$env:DEMO_VIDEOS_CACHE = "C:\absolute\chosen\path\demo-videos-cache"`. Pass the same
value to every Cirro invocation, including new shells, changed working directories, and
tests. Do not assume an OS-default cache or temp path is writable unless the active
sandbox permits it.

The launcher downloads the pinned release from the OpenAI CDN on first use. It checks
the SHA-256 of the release's `SHA256SUMS` against the skill's pin, then checks the
selected platform archive against that manifest. It caches both files and rechecks them
before every use. If `DEMO_VIDEOS_CACHE` is unset, the launcher defaults to
`.demo-videos-cache` in the working directory. Each run extracts a fresh private copy,
keeps its libraries together, and removes it on exit. A verified cache works offline. No
Python, pip, FFmpeg installation, or Node.js is needed for editing.

Supports Ubuntu 24.04-compatible Linux x64/ARM64, macOS 14+ Apple Silicon or macOS 15+
Intel, and Windows 11 x64/ARM64. macOS/Linux need curl and unzip; Windows uses system
curl and tar. First use needs HTTPS access to `persistent.oaistatic.com`. For setup
failures, report the exact error and platform; checksum errors name the cache file to
remove before retrying. Keep TLS verification and OS security policies enabled. The
macOS and Windows binaries are signed; Linux binaries have no OS publisher signature.
The launcher verifies downloaded bytes against the manifest pin, not platform
signatures.

Referenced files: 3

View saved version →

---
name: share-demo-video
description: Share demo videos on GitHub, GitLab, or another destination. Use for a single demo or a before-and-after comparison.
---

# Share a demo video

When the user is working on a PR or MR, upload and include the demo video there as part
of completing the work. For other destinations, use the one the user requested. Ask
only if the destination or audience is unclear. If the user requests only a draft,
keep it unpublished; attachments can become accessible before a comment is posted.

## Choose what to show

Use **Before / After** when both recordings show the same task on the original and
changed versions. Keep the app state, data, viewport, and pacing comparable where
possible. Explain what happened in each video and identify the versions tested. Show
failures as they occurred. Do not use an unrelated older video as the baseline.

For a new feature, or when there is no baseline, show **Result**. Explain what the video
shows and mention any important limitations. Do not add an empty Before column or imply
that a baseline exists. Separate operating systems or scenarios when that makes the
comparison easier to understand.

## Format the comparison

For two related videos, use a two-column table with the players in the same row. This
applies to Before / After, platform checks, and two workflows. Label each column for
what it shows; two different workflows are not a Before / After comparison.

```markdown
### Theme switching

| Before | After |
| --- | --- |
| Selecting Dark leaves the sidebar light. | Selecting Dark updates both panels. |
| [Watch before](BEFORE_URL) | [Watch after](AFTER_URL) |
| PLATFORM, VERSION_A | PLATFORM, VERSION_B |
```

Use verified upload URLs and describe what the videos show. GitHub attachment links in
the media row can render as players inside the cells; see the [GitHub guide](references/github.md).
For GitLab, use image Markdown with the returned upload URLs in that row. Check that
both players appear inside their cells, not below a table containing only descriptions.
If the destination does not render players in cells, keep labeled links or linked
previews in the table. Use stacked players when side-by-side viewing is unsuitable or
the user requests it, and explain that layout choice.

For a single video, use one heading, a sentence explaining the action and result, and one
player or labeled link. Add a still preview if it helps readers or provides a fallback
for an unsupported player. Host preview images where the intended audience can access
them.

## Prepare the video

Use [Create Demo Video](../create-demo-video/SKILL.md) if the recording needs editing.
Check the final video for readability and private information. Check the preview frame,
captions, audio if present, and filenames too. Keep raw footage private unless the user
asked to share it.

Prefer the plugin's VP9 `.webm` output. Keep the extension and use `video/webm` when an
upload API needs a MIME type. Check the destination's file size limit and test browser
playback. A destination that accepts WebM may not play every WebM video. Do not silently
change codecs, rename WebM to MP4, or use another host to get around a failed upload.

Choose a preview frame that shows what the viewer should notice, such as the failure in
Before or the result in After. If rendering with Cirro, set `edit.cover.at_ms` to that
frame on the story timeline. Cirro places the composed frame before the video. A codec
keyframe does not select the host's thumbnail. Check the hosted preview. If the host
chooses a different frame, use its thumbnail option or link a separate preview image if
available.

## Upload and describe

For GitHub, read [Publish to GitHub](references/github.md). For GitLab, read
[Publish to GitLab](references/gitlab.md). Use the repository's host, including its
enterprise or self-managed host. Check installed CLI help before using a flag; versions
and host capabilities differ. Use authenticated tools without printing tokens.

Use a supported attachment flow or an existing integration. For another host, check
audience access, link durability, and embedding support.

Confirm the repository or project and audience before uploading. Use a private
destination for private material. Do not assume that an externally hosted attachment is
private because the PR is private. Upload each final file once and reuse its durable
URL. Keep temporary signed URLs, credentials, local paths, and expiring CI artifacts out
of the description.

For an existing PR or MR, keep unrelated description content and follow its template. If
the user asks for a comment, post a comment. Add a short heading and explain the task,
result, and any platform or version details needed to understand the video. Say what the
viewer should notice instead of only saying “it works.”

## Check and return

Check the published page, not just the submitted Markdown. Check the players or links,
previews, table layout, and access for the intended audience. If inline playback does
not work, use a labeled link or linked preview instead of a blank player. Reuse existing
upload URLs when fixing formatting.

Return the published destination and mention any limitations. If you cannot verify
access for the intended audience, say so. If publishing is blocked or the user requested
only a draft, return the prepared files and copy-ready Markdown. Label it as a draft.

Referenced files: 3