@tscaps/engine 0.2.1 → 0.3.0

package/dist/modules/transcription/WhisperInferenceProgressTracker.js

@@ -0,0 +1,102 @@
+/**
+ * Turns Whisper's chunk-relative timestamp stream into a monotonic
+ * fraction of the inference work done so far, in
+ * `[0, MAX_STREAMING_FRACTION]`.
+ *
+ * The transformers.js pipeline slices audio into fixed windows of
+ * `chunkLengthSeconds` and slides them by `chunkLengthSeconds - 2 *
+ * strideLengthSeconds`, decoding each window independently. Whisper's
+ * predicted timestamps restart at zero on every window, so a backward
+ * step in the observed stream is treated as the boundary between two
+ * pipeline windows. Small backward jitter *within* a window (the
+ * decoder occasionally re-emits an earlier timestamp) is tolerated up
+ * to `INTRA_CHUNK_TOLERANCE_SECONDS`.
+ *
+ * Progress is measured against the audio each window decodes, not
+ * against the position reached in the source. Consecutive windows
+ * overlap by `2 * strideLengthSeconds`, and that overlap is decoded
+ * twice: a position-based fraction cannot advance until a new window
+ * has re-decoded everything the previous one already covered, which
+ * shows up as the bar sitting frozen for the first third of every
+ * window. Counting each window's own audio makes the fraction track
+ * the decoder's actual cost instead.
+ *
+ * The returned fraction never decreases and never reaches `1`:
+ * Whisper still runs a word-timestamp post-processing pass after the
+ * last streamed segment, so a strictly-below-one ceiling leaves room
+ * for the caller to emit the terminal `1` from outside the streamer
+ * once the whole call actually completes.
+ */
+export class WhisperInferenceProgressTracker {
+    static INTRA_CHUNK_TOLERANCE_SECONDS = 1;
+    static MAX_STREAMING_FRACTION = 0.95;
+    windowSeconds;
+    totalWorkSeconds;
+    windowAdvanceSeconds;
+    currentWindowIndex = 0;
+    workBeforeCurrentWindow = 0;
+    lastReportedChunkTime = 0;
+    lastFraction = 0;
+    constructor(durationSeconds, chunkLengthSeconds, strideLengthSeconds) {
+        this.windowAdvanceSeconds = Math.max(1, chunkLengthSeconds - 2 * strideLengthSeconds);
+        this.windowSeconds = this.measureWindows(durationSeconds, chunkLengthSeconds);
+        this.totalWorkSeconds = this.windowSeconds.reduce((total, seconds) => total + seconds, 0);
+    }
+    /** The audio each pipeline window decodes, in window order. */
+    get windowLayout() {
+        return this.windowSeconds;
+    }
+    /** How far the pipeline slides between consecutive windows, in seconds. */
+    get advanceSeconds() {
+        return this.windowAdvanceSeconds;
+    }
+    /**
+     * Feeds a chunk-relative timestamp and returns the resulting monotonic
+     * progress fraction over the whole inference.
+     */
+    observeChunkEnd(timeWithinChunk) {
+        if (this.isNewPipelineWindow(timeWithinChunk)) {
+            this.advanceWindow();
+        }
+        this.lastReportedChunkTime = timeWithinChunk;
+        this.lastFraction = Math.max(this.lastFraction, this.fractionAt(timeWithinChunk));
+        return this.lastFraction;
+    }
+    /**
+     * Reproduces the window layout the transformers.js ASR pipeline builds
+     * for this audio, as the amount of audio each window carries. The last
+     * window is short whenever the audio does not end on a window boundary.
+     */
+    measureWindows(durationSeconds, chunkLengthSeconds) {
+        const advance = this.windowAdvanceSeconds;
+        const windows = [];
+        for (let start = 0;; start += advance) {
+            windows.push(Math.min(chunkLengthSeconds, durationSeconds - start));
+            if (start + chunkLengthSeconds >= durationSeconds)
+                return windows;
+        }
+    }
+    isNewPipelineWindow(timeWithinChunk) {
+        const tolerance = WhisperInferenceProgressTracker.INTRA_CHUNK_TOLERANCE_SECONDS;
+        return timeWithinChunk < this.lastReportedChunkTime - tolerance;
+    }
+    // Whisper can report more boundaries than the layout predicts; staying on
+    // the last window keeps the fraction below its ceiling instead of overshooting.
+    advanceWindow() {
+        if (this.currentWindowIndex >= this.windowSeconds.length - 1)
+            return;
+        this.workBeforeCurrentWindow += this.currentWindowSeconds();
+        this.currentWindowIndex += 1;
+    }
+    currentWindowSeconds() {
+        return this.windowSeconds[this.currentWindowIndex] ?? 0;
+    }
+    fractionAt(timeWithinChunk) {
+        if (this.totalWorkSeconds <= 0)
+            return 0;
+        const workWithinWindow = Math.min(Math.max(timeWithinChunk, 0), this.currentWindowSeconds());
+        const fraction = (this.workBeforeCurrentWindow + workWithinWindow) / this.totalWorkSeconds;
+        return Math.min(WhisperInferenceProgressTracker.MAX_STREAMING_FRACTION, fraction);
+    }
+}
+//# sourceMappingURL=WhisperInferenceProgressTracker.js.map

