reacthub-pixitweenjs 0.2.109-alpha.7 → 0.3.0-alpha.4

package/dist/utils/captions/captionDisplay.d.ts

@@ -0,0 +1,57 @@
+import { CaptionRenderMode } from './captionPose';
+/** The words to draw, and the index of `words[0]` of that list within the full segment. */
+export declare function displayedWordsFor<T>(mode: CaptionRenderMode, words: ReadonlyArray<T>, activeIndex: number): {
+    words: T[];
+    offset: number;
+};
+export interface ParsedColor {
+    /** 0xRRGGBB */
+    color: number;
+    /** 0..1 */
+    alpha: number;
+}
+/**
+ * Parse `#rgb`, `#rrggbb`, `#rrggbbaa`, `rgb()`, `rgba()` (comma or space separated, % alpha) and
+ * `transparent`. Returns null for anything else (named colours: let the caller fall back to Pixi).
+ *
+ * Fix vs Clippy: its boxed-caption background only understood `rgba(...)` strings; a hex or
+ * `rgb()` background was silently ignored and the default black box drawn instead.
+ */
+export declare function parseCaptionColor(input: string | null | undefined): ParsedColor | null;
+export interface BoxedBackground {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    radius: number;
+    color: number;
+    alpha: number;
+}
+export declare const BOXED_PADDING = 12;
+export declare const DEFAULT_BOXED_COLOR: ParsedColor;
+/** Corner radius per boxed preset. */
+export declare const boxedRadiusFor: (captionStyleId: string | null | undefined) => number;
+/**
+ * The rounded box behind the whole caption in `boxed` mode, in coordinates relative to the
+ * caption centre. `captionBgColor` unset / `transparent` / unparseable falls back to the
+ * default 75% black (Clippy's behaviour).
+ */
+export declare function boxedBackgroundSpec(contentWidth: number, contentHeight: number, captionBgColor: string | null | undefined, captionStyleId: string | null | undefined): BoxedBackground;
+export interface WordboxPill {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    radius: number;
+}
+export declare const WORDBOX_GROW_MS = 120;
+/**
+ * The rounded pill behind the active word in `wordbox` mode: grows from the word's centre over
+ * 120 ms (ease-out-cubic). Relative to the caption centre.
+ */
+export declare function wordboxPillSpec(pos: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}, totalWidth: number, totalHeight: number, elapsedMs: number, fontSize: number): WordboxPill;

package/dist/utils/captions/captionPose.d.ts

