explainer-video-create
Create a narrated 3Blue1Brown-style animated explainer video about how an existing project feature works, using manim with ElevenLabs or local text-to-speech. Use when the user asks for an explainer,
SKILL.mdplugins/yarstack/skills/explainer-video-create/SKILL.md
GitHubExplainer Video Creation
Produce one narrated MP4 that teaches how a feature works. Every narrated claim must come from investigated evidence.
Workflow
1. Set the scope
Extract the project, feature, focus, audience, narration language, and output path from the request. Default to engineers who know the domain, English narration, a 3 to 5 minute length, and ~/Desktop/<feature>-explainer.mp4, or the scratch directory when ~/Desktop does not exist. Ask only when the feature or project cannot be identified.
2. Investigate the feature
Run system-investigate on the feature in read-only mode. Record a short fact sheet in the scratch directory:
- each mechanism, state change, rule, and failure path the video will show, with a
file:linereference; - one concrete example from repository history, such as a real commit, PR, or log line, when one exists;
- facts that the evidence does not settle.
Narrate only facts from the sheet. Leave out inconclusive facts or present them as open questions.
3. Choose the voice
Select the first available provider:
elevenlabs:ELEVENLABS_API_KEYis in the environment, or in a.envfile that the user named or that exists in the working directory or project root. Validate it withnarrate.py --provider elevenlabs --language <ISO 639-1 code> --check-key, adding--env-file <path>when the key is in a file, before you write narration that depends on it. The check also fails when the script's model does not support the narration language.sayon macOS, orespeakwhenespeak-ngis installed.silent, which only sets the timing.
The default voices speak English. For any other narration language, choose a voice for that language and pass it as --voice: an ElevenLabs voice ID, a voice from say -v '?', or a voice from espeak-ng --voices.
If no key is found, or the key fails validation, ask the user once. Offer three choices: give a key, use the best local voice, or make a silent video. Continue with the local voice only if the user agrees. Never print, log, or copy a key. ElevenLabs receives the narration text, so keep secrets, customer data, and internal hostnames out of the narration.
The default ElevenLabs voice is Jack John (7EzWGsX10sAS4c9m9cPf), a voice from the ElevenLabs voice library. If the account cannot use it, pass another voice from narrate.py --provider elevenlabs --list-voices, or ask the user to add Jack John from the voice library; do not change the account yourself. When the user names an ElevenLabs voice, find its id with --list-voices and pass it as --voice. The script uses Eleven v4 at stability 1.0 and style 0. Lower values make the voice over-act explanatory text. Keep the voice's own pace. Pass --speed only when the user asks for a faster or slower voice. Eleven v4 ignores the speed voice setting, so the script changes the tempo of each clip after synthesis.
4. Prepare tools
Require ffmpeg and ffprobe. Create an isolated environment in the scratch directory, with Python 3.12 for manim wheel support. Prefer uv venv --python 3.12 followed by uv pip install manim. Ask before you make any system-wide installation. Use Text objects so that LaTeX is not needed.
5. Write the storyboard and narration
Plan 5 to 8 scenes. Give each scene one idea and split it into beats of 1 to 3 spoken sentences. A beat is the unit of audio-to-picture sync. A typical arc:
- Problem: show the failure that the feature prevents.
- Core rule: state the key invariant in one sentence.
- One scene for each mechanism.
- Failure and recovery paths.
- Recap: the invariant again, now earned.
Follow 3Blue1Brown style. Use a dark background and one visual metaphor for each idea. Build the picture step by step and use motion to show change. Give each color one meaning for the whole video. Keep text to short labels. Leave file paths and long hashes on screen only.
Write narration as plain speech in the narration language for text-to-speech:
- Replace terms that the voice says wrong with plain words. Do not use phonetic spellings; the voice reads them inconsistently.
- Use no commas, colons, semicolons, or dashes inside a sentence, because the voice pauses at each one. End each clause with a full stop instead.
- Add no delivery tag by default. When the user wants a different tone, start the first beat of each scene with one tag, such as
[serious]. ElevenLabs reads each scene in one take, so the tag sets the tone for the whole scene. - Compare the words per second that
narrate.pyprints for each scene. A long take often reads faster than the rest. Start that scene's first beat with[speaking slowly and clearly]and generate it again. Never change the tempo to fix the pace. - Use
[short pause]where a break helps, such as before a value read aloud. Do not add emotion tags such as[concerned]or[excited]to single lines; they make explanatory narration sound acted.
Save the narration as narration.json in scene order: {"S1Problem": ["beat", ...], ...}.
6. Generate the audio
Copy scripts/scenekit.py from this skill's directory into the scratch directory. Run scripts/narrate.py narration.json --provider <provider> --language <code> there, with --voice when step 3 requires it. It writes one clip per beat and audio/durations.json. ElevenLabs reads each scene in one take with a [long pause] between beats, and the script cuts the take inside those pauses, so the pace stays even across a scene. End every beat with a full stop or a question mark, and do not write [long pause] in a beat yourself. An edited beat regenerates only its own scene.
7. Write the scenes
Write scenes.py with from manim import * and from scenekit import *. Give each scene class the same name as its narration.json key, subclass Narrated, and wrap the animations for beat i in with self.beat(i):. Keep the animations in each beat shorter than the clip, because the beat waits until the clip ends. Call self.clear_all() between visual sections. Draw arrows with arrow() and animate them with grow_arrow(), because manim's Arrow and GrowArrow scale the tip and the line width with the arrow's length.
When a scene must show the real product interface, record it instead of animating it. Give that scene one beat for each recorded step.
- Run the product locally with its API stubbed at the boundary, so the recording creates nothing in a shared environment. Use realistic data without customer or colleague details.
- Script the steps with browser automation. Inject
../bug-report-reproduce/scripts/cursor.jsinto every page, move the pointer in small steps before each click, and write the end time of each step in seconds tostep-ends.json. - Open the first page and wait until it renders before the capture starts, because the browser shows a blank white page during navigation. Capture with a
page.screenshotloop at device scale factor 1.5 on a 1280 by 720 viewport, then join the frames at their timestamps into a 30 fps MP4. Built-in video recording and the CDP screencast capture CSS pixels, so the text is not sharp. CSSzoombreaks the position of popovers and tooltips. - Run
scripts/screencast.py <scene> <recording> step-ends.json audio media/videos/scenes/1080p30/<scene>.mp4. It holds each step's last frame until its clip ends, so a new voice does not need a new recording. Never change the audio tempo or cut narration to fit a recording. Make the picture wait for the voice.
8. Render a draft and inspect it
Render with manim -ql --disable_caching scenes.py <scene names>, and write each recorded scene to the 480p15 directory with screencast.py. Then run scripts/assemble.py sheets narration.json media/videos/scenes/480p15 sheets and view every sheet. Fix text cut off at the frame edge, overlapping labels, unreadable sizes, and objects that remain from an earlier beat. Render again only the scenes you changed.
9. Render the final video
Render with manim -qh --fps 30 --disable_caching. Then run scripts/assemble.py concat narration.json media/videos/scenes/1080p30 <output>. The script converts every scene to the first scene's format and pads its audio before it joins the scenes, and it fails when the audio and video lengths differ.
Result
Report the output path, the length, the voice provider, the scenes and the claims each one makes with its file:line evidence, the facts left out, and the scratch path of narration.json and scenes.py for later edits. Do not publish or upload the video unless the user asks.