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": "[email protected]" } | | 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