package/dist/modules/transcription/WhisperInferenceProgressTracker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"WhisperInferenceProgressTracker.js","sourceRoot":"","sources":["../../../src/modules/transcription/WhisperInferenceProgressTracker.ts"],"names":[],"mappings":"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"}

package/dist/modules/transcription/WhisperLoopAbortLogitsProcessor.d.ts

@@ -0,0 +1,38 @@
+import type { Tensor } from '@huggingface/transformers';
+/**
+ * Cuts short a generation that has degenerated into a repetition loop.
+ *
+ * Detection: the tail of the generated sequence contains at least
+ * `MIN_FULL_PERIODS` verbatim repetitions of some unit AND spans at
+ * least `MIN_REPETITION_TOKENS` tokens. On detection every logit
+ * except end-of-sequence is forced to `-Infinity`, so the next step
+ * emits end-of-sequence and the generation stops without burning the
+ * rest of the token budget on garbage.
+ *
+ * The guard only ends generations early; it never alters the content
+ * of a healthy one.
+ *
+ * Deliberately not a subclass of the inference library's processor base.
+ * Extending it would make this file load the library, and none of the
+ * detection below needs anything from it — `apply` is the whole of it.
+ * A thin subclass built once the library is loaded adapts this to what
+ * the pipeline expects.
+ */
+export declare class WhisperLoopAbortLogitsProcessor {
+    private readonly endOfSequenceTokenId;
+    private fired;
+    constructor(endOfSequenceTokenId: number);
+    /**
+     * Inspects one generation step and, on a detected loop, rewrites the
+     * logits so the next token can only be end-of-sequence. Returns the
+     * same tensor it was given, rewritten in place or untouched.
+     */
+    apply(inputIds: bigint[][], logits: Tensor): Tensor;
+    /** True when the guard fired since the previous call; reading resets it. */
+    consumeFired(): boolean;
+    private endsInRepetitionLoop;
+    private detectionWindowFor;
+    private isPeriodic;
+    private forceEndOfSequence;
+}
+//# sourceMappingURL=WhisperLoopAbortLogitsProcessor.d.ts.map

