Dynamic promo video (HTML scenes + voiceover + music)
Produces a 1280x720, ~25-45s MP4: animated scenes in one HTML page, rendered frame by frame with Playwright, encoded with ffmpeg, narrated with a TTS voice (e.g. ElevenLabs), with ducked background music.
below means this skill's folder. Only the template is copied into the work folder; the scripts run from
(each has
). Needs Node + Playwright/Chromium (preinstalled in cloud sessions; do not reinstall), ffmpeg/ffprobe, Python 3 with numpy.
| Step | Use |
|---|
| Scenes | assets/template/index.html
· details: references/scene-engine.md |
| Real page screenshots | references/screenshots.md |
| Voiceover | references/voiceover.md · scripts/tts_elevenlabs.py
, |
| Render + encode | |
| Music, mix | , · references/music-and-mix.md |
| Check | |
Inputs
| Flag | Meaning |
|---|
| , | Build the default demo instead of a real project: a placeholder video, then how to make one with this skill; see Demo below. |
| Build the self demo: the skill explaining itself (what it is, how it works, install, use). |
| Narrate with the default ElevenLabs voice . |
--voice-elevenlabs=<voice-id>
| Narrate with that ElevenLabs voice. A bare = . |
- Narration uses ElevenLabs only if one route is available, checked in this order:
- the ElevenLabs MCP connector (its tool can be loaded with ToolSearch), or
- an API key: is set, or the session's network secrets hold one for (then run
scripts/tts_elevenlabs.py
).
- Real project, no voice flag: narrate with the default voice if a route exists, else music only.
- (any variant) without a voice flag: music only. With (or the default voice id), use the variant's bundled clips: no ElevenLabs route is needed and no credits are spent.
- A voice flag was given but no route exists: say so, offer to connect the connector, add a key or attach clips; do not silently drop the voice. Never invent a voice id and never fake narration.
- A voice the user names in words is looked up with the connector's voice list; otherwise use the id as given.
Demo ()
No research, storyboard or editing. Each variant lives in
:
,
(one line per scene,
= none) and
, which maps each scene to its approved recording in the shared
(default voice).
- default (48s): scenes 1-6 are the generic template, a placeholder for the viewer's own video; scenes 7-9 show how to make one: a bridge ("that was a placeholder"), the three install routes from , get started (music only). The cover is tagged "Demo of Skill /dynamic-promo-video · sugatoray/aiskills".
- self (32s): the skill explaining itself: cover, the problem, the scene engine's code, the three install routes, usage, get started.
| Request | Run |
| --- | --- |
| / |
python3 SKILL_DIR/scripts/demo.py
(music only) |
| | python3 SKILL_DIR/scripts/demo.py --variant self
|
| add (or the default voice id) | add : the bundled clips, no ElevenLabs route needed, no credits |
| add --voice-elevenlabs=<other id>
, API key | add (generates the clips) |
| add --voice-elevenlabs=<other id>
, MCP connector | generate one clip per non- line of the variant's (see references/voiceover.md), save as , add |
With
the result is identical every run (same frames, same audio). Output:
promo-demo/demo_final.mp4
and
, checked; deliver as in step 5. The skill icons are simplified drawings.
0. Before building
- Research the subject first: README, package page, marketplace listing, install commands. Use real names, commands and versions. Do not invent features.
- Use the project's real branding (banner, icon, colors, fonts) and real screenshots from its docs where possible. Check the repo for docs images before drawing anything.
- Sandbox network is allowlisted: npm registry, marketplace and github.com web pages are usually blocked from the shell. Git clone of a public repo often works (use the add_repo tool, then clone). If the repo's own CLAUDE.md says to read docs first and the task is not editing the repo, say you are skipping them.
- Make a task list. Last task: check frames and audio, then deliver.
1. Storyboard (write the narration first)
Typical 6 scenes: (1) cover/title, (2) the problem, (3) the product in action, (4) install commands, (5) editor/extension usage, (6) end card with commands and links. The template has exactly these.
Write one narration line per scene (about 2.5-3 words per second). Scene length is set by the narration, not the other way round.
2. Build the scenes
Copy
SKILL_DIR/assets/template/index.html
into the work folder and edit it: brand CSS variables, scene text, real screenshots, camera keyframes. Rules that matter most:
- Everything is a function of through ; no CSS animation, no timers.
- Frame 0 is a finished cover (social platforms use it as the preview). Scene 1 only fades out.
- Icons are simplified drawings, not official logos; say so unless official files are supplied.
- Do not reuse a class name a script queries with .
3. Preview, then voice, then retime
bash
node SKILL_DIR/scripts/render.js index.html --preview 0,6,12,17,23,29 --thumbnail thumbnail.png
Look at the preview frames before going on. Then produce the voice clips with the voice from Inputs (details in references/voiceover.md; one generation per scene, never re-run a paid generation). With an API key:
bash
python3 SKILL_DIR/scripts/tts_elevenlabs.py --script narration.txt --voice <voice-id> --dry-run # check the plan first
python3 SKILL_DIR/scripts/tts_elevenlabs.py --script narration.txt --voice <voice-id>
With the MCP connector, call
once per scene with that
. A scene with no narration gets the line
(no clip; pass
to timing.py). If the voice says a name wrong, write it the way it sounds, test the name alone (about 15 credits) and splice the approved sample into the clip instead of regenerating the line (references/voiceover.md). Then retime:
bash
python3 SKILL_DIR/scripts/timing.py --authored 0,4,9,15,21,26,31 --clips vo0.mp3 vo1.mp3 vo2.mp3 vo3.mp3 vo4.mp3 vo5.mp3
Add
to write the new
into the page (or paste the printed line). Scenes stretch to fit; the voice is never sped up.
4. Render, music, mix
bash
node SKILL_DIR/scripts/render.js index.html --encode promo_silent.mp4
python3 SKILL_DIR/scripts/music.py --style energetic --duration <total> --out music.wav
python3 SKILL_DIR/scripts/mix.py --video promo_silent.mp4 --music music.wav --voice 0.3:vo0.mp3 ... --out promo_final.mp4
Use a licensed track instead of
when the user supplies one; if synthesized, say it is simple and synthesized. Copy the
arguments from timing.py's output. If only visuals change later, re-render and run
mix.py --audio-from <previous final>
.
5. Verify and deliver
bash
python3 SKILL_DIR/scripts/verify.py promo_final.mp4 --frames <one time per scene>
- It must report both streams with near-equal durations; read the per-second dB line (voice present, music dipping under it).
- Look at frame 0, one frame per scene and the last frame in . Confirm no overlaps or clipped text.
- Say clearly which file has sound: keep the / names.
- Send with SendUserFile (display render), plus . Summarize in a few lines: what each scene shows, what is real vs. drawn, and what you could not verify (you have not listened to the audio).
- Offer a LinkedIn/social post note only if asked; keep claims to what the README documents (for example "early development").