@@ -0,0 +1,107 @@
+export type CaptionRenderMode = 'none' | 'pop' | 'glow' | 'boxed' | 'vhs' | 'wordbox' | 'punch' | 'slam' | 'glowpop' | 'springpop';
+export interface PoseWord {
+    text?: string;
+    word?: string;
+    start: number;
+    end: number;
+    /** One emoji grapheme drawn above the word (Glow Pop). */
+    emoji?: string;
+    /** Image URL (or, after the renderer's download step, a local path) for `emoji`. */
+    emojiSrc?: string;
+    /** Per-word fill (`#RRGGBB`), used by Spring Pop where the colour changes word to word. */
+    color?: string;
+}
+/** `transformation.captionStyleId` → render mode. Unknown ids draw as `pop`. */
+export declare const captionModeFor: (captionStyleId: unknown) => CaptionRenderMode;
+/** Modes that draw only the active word. */
+export declare const isSingleWordMode: (mode: CaptionRenderMode) => boolean;
+/**
+ * Index of the word drawn at `t`, or -1. `slam` holds the last word that has started across gaps; every other mode
+ * shows a word only inside its own `[start, end)` window.
+ */
+export declare const activeWordIndexAt: (words: PoseWord[], t: number, mode: CaptionRenderMode) => number;
+/**
+ * Glow Pop timing (ms), measured from a 10 fps reference: each word spends about one frame as a horizontal
+ * motion-blur streak coming in and one going out; its emoji pops in with an overshoot over ~0.35 s and shrinks away.
+ */
+export declare const GLOW_POP_ENTER_MS = 100;
+export declare const GLOW_POP_EXIT_MS = 100;
+export declare const GLOW_POP_EMOJI_MS = 350;
+/**
+ * Horizontal blur strength at the peak of a streak, as a multiple of the font size, and the word's alpha at that
+ * peak. Tuned on a real headless render against the reference: in the CapCut streak frames about 30% of the crisp
+ * word's white pixels survive, so the streak must stay bright. A 0.3 em gaussian at alpha 0.4 left almost nothing.
+ */
+export declare const GLOW_POP_BLUR_EM = 0.12;
+export declare const GLOW_POP_STREAK_ALPHA = 0.6;
+/**
+ * Bloom: the wide soft white light behind the word (and the warm halo behind its emoji) in the reference. Drawn as a
+ * blurred copy of the word under it — one text dropShadow cannot spread this far. Blur is a multiple of the font
+ * size; alpha multiplies the word's alpha.
+ */
+export declare const GLOW_POP_BLOOM_BLUR_EM = 0.3;
+export declare const GLOW_POP_BLOOM_ALPHA = 0.8;
+/**
+ * How many blurred copies are stacked. One copy at alpha 1 lifted the band below a short word (`EYE`) by +19 luma
+ * where the reference shows +30 over its blank frame; the reference halo does not shrink with the word.
+ */
+export declare const GLOW_POP_BLOOM_PASSES = 2;
+export declare const GLOW_POP_EMOJI_BLOOM_ALPHA = 0.55;
+/** Emoji size and vertical offset (centre above the word centre), as multiples of the font size. */
+export declare const GLOW_POP_EMOJI_SIZE_EM = 1.5;
+export declare const GLOW_POP_EMOJI_OFFSET_EM = 1.35;
+export declare const easeOutBack: (t: number) => number;
+export interface GlowPopMotion {
+    alpha: number;
+    /** Horizontal blur strength in px. */
+    blur: number;
+    scale: number;
+    emojiScale: number;
+}
+/** Per-frame look of the active Glow Pop word from how long it has been on and how long it has left. */
+export declare const glowPopMotion: (elapsedMs: number, remainingMs: number, fontSize: number) => GlowPopMotion;
+/**
+ * Spring Pop (CapCut "viral reel" captions), measured at the clip's native 30 fps by `analyze-captions` pass 2
+ * (phase 195.0): each word drops in from above on a damped spring, bobbing up and down until the next word replaces
+ * it, entering through a vertical motion blur. The spring is y(t) = -A * e^(-zeta*w*t) * cos(w*t), +y down, so a word
+ * starts above its rest position and falls through it. Fitted on 27 words of one clip: 4-6 Hz, zeta 0.1-0.15,
+ * amplitude 0.2-0.26 of the glyph height (~0.18 of the font size).
+ */
+export declare const SPRING_POP_FREQUENCY_HZ = 5;
+export declare const SPRING_POP_DAMPING = 0.12;
+export declare const SPRING_POP_AMPLITUDE_EM = 0.2;
+/** Vertical-blur window at the start of a word (ms), peak strength (font-size multiple) and the word's alpha then. */
+export declare const SPRING_POP_BLUR_MS = 150;
+export declare const SPRING_POP_BLUR_EM = 0.1;
+export declare const SPRING_POP_BLUR_ALPHA = 0.75;
+/** Bloom behind the word: same recipe as Glow Pop, a little lighter (the clip's glow is a thin halo with colour fringe). */
+export declare const SPRING_POP_BLOOM_BLUR_EM = 0.22;
+export declare const SPRING_POP_BLOOM_ALPHA = 0.7;
+export interface SpringPopMotion {
+    alpha: number;
+    /** Vertical offset from the word's rest position in px (+ down). */
+    dy: number;
+    /** Vertical blur strength in px. */
+    blur: number;
+    /** Vertical stretch while the word is smeared (1 = none). */
+    scaleY: number;
+}
+/** Per-frame look of the active Spring Pop word from how long it has been on screen. Seekable and pure. */
+export declare const springPopMotion: (elapsedMs: number, fontSize: number) => SpringPopMotion;
+/** Vertical colour-channel split learned from the viral Reel: cool copy above, warm copy below, shrinking to a fringe. */
+export declare const SPRING_POP_SPLIT_MS = 150;
+export declare const SPRING_POP_SPLIT_EM = 0.072;
+export declare const SPRING_POP_SPLIT_SETTLED_EM = 0.029;
+export declare const SPRING_POP_SPLIT_TOP = "#5AA9FF";
+export declare const SPRING_POP_SPLIT_BOTTOM = "#FFA14A";
+export declare const SPRING_POP_SPLIT_ALPHA = 0.75;
+/** Total top-to-bottom separation in px of the split copies (each copy sits half of it from the word). Seekable and pure. */
+export declare const springPopSplit: (elapsedMs: number, fontSize: number) => number;
+/** Seekable scale of the active word for the 071 CapCut modes (`punch`, `slam`); 1 for every other mode. */
+export declare const activeWordScaleFor: (mode: CaptionRenderMode, elapsedMs: number) => number;
+/** Pinned emoji art (Noto Color Emoji PNG, 128 px), so the editor and the render draw the same glyph. */
+export declare const EMOJI_CDN_BASE = "https://cdn.jsdelivr.net/gh/googlefonts/noto-emoji@v2.047/png/128";
+/** Noto file name for an emoji: codepoints in lower-case hex joined by `_`, without the VS16 selector. */
+export declare const notoEmojiFileName: (emoji: string) => string | null;
+/** Where the word's emoji image comes from: an explicit `emojiSrc`, else the pinned Noto URL for `emoji`. */
+export declare const resolveEmojiSrc: (word: Pick<PoseWord, "emoji" | "emojiSrc">) => string | null;

