@spark-apps/quickpeek 1.2.3 → 1.2.5

package/dist/index.d.mts

@@ -1,16 +1,11 @@
-import { U as UserTier, C as Config } from './scraping-C334VxX5.mjs';
-export { A as AIError, a as AIResponse, b as AIResult, c as CLI_BACKOFF_MS, d as CONFIG_FILE, e as CaptionStyle, f as CaptionWordStyle, g as ChatOptions, D as DEFAULT_CAPTIONS, h as DEFAULT_CONFIG, E as EXCLUDED_LINK_PATTERNS, i as ElementInfo, j as ElementType, F as FEATURES, H as HighlightMode, I as INTERACTIVE_SELECTORS, P as Plan, R as RateLimitInfo, k as RetryNotice, S as SERVER_BACKOFF_MS, l as SparkStatus, m as SparkSubscription, n as SparkTrial, o as Step, p as SuggestedAction, T as Tier, V as VERSION, q as buildSystemPrompt, r as buildUserPrompt, s as callAI, t as callAIViaRelay, u as crawlPage, v as getErrorMessage, w as getLanguageName, x as getStatus, y as getStatusCached, z as getTierByEmail, B as hasAccess, G as hasTrialRemaining, J as idSelector, K as isCanceling, L as isExcludedLink, M as isPaid, N as isVerified, O as normalizeUrl, Q as parseAIPlanResponse, W as parsePartial, X as pricingUrl, Y as rgbaToHex, Z as shouldSkipLink, _ as showPaywall, $ as toTitleCase } from './scraping-C334VxX5.mjs';
-export { WIDE_VOICES as LANGUAGE_VOICES, hexToAss as hexToASS, windowsDrivePathToWsl as windowsPathToWSL } from '@spark-apps/video-kit';
+import { U as UserTier, C as CaptionStyle, a as CaptionPosition, b as Config, V as VoiceRate } from './voices-ufga0oOn.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 callAIViaRelay, Q as crawlPage, W as deStock, X as defaultCaptionsFor, Y as getErrorMessage, Z as getLanguageName, _ as getOrRefreshRelayToken, $ as getStatus, a0 as getStatusCached, a1 as getTierByEmail, a2 as gotoSettled, a3 as hasTrialRemaining, a4 as hasVoice, a5 as idSelector, a6 as internationalVoiceFor, a7 as isCanceling, a8 as isExcludedLink, a9 as isPaid, aa as isVerified, ab as normalizeUrl, ac as parseAIPlanResponse, ad as parsePartial, ae as pricingUrl, af as rgbaToHex, ag as runPooled, ah as shouldSkipLink, ai as showPaywall, aj as stripLongDashes, ak as toTitleCase, al as voiceFor, am as waitForPlaceholdersGone } from './voices-ufga0oOn.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
  */
