alexansart/demo-studio

produce-video

End-to-end production of a narrated, captioned demo video for any web app — chains narration generation (narrate), silent Playwright recording (film-demo, smart zooms + guardrails), and narration sync with burned captions (sync-narration) into one final .mp4.

ソースを見る

使い方

  1. インストールコマンドをコピーし、自分の環境へ導入する前にソースを確認します。
  2. 必要なツール、認証情報、対応環境を原文で確認します。
  3. 入力と成果物を指定し、出力を資料と照合します。
npx skills add https://github.com/alexansart/demo-studio --skill produce-video

開始前の確認

  • 導入にはモデル契約、API枠、ファイルへのアクセス許可は含まれません。
  • スター数や導入数は活動の指標であり、独立した品質・安全性試験ではありません。
リポジトリの原文

見出し、例、コード、表、リンク、参照画像を含む原文を表示しています。

Produce a demo video, A → Z

One request in → one finished .mp4 out (narrated + captioned if narration is enabled, silent otherwise). This skill is the orchestrator: it owns the chaining logic and the order of operations. The three stage skills own their domain detail and remain the source of truth for it.

MANDATORY — read all three stage skills before starting (this file only adds what happens between them; skipping them is how quality gets lost):

StageSkill to readOwns
VoicenarrateElevenLabs voice/model defaults, script script-writing rules, credits
Silent videofilm-demo (+ its reference.md)Camera model (focus/wide), cursor, speed-ups, guardrails, inspect/verify loop
Sync + captionssync-narrationWhisper alignment, segmentTargets, gaps, pre/post-roll, caption burn, ffmpeg gotchas

If this is the first time this skill runs in a project, run demo-setup first (or check that demo.config.json already exists at the project root) — every stage below reads it for the base URL, output directory, narration provider, and style preset. For scaffold patterns (login off-camera, beat plan, compose caps), read demo-setup/examples/ and demo-setup/references/.

Pipeline

Request (what the app does, what to say, output path)
  │
  ├─ 0. SCRIPT     write demos/<slug>/script.md (beats + narration text)
  ├─ 1. VOICE      script → narration.mp3           (narrate)            — skip if narration.provider = "none"
  ├─ 2. ALIGN      mp3 → aligned.json                (whisper — sentence durations) — skip if no narration
  ├─ 3. RECORD     beats → <slug>-no-sound.mp4        (film-demo, holds sized from step 2)
  ├─ 4. SYNC       mp3 + no-sound → <slug>.mp4        (sync-narration, burned captions) — skip if no narration
  └─ 5. QA         frames + audio tail + output path → deliver

Voice comes first, always (when narration is enabled). Align the mp3 before recording so each sentence's exact duration sizes the on-screen holds. After that, the video adapts to the voice, not the other way around.

Silent mode: if demo.config.json → narration.provider is "none" (the default — no API key required), skip stages 1/2/4 entirely: film-demo records straight to the final output, using its own idle-gap speed-up (no narration-driven holds to protect).

Artifacts (in demo.config.json → output.dir, default demos/<slug>/):

demos/<slug>/script.md          the beat + narration script (source of truth for this run)
demos/<slug>/narration.mp3      narration (never retouched after ✓) — narrated mode only
demos/<slug>/no-sound.mp4       silent recording (keep for re-syncs) — narrated mode only
demos/<slug>/final.mp4          FINAL deliverable

Checklist

Production progress:
- [ ] 0. Confirm demo.config.json exists (else run demo-setup); write demos/<slug>/script.md
- [ ] 1. Generate narration.mp3 (narrate, exact filename) + ffprobe check — skip if silent mode
- [ ] 2. Align mp3 (align-narration.py) → per-sentence durations table — skip if silent mode
- [ ] 3. Write beat plan: sentence ↔ beat ↔ min on-screen hold — skip if silent mode
- [ ] 4. Record silent video with film-demo (narration-aware config below if narrated)
- [ ] 5. film-demo gates: guardrails alerts resolved, inspect frames read, verify pass
- [ ] 6. Copy final.mp4 → no-sound.mp4 (narrated mode only)
- [ ] 7. Sync: contact sheet → targets → cues.txt → plan → validate → render — skip if silent mode
- [ ] 8. QA gates (below) on the final mp4
- [ ] 9. Deliver: absolute path + duration + justified alerts

Stage 0 — Write the script

Write demos/<slug>/script.md with two parallel tracks, beat order = narration order:

markdown
# <Video title>

## Say (skip this section entirely for silent mode)
1. "Here's how it works."
2. "Type your task, hit add, and watch it appear instantly."
3. "That's it — no page reload, no setup."