package/dist/utils/captions/captionVisual.d.ts

@@ -0,0 +1,32 @@
+import { CaptionRenderMode, GlowPopMotion, SpringPopMotion } from './captionPose';
+/** Which TextStyle family to draw the word with. */
+export type WordStyleKind = "base" | "active" | "inactive";
+export interface WordVisual {
+    styleKind: WordStyleKind;
+    alpha: number;
+    /** Uniform scale, or a non-uniform one (spring-pop stretches Y while smeared). */
+    scale: number | {
+        x: number;
+        y: number;
+    };
+    /** Vertical offset from the rest position, px (+ down). */
+    dy: number;
+    /** Horizontal blur strength, px. 0 = no filter. */
+    blurX: number;
+    /** Vertical blur strength, px. 0 = no filter. */
+    blurY: number;
+    glowPop?: GlowPopMotion;
+    springPop?: SpringPopMotion;
+    /** Spring-pop colour-channel separation, px. */
+    split?: number;
+}
+/** Filters are only attached when the blur is visible (matches Clippy's `> 0.5` threshold). */
+export declare const MIN_VISIBLE_BLUR = 0.5;
+/**
+ * The look of one word.
+ * @param elapsedMs   ms since the active word started (0 when none)
+ * @param remainingMs ms until the active word ends
+ */
+export declare function wordVisualFor(mode: CaptionRenderMode, isActive: boolean, elapsedMs: number, remainingMs: number, fontSize: number): WordVisual;
+/** Modes whose look changes continuously with time within a word (need per-frame updates). */
+export declare const isTimeBasedMode: (mode: CaptionRenderMode) => boolean;

