@bendyline/squisq 1.5.2 → 2.0.0

package/dist/narration/index.d.ts

@@ -0,0 +1,618 @@
+import { F as Doc, e as AudioBookmark } from '../Doc-ylqWKDc_.js';
+import '../types-BwMPl2CB.js';
+
+/**
+ * Shared types + tuning configs for the narration engine.
+ *
+ * The engine is pure TypeScript with zero dependencies and no DOM/Node
+ * APIs: audio arrives as mono `Float32Array` PCM (the editor decodes
+ * WebM/MP4 on its side), and every stage is a deterministic step
+ * function `(state, input, config) → state` so the whole pipeline is
+ * unit-testable in Node with synthetic signals. No `Date.now`, no
+ * `Math.random`, no timers anywhere in this module.
+ */
+/** One word of the teleprompter script, positioned inside {@link NarrationScript.sourceText}. */
+interface ScriptToken {
+    /** The word as displayed (no surrounding whitespace). */
+    text: string;
+    /** Start offset into {@link NarrationScript.sourceText}. */
+    charOffset: number;
+    /** Exclusive end offset into {@link NarrationScript.sourceText}. */
+    charEnd: number;
+    /** Id of the doc block this word belongs to. */
+    blockId: string;
+    /** Index into {@link NarrationScript.blocks}. */
+    blockIndex: number;
+    /** Estimated syllable count (≥ 1 for spoken tokens; 0 when `spoken` is false). */
+    syllables: number;
+    /** Spoken-word equivalents (numbers count as several words; 0 when not spoken). */
+    spokenWordEquiv: number;
+    /**
+     * Pause class after this token:
+     * 0 none · 1 clause/sentence punctuation · 2 paragraph break · 3 block boundary.
+     */
+    pauseAfter: 0 | 1 | 2 | 3;
+    /**
+     * Whether this token is actually spoken. Standalone punctuation runs —
+     * an em-dash, a lone bullet, `···` — tokenize on whitespace like words
+     * but carry no letters or digits: they DISPLAY in the prompter yet must
+     * never be the highlighted active word, are never paused on, and add no
+     * syllables to the pacing/alignment model.
+     */
+    spoken: boolean;
+}
+/** The token/char span of one doc block inside the script. */
+interface ScriptBlockRange {
+    blockId: string;
+    /** The block's heading text, when present. */
+    heading?: string;
+    /** Inclusive index into {@link NarrationScript.tokens}. */
+    tokenStart: number;
+    /** Exclusive index into {@link NarrationScript.tokens}. */
+    tokenEnd: number;
+    /** Start offset into {@link NarrationScript.sourceText} (includes the spoken title). */
+    charStart: number;
+    /** Exclusive end offset into {@link NarrationScript.sourceText}. */
+    charEnd: number;
+}
+/**
+ * The teleprompter script derived from a Doc. `sourceText` is canonical:
+ * it is stored verbatim in the timing sidecar, and every `charOffset`
+ * indexes into it. Building is deterministic — the same Doc always
+ * yields a byte-identical script.
+ */
+interface NarrationScript {
+    sourceText: string;
+    tokens: ScriptToken[];
+    blocks: ScriptBlockRange[];
+    totalSyllables: number;
+    /**
+     * Prefix sums: `cumulativeSyllables[i]` = syllables of `tokens[0..i-1]`.
+     * Length is `tokens.length + 1`.
+     */
+    cumulativeSyllables: number[];
+}
+/** Per-frame acoustic features extracted from PCM. */
+interface FrameFeatures {
+    /** Frame CENTER time in seconds from the start of the signal. */
+    tSec: number;
+    /** Full-band root-mean-square of the frame. */
+    rms: number;
+    /** Mean square of the 250–3000 Hz bandpassed frame (speech band energy). */
+    bandEnergy: number;
+    /** Zero crossings / (frameLength − 1), in [0, 1]. */
+    zcr: number;
+}
+interface FeatureConfig {
+    /** Analysis frame length in samples (~21 ms @ 48 kHz). */
+    frameSize: number;
+    /** Hop between frame starts in seconds (live 0.02; the aligner uses 0.01). */
+    hopSec: number;
+    /** Bandpass high-pass corner (Hz). */
+    bandLowHz: number;
+    /** Bandpass low-pass corner (Hz). */
+    bandHighHz: number;
+}
+declare const DEFAULT_FEATURE_CONFIG: FeatureConfig;
+interface VadConfig {
+    /** Floor-seeding period before any speech decision (ms). */
+    warmupMs: number;
+    /** Floor attack toward minima (per-frame EMA alpha when energy < floor). */
+    alphaDown: number;
+    /** Floor release (per-frame EMA alpha when energy ≥ floor; frozen while speaking). */
+    alphaUp: number;
+    /** Enter speech when energy > floor × enterRatio for enterFrames frames. */
+    enterRatio: number;
+    /**
+     * Exit hysteresis: sub-exit frames only count once energy < floor ×
+     * exitRatio. The floor is a LOW-percentile tracker, so steady room
+     * noise runs ~1.8–2.3× above it — exitRatio must sit above that band
+     * (and below enterRatio) or silence never registers.
+     */
+    exitRatio: number;
+    /** Consecutive supra-enter frames required to enter speech. */
+    enterFrames: number;
+    /** Sub-exit dwell required to leave speech (ms). */
+    hangoverMs: number;
+    /**
+     * Dip-starved rebaseline: real speech dips below enterRatio × floor
+     * between syllables; a "speech" that stays strongly above the floor
+     * for this long with zero dips is a shifted noise floor — adopt it
+     * and exit. Guards against a step change in room noise wedging the
+     * VAD open forever (the floor is otherwise frozen while speaking).
+     */
+    noiseRebaselineSec: number;
+    /** Absolute floor clamp guarding digital silence. */
+    floorMin: number;
+}
+declare const DEFAULT_VAD_CONFIG: VadConfig;
+interface NucleiConfig {
+    /** One-pole low-pass cutoff for the amplitude envelope (Hz). */
+    envelopeHz: number;
+    /** Minimum spacing between accepted syllable onsets (ms) — caps ~8.3 syl/s. */
+    minInterOnsetMs: number;
+    /** Peak must exceed valley-since-last-peak × this ratio. */
+    prominenceRatio: number;
+    /** Peak must exceed the decaying loudness reference × this fraction. */
+    minRelPeak: number;
+    /** Decay time constant of the loudness reference (s). */
+    peakRefTauSec: number;
+}
+declare const DEFAULT_NUCLEI_CONFIG: NucleiConfig;
+interface PacingConfig {
+    /** The user's base speaking rate (words per minute). */
+    baseWpm: number;
+    /**
+     * How strongly the detected voice rate steers the cruise velocity vs.
+     * the user's set pace, in [0, 1]. The speaking-cruise velocity is
+     * `voiceBlend·voiceRate + (1 − voiceBlend)·baseRate`, so the WPM slider
+     * is ALWAYS felt (it never fully cancels) and an under-counting detector
+     * can't drag the prompter to a crawl. 1 = pure voice-follow (the old
+     * behavior, where WPM only mattered at the clamps); 0 = ignore the voice.
+     */
+    voiceBlend: number;
+    /** Clamp on the cruise velocity as a fraction of the set pace. */
+    minRateMult: number;
+    maxRateMult: number;
+    /** EMA time constant for the detected syllable rate (s). */
+    rateEmaTauSec: number;
+    /** Velocity slew time constant while speaking (s). */
+    velSlewTauSec: number;
+    /** Velocity decay time constant in silence (s) — halted within ~250 ms. */
+    haltTauSec: number;
+    /** Proportional gain of the forward-only catch-up boost (per syllable behind). */
+    kP: number;
+    /** Integral gain of the forward-only boost (per syllable·second behind). */
+    kI: number;
+    /** Anti-windup clamp on the (≤ 0) behind-error integral (syllable·seconds). */
+    intClamp: number;
+    /** Max fraction the catch-up boost may ADD to the cruise velocity. */
+    maxCorrection: number;
+    /** Window (words ahead) used for the local expected syllables-per-word. */
+    sylWindowWords: number;
+    /** Reader-ahead error beyond this hard-resyncs the prompter FORWARD. */
+    resyncSyllables: number;
+}
+declare const DEFAULT_PACING_CONFIG: PacingConfig;
+interface AlignConfig {
+    /** Fine analysis hop for the offline pass (s). */
+    hopSec: number;
+    /** Non-speech runs at least this long become GAP events (s). */
+    gapMinSec: number;
+    /** Sakoe-Chiba band half-width around the live-trace prior (s). */
+    bandRadiusSec: number;
+    /** Band half-width when no trace exists (s); also floored at 10% of take length. */
+    bandRadiusNoTraceSec: number;
+    /** Cost weight for |Δt| on syllable↔syllable matches (normalized by band radius). */
+    matchTimeWeight: number;
+    /** Cost of matching an expected pause slot to a detected syllable (reader didn't pause). */
+    pauseToSylCost: number;
+    /** Cost of matching an expected syllable slot to a detected gap (mid-sentence hesitation). */
+    sylToGapCost: number;
+    /** Cost of skipping an expected slot (merged/unspoken syllable). */
+    deleteCost: number;
+    /** Cost of skipping a detected event (filler word, breath, click). */
+    insertCost: number;
+    /** Snap a block start to a silence-gap end within this window before it (s). */
+    blockSnapWindowSec: number;
+    /** Padding after the last speech for the final block's end (s). */
+    tailPadSec: number;
+}
+declare const DEFAULT_ALIGN_CONFIG: AlignConfig;
+/** Refined timestamp of one script token. */
+interface WordTiming {
+    tokenIndex: number;
+    /** Seconds into the take when the word begins. Monotonically non-decreasing. */
+    tSec: number;
+    /** True when this word had no matched syllable and was interpolated. */
+    interpolated: boolean;
+}
+/** Narration time range of one doc block. Ranges are CONTIGUOUS: endSec === next.startSec. */
+interface NarrationBlockRange {
+    blockId: string;
+    heading?: string;
+    blockIndex: number;
+    charStart: number;
+    charEnd: number;
+    startSec: number;
+    endSec: number;
+}
+interface NarrationAlignment {
+    /** One entry per script token, monotonic in time. */
+    words: WordTiming[];
+    blocks: NarrationBlockRange[];
+    /** Total syllable onsets detected in the take (diagnostics). */
+    detectedSyllables: number;
+    /** Total DTW path cost (diagnostics/QA). */
+    cost: number;
+}
+
+/**
+ * Deterministic English-oriented syllable estimation.
+ *
+ * Approximation limits (accepted by design): ±1 on roughly 15% of
+ * English words; systematically wrong on loanwords ("cafe", "naive"),
+ * some vowel-hiatus words ("create", "quiet"), and non-English text.
+ * Every consumer tolerates per-word error — the pacing controller
+ * smooths rates and anchors on cumulative sums, and the aligner pays
+ * symmetric insert/delete costs — so the estimator only needs to be
+ * unbiased on average. Exact outputs are part of the deterministic
+ * contract (tests pin a corpus table).
+ */
+/**
+ * Estimate the syllable count of a single whitespace-delimited token.
+ * Always ≥ 1 for non-empty tokens.
+ */
+declare function estimateSyllables(token: string): number;
+
+/**
+ * Teleprompter script model: a Doc flattened into an ordered word-token
+ * stream with per-block ranges.
+ *
+ * `sourceText` is the canonical narration text — it is stored verbatim
+ * in the timing sidecar, and every token/block `charOffset` indexes into
+ * it. Determinism matters: the same Doc always builds a byte-identical
+ * script, because sidecar↔doc matching later compares slices of this
+ * exact string.
+ */
+
+interface BuildScriptOptions {
+    /** Include block headings as spoken text (readers usually speak them). Default true. */
+    includeTitles?: boolean;
+    /** Separator joining block texts inside `sourceText`. Default '\n\n'. */
+    blockSeparator?: string;
+}
+/**
+ * Build the narration script for a doc. Blocks with no spoken text
+ * (pure-media sections, container-template children) contribute no
+ * tokens and no block range.
+ */
+declare function buildNarrationScript(doc: Doc, options?: BuildScriptOptions): NarrationScript;
+/**
+ * Expected cumulative syllables at a (fractional) word position —
+ * linear interpolation over the prefix sums.
+ */
+declare function expectedSyllablesAt(script: NarrationScript, wordPos: number): number;
+/**
+ * Inverse of {@link expectedSyllablesAt}: the fractional word position at
+ * which the script reaches `syllables` cumulative syllables. Used by the
+ * pacing controller's hard resync.
+ */
+declare function wordPosAtExpectedSyllables(script: NarrationScript, syllables: number): number;
+/** Index of the token containing (or following) a char offset into sourceText. */
+declare function wordIndexAtChar(script: NarrationScript, charOffset: number): number;
+/**
+ * Index of the active word at a playback time, given aligned word
+ * timings — the last word whose `tSec` ≤ `tSec` (or 0 before the first).
+ */
+declare function wordIndexAtTime(words: WordTiming[], tSec: number): number;
+
+/**
+ * Frame feature extraction: full-band RMS, speech-band energy, and
+ * zero-crossing rate over hopped (possibly overlapping) frames.
+ *
+ * Band energy uses two cascaded RBJ biquads — a high-pass at
+ * `bandLowHz` and a low-pass at `bandHighHz` (both Q = 1/√2,
+ * Audio-EQ-Cookbook closed forms) — rather than an FFT or Goertzel
+ * bins: a Butterworth-ish cascade gives a true maximally-flat band in
+ * one O(N) pass, and the filter state persists across hops, which is
+ * exactly right for streaming (no window-boundary energy jitter).
+ * Goertzel measures single frequencies (DTMF-style) — wrong tool for
+ * broadband speech energy.
+ */
+
+interface BiquadCoeffs {
+    b0: number;
+    b1: number;
+    b2: number;
+    a1: number;
+    a2: number;
+}
+interface BiquadState {
+    x1: number;
+    x2: number;
+    y1: number;
+    y2: number;
+}
+interface BandpassState {
+    coeffs: {
+        hp: BiquadCoeffs;
+        lp: BiquadCoeffs;
+    };
+    hp: BiquadState;
+    lp: BiquadState;
+}
+/** Create bandpass state for a sample rate (corners derived at init). */
+declare function createBandpass(sampleRate: number, lowHz?: number, highHz?: number): BandpassState;
+/**
+ * Run the bandpass over a chunk. Pure in the state: returns a NEW state,
+ * writes filtered samples into `output` (may alias `input`).
+ */
+declare function bandpassRun(state: BandpassState, input: Float32Array, output: Float32Array): BandpassState;
+interface FeatureState {
+    sampleRate: number;
+    config: FeatureConfig;
+    /** Hop between frame starts, in samples. */
+    hopSamples: number;
+    bandpass: BandpassState;
+    /** Unconsumed raw samples (the next frame's prefix). */
+    rawCarry: Float32Array;
+    /** Bandpassed twin of `rawCarry`. */
+    bandCarry: Float32Array;
+    /** Absolute sample index of `rawCarry[0]` from the start of the signal. */
+    carryStartSample: number;
+}
+declare function createFeatureState(sampleRate: number, config?: Partial<FeatureConfig>): FeatureState;
+/**
+ * Feed a hop of PCM. Returns a new state plus every complete frame the
+ * buffered signal now covers (usually 0–1 for worklet-sized hops, more
+ * for large chunks).
+ */
+declare function featureStep(state: FeatureState, hop: Float32Array): {
+    state: FeatureState;
+    frames: FrameFeatures[];
+};
+/** Batch feature extraction over a whole take (the aligner's entry point). */
+declare function extractFrameFeatures(pcm: Float32Array, sampleRate: number, config?: Partial<FeatureConfig>): FrameFeatures[];
+
+/**
+ * Adaptive voice-activity detection over frame features.
+ *
+ * The noise floor is an asymmetric EMA of band energy that hugs minima
+ * (≈ a 5th-percentile tracker): fast attack toward quieter frames, slow
+ * release upward, and FROZEN upward while speaking so long speech can't
+ * inflate it. Speech enters via a ratio threshold with a
+ * consecutive-frame debounce and exits after a continuous sub-exit
+ * dwell (hangover) — the hangover also bridges trailing fricatives and
+ * inter-word dips. A dip-starved rebaseline escape keeps a step change
+ * in room noise from wedging the detector open: real speech dips below
+ * the enter threshold between syllables, steady noise never does.
+ */
+
+interface VadState {
+    /** Adaptive noise-floor estimate (band-energy units). */
+    noiseFloor: number;
+    /** The VAD decision — the stage's output. */
+    speaking: boolean;
+    /** Consecutive supra-enter frames observed while silent. */
+    enterStreak: number;
+    /** tSec when the current sub-exit dwell began (while speaking), else null. */
+    subExitSince: number | null;
+    /** tSec when the current zero-dip run began (while speaking), else null. */
+    noDipSince: number | null;
+    /** No speech decisions before this time (floor seeding). */
+    warmupUntilSec: number;
+    /** False until the first frame seeds the floor. */
+    seeded: boolean;
+    lastTSec: number;
+}
+declare function createVadState(config?: Partial<VadConfig>): VadState;
+/** Pure per-frame step. `state.speaking` on the returned state is the decision for this frame. */
+declare function vadStep(state: VadState, frame: FrameFeatures, config?: Partial<VadConfig>): VadState;
+
+/**
+ * Syllable-nuclei detection: vowel nuclei show up as peaks in a
+ * low-passed amplitude envelope of the speech-band signal.
+ *
+ * Envelope = one-pole low-pass (≈10 Hz) over √bandEnergy (amplitude
+ * domain, so peaks are nuclei rather than energy spikes). A peak is
+ * emitted one frame late (local-max needs one frame of lookahead —
+ * ~20 ms live latency) and accepted only when: VAD says speaking, it
+ * clears the minimum inter-onset spacing, it is prominent relative to
+ * the valley since the last accepted peak, and it clears a decaying
+ * loudness reference (guards against ripples inside quiet speech).
+ */
+
+interface NucleiState {
+    /** One-pole envelope of √bandEnergy. */
+    env: number;
+    prevEnv: number;
+    prevPrevEnv: number;
+    /** tSec of the previous frame (the peak-candidate time). */
+    prevTSec: number;
+    /** Envelope minimum since the last accepted peak. */
+    valley: number;
+    lastOnsetTSec: number;
+    /** Decaying loudness reference. */
+    peakRef: number;
+    lastTSec: number;
+    framesSeen: number;
+}
+declare function createNucleiState(_config?: Partial<NucleiConfig>): NucleiState;
+/**
+ * Pure per-frame step. `onset` is the tSec of a newly accepted syllable
+ * nucleus (emitted once, at its peak frame), or null.
+ */
+declare function nucleiStep(state: NucleiState, frame: FrameFeatures, speaking: boolean, config?: Partial<NucleiConfig>): {
+    state: NucleiState;
+    onset: number | null;
+};
+/** Batch wrapper for the offline aligner. `vadFlags[i]` pairs with `frames[i]`. */
+declare function detectSyllableOnsets(frames: FrameFeatures[], vadFlags: boolean[], config?: Partial<NucleiConfig>): number[];
+
+/**
+ * The teleprompter pacing controller.
+ *
+ * A pure, deterministic step function: given the current state, one
+ * analysis tick (VAD flag + syllable onsets), and the script, produce
+ * the next state. The prompter position (`wordPos`) advances at a
+ * velocity that (a) halts within ~250 ms of silence, (b) tracks the
+ * reader's detected syllable rate while speaking, and (c) is corrected
+ * by a PI loop on cumulative detected-vs-expected syllables so the
+ * highlight can't drift arbitrarily far from the voice. Silence near an
+ * expected paragraph/block break is legitimate and accrues no error.
+ */
+
+interface PacingTick {
+    tSec: number;
+    speaking: boolean;
+    /** Syllable onsets detected in this tick (0 or 1 for frame-sized ticks). */
+    onsets: number;
+}
+interface PacingState {
+    /** Fractional word position — the active token is `floor(wordPos)`. */
+    wordPos: number;
+    /** Current scroll velocity in words per second. */
+    velocityWps: number;
+    /** EMA of the detected syllable rate (syl/s); 0 until two onsets arrive. */
+    emaSylPerSec: number;
+    lastOnsetTSec: number | null;
+    /** Syllables detected since the last anchor. */
+    cumDetectedSyl: number;
+    /** Expected cumulative syllables at the last anchor position. */
+    anchorExpectedSyl: number;
+    /** PI integral of the cumulative-syllable error (syl·s). */
+    errIntegral: number;
+    /** Continuous silence observed so far (s). */
+    silenceSec: number;
+    lastTSec: number | null;
+    /** True when silent and fully stopped. */
+    halted: boolean;
+}
+declare function createPacingState(startWordPos?: number): PacingState;
+/** Pure controller step — same inputs always yield the same output state. */
+declare function pacingStep(state: PacingState, tick: PacingTick, script: NarrationScript, config?: Partial<PacingConfig>): PacingState;
+/**
+ * Re-anchor after a manual nudge/scroll: the new position becomes the
+ * zero-error reference. The learned rate EMA survives.
+ */
+declare function reanchorPacing(state: PacingState, wordPos: number, script: NarrationScript): PacingState;
+
+/**
+ * Live-session composition: one pure call per PCM hop runs feature
+ * extraction → VAD → nuclei → pacing. This is the only surface the
+ * editor's mic loop needs — feed it worklet batches, read
+ * `state.pacing.wordPos` / `state.vad.speaking` / `state.lastFrame`.
+ */
+
+interface NarrationSessionConfig {
+    feature?: Partial<FeatureConfig>;
+    vad?: Partial<VadConfig>;
+    nuclei?: Partial<NucleiConfig>;
+    pacing?: Partial<PacingConfig>;
+}
+interface NarrationSessionState {
+    script: NarrationScript;
+    config: NarrationSessionConfig;
+    features: FeatureState;
+    vad: VadState;
+    nuclei: NucleiState;
+    pacing: PacingState;
+    /** Most recent analysis frame — drives the UI level meter. */
+    lastFrame: FrameFeatures | null;
+    /** Seconds of PCM consumed so far. */
+    tSec: number;
+}
+declare function createNarrationSession(sampleRate: number, script: NarrationScript, config?: NarrationSessionConfig): NarrationSessionState;
+/** Feed one hop of mono PCM; every completed frame advances VAD/nuclei/pacing. */
+declare function narrationSessionStep(state: NarrationSessionState, hop: Float32Array): NarrationSessionState;
+/** Manual nudge/scroll: re-anchor the pacing controller at a word position. */
+declare function reanchorSession(state: NarrationSessionState, wordPos: number): NarrationSessionState;
+
+/**
+ * Live prompter trace: sparse `{ tMs, wordPos }` samples the UI records
+ * while the reader records a take (~4 Hz plus one on every re-anchor).
+ * The offline aligner uses it as a prior — a Sakoe-Chiba band around
+ * the trace keeps the DTW honest and cheap.
+ */
+interface TraceSample {
+    tMs: number;
+    wordPos: number;
+}
+interface NarrationTrace {
+    samples: TraceSample[];
+}
+/** Clamped linear interpolation of the trace at a time. */
+declare function traceWordPosAt(trace: NarrationTrace, tSec: number): number;
+/** Downsample to at most `maxSamples`, always keeping both endpoints. */
+declare function downsampleTrace(trace: NarrationTrace, maxSamples: number): NarrationTrace;
+
+/**
+ * Offline narration alignment: refine word/block timestamps from a
+ * recorded take.
+ *
+ * Pipeline: fine-hop features → VAD flags → syllable onsets + silence
+ * gaps (the DETECTED event sequence) vs. the script's expected
+ * syllable/pause slots (the EXPECTED sequence), aligned with a banded
+ * DTW. The band (Sakoe-Chiba style) follows the live prompter trace
+ * when one exists — the trace is what the reader actually saw — and a
+ * proportional prior otherwise. Matched slots yield word timestamps;
+ * block starts snap to the end of the breath gap readers take before a
+ * heading; block ranges are made CONTIGUOUS because downstream preview
+ * building re-derives start times from durations.
+ */
+
+interface AlignInput {
+    /** Mono PCM of the whole take. */
+    pcm: Float32Array;
+    sampleRate: number;
+    script: NarrationScript;
+    /** Live prompter trace recorded during the take, if any. */
+    trace?: NarrationTrace;
+}
+declare function alignNarration(input: AlignInput, config?: Partial<AlignConfig>): NarrationAlignment;
+
+/**
+ * Narration timing sidecar v3 — the extended `<audio>.timing.json`.
+ *
+ * v1 (the recorder's original shape) is `{ sourceText, duration,
+ * bookmarks }` with bookmarks always empty. v3 fills the bookmarks with
+ * real per-word timings from the aligner and adds contiguous per-block
+ * ranges. `version: 2` is already taken by the consolidated root
+ * `timing.json` (`{ version: 2, sections }`), hence v3.
+ *
+ * Compatibility contract (tested in both directions): v3 is a strict
+ * superset of v1, so the legacy `parseTimingJson` gate (requires
+ * `sourceText` + `duration`, ignores unknown keys) keeps accepting v3
+ * files; {@link parseNarrationTimingJson} accepts v1 files and returns
+ * them with empty `blocks`.
+ */
+
+/** Narration time range of one doc block at record time. */
+interface NarrationTimingBlock {
+    /** Doc block id at record time (primary match key; ids can drift on heading edits). */
+    blockId?: string;
+    /** Block heading at record time (human-readable + fuzzy match key). */
+    heading?: string;
+    /** Index in renderable-block order at record time. */
+    blockIndex: number;
+    /** Char range into `sourceText` — the durable content key. */
+    charStart: number;
+    charEnd: number;
+    startSec: number;
+    /** Contiguous with the next block's startSec (aligner invariant). */
+    endSec: number;
+}
+interface NarrationTimingJsonV3 {
+    version: 3;
+    /** EXACTLY the NarrationScript.sourceText of the take. */
+    sourceText: string;
+    /** Take length in seconds (decoded-PCM length, not the recorder clock). */
+    duration: number;
+    /** Per-word timings: { id: `word-${i}`, time, charOffset, textFragment }. */
+    bookmarks: AudioBookmark[];
+    blocks: NarrationTimingBlock[];
+    /** Start skew of the companion camera recording, when one exists. */
+    cameraOffsetSec?: number;
+    /** Provenance of the timing data. */
+    generator?: {
+        name: string;
+        method: 'dsp-align';
+        baseWpm?: number;
+    };
+}
+interface BuildNarrationTimingOptions {
+    cameraOffsetSec?: number;
+    baseWpm?: number;
+}
+/** Build the v3 sidecar payload from a script + its alignment. Pure. */
+declare function buildNarrationTimingJson(script: NarrationScript, alignment: NarrationAlignment, durationSec: number, options?: BuildNarrationTimingOptions): NarrationTimingJsonV3;
+/**
+ * Tolerant parse: accepts v3, and v1 (`{ sourceText, duration,
+ * bookmarks? }`) which comes back with empty `blocks`. Returns null for
+ * malformed payloads. Blocks are sorted and clamped monotonic
+ * defensively (hand-edited sidecars).
+ */
+declare function parseNarrationTimingJson(data: ArrayBuffer | Uint8Array | string): NarrationTimingJsonV3 | null;
+
+export { type AlignConfig, type AlignInput, type BandpassState, type BuildNarrationTimingOptions, type BuildScriptOptions, DEFAULT_ALIGN_CONFIG, DEFAULT_FEATURE_CONFIG, DEFAULT_NUCLEI_CONFIG, DEFAULT_PACING_CONFIG, DEFAULT_VAD_CONFIG, type FeatureConfig, type FeatureState, type FrameFeatures, type NarrationAlignment, type NarrationBlockRange, type NarrationScript, type NarrationSessionConfig, type NarrationSessionState, type NarrationTimingBlock, type NarrationTimingJsonV3, type NarrationTrace, type NucleiConfig, type NucleiState, type PacingConfig, type PacingState, type PacingTick, type ScriptBlockRange, type ScriptToken, type TraceSample, type VadConfig, type VadState, type WordTiming, alignNarration, bandpassRun, buildNarrationScript, buildNarrationTimingJson, createBandpass, createFeatureState, createNarrationSession, createNucleiState, createPacingState, createVadState, detectSyllableOnsets, downsampleTrace, estimateSyllables, expectedSyllablesAt, extractFrameFeatures, featureStep, narrationSessionStep, nucleiStep, pacingStep, parseNarrationTimingJson, reanchorPacing, reanchorSession, traceWordPosAt, vadStep, wordIndexAtChar, wordIndexAtTime, wordPosAtExpectedSyllables };