Video Explainer

Create a scripted 1080p product walkthrough that stays synchronized with its narration. Keep credentials, browser state, source data, and rendered videos out of Git.

Workflow

1. Inspect the target page before writing selectors.
2. If login is required, run node src/login.js <url> and save state under .auth/.
3. Take a screenshot and identify the smallest useful story.
4. Probe important selectors with node src/probe.js <url> <selector...>.
5. Write narration first. Keep each line focused on one idea.
6. Create or update a scene file under demos/.
7. Render silently with node src/demo.js <name> --voice=none.
8. Read every selector warning and fix missing targets.
9. Inspect the MP4 and representative frames before sharing it.
10. Add narration only after the silent version is correct.

Quality rules

• Use a 1280 by 720 viewport unless the product needs a different aspect ratio.
• Open and close with title cards.
• Use at least two zooms in a video longer than one minute.
• Zoom out before clicking so the cursor lands predictably.
• Prefer visible text selectors over generated CSS class names.
• Highlight a useful container instead of a tiny label.
• Write narration in short sentences that sound natural when spoken.
• Spell out numbers in narration when text-to-speech pronunciation matters.

Authentication

Use src/login.js to create a Playwright storage state file. Pass it with --storage-state=.auth/state.json or set VIDEO_EXPLAINER_STORAGE_STATE.

Never put cookies or tokens in a demo JSON file. Never commit .auth/ or .env.

Voice choices

• --voice=none is free and is the default.
• --voice=elevenlabs uses ELEVENLABS_API_KEY and ELEVENLABS_VOICE_ID from the environment or .env.
• --voice=system uses the macOS say command.

Tell the user before using a metered voice provider. State which provider will receive the narration text.

Scene types

Use the schema and examples in README.md and demos/sample.json. The runner supports title, navigate, wait, click, hover, type, caption, highlight, scroll, zoom, zoomOut, and narrate scenes.

Any scene can include say. Its screen time expands to fit the spoken clip. A caption without say narrates its own text.

Verification

Before delivery:

• Confirm the run log has no unresolved selector warnings.
• Confirm no private data appears in the scene file or captured page.
• Confirm captions stay inside the frame.
• Confirm audio finishes before the associated visual changes.
• Confirm the final file is 1920 by 1080 and opens successfully.
• Keep the output under output/ and share it through the user's chosen file service.