Product demo videos, generated from a JSON file. No screen recorder, no video editor.
You describe what to show. It opens the site in a clean headless browser, glides an animated cursor,
clicks, types, zooms into what matters, drops captions, reads them aloud in a synthesized voice,
adds click and keystroke sounds over a music bed, and writes a finished .mp4.
Читать по-русски: docs/i18n/README.ru.md - подробное пошаговое руководство.
The GIF above was produced by silky-recorder itself, from scenarios/wikipedia-en.json.
Product demos rot. You ship a redesign, and every tutorial video you own is suddenly wrong. Re-recording them means booting a screen recorder, doing a flawless take, and editing - for each one, every release. So teams quietly stop updating them.
silky-recorder makes a demo an artifact of your repository instead of a one-off performance:
- The scenario is a text file. It lives in git, gets reviewed in pull requests, and diffs like code.
- Re-recording is one command. UI changed? Run it again. No take, no edit, no timeline.
- It runs headless. Recording happens in the background - keep using your machine.
- It runs in CI. Regenerate every demo on release and never ship a stale one again - see Running in CI.
Requires Node.js 18+.
git clone https://github.com/harlamenko/silky-recorder
cd silky-recorder
npm install # also fetches a Chromium build, ~1-3 min, first time onlynpm run record scenarios/wikipedia-en.jsonYou get out/demo-en.mp4. That is the whole loop.
Two parts: meta for global settings, steps for what happens, in order.
{
"meta": {
"title": "How to find an article",
"url": "https://en.wikipedia.org/wiki/Main_Page",
"auth": { "type": "none" },
"out": "out/demo.mp4"
},
"steps": [
{ "type": "title", "text": "How to find an article", "hold": 2500 },
{ "type": "caption", "text": "Type your query", "read": 2500 },
{ "type": "click", "target": "input[name=\"search\"]" },
{ "type": "type", "target": "input[name=\"search\"]", "text": "Cat" },
{ "type": "key", "key": "Enter" },
{ "type": "zoom", "target": "h1", "scale": 1.4, "hold": 2500 },
{ "type": "outro", "text": "Done" }
]
}| Step | Parameters | What it does |
|---|---|---|
title / outro |
text, sub, hold |
Full-screen title card at the start / end |
caption |
text, read |
Bottom toast, held for read ms, then slides away |
move |
target, dur |
Glides the cursor to an element |
click |
target, move |
Cursor to element, then click, with click sound |
type |
target, text, cps |
Types into a field with keystroke sounds; cps = characters per second |
key |
key |
Presses a key, e.g. Enter to submit |
zoom |
target, scale, hold |
Zooms the camera to an element, holds, returns |
scroll |
target |
Smooth-scrolls an element into view |
hover |
target, zoom, hold |
Hovers an element, optionally zoomed |
say |
text, hold |
A narrator line with nothing on screen |
wait |
ms |
Explicit pause |
Two ways, use whichever is clearer:
{ "target": "button.save" } // CSS selector
{ "target": { "text": "Save" } } // by visible text
{ "target": { "css": "h2", "index": 1 } } // nth matchFull reference: scenarios/FORMAT.md.
Add one line to meta and the video narrates itself - caption, title and outro text is read aloud,
and the music ducks under the voice and comes back after:
"voice": { "name": "en-US-AriaNeural" }Nothing extra to install; the synthesizer ships with npm install. List the available voices with
silky voices en-US.
Captions are short, speech is not. The say field decouples the two:
{ "type": "caption", "text": "Open the article", "read": 2000,
"say": "Press Enter to open the article." }"say": "..."- read this instead of what is on screen."say": false- stay silent on this step.sayworks on any step, so you can narrate a click or a scroll too.
Because every line is synthesized before the browser opens, its exact duration is known up front:
read and hold become minimums, and a caption never slides away mid-sentence. Each line is
synthesized once and cached in voice/, so re-recording the same scenario needs no network.
A fully narrated example lives in scenarios/wikipedia.json.
Four auth strategies, set in meta.auth:
| Strategy | Use when |
|---|---|
{ "type": "none" } |
Public site |
{ "type": "state", "file": "auth/state.json" } |
Log in once via silky login, session is reused |
{ "type": "token", "key": "authToken", "env": "AUTH_TOKEN" } |
Auth token in localStorage - good for CI |
{ "type": "cdp", "endpoint": "http://127.0.0.1:9222" } |
Attach to a Chrome you already have open |
The token strategy is what makes unattended CI runs practical: no interactive login, no stored
cookies to expire.
You can also hide noisy elements from the recording entirely:
"hide": ["app-monitoring-widget", ".cookie-banner"]The point is that the videos rebuild themselves - on every release tag, say - so a demo physically cannot fall behind the UI.
That needs a login with no human in it, which means auth.type: "token": the token lives in a
repository secret and arrives as an environment variable. The state strategy will not do here,
since it starts with someone logging in through a real browser window.
name: demo
on:
push:
tags: ['v*']
workflow_dispatch:
jobs:
record:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with: { node-version: 20, cache: npm }
- run: npm ci
- run: npx playwright install --with-deps chromium # system libraries for the browser
- uses: actions/cache@v4 # narration cache: do not re-synthesize the same lines
with:
path: voice
key: voice-${{ hashFiles('scenarios/*.json') }}
- run: node bin/silky.mjs record scenarios/my.json
env:
AUTH_TOKEN: ${{ secrets.DEMO_AUTH_TOKEN }}
- uses: actions/upload-artifact@v4
with:
name: demo
path: out/*.mp4Worth knowing up front:
- No ffmpeg to install - it ships with
npm installasffmpeg-static. - Narration needs network at record time. The
voice/cache removes most of the calls, but a line you have never synthesized before still goes out to the service. - There is no GPU in a runner, so rasterization is software and recording runs noticeably slower than on your laptop. Budget for it on long scenarios and raise the job timeout.
- The result lands in
out/, which is gitignored - collect it as a build artifact, as above. - Non-Latin captions need fonts in the runner image.
ubuntu-latestrenders Cyrillic fine; bare containers may need fonts installed.
Scenarios are plain JSON against a documented schema, which makes them an easy target for a coding
agent. Point one at scenarios/FORMAT.md and your app, describe the flow in prose, and let it emit
the file. Review the diff like any other code.
The repo ships a Claude Code skill for exactly this - .claude/skills/scenario-author/SKILL.md.
It explores your app through Playwright, picks stable selectors, and writes the scenario for you.
- Every narration line is synthesized and cached before the browser starts, so speech durations are known in advance and the step timings are laid out around them.
- Playwright drives a clean, isolated Chromium - no extensions, no profile artifacts, nothing that would leak into the frame. Frames are pulled through the DevTools screencast with exact timestamps, which is what keeps the result smooth at 60 fps; Playwright's built-in recorder caps out around 25 fps and drops frames on longer takes.
- The cursor, zoom camera, captions and title cards are rendered as an overlay inside the page, so there is no compositing step and no dependency on the host window manager. The overlay re-injects itself on navigation.
- ffmpeg assembles the frames into an even 60 fps track (
meta.fpsto change it), mixes in the voice, music and click/keystroke sounds at the exact action timings, and writes the.mp4.
Three runtime dependencies, all self-contained: playwright, ffmpeg-static and node-edge-tts.
Runs on macOS, Windows and Linux.
Point meta.music and meta.sfx at your own files:
"music": { "file": "assets/my-track.mp3", "vol": 0.8 },
"sfx": { "click": "assets/click.wav", "key": "assets/key.wav" }See assets/NOTICE.md for the provenance of the bundled defaults, and replace
them if you plan wide public distribution.
silky record <scenario.json> record the video
--headed show the browser instead of running headless
-v, --verbose print each step
silky login <scenario.json> log in once and save the session
silky voices [locale] list narration voices, e.g. silky voices en-US
silky-recorder is free and MIT-licensed, and stays that way. If it saved you an afternoon of re-recording, you can buy me a coffee:
- USDT (TRC-20) -
TPVXMisJGSh1QQLipd7ATbdqrSLBdmrU78 - Boosty - boosty.to/haste, if you hold a card issued in Russia
The same crypto address accepts TRX and any other TRC-20 token. Please mind the network: funds sent over another chain to a TRON address cannot be recovered.
Not into crypto? Starring the repo and telling one other person about it helps just as much.
Code is MIT (LICENSE). Bundled media in assets/ - see assets/NOTICE.md.