package/dist/utils/captions/captionWordLayout.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Word layout for karaoke captions (PixiCaptionsTrack): wrapping, centring and the gap between words. Pure — the
+ * caller measures the words with Pixi and passes numbers in, so the same rules run in the editor, the studio
+ * preview and the server render. MIRRORED: keep byte-identical to `clippy-pixijs-nodejs/src/captionWordLayout.ts`
+ * — the editor preview and the render must place words the same way. Both repos run a mirror test.
+ *
+ * Two defects this exists to prevent, both seen on a real UGC film ("feellighterand"):
+ *  1. The space was measured with `wordWrap` on, whose trimRight collapses a lone space to 0 px, so words sat
+ *     edge to edge. The caller now measures it with wrapping off; `resolveSpaceWidth` also falls back to a
+ *     fontSize-based width when a font still reports ~0.
+ *  2. The active word is drawn at 1.05–1.08× around its centre, so it grows into its neighbours. Each word's slot
+ *     is reserved at the scale it can reach, so a highlighted word stays inside its own room.
+ */
+/** A real space is about 0.28 em; used when measuring it gives ~0. */
+export declare const FALLBACK_SPACE_EM = 0.28;
+/**
+ * Extra gap between words in em, ON TOP of the real space and the room kept for the highlighted word. Zero by
+ * default: 0.1 em on top of those two read as about two spaces between words on a real UGC film. Raise it per
+ * caption with `transformation.wordSpacing` (px) for heavy strokes or wide fonts.
+ */
+export declare const DEFAULT_WORD_SPACING_EM = 0;
+/** Line pitch as a multiple of the tallest word on the line. */
+export declare const LINE_PITCH = 1.2;
+export interface WordMetric {
+    width: number;
+    height: number;
+}
+export interface WordPosition {
+    /** Left edge of the word's slot (the slot is `width` wide, already widened for the active scale). */
+    x: number;
+    y: number;
+    /** The slot width: the word's measured width times `activeScale`. Draw the word centred in it. */
+    width: number;
+    height: number;
+}
+export interface CaptionLine {
+    start: number;
+    end: number;
+    width: number;
+    height: number;
+}
+export interface CaptionLayout {
+    positions: WordPosition[];
+    lines: CaptionLine[];
+    totalWidth: number;
+    totalHeight: number;
+}
+export interface CaptionLayoutOptions {
+    /** Measured width of a single space with wrapping OFF; may be ~0 (see `resolveSpaceWidth`). */
+    spaceWidth: number;
+    fontSize: number;
+    maxLineWidth: number;
+    /** Extra px between words. Omitted → `DEFAULT_WORD_SPACING_EM * fontSize`. */
+    wordSpacing?: number;
+    /** The largest scale any word is drawn at (1 when the style does not scale the active word). */
+    activeScale?: number;
+}
+/** The measured space when it is believable, else the em-based fallback. */
+export declare const resolveSpaceWidth: (measured: number, fontSize: number) => number;
+/** The extra gap: an explicit non-negative px value, else the default for this font size. */
+export declare const resolveWordSpacing: (wordSpacing: unknown, fontSize: number) => number;
+/** How big the active word gets, per render mode — the slot reserves this much. */
+export declare const activeScaleFor: (renderMode: string) => number;
+export declare const transformCaptionText: (text: string, textTransform: string) => string;
+export declare const activeWordWindow: <T>(words: T[], activeIndex: number, size?: number) => T[];
+export declare const easeCaptionProgress: (elapsedMs: number, durationMs: number) => number;
+export declare function layoutCaptionWords(words: WordMetric[], opts: CaptionLayoutOptions): CaptionLayout;

package/dist/utils/captions/groupSegments.d.ts

@@ -0,0 +1,20 @@
+import { CaptionSegment, CaptionWord } from './types';
+export interface GroupWordsOptions {
+    /**
+     * A silence of at least this many seconds between two words starts a new
+     * segment. Clippy templates use 0.35 (glow-pop) and 0.4 (spring-pop).
+     */
+    segmentGapSec?: number;
+    /** Hard cap on words per segment. */
+    maxWords?: number;
+    /** Start a new segment once it would span longer than this many seconds. */
+    maxDurationSec?: number;
+    /** Prefix for generated ids: `<prefix>_0`, `<prefix>_1`, ... */
+    idPrefix?: string;
+}
+export declare const DEFAULT_SEGMENT_GAP_SEC = 0.35;
+/**
+ * Group a flat, word-timed transcript into caption segments (pages).
+ * Words are sorted by start first; the input array is not mutated.
+ */
+export declare function groupWordsIntoSegments(words: ReadonlyArray<CaptionWord>, opts?: GroupWordsOptions): CaptionSegment[];

package/dist/utils/captions/index.d.ts

@@ -0,0 +1,10 @@
+export * from './captionPose';
+export * from './captionWordLayout';
+export * from './types';
+export * from './groupSegments';
+export * from './parseSubtitles';
+export * from './timeBase';
+export * from './sampleCaption';
+export * from './captionClock';
+export * from './captionVisual';
+export * from './captionDisplay';

package/dist/utils/captions/parseSubtitles.d.ts