## Show
1. Open the app, wait for it to settle.
2. Focus the task input.
3. Type "Ship the v1 release".
4. Click Add — expect the new item in the list.
5. Wide — let the viewer see the list update.
6. Focus the new list item, hold ~2s (the payoff).
7. Wide, hold 2.5s, stop.

Keep total narration to ~150 words/minute of planned video length (a 60s video ≈ 150 words). If the user gave you the app's flow but no narration text and narration is enabled, draft the Say lines yourself from what the Show beats actually do — never invent behavior the app doesn't have.

Stage 1 — Voice (narrated mode only)

Follow narrate exactly. Use the current Say text from script.md:

bash
python <narrate-skill-dir>/scripts/generate_narration.py \
  --out demos/<slug>/narration.mp3 \
  --text-file /tmp/say.txt

Gate: ffprobe duration > 0 and plausible (~150 words/min). Narration costs API credits — if the mp3 already exists and Say hasn't changed, reuse it; any Say edit → regenerate.

Stage 2 — Align (before recording, not after)

bash
pip install -r <sync-narration-skill-dir>/scripts/requirements.txt   # once
python <sync-narration-skill-dir>/scripts/align-narration.py \
  demos/<slug>/narration.mp3 \
  --script-file /tmp/say.txt --out /tmp/aligned.json

From sentences[], build the beat plan and put it as a comment block at the top of run.mjs:

// BEAT PLAN (from aligned.json)
// #  sentence (first words…)      dur    beat                     min hold
// 1  "Here's how it works…"       2.1s   app loads                3s
// 2  "Type your task…"            4.8s   type + add                6s

Min hold = sentence duration + ~1.2s. The sync stage can stretch silence between sentences, but it can never make a beat that left the screen too early stay longer — an undersized hold forces narration to spill over the next beat.

Stage 3 — Record silent (film-demo, narration-aware when applicable)

Follow the whole film-demo workflow (beat script, camera plan, guardrails, inspect, verify). Differences specific to narrated videos:

  1. Zero on-screen text. No overlays or caption cards in run.mjs —

captions are burned at sync time from the Say text.

  1. Holds are narration-driven. After each beat's action settles,

pause() until the beat's min hold (beat plan above) is met. These pauses are deliberate, so:

  1. Disable the generic idle compression — it would eat exactly those

holds:

bash
node <film-demo-skill-dir>/scripts/compose.mjs <renderDir> --speedup idleGapMin=9999,toolWaitMax=2.5,preToolWaitMax=2,tailHold=4

Keep lead/tail trims. Do not log an early open() event before the first beat — lead trim anchors on the first timeline event; an early open() blocks trimming dead startup time and forces a huge head-pad at sync. Preload the app off-camera (page.goto + settle) before startFilmRecording; the first filmed event must be the first beat.

  1. Guardrail justifications shift: inactivity and zoom-too-long

alerts during a planned narration hold are expected — justify them against the beat plan (name the sentence). cursor-offscreen and record-alert (error text, click outside zone) are never justifiable, same as always.

  1. Camera ↔ narration: when a clause describes one element, focus() on

it for that hold, then wide(). The pointer must be settled on the element for the clause's whole window — sync (stage 4) cannot fix a cursor that was still traveling.

  1. Opening + payoff: await settle(page) before the first beat (fully

loaded, no spinner, no leftover state from a previous take). End on the RESULT: focus() the changed element, hold ≥ 4s, then stop.

  1. Fail fast, restart from zero. Use expect: on every click with a

knowable outcome. Any error, repeated click, or unexpected state = kill the take, fix, fresh render.

  1. Duration sanity: silent video ≥ padded-audio estimate (sum of sentence

durations + planned inter-sentence gaps) and ≤ 2min.

For silent mode (no narration), skip 2/3/4 above — just follow film-demo as-is; its own speed-up defaults already keep pacing tight.

Copy the accepted render's final.mp4 to no-sound.mp4 (narrated mode only).

Stage 4 — Sync + captions (narrated mode only)

Follow sync-narration end to end. Chaining shortcuts already earned:

  • aligned.json from stage 2 is reused as-is.
  • segmentTargets: read them off the recording's timeline.json (after

compose its timestamps are remapped to final-video time, so each beat's settle moment is exact) plus the camera plan compose prints — still generate the contact sheet to confirm frames match. If the plan builder reports merged sentences (no usable silence between them), pass one target per merged block.

  • cues.txt: split the Say text into caption cues at clause breaks — **≤ 60

chars preferred, 80 hard max**.

  • Keep defaults (--tail-pad 1.0; pre/post-roll and min-silence are

word-safe and silence-aware out of the box).

  • --validate-only first, always; then render **to the requested output