package/dist/modules/transcription/WhisperLoopAbortLogitsProcessor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WhisperLoopAbortLogitsProcessor.d.ts","sourceRoot":"","sources":["../../../src/modules/transcription/WhisperLoopAbortLogitsProcessor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,2BAA2B,CAAC;AAiBxD;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,+BAA+B;IAG9B,OAAO,CAAC,QAAQ,CAAC,oBAAoB;IAFjD,OAAO,CAAC,KAAK,CAAS;gBAEO,oBAAoB,EAAE,MAAM;IAEzD;;;;OAIG;IACH,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM;IASnD,4EAA4E;IAC5E,YAAY,IAAI,OAAO;IAMvB,OAAO,CAAC,oBAAoB;IAc5B,OAAO,CAAC,kBAAkB;IAM1B,OAAO,CAAC,UAAU;IAOlB,OAAO,CAAC,kBAAkB;CAM3B"}

package/dist/modules/transcription/WhisperLoopAbortLogitsProcessor.js

@@ -0,0 +1,94 @@
+// Full repetitions the tail must show before the pattern is trusted as
+// degenerate. Two verbatim repetitions of a phrase can be legitimate
+// emphasis; five cannot realistically be. This is a floor — longer
+// per-period windows still need at least this many repetitions.
+const MIN_FULL_PERIODS = 5;
+// Total token count the repeating tail must reach before it counts. Short
+// repeated tails — a 3-word chorus repeated a handful of times, a hymn
+// refrain — can be legitimate speech and stay below this bar. The
+// combination `MIN_FULL_PERIODS` full periods AND `MIN_REPETITION_TOKENS`
+// total tokens filters those out while still catching the multi-hundred-
+// token degenerate loops Whisper falls into. This is a floor on total
+// length, not a cap on period size.
+const MIN_REPETITION_TOKENS = 50;
+/**
+ * Cuts short a generation that has degenerated into a repetition loop.
+ *
+ * Detection: the tail of the generated sequence contains at least
+ * `MIN_FULL_PERIODS` verbatim repetitions of some unit AND spans at
+ * least `MIN_REPETITION_TOKENS` tokens. On detection every logit
+ * except end-of-sequence is forced to `-Infinity`, so the next step
+ * emits end-of-sequence and the generation stops without burning the
+ * rest of the token budget on garbage.
+ *
+ * The guard only ends generations early; it never alters the content
+ * of a healthy one.
+ *
+ * Deliberately not a subclass of the inference library's processor base.
+ * Extending it would make this file load the library, and none of the
+ * detection below needs anything from it — `apply` is the whole of it.
+ * A thin subclass built once the library is loaded adapts this to what
+ * the pipeline expects.
+ */
+export class WhisperLoopAbortLogitsProcessor {
+    endOfSequenceTokenId;
+    fired = false;
+    constructor(endOfSequenceTokenId) {
+        this.endOfSequenceTokenId = endOfSequenceTokenId;
+    }
+    /**
+     * Inspects one generation step and, on a detected loop, rewrites the
+     * logits so the next token can only be end-of-sequence. Returns the
+     * same tensor it was given, rewritten in place or untouched.
+     */
+    apply(inputIds, logits) {
+        for (let batch = 0; batch < inputIds.length; batch++) {
+            if (!this.endsInRepetitionLoop(inputIds[batch] ?? []))
+                continue;
+            this.fired = true;
+            this.forceEndOfSequence(batch, logits);
+        }
+        return logits;
+    }
+    /** True when the guard fired since the previous call; reading resets it. */
+    consumeFired() {
+        const fired = this.fired;
+        this.fired = false;
+        return fired;
+    }
+    endsInRepetitionLoop(sequence) {
+        const maxPeriod = Math.floor(sequence.length / MIN_FULL_PERIODS);
+        for (let period = 1; period <= maxPeriod; period++) {
+            const windowSize = this.detectionWindowFor(period);
+            if (windowSize > sequence.length)
+                continue;
+            if (this.isPeriodic(sequence, sequence.length - windowSize, period))
+                return true;
+        }
+        return false;
+    }
+    // Smallest multiple of `period` that satisfies both floors: at least
+    // `MIN_FULL_PERIODS` full repetitions, and at least `MIN_REPETITION_TOKENS`
+    // total tokens. Rounding up to a multiple of `period` keeps `isPeriodic`
+    // aligned to full repetitions.
+    detectionWindowFor(period) {
+        const byPeriodFloor = period * MIN_FULL_PERIODS;
+        const byTokenFloor = period * Math.ceil(MIN_REPETITION_TOKENS / period);
+        return Math.max(byPeriodFloor, byTokenFloor);
+    }
+    isPeriodic(sequence, from, period) {
+        for (let i = from + period; i < sequence.length; i++) {
+            if (sequence[i] !== sequence[i - period])
+                return false;
+        }
+        return true;
+    }
+    forceEndOfSequence(batch, logits) {
+        const row = logits[batch];
+        if (!row)
+            return;
+        row.data.fill(-Infinity);
+        row.data[this.endOfSequenceTokenId] = 0;
+    }
+}
+//# sourceMappingURL=WhisperLoopAbortLogitsProcessor.js.map

