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

<div align="center">

# QuickPeek CLI

**Auto-generate demo videos for your web app with AI**

[![npm](https://img.shields.io/npm/v/@spark-apps/quickpeek-cli?style=flat-square&logo=npm&logoColor=white&color=crimson)](https://www.npmjs.com/package/@spark-apps/quickpeek-cli)
[![MIT](https://img.shields.io/badge/License-MIT-blueviolet?style=flat-square)](../../LICENSE)
[![Discord](https://img.shields.io/badge/Discord-Join-5865F2?style=flat-square&logo=discord&logoColor=white)](https://discord.gg/5skXfKRytR)

</div>

---

## Quick Start

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

Or install globally:

```bash
npm install -g @spark-apps/quickpeek-cli
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 |
| **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

```bash
qp localhost:3000
```

### With Options

```bash
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": "test@example.com" }` |
| `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:**
```json
{
  "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:

```json
{
  "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:

```json
{
  "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:

```json
{
  "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):
```json
{
  "video": {
    "transitions": "fade"
  }
}
```

**Per-step** (overrides config):
```json
{
  "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:

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

---

<div align="center">

MIT License - Made with ☕ by [Spark Apps](https://github.com/muammar-yacoob)

</div>