@@ -0,0 +1,25 @@
+import { CaptionSegment, CaptionWord } from './types';
+export interface ParseSubtitleOptions {
+    /**
+     * When a cue has no word timing, spread the cue over its words
+     * proportionally to word length so karaoke modes still have something to
+     * highlight. Default false (cue-level segments only).
+     */
+    estimateWords?: boolean;
+    /** Prefix for generated segment ids. Default "caption". */
+    idPrefix?: string;
+}
+export type SubtitleFormat = "srt" | "vtt" | "unknown";
+/** "01:02:03,456" | "02:03.456" -> seconds, or null when malformed. */
+export declare function parseTimestamp(raw: string): number | null;
+/**
+ * Spread `[start, end]` across the whitespace-separated words of `text`,
+ * weighted by word length (so "a" gets less time than "extraordinary").
+ * Words are contiguous: each ends where the next starts.
+ */
+export declare function estimateWordTimings(text: string, start: number, end: number): CaptionWord[];
+export declare function parseSRT(content: string, opts?: ParseSubtitleOptions): CaptionSegment[];
+export declare function parseVTT(content: string, opts?: ParseSubtitleOptions): CaptionSegment[];
+export declare function detectSubtitleFormat(content: string): SubtitleFormat;
+/** Auto-detect SRT vs WebVTT. Throws on unrecognised content. */
+export declare function parseSubtitles(content: string, opts?: ParseSubtitleOptions): CaptionSegment[];

package/dist/utils/captions/sampleCaption.d.ts

@@ -0,0 +1,25 @@
+import { CaptionRenderMode } from './captionPose';
+import { CaptionSegment, CaptionWord } from './types';
+export interface CaptionSample {
+    /** Segment on screen at `t`, or null. */
+    segment: CaptionSegment | null;
+    /** Index into `segment.words` of the active word, or -1. */
+    wordIndex: number;
+    word: CaptionWord | null;
+    /** Milliseconds since the active word started (0 when none). */
+    elapsedMs: number;
+    /** Milliseconds until the active word ends (0 when none). */
+    remainingMs: number;
+}
+/**
+ * The pure core of Clippy's PixiCaptionsTrack `onRender` loop: what is on
+ * screen at time `t` (seconds, in the same time base as the segments).
+ *
+ * Active segment uses the inclusive range `[start, end]`, exactly as the
+ * editor does; where segments touch, the first match wins. Seek-safe: same
+ * `t` always gives the same result.
+ *
+ * Caveat: in `slam` mode the word is held across gaps, so it can keep
+ * `elapsedMs` growing past `word.end`; `remainingMs` is clamped at 0.
+ */
+export declare function sampleCaptionAt(segments: ReadonlyArray<CaptionSegment>, t: number, mode: CaptionRenderMode): CaptionSample;

package/dist/utils/captions/timeBase.d.ts

@@ -0,0 +1,34 @@
+import { CaptionSegment } from './types';
+/** Cues may overrun the clip by this much and still count as clip-local. */
+export declare const CLIP_LOCAL_TOLERANCE_SEC = 0.5;
+export interface CaptionMediaBounds {
+    /** Timeline start of the associated media clip (seconds). */
+    start: number;
+    /** Timeline end of the associated media clip (seconds). */
+    end: number;
+    /**
+     * Source in-point: where in the source file the clip begins. Clippy calls
+     * this `frameStartAt`. Default 0.
+     */
+    sourceStart?: number;
+}
+/**
+ * True when the segments already start at 0 = clip start, detected by every
+ * cue ending within the clip duration (+ tolerance).
+ */
+export declare function isClipLocal(segments: ReadonlyArray<CaptionSegment>, media: Pick<CaptionMediaBounds, "start" | "end">): boolean;
+/**
+ * Seconds to add to stored caption times to reach timeline-absolute time.
+ *   clip-local      -> media.start
+ *   source-absolute -> media.start - media.sourceStart
+ * Returns 0 when there is no media to anchor to.
+ */
+export declare function resolveCaptionOffset(segments: ReadonlyArray<CaptionSegment>, media?: CaptionMediaBounds | null): number;
+/** Shift every segment and word by `offsetSec`. Does not mutate the input. */
+export declare function projectSegments(segments: ReadonlyArray<CaptionSegment>, offsetSec: number): CaptionSegment[];
+/**
+ * Keep only the part of the captions inside `[rangeStart, rangeEnd]`.
+ * Segments are clamped to the range; words entirely outside are dropped and
+ * the rest are clamped. Segments left with no overlap are removed.
+ */
+export declare function clipSegmentsToRange(segments: ReadonlyArray<CaptionSegment>, rangeStart: number, rangeEnd: number): CaptionSegment[];

package/dist/utils/captions/types.d.ts