package/dist/modules/transcription/WhisperLoopAbortLogitsProcessor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"WhisperLoopAbortLogitsProcessor.js","sourceRoot":"","sources":["../../../src/modules/transcription/WhisperLoopAbortLogitsProcessor.ts"],"names":[],"mappings":"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"}

package/dist/modules/transcription/WhisperModelLoadFailedError.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Raised when preparing the Whisper pipeline fails — the model files
+ * could not be fetched, the runtime could not instantiate them, or an
+ * upstream library rejected the load for any other reason.
+ *
+ * The `.name` string is set explicitly, and exposed as `ERROR_NAME` on
+ * the class, so consumers can recognise the failure across a Worker
+ * boundary (where structured cloning preserves the string fields but
+ * not the class identity) with a single source of truth.
+ */
+export declare class WhisperModelLoadFailedError extends Error {
+    static readonly ERROR_NAME = "WhisperModelLoadFailedError";
+    readonly name = "WhisperModelLoadFailedError";
+}
+//# sourceMappingURL=WhisperModelLoadFailedError.d.ts.map

package/dist/modules/transcription/WhisperModelLoadFailedError.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WhisperModelLoadFailedError.d.ts","sourceRoot":"","sources":["../../../src/modules/transcription/WhisperModelLoadFailedError.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,qBAAa,2BAA4B,SAAQ,KAAK;IACpD,MAAM,CAAC,QAAQ,CAAC,UAAU,iCAAiC;IAC3D,QAAQ,CAAC,IAAI,iCAA0C;CACxD"}

package/dist/modules/transcription/WhisperModelLoadFailedError.js

@@ -0,0 +1,15 @@
+/**
+ * Raised when preparing the Whisper pipeline fails — the model files
+ * could not be fetched, the runtime could not instantiate them, or an
+ * upstream library rejected the load for any other reason.
+ *
+ * The `.name` string is set explicitly, and exposed as `ERROR_NAME` on
+ * the class, so consumers can recognise the failure across a Worker
+ * boundary (where structured cloning preserves the string fields but
+ * not the class identity) with a single source of truth.
+ */
+export class WhisperModelLoadFailedError extends Error {
+    static ERROR_NAME = 'WhisperModelLoadFailedError';
+    name = WhisperModelLoadFailedError.ERROR_NAME;
+}
+//# sourceMappingURL=WhisperModelLoadFailedError.js.map

package/dist/modules/transcription/WhisperModelLoadFailedError.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"WhisperModelLoadFailedError.js","sourceRoot":"","sources":["../../../src/modules/transcription/WhisperModelLoadFailedError.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,MAAM,OAAO,2BAA4B,SAAQ,KAAK;IACpD,MAAM,CAAU,UAAU,GAAG,6BAA6B,CAAC;IAClD,IAAI,GAAG,2BAA2B,CAAC,UAAU,CAAC"}

package/dist/modules/transcription/WhisperTranscriber.d.ts

