@spark-apps/quickpeek

<img src=imgs/logo.png>

Demo videos for your web app with AI

Because Tutorial Videos are Overrated!

Quick Start

npm install -g @spark-apps/quickpeek
qp localhost:3000

Requirements: ffmpeg, Groq API key (free)

Features

Feature	Description
AI Planning	Groq AI analyzes your app and generates demo steps
Script Mode	Provide your own narration script, AI maps it to UI actions
Capture Mode	Record your own interactions → replayable plan.json
Voice Over	Free Edge TTS narration in 60+ languages
Karaoke Captions	Word-by-word highlighted subtitles
Background Music	Optional music with fade in/out
Smart Zoom	Per-step zoom for focused demos
Chrome Extensions	Record demos for Chrome extensions

Examples

Basic — AI generates the plan

qp localhost:3000

Script mode — you write the narration

qp localhost:3000 --script narration.txt

Script file format (one caption per line, # for comments):

# My app demo
We start on the dashboard — your main workspace.
Let's search for a customer by typing their name.
Click the result to open their profile.

Capture mode — record your own interactions

qp capture localhost:3000

Browse the app freely, press Enter when done. QuickPeek converts your clicks, typing, and scrolls into a plan.json that can be replayed as a polished video.

With options

qp localhost:3000 lang=es -d "A todo app for managing daily tasks"

Chrome Extensions

Record demos for Chrome extensions using the chrome: prefix:

qp chrome:your-extension-id

QuickPeek will automatically:

• Find the extension in your Chrome installation
• Load and analyze the extension popup UI
• Generate a demo plan with AI

The popup URL is detected from the extension's manifest.

Option	Description
lang	Voice language (en, es, ar, zh...)
-d, --description	App description to guide AI
-s, --script	Path to narration script file
video.width/height	Resolution (default: 1080x1920)
video.quality	Quality 0-1 (default: 0.5)
music.path	Background music file
music.volume	Music volume 0-1 (default: 0.3)
output.dir	Output directory (default: ./demo)

Config is auto-generated on first run. Edit quickpeek.config.json to customize.

Supported Languages

Code	Language	Code	Language
en	English	ar	Arabic
es	Spanish	fr	French
de	German	zh	Chinese
ja	Japanese	ko	Korean
pt	Portuguese	hi	Hindi
it	Italian	ru	Russian

See src/voices.ts for all 60+ supported languages.

Caption Style

Edit captions.css (auto-generated) to customize:

.caption {
  font-family: Arial, sans-serif;
  -webkit-text-stroke: 3px #000000;
}
.caption .regular {
  font-size: 56px;
  color: #FFFFFF;
}
.caption .highlight {
  font-size: 64px;
  color: #FFFF00;
}

Plan Actions

Edit demo/plan.json to customize your demo. Each step uses one of these actions:

Action	Target	Value	Description
wait	-	-	Pause for narration (intro/outro)
click	"button text"	-	Click button/link
click-N	"button text"	-	Click N times (e.g., click-2, click-3)
type	input[name="field"]	"text to type"	Type into input field
upload	input[type="file"]	"path/to/file"	Upload file to form
select	select[name="field"]	"option text"	Select dropdown option
check	input[type="checkbox"]	-	Toggle checkbox
drag	input[type="range"]	"0"-"100"	Drag slider to value
drag	canvas	"around"	Full 360° rotation (returns to start)
drag	canvas	"rotate"	Rotate ~270° (stays at new angle)
drag	canvas	"rotate:90"	Rotate specific angle (circular)
drag	canvas	"rotate:x-90"	Rotate on X axis (horizontal drag)
drag	canvas	"rotate:y45"	Rotate on Y axis (vertical drag)
drag	-	"left" "right" "up" "down"	Directional drag
scroll	-	"up" "down" "bottom"	Scroll page
scroll	-	"-10" to "10"	Zoom camera (negative=out, positive=in)
media	"scale" or "center"	"path/to/file"	Display image/video fullscreen
showDownload	-	-	Show the last downloaded file

Target shortcuts: For buttons and links, use simplified text like "download" or "extract frame" instead of CSS selectors.

Output

File	Description
demo/demo.mp4	Final video
demo/plan.json	Editable script (re-run to apply changes)

plan.json is also accepted by VidLet's create_project MCP tool, which turns the steps into a .vidlet timeline project for further editing and narration.

🌱 Support & Contributions

⭐ Star the repo & I power up like Mario 🍄
☕ Devs run on coffee - [Buy me one?][coffee-link]
💖 Sponsor Your support helps maintain and improve the tool
💰 Crypto tips welcome - Tip in crypto
🤝 Contributions are welcome - [🍴 Fork][fork-link], improve, PR!
🎥 Need help? [Setup Tutorial][vid-link] • Join Discord

MIT License - Made with ☕ by Spark Apps