@spark-apps/quickpeek 1.2.4 → 1.2.6

package/README.md

@@ -1,21 +1,15 @@
-[license-link]: ./LICENSE
-[privacy-link]: ./PRIVACY.md
-[discord-link]: https://discord.gg/mAjHWE3mSp
-[stars-link]: ../../stargazers
-[issues-link]: ../../issues
+[coffee-link]: https://buymeacoffee.com/spark88
 
 <div align="center">
 
-<img src=imgs/logo.png>
+<img src="https://quickpeek.co/logo.png" alt="QuickPeek" width="220">
 
 **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]
+![MIT](https://img.shields.io/badge/License-MIT-blueviolet?style=flat-square)
 
 [![Listed on Sellular](https://sellular.online/badge/quickpeek.svg)](https://sellular.online/badge/quickpeek/go)
 
@@ -25,18 +19,36 @@
 
 ## Quick Start
 
+Nothing to install:
+
+```bash
+npx @spark-apps/quickpeek https://your-app.com
+```
+
+Or install it for repeat use:
+
 ```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)
+**Requirements:** [ffmpeg](https://ffmpeg.org/download.html). Nothing else. The AI
+runs through QuickPeek's hosted relay, so there is no API key to get.
+
+**Free tier:** 5 videos on an unconfirmed email, then 10 a day once you confirm
+it. No card either way. The CLI asks for an address on the first run because the
+AI planner runs on our servers and is metered per account; over
+[MCP](#mcp-server) no account is needed at all, because your own model does the
+writing. A free video of 20 seconds or under comes out clean; a longer free video
+carries a QuickPeek watermark. The hosted web recorder at quickpeek.co is
+deliberately different: there, free videos are capped at 20 seconds and are
+always watermarked. https://quickpeek.co/pricing sets the two side by side.
 
 ## Features
 
 | Feature | Description |
 |---------|-------------|
-| **AI Planning** | Groq AI analyzes your app and generates demo steps |
+| **AI Planning** | 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 |
@@ -47,13 +59,13 @@ qp localhost:3000
 
 ## Examples
 
-### Basic — AI generates the plan
+### Basic: AI generates the plan
 
 ```bash
 qp localhost:3000
 ```
 
-### Script mode — you write the narration
+### Script mode: you write the narration
 
 ```bash
 qp localhost:3000 --script narration.txt
@@ -63,12 +75,12 @@ Script file format (one caption per line, `#` for comments):
 
 ```
 # My app demo
-We start on the dashboard — your main workspace.
+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
+### Capture mode: record your own interactions
 
 ```bash
 qp capture localhost:3000
@@ -122,7 +134,7 @@ Config is auto-generated on first run. Edit `quickpeek.config.json` to customize
 | `pt` | Portuguese | `hi` | Hindi |
 | `it` | Italian | `ru` | Russian |
 
-See `src/voices.ts` for all 60+ supported languages.
+The full list comes back from the `list_voices` tool on the MCP server.
 
 </details>
 
@@ -131,8 +143,6 @@ See `src/voices.ts` for all 60+ supported languages.
 
 Edit `captions.css` (auto-generated) to customize:
 
-![Classic Yellow](imgs/caption-classic.png)
-
 ```css
 .caption {
   font-family: Arial, sans-serif;
@@ -177,6 +187,40 @@ Edit `demo/plan.json` to customize your demo. Each step uses one of these action
 
 **Target shortcuts:** For buttons and links, use simplified text like `"download"` or `"extract frame"` instead of CSS selectors.
 
+## MCP Server
+
+QuickPeek ships an MCP server (`quickpeek-mcp`) so an AI agent can record a demo
+directly, with no shelling out to the CLI.
+
+```bash
+claude mcp add quickpeek -- npx -y --ignore-scripts --package=@spark-apps/quickpeek quickpeek-mcp
+```
+
+Or add it by hand, for any MCP client:
+
+```json
+{
+  "mcpServers": {
+    "quickpeek": {
+      "command": "npx",
+      "args": ["-y", "--ignore-scripts", "--package=@spark-apps/quickpeek", "quickpeek-mcp"]
+    }
+  }
+}
+```
+
+Published on the [official MCP registry](https://registry.modelcontextprotocol.io)
+as `co.quickpeek/quickpeek`.
+
+**9 tools:** `generate_demo`, `generate_demo_from_script`, `list_demos`,
+`get_demo_config`, `list_voices`, `open_in_editor`, `check_account`, and the
+`start_auth` / `finish_auth` pair for recording an app you have to log into.
+
+The server never calls an AI itself. It hands the planning and narration prompts
+back to you, the calling model, and takes your answer as a parameter, so a demo
+costs you no QuickPeek quota and no second-rate model. That is also why this path
+needs no account at all for the first 5 videos, where the CLI asks for an email.
+
 ## Output
 
 | File | Description |
@@ -190,12 +234,10 @@ Edit `demo/plan.json` to customize your demo. Each step uses one of these action
 
 ## 🌱 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]
+🎬 **See it work** - [Watch a demo](https://www.youtube.com/shorts/HaibrNvJknY)  
+🐛 **Found a bug or want a feature?** Email [support@quickpeek.co](mailto:support@quickpeek.co) - the repo is private, so email is the way in.
 
 <div align="center">
 

package/dist/assets/music/manifest.json

@@ -16,7 +16,7 @@
       "artist": "HoliznaCC0",
       "license": "CC0 1.0 Universal",
       "source": "https://freemusicarchive.org/music/holiznacc0/background-music",
-      "mood": "gentle",
+      "mood": "corporate",
       "duration": 91.777
     },
     {

package/dist/index.d.mts

@@ -1,17 +1,11 @@
-import { U as UserTier, C as CaptionStyle, a as CaptionPosition, b as Config, V as VoiceRate } from './voices-CPpnWn39.mjs';
-export { A as AIError, c as AIResponse, d as AIResult, e as CLI_BACKOFF_MS, f as CONFIG_FILE, g as CaptionPreset, h as CaptionWordStyle, i as ChatOptions, D as DEFAULT_CAPTIONS, j as DEFAULT_CONFIG, E as EXCLUDED_LINK_PATTERNS, k as ElementInfo, l as ElementType, H as HighlightMode, I as INTERACTIVE_SELECTORS, m as INTERNATIONAL_VOICE, N as NO_CLIP_OUTRO, P as PLAN_MAX_TOKENS, n as Plan, R as RATE_FACTOR, o as RateLimitInfo, p as RetryNotice, S as SERVER_BACKOFF_MS, q as SIZE_PRESETS, r as SparkStatus, s as SparkSubscription, t as SparkTrial, u as Step, v as SuggestedAction, T as Tier, w as VERSION, x as VIDEO_PROFILES, y as VideoProfileName, z as VideoSize, B as VoiceGender, F as applyProfile, G as ariaLabelSelector, J as buildSystemPrompt, K as buildUserPrompt, L as callAI, M as callAIViaRelay, O as crawlPage, Q as deStock, W as defaultCaptionsFor, X as getErrorMessage, Y as getLanguageName, Z as getStatus, _ as getStatusCached, $ as getTierByEmail, a0 as gotoSettled, a1 as hasTrialRemaining, a2 as hasVoice, a3 as idSelector, a4 as internationalVoiceFor, a5 as isCanceling, a6 as isExcludedLink, a7 as isPaid, a8 as isVerified, a9 as normalizeUrl, aa as parseAIPlanResponse, ab as parsePartial, ac as pricingUrl, ad as rgbaToHex, ae as runPooled, af as shouldSkipLink, ag as showPaywall, ah as stripLongDashes, ai as toTitleCase, aj as voiceFor, ak as waitForPlaceholdersGone } from './voices-CPpnWn39.mjs';
+import { U as UserTier, C as CaptionStyle, a as CaptionPosition, b as Config, V as VoiceRate } from './voices-5AFt1GDp.mjs';
+export { A as AIError, c as AIResponse, d as AIResult, e as CLI_BACKOFF_MS, f as CONFIG_FILE, g as CaptionPreset, h as CaptionWordStyle, i as ChatOptions, D as DEFAULT_CAPTIONS, j as DEFAULT_CONFIG, E as EXCLUDED_LINK_PATTERNS, k as ElementInfo, l as ElementType, H as HighlightMode, I as INTERACTIVE_SELECTORS, m as INTERNATIONAL_VOICE, N as NO_CLIP_OUTRO, P as PLAN_MAX_TOKENS, n as Plan, R as RATE_FACTOR, o as RELAY_BASE, p as RateLimitInfo, q as RetryNotice, S as SERVER_BACKOFF_MS, r as SIZE_PRESETS, s as SparkStatus, t as SparkSubscription, u as SparkTrial, v as Step, w as SuggestedAction, T as Tier, x as VERSION, y as VIDEO_PROFILES, z as VideoProfileName, B as VideoSize, F as VoiceGender, G as applyProfile, J as ariaLabelSelector, K as buildSystemPrompt, L as buildUserPrompt, M as callAI, O as callAIForPlan, Q as callAIViaRelay, W as crawlPage, X as deStock, Y as defaultCaptionsFor, Z as getErrorMessage, _ as getLanguageName, $ as getOrRefreshRelayToken, a0 as getStatus, a1 as getStatusCached, a2 as getTierByEmail, a3 as gotoSettled, a4 as hasTrialRemaining, a5 as hasVoice, a6 as idSelector, a7 as internationalVoiceFor, a8 as isCanceling, a9 as isExcludedLink, aa as isPaid, ab as isVerified, ac as normalizeUrl, ad as parseAIPlanResponse, ae as parsePartial, af as pricingUrl, ag as rgbaToHex, ah as runPooled, ai as shouldSkipLink, aj as showPaywall, ak as stripLongDashes, al as toTitleCase, am as voiceFor, an as waitForPlaceholdersGone } from './voices-5AFt1GDp.mjs';
 export { MALE_VOICES, MULTILINGUAL_VOICES, WIDE_VOICES, hexToAss as hexToASS, windowsDrivePathToWsl as windowsPathToWSL } from '@spark-apps/video-kit';
 import 'playwright';
 
 /**
- * Billing utilities — watermark decisions and upgrade URL generation
+ * Billing utilities — upgrade URL generation
  */
-
-/**
- * Check if watermark should be applied
- * Watermark applies to free tier videos longer than 20 seconds
- */
-declare function shouldWatermark(tier: UserTier, videoDurationSeconds: number): boolean;
 /**
  * Get upgrade URL for pricing page
  */
@@ -73,6 +67,38 @@ interface ComposeOptions {
     stepTransitions?: StepTransition[] | undefined;
     /** 'off' pins the deliverable encode to libx264; anything else probes for a GPU. */
     hwaccel?: 'auto' | 'off' | undefined;
+    /**
+     * The tempo pass that will run AFTER this compose, if any.
+     *
+     * That pass speeds the finished file up, and it cannot tell a narrator from
+     * a song: a demo scored with a track came out with the music playing 1.2x,
+     * which is audible on anything with a beat and is simply wrong - the voice
+     * is what the pacing is for. The bed is laid down pre-slowed by the same
+     * factor here, so the later speed-up returns it to its natural tempo.
+     * atempo preserves pitch in both directions, so the round trip is a tempo
+     * change and not a transposition. 1 (the default) changes nothing.
+     */
+    tempo?: number | undefined;
+    /**
+     * Where the music bed starts, in seconds on this compose's timeline.
+     *
+     * 0 (the default) scores the whole video. Set to the closing card's start
+     * and the demo plays dry, with the song arriving as the card does - which
+     * is what you want when the track is the product's own and is meant to be
+     * heard rather than ducked under a narrator for a minute first.
+     */
+    musicStartSecs?: number | undefined;
+    /**
+     * Length of the music file, in seconds, so its END can be landed on the
+     * video's end.
+     *
+     * A song has an ending, and a song cut off two thirds through does not: it
+     * stops. Given the track's length, the bed is seeked so that its last note
+     * falls on the last frame, which is what makes a closing card feel closed
+     * rather than interrupted. Omitted, the bed plays from its beginning as
+     * before.
+     */
+    musicDurationSecs?: number | undefined;
 }
 interface ConcatVideoOptions {
     inputPath: string;
@@ -821,6 +847,19 @@ declare function resolveRate(config: Config): VoiceRate;
  * engine to unescape an entity it may not have escaped itself.
  */
 declare function speakSymbols(text: string): string;
+/**
+ * A caption as the voice should receive it.
+ *
+ * Order is load-bearing and each pass documents why above it: symbols before
+ * anything (a bare "&" invalidates the SSML), domains before toSpokenForm
+ * (matching "vidlet dot app" cannot tell an address from prose), acronyms
+ * after (so a TLD spelled here is not re-spelled), numbers last.
+ *
+ * Exported so the shaping can be asserted directly. It used to be one inline
+ * expression, which meant the only way to test a pronunciation was to
+ * re-create the chain in the test and hope it stayed in step.
+ */
+declare function spokenForm(caption: string): string;
 declare function generateVoiceover(steps: TTSStep[], config: Config, workDir: string, outputDir: string, logError: (context: string, error: unknown) => Promise<void>, task: (text: string) => {
     succeed: (text?: string) => void;
 }, info: (text: string) => void): Promise<AudioResult>;
@@ -904,4 +943,4 @@ declare function buildWatermarkFilters(opts: {
     endsOnCreditsCard?: boolean;
 }): string;
 
-export { type ApplyTransitionsOptions, type AudioResult, type BlendTransition, CURSOR_CSS, CURSOR_PNG, CURSOR_SCRIPT, type CaptionCue, CaptionPosition, type CaptionRenderContext, CaptionStyle, type ComposeOptions, type ConcatVideoOptions, Config, EMPTY_SPAN_SPEED, GIF_DEFAULTS, type GifOptions, type LenientParse, MUSIC_BED_LUFS, NARRATION_LEAD_IN_MS, type SilenceSpan, type SpeedUpOptions, type SpliceVideosOptions, type SpokenWord, type StepAudio, type StepSync, type StepTransition, TRIM_EDGE_SILENCE, type TTSStep, type TimeSegment, UserTier, VOICE_LEAD_MS, type VideoOverlay, VoiceRate, type VoiceoverMeta, type WordTiming, alignVoiceoverToRecording, alignWordsToCaption, applyTransitions, atempoChain, buildCompressionFilter, buildConcatArgs, buildGifArgs, buildKeepSegments, buildPaletteArgs, buildRetimeFilter, buildStepTransitions, buildWatermarkFilters, canReuseVoiceover, captionCanvas, composeVideo, compressSilentSpans, concatMedia, concatVideoWithFullFrameOutro, concatVideoWithOutro, convertToGif, coverFilterChain, cutSpansFromVideo, detectBlackSpans, detectFrozenSpans, detectSilences, detectWhiteSpans, estimateWordTimings, extractJsonCandidates, generateASSHeader, generateSilence, generateVoiceover, getAudioCodec, getMediaDuration, getUpgradeUrl, getVideoDimensions, getVideoStreamDuration, hasAudioStream, intersectSpans, isHonestWav, loadExistingVoiceover, loadVoiceoverMeta, mapTimestampsAfterCompression, mergeSpans, parseAIJson, parseWordBoundaries, positionToAlignment, registerFreeUser, renderCaptionsAss, repairUnicodeEscapes, resetVoiceEngine, resolveCaptionFont, resolveCaptions, resolveRate, resolveVoice, retimeSpansInVideo, salvageTruncatedJson, shouldWatermark, speakSymbols, speedUpMiddle, speedUpVideo, spliceVideos, spokenWordTimings, synthesizeSpeech, trimEdgeSilence };
+export { type ApplyTransitionsOptions, type AudioResult, type BlendTransition, CURSOR_CSS, CURSOR_PNG, CURSOR_SCRIPT, type CaptionCue, CaptionPosition, type CaptionRenderContext, CaptionStyle, type ComposeOptions, type ConcatVideoOptions, Config, EMPTY_SPAN_SPEED, GIF_DEFAULTS, type GifOptions, type LenientParse, MUSIC_BED_LUFS, NARRATION_LEAD_IN_MS, type SilenceSpan, type SpeedUpOptions, type SpliceVideosOptions, type SpokenWord, type StepAudio, type StepSync, type StepTransition, TRIM_EDGE_SILENCE, type TTSStep, type TimeSegment, UserTier, VOICE_LEAD_MS, type VideoOverlay, VoiceRate, type VoiceoverMeta, type WordTiming, alignVoiceoverToRecording, alignWordsToCaption, applyTransitions, atempoChain, buildCompressionFilter, buildConcatArgs, buildGifArgs, buildKeepSegments, buildPaletteArgs, buildRetimeFilter, buildStepTransitions, buildWatermarkFilters, canReuseVoiceover, captionCanvas, composeVideo, compressSilentSpans, concatMedia, concatVideoWithFullFrameOutro, concatVideoWithOutro, convertToGif, coverFilterChain, cutSpansFromVideo, detectBlackSpans, detectFrozenSpans, detectSilences, detectWhiteSpans, estimateWordTimings, extractJsonCandidates, generateASSHeader, generateSilence, generateVoiceover, getAudioCodec, getMediaDuration, getUpgradeUrl, getVideoDimensions, getVideoStreamDuration, hasAudioStream, intersectSpans, isHonestWav, loadExistingVoiceover, loadVoiceoverMeta, mapTimestampsAfterCompression, mergeSpans, parseAIJson, parseWordBoundaries, positionToAlignment, registerFreeUser, renderCaptionsAss, repairUnicodeEscapes, resetVoiceEngine, resolveCaptionFont, resolveCaptions, resolveRate, resolveVoice, retimeSpansInVideo, salvageTruncatedJson, speakSymbols, speedUpMiddle, speedUpVideo, spliceVideos, spokenForm, spokenWordTimings, synthesizeSpeech, trimEdgeSilence };