npm package: @spark-apps/quickpeek
Description: Auto-generate demo videos for your web app with AI
Latest version: 1.1.3

[license-link]: ./LICENSE
[privacy-link]: ./PRIVACY.md
[discord-link]: https://discord.gg/5skXfKRytR
[stars-link]: ../../stargazers
[issues-link]: ../../issues

<div align="center">

<img src=imgs/logo.png>

**Demo videos for your web app with AI**

*Because Tutorial Videos are Overrated!*

[![npm](https://img.shields.io/npm/v/@spark-apps/quickpeek?style=flat-square&logo=npm&logoColor=white&color=crimson)](https://www.npmjs.com/package/@spark-apps/quickpeek)
[![MIT](https://img.shields.io/badge/License-MIT-blueviolet?style=flat-square)][license-link]
[![Discord](https://img.shields.io/badge/Discord-Join-5865F2?style=flat-square&logo=discord&logoColor=white)][discord-link]
[![GitHub Stars](https://img.shields.io/github/stars/muammar-yacoob/quickpeek?style=flat-square)][stars-link]

</div>

---

## Quick Start

```bash
npm install -g @spark-apps/quickpeek
qp localhost:3000
```

**Requirements:** [ffmpeg](https://ffmpeg.org/download.html), [Groq API key](https://console.groq.com/keys) (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

```bash
qp localhost:3000
```

### Script mode — you write the narration

```bash
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

```bash
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

```bash
qp localhost:3000 lang=es -d "A todo app for managing daily tasks"
```

### Chrome Extensions

Record demos for Chrome extensions using the `chrome:` prefix:

```bash
qp chrome:your-extension-id
```

QuickPeek will automatically:
1. Find the extension in your Chrome installation
2. Load and analyze the extension popup UI
3. 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.

<details>
<summary><strong>Supported Languages</strong></summary>

| 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.

</details>

<details>
<summary><strong>Caption Style</strong></summary>

Edit `captions.css` (auto-generated) to customize:

![Classic Yellow](imgs/caption-classic.png)

```css
.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;
}
```

</details>

## 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) |

## 🌱 Support & Contributions

⭐ **Star the repo** & I power up like Mario 🍄  
☕ **Devs run on coffee** - [Buy me one?][coffee-link]  
💖 **Sponsor** [Your support][stars-link] helps maintain and improve the tool<br>
💰 **Crypto tips welcome** - [Tip in crypto](https://tip.md/muammar-yacoob)  
🤝 **Contributions are welcome** - [🍴 Fork][fork-link], improve, PR!  
🎥 **Need help?** <img src="https://img.icons8.com/color/20/youtube-play.png" alt="YouTube" width="20" height="20" style="vertical-align: middle;"> [Setup Tutorial][vid-link] • <img src="https://img.icons8.com/color/20/discord--v2.png" alt="Discord" width="20" height="20" style="vertical-align: middle;"> [Join Discord][discord-link]

<div align="center">

---

MIT License - Made with ☕ by [Spark Apps](https://github.com/muammar-yacoob)

</div>