@@ -1,8 +1,9 @@
 import { Document } from '../document/index';
 import type { AudioDecoder } from '../transcription/AudioDecoder';
-import type { Transcriber, TranscriberOptions, TranscriberProgressEvent } from '../transcription/Transcriber';
+import type { ModelFileCache } from '../transcription/ModelFileCache';
+import type { Transcriber, TranscriberOptions, TranscriberProgressEvent, UntranscribedRegion } from '../transcription/Transcriber';
 export declare const WHISPER_SAMPLE_RATE = 16000;
-export type WhisperModel = 'tiny' | 'base' | 'small' | 'distil-small.en' | 'distil-medium.en';
+export type WhisperModel = 'tiny' | 'base' | 'small' | 'medium' | 'distil-small.en' | 'distil-medium.en';
 export type WhisperDevice = 'auto' | 'wasm' | 'webgpu';
 export interface WhisperTranscriberConfig {
     model?: WhisperModel;
@@ -21,24 +22,122 @@ export interface WhisperTranscriberConfig {
  * in a Web Worker (where browser audio APIs are unavailable) with a pre-
  * decoded byte-stream decoder.
  *
- * Progress reporting is real-only: the loading stage tracks model weight
- * download from HuggingFace; the inferring stage emits a single boundary
- * event when inference begins, since the underlying pipeline exposes no
- * usable per-chunk hook in v4.
+ * Progress reporting is real-only for both stages. The loading stage
+ * tracks model weight download from HuggingFace. The inferring stage
+ * hooks a `WhisperTextStreamer` into `model.generate` so each
+ * pipeline-window boundary that Whisper predicts translates into an
+ * `[0, 1]` fraction of the audio processed so far. Clips short enough to
+ * fit in a single window emit no boundaries — the field stays at zero
+ * and the consumer can only render that as indeterminate.
+ *
+ * Coverage policy: every pipeline window's decoding is audited. A
+ * non-final window that ended by its own end-of-sequence but left
+ * audio before the next window's start gets one re-decode over real
+ * audio from that point. A window cut from outside — the repetition-
+ * loop guard or the token ceiling — is degenerate: its unclosed tail
+ * is dropped and its region is deliberately left untranscribed, never
+ * retried. A re-decode that degenerates too is discarded the same way.
+ * The final window is reported the same way when cut or stopped
+ * mid-segment; a clean close there is trusted as the end of speech.
  */
 export declare class WhisperTranscriber implements Transcriber {
     private readonly decoder;
     private readonly model;
     private readonly device;
+    private readonly chunkStitcher;
+    private readonly transformers;
+    private processorLists;
     private pipelinePromise;
-    constructor(decoder: AudioDecoder, { model, device }?: WhisperTranscriberConfig);
+    constructor(decoder: AudioDecoder, { model, device }?: WhisperTranscriberConfig, modelFileCache?: ModelFileCache);
     onProgress?: (event: TranscriberProgressEvent) => void;
+    onUntranscribedRegion?: (region: UntranscribedRegion) => void;
     transcribe(audio: Blob, options?: TranscriberOptions): Promise<Document>;
+    /**
+     * Builds the progress tracker for this audio, or `null` when a single
+     * pipeline window covers everything — no window boundary is ever
+     * reported then, so the progress bar stays indeterminate.
+     */
+    private buildProgressTracker;
+    /**
+     * Builds a `WhisperTextStreamer` that translates Whisper's per-window
+     * timestamp emissions into `[0, 1]` inference progress and feeds the
+     * per-window coverage record.
+     *
+     * `on_finalize` fires at the end of every `model.generate` call — one
+     * per pipeline window while the long-form layering stays opted out —
+     * which makes it the exact window delimiter the coverage record needs.
+     * It is deliberately not wired to progress: the terminal `progress: 1`
+     * can only come from the caller, after the whole call returns.
+     */
+    private buildProgressStreamer;
+    /**
+     * Builds the anti-loop guard for a generation, or `null` when the
+     * model's end-of-sequence token cannot be located — the guard can
+     * only abort by forcing that token.
+     */
+    private buildLoopGuard;
+    private loadPipelineOrFail;
+    private runInferenceOrFail;
+    /**
+     * Loads the pipeline once and reuses it for every later call.
+     *
+     * A failed load is *not* kept. The weights arrive over the network
+     * and the common failure is a transfer that dies partway, which the
+     * next attempt may well complete; caching the rejection would make
+     * every retry fail instantly without ever reaching the network
+     * again, leaving a reload as the only way out.
+     */
     private loadPipeline;
     private resolveDevice;
     private isWebGPUAvailable;
     private buildPipelineOptions;
+    /**
+     * The factory is built from the loaded library, so it is reached
+     * through the same load the pipeline came from rather than held from
+     * construction. By the time any generation runs, that load is settled.
+     */
+    private buildProcessorList;
     private handleLoadProgress;
+    /**
+     * The audio regions the main pass left uncovered. Empty when the
+     * number of generation passes does not match the expected window
+     * layout — that means the underlying pipeline changed its long-form
+     * behaviour and per-window attribution can no longer be trusted.
+     */
+    private detectUncoveredGaps;
+    /**
+     * Replaces the content of every uncovered gap. The main pass's words
+     * inside a gap come from tokens past their window's last closed
+     * segment — the same unclosed tail the reference Whisper decoder
+     * discards before re-decoding — so they are dropped. Dropping is safe
+     * because the word-timestamp alignment is monotonic in token order:
+     * no word of a closed segment lands past that segment's end.
+     *
+     * A rescuable gap gets one extra pass over real audio. A
+     * non-rescuable gap does not — its region is reported and left
+     * untranscribed rather than retried.
+     */
+    private redecodeGaps;
+    private isInsideAnyGap;
+    /**
+     * Runs one extra decoding pass over a full window of real audio
+     * starting at the gap and keeps the words that fall inside it. Words
+     * past the gap's end are dropped — the next pipeline window already
+     * covers that region.
+     *
+     * Best-effort by design: the main transcription is already in hand, so
+     * a failed rescue logs and contributes nothing instead of failing the
+     * whole call.
+     */
+    private rescueGap;
+    private reportUntranscribed;
+    /**
+     * Shifts slice-relative rescue chunks to absolute time and keeps the
+     * ones anchored inside the gap. A chunk with no usable timestamp
+     * cannot be placed and is dropped.
+     */
+    private chunksWithinGap;
+    private mergeChunks;
     private buildDocument;
 }
 //# sourceMappingURL=WhisperTranscriber.d.ts.map

package/dist/modules/transcription/WhisperTranscriber.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"WhisperTranscriber.d.ts","sourceRoot":"","sources":["../../../src/modules/transcription/WhisperTranscriber.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAA8C,MAAM,yBAAyB,CAAC;AAC/F,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qCAAqC,CAAC;AACxE,OAAO,KAAK,EACV,WAAW,EACX,kBAAkB,EAClB,wBAAwB,EACzB,MAAM,oCAAoC,CAAC;AAE5C,eAAO,MAAM,mBAAmB,QAAS,CAAC;AAE1C,MAAM,MAAM,YAAY,GACpB,MAAM,GACN,MAAM,GACN,OAAO,GACP,iBAAiB,GACjB,kBAAkB,CAAC;AAEvB,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,MAAM,GAAG,QAAQ,CAAC;AAEvD,MAAM,WAAW,wBAAwB;IACvC,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB,MAAM,CAAC,EAAE,aAAa,CAAC;CACxB;AA2DD;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,kBAAmB,YAAW,WAAW;IAMlD,OAAO,CAAC,QAAQ,CAAC,OAAO;IAL1B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAe;IACrC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgB;IACvC,OAAO,CAAC,eAAe,CAA4C;gBAGhD,OAAO,EAAE,YAAY,EACtC,EAAE,KAAc,EAAE,MAAe,EAAE,GAAE,wBAA6B;IAOpE,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,wBAAwB,KAAK,IAAI,CAAC;IAEjD,UAAU,CAAC,KAAK,EAAE,IAAI,EAAE,OAAO,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,QAAQ,CAAC;IAe9E,OAAO,CAAC,YAAY;YAoBN,aAAa;YAoBb,iBAAiB;IAW/B,OAAO,CAAC,oBAAoB;IAU5B,OAAO,CAAC,kBAAkB;IAS1B,OAAO,CAAC,aAAa;CAatB"}
+{"version":3,"file":"WhisperTranscriber.d.ts","sourceRoot":"","sources":["../../../src/modules/transcription/WhisperTranscriber.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAA8C,MAAM,yBAAyB,CAAC;AAE/F,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qCAAqC,CAAC;AACxE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uCAAuC,CAAC;AAC5E,OAAO,KAAK,EACV,WAAW,EACX,kBAAkB,EAClB,wBAAwB,EACxB,mBAAmB,EACpB,MAAM,oCAAoC,CAAC;AAU5C,eAAO,MAAM,mBAAmB,QAAS,CAAC;AAE1C,MAAM,MAAM,YAAY,GACpB,MAAM,GACN,MAAM,GACN,OAAO,GACP,QAAQ,GACR,iBAAiB,GACjB,kBAAkB,CAAC;AAEvB,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,MAAM,GAAG,QAAQ,CAAC;AAEvD,MAAM,WAAW,wBAAwB;IACvC,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB,MAAM,CAAC,EAAE,aAAa,CAAC;CACxB;AA4FD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,qBAAa,kBAAmB,YAAW,WAAW;IASlD,OAAO,CAAC,QAAQ,CAAC,OAAO;IAR1B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAe;IACrC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgB;IACvC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAuB;IACrD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAsB;IACnD,OAAO,CAAC,cAAc,CAA2C;IACjE,OAAO,CAAC,eAAe,CAA4C;gBAGhD,OAAO,EAAE,YAAY,EACtC,EAAE,KAAc,EAAE,MAAe,EAAE,GAAE,wBAA6B,EAClE,cAAc,CAAC,EAAE,cAAc;IASjC,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,wBAAwB,KAAK,IAAI,CAAC;IACvD,qBAAqB,CAAC,EAAE,CAAC,MAAM,EAAE,mBAAmB,KAAK,IAAI,CAAC;IAExD,UAAU,CAAC,KAAK,EAAE,IAAI,EAAE,OAAO,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,QAAQ,CAAC;IAqB9E;;;;OAIG;IACH,OAAO,CAAC,oBAAoB;IAU5B;;;;;;;;;;OAUG;YACW,qBAAqB;IAuBnC;;;;OAIG;IACH,OAAO,CAAC,cAAc;YAeR,kBAAkB;YASlB,kBAAkB;IAoBhC;;;;;;;;OAQG;IACH,OAAO,CAAC,YAAY;YAyBN,aAAa;YAoBb,iBAAiB;YAWjB,oBAAoB;IAiBlC;;;;OAIG;YACW,kBAAkB;IAShC,OAAO,CAAC,kBAAkB;IAS1B;;;;;OAKG;IACH,OAAO,CAAC,mBAAmB;IAkB3B;;;;;;;;;;;OAWG;YACW,YAAY;IAuB1B,OAAO,CAAC,cAAc;IAMtB;;;;;;;;;OASG;YACW,SAAS;IAiCvB,OAAO,CAAC,mBAAmB;IAI3B;;;;OAIG;IACH,OAAO,CAAC,eAAe;IAevB,OAAO,CAAC,WAAW;IAMnB,OAAO,CAAC,aAAa;CAatB"}