path**.

  • `leadGap` / `--head-pad` = composed timestamp of the first spoken beat,

not the raw pre-recording offset. Values > 5s always mean wrong sync (spot-check fails): trim dead opening footage in Stage 3, or extend Say so narration covers long waits.

  • Spot-check is mandatory: node <sync-narration-skill-dir>/scripts/spot-check.mjs plan.json

and read EVERY frame.

Stage 5 — QA gates (all must pass before delivering)

  • [ ] Final duration 15s-2min; ends on the result screen (payoff readable ≥ 3s), not mid-action
  • [ ] Narrated mode: spot-check.mjs run on the final render and EVERY frame read
  • [ ] Scrub last 1s of audio: final word decays naturally (post-roll not clipped) — narrated mode
  • [ ] Narrated mode: plan.json leadGap ≤ 5s; opening frames show motion before first spoken word
  • [ ] verify.mjs passes on the silent/final master
  • [ ] No tight focus() zoom held through a loading state or unscripted UI
  • [ ] No narration while the cursor travels — narrated mode
  • [ ] capture-stats.json healthy — `compose.mjs` / `verify.mjs` / sync hard-fail if fps < 25 or p90 > 80ms; else re-record
  • [ ] Final file sits at the exact requested output path
  • [ ] Silent master + .mp3 kept alongside — narrated mode

What to redo when something is wrong

SymptomRedo
Wrong words / wrong voiceStage 1 (only if Say changed or generation was wrong) → then 2, 4
Beat leaves screen before its clause endsStage 3 (raise that hold) → 4. Voice is fixed — never speed it up
Caption early/late, clipped onset/tailStage 4 only (targets, pre/post-roll) — no re-record needed
Cursor moving during a clauseStage 3 (move the action before the hold) → 4
Video too longStage 3 (cut a beat — never rush actions, never trim a mapped payoff)
Nothing happens / mute audio first 10-20sStage 3 (preload off-camera; first event = first beat) → Stage 4 (--head-pad = composed queue time, ≤ 5s)
Draft Say too short for the videoExpand Say (stage 0), regenerate voice → align → record/sync

Deliverable message (required)

markdown
## Video ready

**Final:** `<absolute path to final.mp4>`
- Duration: <X>s
- Mode: <narrated (N sentences, voice) | silent>
- Silent master: `<no-sound.mp4>` (narrated mode) · render `<NNN>` · capture <fps>fps
- Guardrail alerts justified: <list or "none">
- Anomalies: <list or "none">

Anomalies are mandatory to report. Anything that did not behave as expected — a feature that errored and needed a retry/workaround, a beat dropped because the UI never reached the scripted state, a flaky endpoint, a take restarted — goes in the final message, even when the delivered video looks fine. Never let the user discover a bug by watching the video.

同じリポジトリから

関連する Skills

すべての Skills
alexansart
コミュニティ

demo-setup

One-time setup that analyzes the current project and configures it to use the film-demo / narrate / sync-narration / produce-video skills — detects the dev server and framework, asks only when necessary, generates demo.config.json and .env entries, vendors the recording engine and project helpers, and scaffolds a first demo from reference patterns. Use when the user asks to set up, configure, or install demo-studio / video-recording skills for this project, or before running produce-video for th

1時間の導入数
1
GitHub Stars
5
更新日
7月26日
alexansart
コミュニティ

film-demo

Records a polished, silent screen-capture demo video of any web app from a plain-English beat script — Playwright capture with a real cursor, human-speed typing, explicit zone-based zooms (focus/wide) with guaranteed containment, deterministic guardrails (cursor offscreen, zoom too long, inactivity), annotated frame inspection, post-record speed-ups, styled frame, and a verify/iterate loop. Use when the user asks to record, film, or generate a demo/tutorial/product video of a web app.

1時間の導入数
1
GitHub Stars
5
更新日
7月26日
alexansart
コミュニティ

narrate

Generates a narration voiceover .mp3 for a demo video script using the ElevenLabs API — configurable voice/model/stability, deterministic output filename. Use when the user asks to add a voiceover, narration, or spoken audio to a demo/tutorial video, or names ElevenLabs explicitly.

1時間の導入数
1
GitHub Stars
5
更新日
7月26日
alexansart
コミュニティ

sync-narration

Syncs a separately-recorded narration track onto a silent screen recording — pads audio with calculated pauses to match on-screen pacing (no voice during cursor movement), then burns styled captions. Use when the user provides a silent screen-recorded video plus a narration .mp3 and asks to sync/combine/caption them.

1時間の導入数
1
GitHub Stars
5
更新日
7月26日