@@ -0,0 +1,279 @@
+import { z } from 'zod';
+import { PoseWord } from './captionPose';
+export declare const captionWordSchema: z.ZodEffects<z.ZodObject<{
+    text: z.ZodString;
+    start: z.ZodNumber;
+    end: z.ZodNumber;
+    /** One emoji grapheme drawn above the word (glow-pop). */
+    emoji: z.ZodOptional<z.ZodString>;
+    /** Explicit emoji image URL; overrides the pinned Noto CDN lookup. */
+    emojiSrc: z.ZodOptional<z.ZodString>;
+    /** Per-word fill `#RRGGBB` (spring-pop). */
+    color: z.ZodOptional<z.ZodString>;
+    /** ASR confidence 0..1, carried through untouched. */
+    confidence: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    text: string;
+    start: number;
+    end: number;
+    color?: string | undefined;
+    emoji?: string | undefined;
+    emojiSrc?: string | undefined;
+    confidence?: number | undefined;
+}, {
+    text: string;
+    start: number;
+    end: number;
+    color?: string | undefined;
+    emoji?: string | undefined;
+    emojiSrc?: string | undefined;
+    confidence?: number | undefined;
+}>, {
+    text: string;
+    start: number;
+    end: number;
+    color?: string | undefined;
+    emoji?: string | undefined;
+    emojiSrc?: string | undefined;
+    confidence?: number | undefined;
+}, {
+    text: string;
+    start: number;
+    end: number;
+    color?: string | undefined;
+    emoji?: string | undefined;
+    emojiSrc?: string | undefined;
+    confidence?: number | undefined;
+}>;
+export declare const captionSegmentSchema: z.ZodEffects<z.ZodObject<{
+    id: z.ZodString;
+    start: z.ZodNumber;
+    end: z.ZodNumber;
+    text: z.ZodString;
+    words: z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodObject<{
+        text: z.ZodString;
+        start: z.ZodNumber;
+        end: z.ZodNumber;
+        /** One emoji grapheme drawn above the word (glow-pop). */
+        emoji: z.ZodOptional<z.ZodString>;
+        /** Explicit emoji image URL; overrides the pinned Noto CDN lookup. */
+        emojiSrc: z.ZodOptional<z.ZodString>;
+        /** Per-word fill `#RRGGBB` (spring-pop). */
+        color: z.ZodOptional<z.ZodString>;
+        /** ASR confidence 0..1, carried through untouched. */
+        confidence: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        text: string;
+        start: number;
+        end: number;
+        color?: string | undefined;
+        emoji?: string | undefined;
+        emojiSrc?: string | undefined;
+        confidence?: number | undefined;
+    }, {
+        text: string;
+        start: number;
+        end: number;
+        color?: string | undefined;
+        emoji?: string | undefined;
+        emojiSrc?: string | undefined;
+        confidence?: number | undefined;
+    }>, {
+        text: string;
+        start: number;
+        end: number;
+        color?: string | undefined;
+        emoji?: string | undefined;
+        emojiSrc?: string | undefined;
+        confidence?: number | undefined;
+    }, {
+        text: string;
+        start: number;
+        end: number;
+        color?: string | undefined;
+        emoji?: string | undefined;
+        emojiSrc?: string | undefined;
+        confidence?: number | undefined;
+    }>, "many">>;
+}, "strip", z.ZodTypeAny, {
+    text: string;
+    start: number;
+    end: number;
+    id: string;
+    words?: {
+        text: string;
+        start: number;
+        end: number;
+        color?: string | undefined;
+        emoji?: string | undefined;
+        emojiSrc?: string | undefined;
+        confidence?: number | undefined;
+    }[] | undefined;
+}, {
+    text: string;
+    start: number;
+    end: number;
+    id: string;
+    words?: {
+        text: string;
+        start: number;
+        end: number;
+        color?: string | undefined;
+        emoji?: string | undefined;
+        emojiSrc?: string | undefined;
+        confidence?: number | undefined;
+    }[] | undefined;
+}>, {
+    text: string;
+    start: number;
+    end: number;
+    id: string;
+    words?: {
+        text: string;
+        start: number;
+        end: number;
+        color?: string | undefined;
+        emoji?: string | undefined;
+        emojiSrc?: string | undefined;
+        confidence?: number | undefined;
+    }[] | undefined;
+}, {
+    text: string;
+    start: number;
+    end: number;
+    id: string;
+    words?: {
+        text: string;
+        start: number;
+        end: number;
+        color?: string | undefined;
+        emoji?: string | undefined;
+        emojiSrc?: string | undefined;
+        confidence?: number | undefined;
+    }[] | undefined;
+}>;
+export declare const captionSegmentsSchema: z.ZodArray<z.ZodEffects<z.ZodObject<{
+    id: z.ZodString;
+    start: z.ZodNumber;
+    end: z.ZodNumber;
+    text: z.ZodString;
+    words: z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodObject<{
+        text: z.ZodString;
+        start: z.ZodNumber;
+        end: z.ZodNumber;
+        /** One emoji grapheme drawn above the word (glow-pop). */
+        emoji: z.ZodOptional<z.ZodString>;
+        /** Explicit emoji image URL; overrides the pinned Noto CDN lookup. */
+        emojiSrc: z.ZodOptional<z.ZodString>;
+        /** Per-word fill `#RRGGBB` (spring-pop). */
+        color: z.ZodOptional<z.ZodString>;
+        /** ASR confidence 0..1, carried through untouched. */
+        confidence: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        text: string;
+        start: number;
+        end: number;
+        color?: string | undefined;
+        emoji?: string | undefined;
+        emojiSrc?: string | undefined;
+        confidence?: number | undefined;
+    }, {
+        text: string;
+        start: number;
+        end: number;
+        color?: string | undefined;
+        emoji?: string | undefined;
+        emojiSrc?: string | undefined;
+        confidence?: number | undefined;
+    }>, {
+        text: string;
+        start: number;
+        end: number;
+        color?: string | undefined;
+        emoji?: string | undefined;
+        emojiSrc?: string | undefined;
+        confidence?: number | undefined;
+    }, {
+        text: string;
+        start: number;
+        end: number;
+        color?: string | undefined;
+        emoji?: string | undefined;
+        emojiSrc?: string | undefined;
+        confidence?: number | undefined;
+    }>, "many">>;
+}, "strip", z.ZodTypeAny, {
+    text: string;
+    start: number;
+    end: number;
+    id: string;
+    words?: {
+        text: string;
+        start: number;
+        end: number;
+        color?: string | undefined;
+        emoji?: string | undefined;
+        emojiSrc?: string | undefined;
+        confidence?: number | undefined;
+    }[] | undefined;
+}, {
+    text: string;
+    start: number;
+    end: number;
+    id: string;
+    words?: {
+        text: string;
+        start: number;
+        end: number;
+        color?: string | undefined;
+        emoji?: string | undefined;
+        emojiSrc?: string | undefined;
+        confidence?: number | undefined;
+    }[] | undefined;
+}>, {
+    text: string;
+    start: number;
+    end: number;
+    id: string;
+    words?: {
+        text: string;
+        start: number;
+        end: number;
+        color?: string | undefined;
+        emoji?: string | undefined;
+        emojiSrc?: string | undefined;
+        confidence?: number | undefined;
+    }[] | undefined;
+}, {
+    text: string;
+    start: number;
+    end: number;
+    id: string;
+    words?: {
+        text: string;
+        start: number;
+        end: number;
+        color?: string | undefined;
+        emoji?: string | undefined;
+        emojiSrc?: string | undefined;
+        confidence?: number | undefined;
+    }[] | undefined;
+}>, "many">;
+export type CaptionWord = z.infer<typeof captionWordSchema>;
+export type CaptionSegment = z.infer<typeof captionSegmentSchema>;
+/** Strict parse: throws ZodError on any invalid segment. */
+export declare function parseCaptionSegments(input: unknown): CaptionSegment[];
+/** Display text of a word; tolerates the Whisper `word` spelling. */
+export declare const captionWordText: (w: Pick<PoseWord, "text" | "word">) => string;
+/**
+ * Best-effort conversion of API-shaped data into canonical segments.
+ *
+ * Accepts either an array of segments or `{ segments: [...] }` (the Clippy /
+ * Whisper `SubtitleData` envelope). Segment times may be `start/end` or
+ * `startTime/endTime`; word text may be `text` or `word`. Invalid words and
+ * segments are dropped rather than throwing. Output is sorted by start and
+ * has unique-per-input ids.
+ *
+ * Use `parseCaptionSegments` instead when you want strict validation.
+ */
+export declare function normalizeCaptionSegments(input: unknown): CaptionSegment[];