@spark-apps/quickpeek-cli

QuickPeek CLI

Auto-generate demo videos for your web app with AI

Quick Start

npx @spark-apps/quickpeek-cli localhost:3000

Or install globally:

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

Requirements: ffmpeg, Groq API key (free)

Features

Feature	Description
AI Planning	Groq AI analyzes your app and generates demo steps
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
Step Transitions	Fade or blend effects between steps
Video Steps	Insert video clips with optional trimming
Image Steps	Insert custom images as intro slides
Show Downloads	Display downloaded files in the demo

Examples

Basic

qp localhost:3000

With Options

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

Option	Description
lang	Voice language (en, es, ar, zh...)
-d, --description	App description to guide AI
--skip-voice	Reuse existing voiceover

Configuration

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

Option	Description	Default
video.width/height	Resolution	1080x1920
video.quality	Quality 0-1	0.5
video.cursor	Show mouse cursor	true
video.uiHighlight	Element highlight: "outline", "full", false	"outline"
video.fadeIn/fadeOut	Fade duration (ms)	1500
video.transitions	Step transitions: none, fade, blend	none
video.contrast	Video contrast boost 0-1	0.25
video.tempo	Playback speed multiplier	1
video.stepDelay	Delay between steps (ms)	200
music.path	Background music file	-
music.volume	Music volume 0-1	0.3

Output

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

Plan Actions

Edit plan.json to customize the demo steps:

Action	Description	Example
click	Click an element	{ "action": "click", "target": "Submit" }
click-N	Click N times (300ms delay)	{ "action": "click-2", "target": "Next" }
click-N:delay	Click N times with custom delay	{ "action": "click-3:500", "target": "Add" }
type	Type text into input	{ "action": "type", "target": "input[name='email']", "value": "[e-mail]" }
upload	Upload a file	{ "action": "upload", "target": "input[type='file']", "value": "./file.png" }
scroll	Scroll the page	{ "action": "scroll", "value": "80%" }
drag	Drag a slider	{ "action": "drag", "target": "input[type='range']", "value": "50" }
wait	Pause (no caption needed)	{ "action": "wait" }
video	Insert video clip	{ "action": "video", "value": "./intro.mp4" }
image	Insert image slide	{ "action": "image", "value": "./cover.png" }
showDownload	Display last download	{ "action": "showDownload" }

Step Options

Each step can have these optional fields:

Field	Description	Values
zoom	Zoom level on target element	Number (e.g., 1.4)
highlight	Highlight the target element	"outline", "full", false
transition	Transition from previous step	"fade", "blend"
duration	Override step duration (seconds)	Number

Example with zoom and highlight:

{
  "action": "click",
  "target": "Submit Button",
  "caption": "Click the submit button",
  "zoom": 1.5,
  "highlight": "full"
}

Highlight modes:

• "outline" - Yellow border around element
• "full" - Yellow border + dark overlay (spotlight effect)

Video Step

Insert video clips into your demo:

{
  "action": "video",
  "value": "./intro.mp4",
  "target": "center",
  "partial": "0-3.5",
  "caption": "Quick preview of what we'll build"
}

Field	Description	Default
value	Path to video file (mp4, webm, mov)	required
target	"center" (letterbox) or "stretch" (fill frame)	"center"
partial	Trim video: "start-end" in seconds	full video
caption	Voiceover text	-

Partial examples:

• "0-3.5" - first 3.5 seconds
• "2-10" - seconds 2 to 10
• "5-" - from 5 seconds to end

Image Step

Insert static images as intro/outro slides:

{
  "action": "image",
  "value": "./cover.png",
  "target": "center",
  "caption": "Welcome to our app demo!"
}

Field	Description	Default
value	Path to image (png, jpg, gif, webp)	required
target	"center" (letterbox) or "stretch" (fill frame)	"center"
caption	Voiceover text	-

Show Download

Display the last downloaded file in the demo:

{
  "action": "showDownload",
  "caption": "Here's your generated file!"
}

Automatically captures files downloaded during previous steps.

Step Transitions

Add smooth transitions between steps. Set globally in config or per-step in plan.json:

Config-level (applies to all steps):

{
  "video": {
    "transitions": "fade"
  }
}

Per-step (overrides config):

{
  "action": "click",
  "target": "button",
  "caption": "Click to continue",
  "transition": "blend"
}

Value	Effect	Duration
fade	Fade to black, then fade in	0.3s
blend	Quick cross-dissolve	0.15s
none	No transition (config only)	-

Notes:

• First step never has a transition (global fadeIn handles it)
• Per-step transition overrides video.transitions config
• Transitions too close to video start/end are auto-skipped

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

60+ languages supported via Edge TTS.

Caption Styling

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;
}

MIT License - Made with ☕ by Spark Apps