@@ -33,14 +28,27 @@ interface StepSync {
     targetDuration: number;
 }
 interface ComposeOptions {
+    /** Input 0 carries a spliced clip's own audio, to be mixed under the voice. */
+    hasClipAudio?: boolean;
     videoPath: string;
-    assPath: string;
+    /** Burn-in captions. Omit to skip the ass filter entirely (draft). */
+    assPath?: string | undefined;
     outputPath: string;
     voiceoverPath?: string | undefined;
     musicPath?: string | undefined;
     musicVolume?: number | undefined;
     musicFadeIn?: number | undefined;
     musicFadeOut?: number | undefined;
+    /**
+     * Loudness the bed is normalised to before it meets the narration, in LUFS.
+     *
+     * A fixed `musicVolume` cannot produce a consistent bed, because the source
+     * decides everything: two CC0 tracks in the same folder measure -31 dB and
+     * -15 dB mean, so the same gain makes one inaudible and the other a
+     * competitor. Normalising first makes the bed a level rather than a
+     * multiplier, and `musicVolume` goes back to being the trim it reads as.
+     */
+    musicTargetLufs?: number | undefined;
     width: number;
     height: number;
     fps: number;
@@ -53,9 +61,44 @@ interface ComposeOptions {
     contrast?: number | undefined;
     trimStart?: number | undefined;
     userTier?: UserTier | undefined;
+    endsOnCreditsCard?: boolean | undefined;
     mainContentDuration?: number | undefined;
     stepSync?: StepSync[] | undefined;
     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;
@@ -69,7 +112,27 @@ interface VideoOverlay {
     path: string;
     startTime: number;
     duration: number;
-    mode: 'stretch' | 'center';
+    /**
+     * How the source is fitted to the frame.
+     *
+     * stretch = fill the frame's width, crop the height if it overflows.
+     * center  = scale to fit, letterbox the rest.
+     * cover   = fill the frame with a blurred, enlarged copy of the source and
+     *           sit the source itself on top of it, untouched. A 1200x630 OG
+     *           card in a 9:16 frame is 16:9 either way; the only question is
+     *           what fills the two thirds of the frame it cannot reach, and a
+     *           blurred continuation of the card reads as design where a black
+     *           band reads as a mistake.
+     */
+    mode: 'stretch' | 'center' | 'cover';
+    /**
+     * The source is a still image (png/jpg/webp), not a clip.
+     *
+     * A still has exactly one frame, so it has to be looped for the length of
+     * its window or the overlay holds a single frame at EOF and the window
+     * plays whatever is underneath it.
+     */
+    still?: boolean;
     trimStart?: number;
     trimEnd?: number;
 }
@@ -105,6 +168,34 @@ interface TimeSegment {
     end: number;
 }
 
+/**
+ * A beat of silence before the narrator starts, in milliseconds.
+ *
+ * The voice used to be faded in over the same duration as the picture, which
+ * ate the first syllable - and the first syllable belongs to the hook, the one
+ * line that has to land. A short delay gives the viewer the same moment to
+ * settle without softening the words.
+ */
+declare const VOICE_LEAD_MS = 200;
+/**
+ * Loudness the music bed is normalised to before the mix, in LUFS.
+ *
+ * Measured, not guessed. Running this exact graph over the accordio
+ * narration puts the bed at -26.7 dB mean in a gap between lines while the
+ * speech measures -13.7 dB: thirteen dB under the voice, which is a bed. Each
+ * dB here moves that reading a dB, so the number is a real control - -38 gives
+ * -30.6, -42 gives -34.7.
+ *
+ * Over a long passage with no narration at all - the closing card - the master
+ * chain's single-pass loudnorm is dynamic and opens up, and the bed rises to
+ * about -18 dB. That is the intended shape: discreet under the voice, present
+ * where there is nothing else.
+ *
+ * What it replaced measured -39 dB at source and -45 dB after its own volume
+ * trim, and read in the finished file at -32 dB against -15 dB of speech.
+ * That is not a quiet bed, it is no bed: the video was speech in a vacuum.
+ */
+declare const MUSIC_BED_LUFS = -34;
 /**
  * Compose final video with subtitles, voiceover, and music
  */
@@ -120,6 +211,45 @@ declare function buildKeepSegments(eventTimestampsSeconds: number[], totalDurati
  */
 declare function mapTimestampsAfterCompression(originalTimestampsSeconds: number[], segments: TimeSegment[]): number[];
 
+/**
+ * Video → optimized GIF conversion (ported from VidLet's togif tool).
+ * Two-pass: generate a tuned palette, then map the video through it —
+ * dramatically better colour than ffmpeg's default 256-colour GIF path.
+ */
+interface GifOptions {
+    input: string;
+    output: string;
+    fps?: number;
+    width?: number;
+    dither?: string;
+    statsMode?: string;
+}
+declare const GIF_DEFAULTS: {
+    readonly fps: 15;
+    readonly width: 480;
+    readonly dither: "sierra2_4a";
+    readonly statsMode: "full";
+};
+declare function buildPaletteArgs(input: string, palettePath: string, fps: number, width: number, statsMode: string): string[];
+declare function buildGifArgs(input: string, palettePath: string, output: string, fps: number, width: number, dither: string): string[];
+declare function convertToGif(options: GifOptions): Promise<string>;
+
+/**
+ * The video stream's pixel dimensions.
+ *
+ * Needed because the splice pass scales its overlays to match the video it is
+ * pasting them onto, and that video is the raw recording, which is smaller
+ * than the configured output whenever video.zoom is in play: a short records
+ * at 540x960 and is upscaled to 1080x1920 only at compose. Scaling overlays to
+ * the output size instead put them in at 2x and cropped everything but the
+ * middle of each card.
+ */
+declare function getVideoDimensions(filePath: string): Promise<{
+    width: number;
+    height: number;
+}>;
+/** Whether a file carries an audio stream at all. */
+declare function hasAudioStream(filePath: string): Promise<boolean>;
 /**
  * Run ffprobe to get media duration in milliseconds
  */
@@ -146,6 +276,22 @@ declare function isHonestWav(filePath: string): Promise<boolean>;
  */
 declare function buildConcatArgs(listPath: string, output: string): string[];
 declare function concatMedia(listPath: string, output: string): Promise<void>;
+/**
+ * Strip the silence a TTS engine leaves on both ends of a clip.
+ *
+ * Every edge-tts clip arrives with its own lead-in and tail, typically a few
+ * hundred ms each. One clip per caption, concatenated, means each boundary
+ * stacks tail + the pad that aligns the step + the next clip's lead-in - the
+ * "robotic pause" between sentences. Trimming here rather than at concat time
+ * keeps the clip the unit of truth: the duration measured after this call,
+ * the padding computed from it, and the word timings rebased in
+ * spokenWordTimings all describe the same audio.
+ *
+ * -45dB rather than a hard zero: edge-tts pads with near-silent noise, not
+ * digital black, so a stricter gate finds nothing to remove.
+ */
+declare const TRIM_EDGE_SILENCE: string;
+declare function trimEdgeSilence(filePath: string): Promise<void>;
 /**
  * Generate silence audio file of specified duration
  */
@@ -160,6 +306,262 @@ declare function speedUpVideo(opts: SpeedUpOptions): Promise<void>;
  * Returns the combined video for further processing (composition with audio)
  */
 declare function concatVideoWithOutro(opts: ConcatVideoOptions): Promise<void>;
+/**
+ * Append an outro that is already a full frame, unchanged.
+ *
+ * concatVideoWithOutro treats its outro as a badge: it shrinks it to 60% and
+ * overlays it on black, which is right for the bundled square watermark and
+ * wrong for a rendered credits card, which is composed at the video's exact
+ * size and must not be shrunk inside its own frame.
+ *
+ * setsar on both inputs because concat refuses streams whose sample aspect
+ * ratios disagree, and a card rendered by the browser does not necessarily
+ * carry the same SAR as a recorded page.
+ */
+declare function concatVideoWithFullFrameOutro(opts: ConcatVideoOptions): Promise<void>;
+
+/**
+ * Compressing dead air out of a finished demo.
+ *
+ * A step whose narration ends before the step does leaves the video sitting
+ * on a still frame with nothing being said - padding that keeps audio and
+ * video in sync, plus any deliberate hold while an async result loads. Held
+ * for a second it reads as a beat; held for five it reads as a hang.
+ *
+ * This runs AFTER compose on purpose. By then the captions are burned in and
+ * the silent spans have none on screen (a karaoke line ends with its last
+ * word), so speeding those spans up removes the dead time without touching
+ * caption timing, the recorder, or the TTS timeline - the three things that
+ * have to agree with each other. What is sped up is silence, so it is
+ * inaudible, and the visuals still play through: a result that appears during
+ * a hold is still seen, just briskly.
+ */
+/** A silent stretch of the mixed audio, in seconds. */
+interface SilenceSpan {
+    start: number;
+    end: number;
+    /** Longest this span may run after compression. Defaults to the pass's cap. */
+    cap?: number;
+}
+/**
+ * Length of the video stream in seconds, or 0 if it cannot be read.
+ *
+ * Distinct from the container's duration, which reports whichever stream runs
+ * longest - usually the audio, since compose pads it to the voiceover.
+ */
+declare function getVideoStreamDuration(inputPath: string): Promise<number>;
+declare function detectSilences(inputPath: string, minDurSecs: number): Promise<SilenceSpan[]>;
+/**
+ * Find stretches where the picture stops changing.
+ *
+ * Silence is not the only kind of dead air. A page that finishes an animation
+ * - a confetti burst settling, a spinner resolving - holds a still frame for
+ * as long as the step is paced to last, and that reads as a hang even with
+ * narration over it. freezedetect reports those stretches; they are treated
+ * like silence, and for the same reason.
+ */
+declare function detectFrozenSpans(inputPath: string, minDurSecs: number): Promise<SilenceSpan[]>;
+/**
+ * Spans where the picture is essentially black.
+ *
+ * A frozen span and a black span are not the same thing, and the difference
+ * matters. A frozen span is a still screen: the viewer is looking at something,
+ * so it earns the FROZEN_MAX_SECS ceiling and gets shortened, not cut. A black
+ * span is a page mid-transition, and it is worth nothing at any length. One run
+ * shipped 9.4 seconds of it in a 75 second video.
+ *
+ * Playwright records continuously and cannot be paused across a navigation, so
+ * these frames cannot be prevented at capture time. They are removed here
+ * instead, and only where the audio is silent too, so no narration is ever cut.
+ */
+declare function detectBlackSpans(inputPath: string, minDurSecs: number): Promise<SilenceSpan[]>;
+/**
+ * Spans where the picture is essentially white.
+ *
+ * blackdetect over an inverted picture. A page that flashes white between
+ * routes is as empty as one that flashes black, and a light-themed app makes
+ * white the common case, so detecting only one of the two fixes half the sites.
+ */
+declare function detectWhiteSpans(inputPath: string, minDurSecs: number): Promise<SilenceSpan[]>;
+/**
+ * Where two sets of spans overlap.
+ *
+ * A frozen picture is only safe to speed up while nothing is being said over
+ * it - rushing a still frame is free, rushing a sentence is not. The overlap
+ * of "frozen" and "silent" is exactly the footage with nothing happening in
+ * either channel.
+ */
+declare function intersectSpans(a: SilenceSpan[], b: SilenceSpan[]): SilenceSpan[];
+/** Fold overlapping or touching spans into one. */
+declare function mergeSpans(spans: SilenceSpan[]): SilenceSpan[];
+/** atempo caps at 2x per instance, so a bigger speed-up is a chain of them. */
+declare function atempoChain(factor: number): string;
+/**
+ * Build the filter_complex that plays `spans` fast and the rest untouched.
+ *
+ * Split out from the run so the graph can be unit-tested: an ffmpeg filter
+ * error surfaces as a wall of text at render time, which is a bad place to
+ * discover an off-by-one in the segment list.
+ */
+declare function buildCompressionFilter(spans: SilenceSpan[], totalSecs: number, maxSecs: number, protectAfterSecs?: number, 
+/**
+ * Everything BEFORE this is the opening card, protected for the same reason
+ * as the closing one and previously not protected at all.
+ *
+ * It did not need to be while the intro card was narrated over: a spoken
+ * card is not a silent span. A card prepended as its own step has no
+ * narration, so it is silent AND frozen, and this pass gave it the frozen
+ * ceiling of 0.6s - a title card gone before it can be read.
+ */
+protectBeforeSecs?: number): string | null;
+/**
+ * Drop spans from a silent video, in its own timeline.
+ *
+ * The recording has no audio yet, so there is nothing to desync: this is the
+ * one place in the pipeline where a span can simply be deleted. Doing it here
+ * rather than after compose also avoids the coordinate problem that made an
+ * earlier attempt a no-op. A recording is 145s where its composed video is
+ * 74s, because compose trims the page load off the front and the later passes
+ * squeeze the rest, so a span measured during recording means nothing once
+ * those have run.
+ */
+declare function cutSpansFromVideo(inputPath: string, outputPath: string, spans: Array<{
+    start: number;
+    end: number;
+}>, preset: string): Promise<boolean>;
+/**
+ * How much faster a loading screen plays than the footage around it.
+ *
+ * The empty stretches in a recording are almost always one thing: the app's
+ * own splash while a route loads. A sellular run spent 17 of its 66 seconds
+ * on that screen. Five is fast enough that it reads as a flicker rather than
+ * a wait, and slow enough that the logo is still legible going past.
+ */
+declare const EMPTY_SPAN_SPEED = 5;
+/**
+ * Build the filter that removes every empty span from view without changing
+ * how long anything lasts, one step at a time.
+ *
+ * The point of doing it per step is that every step boundary comes out exactly
+ * where it went in. Cutting empty frames is the obvious move and it does not
+ * work: the narration for each step is already synthesised at a fixed length,
+ * so shortening the picture under it desyncs everything downstream, and the
+ * guard that stops that from happening starves the cut until it removes
+ * nothing at all. So the seconds are not removed, they are re-spent.
+ *
+ * A step with real footage either side of the splash plays the splash at
+ * `speed` and stretches that footage to fill exactly what it freed. A step
+ * that is nearly all splash - a route whose loading screen outlasts the line
+ * narrated over it - has nothing to stretch, so the splash is replaced by a
+ * still of the page that arrives after it. Both leave the step the length it
+ * was, and neither leaves an empty screen up.
+ *
+ * Returns null when there is nothing worth doing, so the caller can skip a
+ * re-encode that would change nothing.
+ */
+declare function buildRetimeFilter(spans: Array<{
+    start: number;
+    end: number;
+}>, stepBounds: Array<{
+    from: number;
+    to: number;
+}>, speed: number, fps: number): string | null;
+/**
+ * Play the empty stretches of a silent recording fast, keeping every step the
+ * length it was.
+ *
+ * Resolves false when the filter had nothing to do or ffmpeg refused it, and
+ * the caller keeps the original recording.
+ */
+declare function retimeSpansInVideo(inputPath: string, outputPath: string, spans: Array<{
+    start: number;
+    end: number;
+}>, stepBounds: Array<{
+    from: number;
+    to: number;
+}>, speed: number, fps: number, preset: string): Promise<boolean>;
+declare function compressSilentSpans(inputPath: string, outputPath: string, totalSecs: number, maxSecs: number, preset: string, protectAfterSecs?: number, 
+/**
+ * The narration on its own, when there is one.
+ *
+ * Silence has to be measured against the voice, not against the mix: any
+ * backing track - a music bed, room tone - is continuous by design, so a
+ * mixed file has no silence in it at all and every pause looks like speech.
+ */
+narrationPath?: string, 
+/** Opening card to leave alone, in seconds from the start. See the filter. */
+protectBeforeSecs?: number, 
+/**
+ * Spans the recorder KNOWS were a page loading rather than a page showing.
+ *
+ * Cut on the recorder's word, not on a detector's guess. blackdetect cannot
+ * tell a loading screen from a dark-themed app, and the silence guard
+ * refuses to cut anything with a voice over it, which is exactly the case
+ * here: the narration describing a result is queued behind the wait for it.
+ * The recorder measured this span, so it needs no evidence.
+ */
+leadSpans?: Array<{
+    start: number;
+    end: number;
+}>, 
+/**
+ * Spans that are playing CONTENT, however quiet they are.
+ *
+ * A clip spliced in under no narration is silent by nature and frozen to a
+ * freeze detector between cuts, so every heuristic here reads it as dead
+ * air and compresses it to the ceiling. A nine-second demo arrived as
+ * three-quarters of a second. Silence during a clip is the clip, not a
+ * hang, so these spans are removed from the compression list outright.
+ */
+keepSpans?: Array<{
+    start: number;
+    end: number;
+}>): Promise<boolean>;
+/**
+ * Speed up only the middle of a video, leaving its ends untouched.
+ *
+ * A demo opens on a title card and closes on a credits card. Speeding the
+ * whole file to fit a length limit rushes both: the card the viewer is meant
+ * to read, and the offer they are meant to write down. Only the demo between
+ * them is compressible.
+ *
+ * Returns false when the ends already fill the budget - there is nothing to
+ * squeeze then, and the honest answer is a shorter plan.
+ */
+declare function speedUpMiddle(inputPath: string, outputPath: string, totalSecs: number, targetSecs: number, introSecs: number, outroSecs: number, maxFactor: number, preset: string): Promise<{
+    ok: boolean;
+    factor: number;
+    reachedTarget: boolean;
+}>;
+
+/**
+ * Fill the frame with the card's own colours, then lay the card on it.
+ *
+ * A 1200x630 OG card is the shape every site publishes and the wrong shape for
+ * a 9:16 opening: centred, it floats in two thirds of a frame of flat #1a1a2e,
+ * which is what "letterboxed with dead space" looks like. Cropping it to fill
+ * instead would throw away the half of the card the headline is written
+ * across. So the backdrop is built from the card itself - the frame is full,
+ * the colours are the card's own, and not a pixel of the card is lost.
+ *
+ * The backdrop is RESAMPLED DOWN to a handful of pixels before it is blown
+ * back up, rather than blurred at full resolution. Blur is the obvious move
+ * and it is wrong here, because an OG card is mostly TYPE: a 1200px-wide
+ * headline enlarged 3x stays legible through sigma=28, so the opening frame
+ * showed the same words twice - huge and soft behind the card, sharp on it.
+ * That reads as a rendering fault rather than a design, and it was the first
+ * thing anyone saw of the product.
+ *
+ * Ten pixels of height cannot carry a glyph, so nothing survives to be read
+ * while the card's colour field does. The gblur afterwards only takes the
+ * blockiness off the upscale.
+ *
+ * The downscale is its own `scale` with BOTH dimensions given. `scale=40:-2`
+ * is silently ignored at these sizes - the first attempt at this looked
+ * completely unchanged because of it, which is why the test asserts the
+ * literal pair rather than just "smaller than the frame".
+ */
+declare function coverFilterChain(inputIdx: number, width: number, height: number): string;
 
 /**
  * Splice video files into the recording at specific timestamps
@@ -248,32 +650,6 @@ interface LenientParse<T> {
  */
 declare function parseAIJson<T>(content: string): LenientParse<T> | null;
 
-declare const CURSOR_CSS = "\n  #qp-cursor {\n    position: fixed;\n    width: 32px;\n    height: 38px;\n    background: url(\"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAMgAAAEsBAMAAAB01OGNAAAAIGNIUk0AAHomAACAhAAA+gAAAIDoAAB1MAAA6mAAADqYAAAXcJy6UTwAAAAtUExURUdwTAAAAAAAAAAAAAAAAAAAAAAAAB0dHVZWVtvb2/X19f///6mpqXV1df////vm1ewAAAAGdFJOUwAltTfpcLO208EAAAABYktHRA5vvTBPAAAAB3RJTUUH6QwFFREKplBWTAAABqdJREFUeNq93c+OFFUUx/EeCHud6H7A4HpCOu6NiWsWZh5Ax8YFbAdNWBPxBcCo+yGjD+CAW1ywh0Rexu6uulX3Vp269/c7f7o3Bpjhk6+H6TrU0LdXR6sDPI4/OgCyvn0I5NsDpKw3B0hZbw6Qst4cIGWLxKdskfiUHRKeskPCU/ZIdMoeiU7pkOCUDglO6ZHYlB6JTUlIaEpCQlMGJDJlQCJTRiQwZUQCUzIkLiVD4lJyJCwlR8JSCiQqpUCiUkokKKVEglImSEzKBIlJmSIhKT3yY2hKjzx7GpnSI7+8iExJyN+RKQl5FZkyIJEpAxKZMiKBKSMSmJIhcSkZEpeSI2EpORKWUiBRKQUSlVIiQSklEpQyQWJSJkhMyhQJSZkiISkzJCJlhkSkzJGAlDkSkCIg/ikC4p8iIe4pEuKeIiLeKSLinSIjziky4pyygPimLCC+KUuIa8oS4pqyiHimLCKeKcuIY8oy4phSQfxSKohfSg1xS6khbilVxCulinil1BGnlDrilNJAfFIaiE9KC3FJaSEuKU3EI6WJeKS0EYeUNuKQAiD2FACxpyCIOQVBzCkQYk2BEGsKhhhTMMSYAiK2FBCxpaCIKQVFTCkwYkmBEUsKjhhScMSQQiD6FALRpzCIOoVB1CkUok2hEG0KhyhTOESZQiK6FBLRpbCIKoVFVCk0okmhEU0KjyhSeESRokD4FAXCp2gQOkWD0CkqhE1RIWyKDiFTdAiZokS4FCXCpWgRKkWLUClqhElRI0yKHiFS9AiRYkDwFAOCp1gQOMWCwCkmBE0xIWiKDQFTbAiYYkSwFCOCpVgRKMWKQClmBEkxI0iKHQFS7AiQ4oC0UxyQdooH0kzxQJopLkgrxQVppfggjRQfpJHihNRTnJB6ihdSTfFCqiluSC3FDaml+CGVFD+kkuKILKc4IsspnshiiieymOKKLKW4Iq8u5RRf5FpO8UUWpuKMyCnOiJzijYgp3oiY4o5IKe6IlEIhL38FHr9fzFK47/0On195PL6YpVDIX4CRP1IKhbxGSvLHbQUy/snhUrg/XW9IpE/hkOcs0qVwyD8s0qWQ349nJ9+lcAg9+S6FfFqhJ79PIZFLGtmlkMifPLJNYf/5wgWvfAYg11f5j951H39+B3/cBZA/3uY/+nccJ/5oItdPi19Lkz91RV5snuQ/fN0jJ57I9svvkTT5rzyR7RX7wW/C5L93RPbPI8Xknysmj7zWQZz8fTeke0J8aJ088vqTR1czl5t8Fel/w2Ly12/6oXghaRn8IEz+nJh8DRkuUc/yn02XYGLy0Ou0ysn3X44+/75rvNb+IE3+OxdkXM/Lr3l+8stIvjSIkz91QMaQzeYn2+QXkWL7KSafnogd/jlcHiJPHn8iXkLKNe7BW9Pk26/73T/+y3/tkp38AjLdR4vJp+XrxIhMQuRL8Jc2ZLZYF5OnL8Gt18ff6f9bTJ5dvkQku6vw6Ub4AHb5ap1ZcPS5MHn2Eiwhxe2Rs8rk0Utw8xyJ/gNMy5eAlPd5bkiTJ5ev5tkeN7+uTP6+FpncsEqTt6zd7fNWpMmTy9cMmd15+0SYPLl8tc/AuVWZPLh8TZH5LURx8unOFzb59rlEafKG5WuCSPdC0+SvhMljyxdwVtSx9DVPTb5ExPvTafIfpMmf8oh4pz1NXr92F8jCtz+kyVPLF3Km2jfdz+mXrxxZCLFPHjnnTpw8s3xlyFLIMHn18gWdPVibPLJ8jchiyPBB5eTf4ZOHzoNMky+eiInlCzrZMk1eWruR5Qs6o/NImjxxCcZOGz2rTB64BGPnpkqTJ5Yv7ARY4/LVIz9XQ4bJK5cv7FRe49oNni/cT165fIEnJdfW7vYTMXjm8w3pax6ePHh6tW35As/hltfui8ZniUglvDb55vKFno0urd3wJRg95b26dp8SSO3/rTh5dPlCT94XJ48uX/B7CKTJa5Yv+N0QLJOH39fBsnavwRBx7X75vv/kExBpftn2k38oGOAraYBnuS+6DxwvwaPRmvwaDZmt3ZkBvlwHuFBPJp8breVrjYZM1u7SaEx+jYaUk58Y58gLj5i/lO0mPzE2d4GZYPetxrWbNDoEu68wrN2ssUfAG3Bp7X7CGnsE/R7F2UZ6tI0dwt5Dpo3dJ8LfbDlWGivm3dpuKY0V875z6RLMGtw76J3pDO69ANc6Y3WPCBn+wkUaq48JY3giJg3ukU8+ysgnH2ek5SvUGCYfaaTJhxr95GONbvLRxm7y4cb2iTjeWN08gLFaaYz/AWAIeJtzdhugAAAAAElFTkSuQmCC\") no-repeat;\n    background-size: contain;\n    pointer-events: none;\n    z-index: 2147483647;\n    transform: translate(-3px, -3px);\n    transition: left 800ms ease-out, top 800ms ease-out, transform 0.08s ease-out;\n    filter: drop-shadow(1px 1px 2px rgba(0,0,0,0.3));\n  }\n  #qp-cursor.clicking {\n    transform: translate(-3px, -3px) scale(0.9);\n  }\n";
-/**
- * JavaScript to inject for cursor tracking
- */
-declare const CURSOR_SCRIPT = "\n  (function() {\n    if (document.getElementById('qp-cursor')) return;\n    const cursor = document.createElement('div');\n    cursor.id = 'qp-cursor';\n    document.body.appendChild(cursor);\n\n    document.addEventListener('mousemove', (e) => {\n      cursor.style.left = e.clientX + 'px';\n      cursor.style.top = e.clientY + 'px';\n    });\n\n    document.addEventListener('mousedown', () => cursor.classList.add('clicking'));\n    document.addEventListener('mouseup', () => cursor.classList.remove('clicking'));\n\n    // Start at center\n    cursor.style.left = window.innerWidth / 2 + 'px';\n    cursor.style.top = window.innerHeight / 2 + 'px';\n  })();\n";
-/**
- * Generate ASS subtitle file header
- */
-declare function generateASSHeader(width: number, height: number, font: string, size: number, primaryColor: string, secondaryColor: string, outlineColor: string, backColor: string, bold: boolean, outlineWidth: number, shadow: number, marginBottom: number): string;
-
-/**
- * Subscription and user registration client
- * CLI-only headless registration fallback. Tier/verification checks
- * are now in the SparkStripe gating module (getTierByEmail, isVerified).
- */
-interface RegistrationResult {
-    success: boolean;
-    pendingVerification?: boolean;
-    alreadyVerified?: boolean;
-    error?: string;
-}
-/**
- * Register user for free plan via SparkStripe
- */
-declare function registerFreeUser(email: string): Promise<RegistrationResult>;
-
 /** Minimal step shape needed by TTS modules — compatible with full Step from plan.ts */
 interface TTSStep {
     caption: string;
@@ -304,9 +680,111 @@ interface VoiceoverMeta {
     totalCaptionLength: number;
     stepCount: number;
     voice: string;
+    rate?: string;
     stepDurations: Record<number, number>;
+    stepWords?: Record<number, WordTiming[]>;
 }
 
+/**
+ * CSS and ASS styling for QuickPeek
+ */
+
+declare const CURSOR_CSS = "\n  #qp-cursor {\n    position: fixed;\n    width: 32px;\n    height: 38px;\n    background: url(\"data:image/png;base64,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\") no-repeat;\n    background-size: contain;\n    pointer-events: none;\n    z-index: 2147483647;\n    transform: translate(-3px, -3px);\n    transition: left 800ms ease-out, top 800ms ease-out, transform 0.08s ease-out;\n    filter: drop-shadow(1px 1px 2px rgba(0,0,0,0.3));\n  }\n  #qp-cursor.clicking {\n    transform: translate(-3px, -3px) scale(0.9);\n  }\n";
+/**
+ * JavaScript to inject for cursor tracking
+ */
+declare const CURSOR_SCRIPT = "\n  (function() {\n    if (document.getElementById('qp-cursor')) return;\n    const cursor = document.createElement('div');\n    cursor.id = 'qp-cursor';\n    document.body.appendChild(cursor);\n\n    document.addEventListener('mousemove', (e) => {\n      cursor.style.left = e.clientX + 'px';\n      cursor.style.top = e.clientY + 'px';\n    });\n\n    document.addEventListener('mousedown', () => cursor.classList.add('clicking'));\n    document.addEventListener('mouseup', () => cursor.classList.remove('clicking'));\n\n    // Start at center\n    cursor.style.left = window.innerWidth / 2 + 'px';\n    cursor.style.top = window.innerHeight / 2 + 'px';\n  })();\n";
+/**
+ * Generate ASS subtitle file header
+ */
+declare function generateASSHeader(width: number, height: number, font: string, size: number, primaryColor: string, secondaryColor: string, outlineColor: string, backColor: string, bold: boolean, outlineWidth: number, shadow: number, marginBottom: number, alignment?: number): string;
+/**
+ * Linux font-substitution guard (from VidLet): "Arial Black" is not installed
+ * on Linux, and fontconfig silently falls back to Noto Sans Regular with a
+ * synthesised weight. DejaVu Sans ships a real Bold face on every distro this
+ * runs on.
+ */
+declare function resolveCaptionFont(font: string): string;
+/** ASS numpad alignment: 1-3 bottom, 4-6 middle, 7-9 top. */
+declare function positionToAlignment(position: CaptionPosition, leftAligned?: boolean): number;
+/** One step's caption words, timed in absolute ms on the final video timeline. */
+interface CaptionCue {
+    words: WordTiming[];
+}
+interface CaptionRenderContext {
+    cues: CaptionCue[];
+    width: number;
+    height: number;
+    captions: CaptionStyle;
+}
+/**
+ * The coordinate space captions are drawn in, which is NOT the output size.
+ *
+ * ASS declares its own PlayResX/PlayResY and libass scales that space onto
+ * whatever frame it burns into. Handing it the real output size made every
+ * caption number mean something different at every resolution: at 360x640 a
+ * 112px font goes from 5.8% of the frame height to 17.5%, and a 300px bottom
+ * margin - the "lower third" the preset intends - lands 47% of the way up,
+ * which is dead centre over the product. So the space is pinned to the size
+ * the numbers were authored for and libass does the scaling.
+ *
+ * A 1080x1920 render is unaffected: the scale factor is exactly 1.
+ */
+declare function captionCanvas(width: number, height: number): {
+    width: number;
+    height: number;
+};
+/**
+ * The caption style a render actually uses: the canvas decides the geometry,
+ * captions.css supplies the face and the colours, `video.captions` overrides
+ * anything.
+ *
+ * The canvas wins over captions.css because the numbers in that file were
+ * never a preference. QuickPeek writes it on first run with 56px text 80px
+ * off the bottom - fine for a 16:9 tutorial, a desktop subtitle lost under
+ * the player chrome on the 9:16 short that is now the default shape - and no
+ * user ever chose those numbers. `--profile short` already overrode them for
+ * exactly this reason; the only change here is that a plain run gets the same
+ * treatment instead of depending on which command was typed.
+ *
+ * What the frame size genuinely cannot know stays with the CSS: the typeface
+ * and the colours, which are brand decisions. Anything else belongs to
+ * `video.captions` in quickpeek.config.json, which wins over both.
+ */
+declare function resolveCaptions(css: CaptionStyle, video: Config['video']): CaptionStyle;
+/** Render a complete ASS document for the configured caption preset. */
+declare function renderCaptionsAss(context: CaptionRenderContext): string;
+
+/**
+ * Subscription and user registration client
+ * CLI-only headless registration fallback. Tier/verification checks
+ * are now in the SparkStripe gating module (getTierByEmail, isVerified).
+ */
+interface RegistrationResult {
+    success: boolean;
+    pendingVerification?: boolean;
+    alreadyVerified?: boolean;
+    error?: string;
+}
+/**
+ * Register user for free plan via SparkStripe
+ */
+declare function registerFreeUser(email: string): Promise<RegistrationResult>;
+
+/**
+ * Silence before the first word.
+ *
+ * Narration that starts on frame one talks over a viewer who is still taking
+ * in the opening card, and the first syllable lands before anyone is
+ * listening. Part of the audio rather than a compose-time delay, so the
+ * captions, the step durations and the dead-air pass all measure the same
+ * timeline.
+ *
+ * Here rather than beside the code that lays it down, because the
+ * realignment pass has to know about it too and importing across those two
+ * modules the other way would close a cycle.
+ */
+declare const NARRATION_LEAD_IN_MS = 300;
 /**
  * Load existing voiceover metadata if available
  */
@@ -323,7 +801,7 @@ interface Step {
 /**
  * Check if existing voiceover can be reused
  */
-declare function canReuseVoiceover(steps: Step[], voice: string, existingMeta: VoiceoverMeta | null): {
+declare function canReuseVoiceover(steps: Step[], voice: string, rate: string, existingMeta: VoiceoverMeta | null): {
     canReuse: boolean;
     reason?: string;
 };
@@ -347,17 +825,94 @@ declare function loadExistingVoiceover(steps: Step[], outputDir: string, meta: V
 }>;
 
 declare function resolveVoice(config: Config): string | null;
+/** The narration pace for this config, as the enum the meta stores. */
+declare function resolveRate(config: Config): VoiceRate;
+/**
+ * Characters an SSML payload cannot carry.
+ *
+ * Both engines build SSML and drop the caption into it as-is, so a bare "&"
+ * makes the request invalid XML by the time the service sees it. It does not
+ * fail loudly: the Node engine returns an empty stream ("No audio data
+ * received"), the step is left with no clip, and because `stepWords` only
+ * records steps that produced words, the step vanishes from the metadata too.
+ * The video still renders - one step just has no voice.
+ *
+ * Found on Anysite's closing card, "Live Web Data for GTM & Marketing Teams":
+ * the whole closing line was silent while every other step in the same run
+ * synthesised fine. That is the worst shape a bug can take here, because the
+ * missing narration is at the end where nobody re-watches.
+ *
+ * Spoken, not escaped. "&" is read "and" by any English speaker, the burned
+ * caption still shows the symbol, and nothing downstream has to trust an
+ * 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>;
 
 /**
- * Synthesize speech using Python edge-tts (more reliable than Node.js msedge-tts)
- * Falls back to Node.js msedge-tts if Python is unavailable
+ * A word as the synthesizer actually spoke it, in ms from the start of the
+ * clip it was asked to produce — before any trimming this pipeline does to it.
+ */
+interface SpokenWord {
+    word: string;
+    start: number;
+    end: number;
+}
+/** Starts a new run, so the next line chooses the engine again. */
+declare function resetVoiceEngine(): void;
+declare function synthesizeSpeech(rawText: string, outputPath: string, voice: string, rate?: string): Promise<SpokenWord[] | null>;
+/**
+ * Pull the word boundaries out of the raw metadata stream.
+ *
+ * Each websocket frame is a complete JSON object, but a Readable is free to
+ * coalesce them into one chunk, so the concatenated text is split on brace
+ * depth rather than parsed whole. A frame that does not parse is skipped: a
+ * missing word costs a slightly-off highlight, throwing costs the clip.
  */
-declare function synthesizeSpeech(text: string, outputPath: string, voice: string): Promise<void>;
+declare function parseWordBoundaries(raw: string): SpokenWord[] | null;
 
 declare function estimateWordTimings(caption: string, duration: number): WordTiming[];
+/**
+ * Marry the authored caption text to the timings the voice reported.
+ *
+ * The burned-in captions must show the caption as WRITTEN, and the spoken word
+ * list does not always match it one for one — the text handed to the voice is
+ * the spoken form ("vidlet dot app" for a domain), and a number reads as
+ * several words. So the spoken words are used only as a clock. When the counts
+ * line up, each caption word takes its spoken counterpart's timing. When they
+ * don't, the caption words are spread evenly across the actual speech
+ * envelope — still better than a blind estimate, because the envelope excludes
+ * the silence the voice leaves at either end of a clip.
+ */
+declare function alignWordsToCaption(caption: string, spoken: SpokenWord[]): WordTiming[];
+/**
+ * Real word timings for a clip, from the boundaries the voice reported while
+ * speaking it. Null when the engine gave none, and callers fall back to
+ * estimateWordTimings. Timings are ms relative to the start of the clip.
+ *
+ * The engine times words against the audio it produced, but the clip on disk
+ * has since had its leading silence trimmed, so every offset is early by
+ * however much came off the front. The trim gate is set just under the noise
+ * edge-tts pads with, which puts the cut where the first word begins — so the
+ * first word's own offset IS what was removed, and rebasing on it re-anchors
+ * the whole clip without measuring the file again.
+ */
+declare function spokenWordTimings(caption: string, spoken: SpokenWord[] | null): WordTiming[] | null;
 /**
  * Align voiceover to actual recording durations
  * If any step's recording took longer than its voiceover, pad with silence
@@ -377,6 +932,15 @@ declare function alignVoiceoverToRecording(stepAudio: Map<number, StepAudio>, ac
 declare function buildWatermarkFilters(opts: {
     tier: UserTier;
     videoDuration: number;
+    /**
+     * The video ends on a credits card that already names QuickPeek.
+     *
+     * The end text is drawn along the bottom of the last three seconds, which
+     * is exactly where that card carries the offer - two overlays stacked on
+     * the same strip, saying the same thing twice. The corner mark stays: it is
+     * the part that marks the whole video, not just its ending.
+     */
+    endsOnCreditsCard?: boolean;
 }): string;
 
-export { type ApplyTransitionsOptions, type AudioResult, type BlendTransition, CURSOR_CSS, CURSOR_PNG, CURSOR_SCRIPT, type ComposeOptions, type ConcatVideoOptions, Config, type LenientParse, type SpeedUpOptions, type SpliceVideosOptions, type StepAudio, type StepSync, type StepTransition, type TTSStep, type TimeSegment, UserTier, type VideoOverlay, type VoiceoverMeta, type WordTiming, alignVoiceoverToRecording, applyTransitions, buildConcatArgs, buildKeepSegments, buildStepTransitions, buildWatermarkFilters, canReuseVoiceover, composeVideo, concatMedia, concatVideoWithOutro, estimateWordTimings, extractJsonCandidates, generateASSHeader, generateSilence, generateVoiceover, getAudioCodec, getMediaDuration, getUpgradeUrl, isHonestWav, loadExistingVoiceover, loadVoiceoverMeta, mapTimestampsAfterCompression, parseAIJson, registerFreeUser, repairUnicodeEscapes, resolveVoice, salvageTruncatedJson, shouldWatermark, speedUpVideo, spliceVideos, synthesizeSpeech };
+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 };