@happyvertical/speech 0.97.0 → 0.98.0

package/dist/local.js

@@ -0,0 +1,963 @@
+import { C as SpeechProviderError, S as SpeechError, f as readEnv, h as reportSpeechUsage, o as defaultEnv, p as resolveTranscriberConfig, r as registerOptionalTranscriber, v as normalizeAudioInput, x as SpeechConfigurationError, y as normalizeMimeType } from "./chunks/registry-DfID41Ew.js";
+//#region src/adapters/local/env.ts
+/**
+* Environment configuration for the `local` transcriber. Explicit options win,
+* then the factory context, then `HAVE_SPEECH_TRANSCRIBER_*` variables (Node).
+*/
+/** Local-only environment variables, in priority order. */
+var LOCAL_TRANSCRIBER_ENV_KEYS = {
+	device: ["HAVE_SPEECH_TRANSCRIBER_DEVICE"],
+	dtype: ["HAVE_SPEECH_TRANSCRIBER_DTYPE"],
+	cacheDir: ["HAVE_SPEECH_TRANSCRIBER_CACHE_DIR"],
+	modelHost: ["HAVE_SPEECH_TRANSCRIBER_MODEL_HOST"]
+};
+/**
+* Merges explicit options with the environment. `model` and `maxBytes` reuse
+* the shared `HAVE_SPEECH_TRANSCRIBER_MODEL`/`_MAX_BYTES` keys.
+*/
+function resolveLocalTranscriberOptions(options = {}, context = {}) {
+	const env = context.env ?? defaultEnv();
+	const shared = resolveTranscriberConfig({
+		model: options.model,
+		maxBytes: options.maxBytes
+	}, { env });
+	return {
+		...options,
+		type: "local",
+		model: shared.model,
+		maxBytes: shared.maxBytes,
+		device: options.device ?? readEnv(env, ...LOCAL_TRANSCRIBER_ENV_KEYS.device),
+		dtype: options.dtype ?? readEnv(env, ...LOCAL_TRANSCRIBER_ENV_KEYS.dtype),
+		cacheDir: options.cacheDir ?? readEnv(env, ...LOCAL_TRANSCRIBER_ENV_KEYS.cacheDir),
+		modelHost: options.modelHost ?? readEnv(env, ...LOCAL_TRANSCRIBER_ENV_KEYS.modelHost)
+	};
+}
+//#endregion
+//#region src/adapters/local/runtime.ts
+/**
+* Loads the optional `@huggingface/transformers` peer dependency and builds
+* `automatic-speech-recognition` pipelines from it.
+*
+* This is the only module that names the peer. It is reachable only from the
+* `@happyvertical/speech/local` entry, never from the core entry.
+*/
+var TRANSFORMERS_PACKAGE = "@huggingface/transformers";
+var TRANSFORMERS_INSTALL_HINT = `Local transcription needs the optional peer dependency ${TRANSFORMERS_PACKAGE}. Install it with \`pnpm add ${TRANSFORMERS_PACKAGE}\` (or npm/yarn equivalent).`;
+/**
+* Resolves the transformers.js module: an injected module or loader, else a
+* dynamic import of the peer. A missing peer becomes a
+* `SpeechConfigurationError` with an install hint.
+*/
+async function loadTransformers(runtime) {
+	let loaded;
+	try {
+		loaded = typeof runtime === "function" ? await runtime() : runtime ?? await importTransformers();
+	} catch (error) {
+		if (error instanceof SpeechConfigurationError) throw error;
+		const configurationError = new SpeechConfigurationError(`${TRANSFORMERS_INSTALL_HINT} (${errorMessage$2(error)})`, "local");
+		configurationError.cause = error;
+		throw configurationError;
+	}
+	const candidate = loaded;
+	const module = typeof candidate?.pipeline === "function" ? candidate : candidate?.default;
+	if (typeof module?.pipeline !== "function") throw new SpeechConfigurationError(`${TRANSFORMERS_PACKAGE} did not export pipeline(); expected v4 or later`, "local");
+	return module;
+}
+/** Isolated so tests can observe whether the peer was ever imported. */
+function importTransformers() {
+	return import("@huggingface/transformers");
+}
+/**
+* Creates the ASR pipeline. `device: 'auto'` resolves to WebGPU when a
+* browser adapter is available (retrying on WASM if WebGPU fails to
+* initialise) and to CPU elsewhere.
+*/
+async function createAsrPipeline(transformers, options) {
+	const device = options.device === "auto" ? await detectAutoDevice() : options.device;
+	const build = (selected) => transformers.pipeline("automatic-speech-recognition", options.model, {
+		device: selected,
+		...options.dtype ? { dtype: options.dtype } : {},
+		...options.revision ? { revision: options.revision } : {},
+		...options.cacheDir ? { cache_dir: options.cacheDir } : {},
+		...options.onProgress ? { progress_callback: options.onProgress } : {}
+	});
+	try {
+		return {
+			pipeline: await build(device),
+			device
+		};
+	} catch (error) {
+		if (options.device === "auto" && device === "webgpu") return {
+			pipeline: await build("wasm"),
+			device: "wasm"
+		};
+		throw error;
+	}
+}
+/** `webgpu` when a browser exposes a usable adapter, `wasm` in other browsers, `cpu` in Node. */
+async function detectAutoDevice() {
+	if (isNodeRuntime()) return "cpu";
+	const gpu = globalThis.navigator?.gpu;
+	if (gpu) try {
+		if (await gpu.requestAdapter()) return "webgpu";
+	} catch {}
+	return "wasm";
+}
+function isNodeRuntime() {
+	return Boolean(globalThis.process?.versions?.node);
+}
+function errorMessage$2(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+//#endregion
+//#region src/adapters/local/abort.ts
+/**
+* Rejects with the signal's reason as soon as it aborts, without waiting for
+* `promise` (which keeps running; its eventual result is ignored).
+*/
+function raceAbort(promise, signal) {
+	if (!signal) return promise;
+	if (signal.aborted) {
+		promise.catch(() => void 0);
+		return Promise.reject(signal.reason);
+	}
+	return new Promise((resolve, reject) => {
+		const onAbort = () => reject(signal.reason);
+		signal.addEventListener("abort", onAbort, { once: true });
+		promise.then((value) => {
+			signal.removeEventListener("abort", onAbort);
+			resolve(value);
+		}, (error) => {
+			signal.removeEventListener("abort", onAbort);
+			reject(error);
+		});
+	});
+}
+//#endregion
+//#region src/adapters/local/audio.ts
+/**
+* Audio decoding for on-device inference: turns encoded bytes into 16 kHz
+* mono Float32 PCM, the input Whisper and Moonshine expect.
+*
+* - WAV (PCM 8/16/24/32-bit, IEEE float 32/64, WAVE_FORMAT_EXTENSIBLE) and raw
+*   `audio/pcm` are decoded in-process in every runtime, including workers.
+* - Anything else goes to the caller's `decodeAudio` hook, or, in browsers,
+*   to `OfflineAudioContext.decodeAudioData` (MediaRecorder WebM/Opus, Safari
+*   `audio/mp4`, MP3, ...).
+*/
+/** Sample rate expected by Whisper and Moonshine feature extractors. */
+var LOCAL_SAMPLE_RATE = 16e3;
+var ADAPTER = "local";
+var WAV_MIME_TYPES = /* @__PURE__ */ new Set([
+	"audio/wav",
+	"audio/wave",
+	"audio/x-wav",
+	"audio/vnd.wave"
+]);
+var PCM_MIME_TYPES = /* @__PURE__ */ new Set([
+	"audio/pcm",
+	"audio/x-pcm",
+	"audio/raw"
+]);
+/**
+* Decodes `bytes` and returns 16 kHz mono Float32 samples.
+*
+* Raw PCM (`audio/pcm`) is little-endian signed 16-bit by default; pass
+* `encoding=f32le` for Float32. The rate comes from the `rate` MIME parameter
+* or `sampleRate`, the channel count from `channels` (default 1).
+*/
+async function decodeToPcm16k(bytes, options) {
+	return toPcm16k(await raceAbort(decodeAudioBytes(bytes, options), options.signal));
+}
+/** Downmixes decoded audio to mono and resamples it to 16 kHz. */
+function toPcm16k(decoded) {
+	return resample(downmix(decoded.samples), decoded.sampleRate, LOCAL_SAMPLE_RATE);
+}
+/**
+* True for WAV and raw PCM, which this module decodes itself in every
+* runtime, including Web Workers.
+*/
+function isInProcessDecodable(bytes, mimeType) {
+	const essence = normalizeMimeType(mimeType);
+	return Boolean(essence && (WAV_MIME_TYPES.has(essence) || PCM_MIME_TYPES.has(essence)) || isRiffWave(bytes));
+}
+/**
+* Decodes a format without an in-process decoder through the caller's
+* `decodeAudio` hook or, in browsers, `OfflineAudioContext`. Resolves
+* `undefined` when neither is available.
+*/
+async function decodeExternally(bytes, options) {
+	if (options.decodeAudio) {
+		const decoded = await options.decodeAudio({
+			bytes,
+			mimeType: options.mimeType,
+			signal: options.signal
+		});
+		assertDecodedAudio(decoded);
+		return decoded;
+	}
+	if (hasOfflineAudioContext()) return decodeWithAudioContext(bytes);
+}
+async function decodeAudioBytes(bytes, options) {
+	const essence = normalizeMimeType(options.mimeType);
+	if (essence && WAV_MIME_TYPES.has(essence) || isRiffWave(bytes)) return decodeWav(bytes);
+	if (essence && PCM_MIME_TYPES.has(essence)) return decodeRawPcm(bytes, options);
+	const decoded = await decodeExternally(bytes, options);
+	if (decoded) return decoded;
+	throw new SpeechConfigurationError(`Cannot decode '${options.mimeType}' audio on this runtime: pass WAV or audio/pcm, or supply a decodeAudio hook (e.g. ffmpeg) for compressed formats`, ADAPTER);
+}
+function isRiffWave(bytes) {
+	return bytes.byteLength >= 12 && ascii(bytes, 0, 4) === "RIFF" && ascii(bytes, 8, 4) === "WAVE";
+}
+/** Parses a RIFF/WAVE file into per-channel Float32 samples. */
+function decodeWav(bytes) {
+	if (!isRiffWave(bytes)) throw new SpeechConfigurationError("Invalid WAV data: missing RIFF/WAVE header", ADAPTER);
+	const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+	let format;
+	let offset = 12;
+	while (offset + 8 <= bytes.byteLength) {
+		const id = ascii(bytes, offset, 4);
+		const size = view.getUint32(offset + 4, true);
+		const body = offset + 8;
+		if (id === "fmt ") format = readWavFormat(view, body, size);
+		else if (id === "data") {
+			if (!format) throw new SpeechConfigurationError("Invalid WAV data: data chunk before fmt chunk", ADAPTER);
+			const available = bytes.byteLength - body;
+			const length = size === 0 || size > available ? available : size;
+			return {
+				samples: deinterleave(bytes.subarray(body, body + length), format.channels, format.encoding),
+				sampleRate: format.sampleRate
+			};
+		}
+		offset = body + size + size % 2;
+	}
+	throw new SpeechConfigurationError("Invalid WAV data: no data chunk", ADAPTER);
+}
+var WAVE_FORMAT_PCM = 1;
+var WAVE_FORMAT_IEEE_FLOAT = 3;
+var WAVE_FORMAT_EXTENSIBLE = 65534;
+function readWavFormat(view, body, size) {
+	if (size < 16) throw new SpeechConfigurationError("Invalid WAV data: fmt chunk too short", ADAPTER);
+	let tag = view.getUint16(body, true);
+	const channels = view.getUint16(body + 2, true);
+	const sampleRate = view.getUint32(body + 4, true);
+	const bitsPerSample = view.getUint16(body + 14, true);
+	if (tag === WAVE_FORMAT_EXTENSIBLE && size >= 26) tag = view.getUint16(body + 24, true);
+	const encoding = tag === WAVE_FORMAT_PCM ? {
+		8: "u8",
+		16: "s16le",
+		24: "s24le",
+		32: "s32le"
+	}[bitsPerSample] : tag === WAVE_FORMAT_IEEE_FLOAT ? {
+		32: "f32le",
+		64: "f64le"
+	}[bitsPerSample] : void 0;
+	if (!encoding || channels < 1 || sampleRate < 1) throw new SpeechConfigurationError(`Unsupported WAV encoding (format ${tag}, ${bitsPerSample}-bit, ${channels} channels); use PCM or IEEE float, or supply a decodeAudio hook`, ADAPTER);
+	return {
+		channels,
+		sampleRate,
+		encoding
+	};
+}
+function decodeRawPcm(bytes, options) {
+	const params = mimeParameters(options.mimeType);
+	const sampleRate = positiveInteger(params.rate) ?? explicitPositiveInteger(options.sampleRate, "sampleRate");
+	const channels = positiveInteger(params.channels) ?? explicitPositiveInteger(options.channels, "channels") ?? 1;
+	const encoding = (params.encoding ?? "s16le").toLowerCase();
+	if (!sampleRate) throw new SpeechConfigurationError("Raw PCM audio needs a sample rate: use 'audio/pcm;rate=16000' or AudioInput.sampleRate", ADAPTER);
+	if (encoding !== "s16le" && encoding !== "f32le") throw new SpeechConfigurationError(`Unsupported raw PCM encoding '${encoding}' (expected s16le or f32le)`, ADAPTER);
+	return {
+		samples: deinterleave(bytes, channels, encoding),
+		sampleRate
+	};
+}
+var BYTES_PER_SAMPLE = {
+	u8: 1,
+	s16le: 2,
+	s24le: 3,
+	s32le: 4,
+	f32le: 4,
+	f64le: 8
+};
+function deinterleave(bytes, channels, encoding) {
+	const width = BYTES_PER_SAMPLE[encoding];
+	const frames = Math.floor(bytes.byteLength / (width * channels));
+	const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+	const output = Array.from({ length: channels }, () => new Float32Array(frames));
+	for (let frame = 0; frame < frames; frame++) for (let channel = 0; channel < channels; channel++) {
+		const at = (frame * channels + channel) * width;
+		output[channel][frame] = readSample(view, at, encoding);
+	}
+	return output;
+}
+function readSample(view, at, encoding) {
+	switch (encoding) {
+		case "u8": return (view.getUint8(at) - 128) / 128;
+		case "s16le": return view.getInt16(at, true) / 32768;
+		case "s24le": return (view.getUint8(at) | view.getUint8(at + 1) << 8 | view.getInt8(at + 2) << 16) / 8388608;
+		case "s32le": return view.getInt32(at, true) / 2147483648;
+		case "f32le": return view.getFloat32(at, true);
+		case "f64le": return view.getFloat64(at, true);
+	}
+}
+/** Averages channels into one mono track. */
+function downmix(samples) {
+	if (samples instanceof Float32Array) return samples;
+	if (samples.length === 1) return samples[0];
+	const length = Math.min(...samples.map((channel) => channel.length));
+	const mono = new Float32Array(length);
+	for (const channel of samples) for (let index = 0; index < length; index++) mono[index] = mono[index] + channel[index] / samples.length;
+	return mono;
+}
+/**
+* Resamples mono audio with linear interpolation. When downsampling, a box
+* filter one source period wide is applied first to limit aliasing; this is
+* adequate for speech recognition, not for music playback.
+*/
+function resample(samples, fromRate, toRate) {
+	if (fromRate === toRate || samples.length === 0) return samples;
+	const ratio = fromRate / toRate;
+	const source = ratio > 1 ? boxFilter(samples, Math.round(ratio)) : samples;
+	const length = Math.max(1, Math.round(samples.length / ratio));
+	const output = new Float32Array(length);
+	for (let index = 0; index < length; index++) {
+		const position = index * ratio;
+		const left = Math.floor(position);
+		const right = Math.min(left + 1, source.length - 1);
+		const fraction = position - left;
+		output[index] = source[left] * (1 - fraction) + source[right] * fraction;
+	}
+	return output;
+}
+function boxFilter(samples, width) {
+	if (width <= 1) return samples;
+	const output = new Float32Array(samples.length);
+	const half = Math.floor(width / 2);
+	let sum = 0;
+	let count = 0;
+	let start = 0;
+	let end = 0;
+	for (let index = 0; index < samples.length; index++) {
+		const windowStart = Math.max(0, index - half);
+		const windowEnd = Math.min(samples.length, index - half + width);
+		while (end < windowEnd) {
+			sum += samples[end];
+			count++;
+			end++;
+		}
+		while (start < windowStart) {
+			sum -= samples[start];
+			count--;
+			start++;
+		}
+		output[index] = sum / count;
+	}
+	return output;
+}
+function hasOfflineAudioContext() {
+	return typeof globalThis.OfflineAudioContext === "function";
+}
+/**
+* Browser decode path. Decoding through a 16 kHz `OfflineAudioContext` makes
+* the browser resample with its own high-quality resampler. Not available in
+* Web Workers: decode on the main thread (see the worker client).
+*/
+async function decodeWithAudioContext(bytes) {
+	const context = new OfflineAudioContext(1, 1, LOCAL_SAMPLE_RATE);
+	const copy = new Uint8Array(bytes.byteLength);
+	copy.set(bytes);
+	let buffer;
+	try {
+		buffer = await context.decodeAudioData(copy.buffer);
+	} catch (error) {
+		throw new SpeechConfigurationError(`The browser could not decode the audio: ${errorMessage$1(error)}`, ADAPTER);
+	}
+	return {
+		samples: Array.from({ length: buffer.numberOfChannels }, (_, index) => buffer.getChannelData(index)),
+		sampleRate: buffer.sampleRate
+	};
+}
+function assertDecodedAudio(decoded) {
+	const channels = decoded?.samples instanceof Float32Array ? [decoded.samples] : decoded?.samples;
+	if (!Array.isArray(channels) || channels.length === 0 || !channels.every((channel) => channel instanceof Float32Array) || !(decoded.sampleRate > 0)) throw new SpeechConfigurationError("decodeAudio must return { samples: Float32Array | Float32Array[], sampleRate }", ADAPTER);
+}
+function mimeParameters(mimeType) {
+	const params = {};
+	for (const part of mimeType.split(";").slice(1)) {
+		const [key, value] = part.split("=");
+		if (key && value) params[key.trim().toLowerCase()] = value.trim().replace(/^"|"$/g, "");
+	}
+	return params;
+}
+function positiveInteger(value) {
+	const parsed = value ? Number.parseInt(value, 10) : NaN;
+	return Number.isFinite(parsed) && parsed > 0 ? parsed : void 0;
+}
+/** Validates a caller-supplied `AudioInput.sampleRate`/`channels`. */
+function explicitPositiveInteger(value, name) {
+	if (value === void 0 || value === null) return;
+	if (!Number.isInteger(value) || value < 1) throw new SpeechConfigurationError(`AudioInput.${name} must be a positive integer, got ${String(value)}`, ADAPTER);
+	return value;
+}
+function ascii(bytes, offset, length) {
+	return String.fromCharCode(...bytes.subarray(offset, offset + length));
+}
+function errorMessage$1(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+//#endregion
+//#region src/adapters/local/transcriber.ts
+/** Small multilingual Whisper (~80 MB at the default q8 quantisation). */
+var DEFAULT_LOCAL_MODEL = "onnx-community/whisper-base";
+var DEFAULT_CHUNK_LENGTH_SECONDS = 30;
+var WHISPER_WINDOW_SECONDS = 30;
+var WHISPER_MODEL_TYPES = /* @__PURE__ */ new Set(["whisper", "lite-whisper"]);
+/**
+* On-device speech-to-text with transformers.js (Whisper or Moonshine ONNX).
+* Runs on WebGPU/WASM in browsers and onnxruntime-node in Node; no audio
+* leaves the device and no API key is involved.
+*/
+var LocalTranscriber = class {
+	type = "local";
+	options;
+	model;
+	maxBytes;
+	onUsage;
+	runtime;
+	pipelines = /* @__PURE__ */ new Map();
+	/** Serialises inference: ONNX sessions (especially WebGPU) run one call at a time. */
+	queue = Promise.resolve();
+	constructor(options = {}) {
+		this.options = options;
+		this.model = options.model?.trim() || "onnx-community/whisper-base";
+		this.maxBytes = options.maxBytes ?? 26214400;
+		this.onUsage = options.onUsage;
+	}
+	/**
+	* Downloads (first time) and initialises the model so the first
+	* `transcribe()` is fast. Progress goes to `onProgress`.
+	*/
+	async preload(model, signal) {
+		await raceAbort(this.loadPipeline(model?.trim() || this.model), signal);
+	}
+	async transcribe(request) {
+		const { signal } = request;
+		const audio = await normalizeAudioInput(request.audio, {
+			mimeType: request.mimeType,
+			maxBytes: request.maxBytes ?? this.maxBytes,
+			adapter: this.type,
+			signal
+		});
+		const format = pcmFormat(request.audio);
+		const samples = await decodeToPcm16k(new Uint8Array(await audio.blob.arrayBuffer()), {
+			mimeType: audio.mimeType,
+			sampleRate: format.sampleRate,
+			channels: format.channels,
+			decodeAudio: this.options.decodeAudio,
+			signal
+		});
+		signal?.throwIfAborted();
+		const model = request.model?.trim() || this.model;
+		const loaded = await raceAbort(this.loadPipeline(model), signal);
+		const audioSeconds = samples.length / LOCAL_SAMPLE_RATE;
+		const output = await raceAbort(this.enqueue(() => this.run(loaded.pipeline, samples, audioSeconds, request)), signal);
+		const usage = {
+			operation: "transcription",
+			provider: this.type,
+			model,
+			audioSeconds,
+			bytes: audio.bytes
+		};
+		const result = {
+			...mapAsrOutput(output, request.timestampGranularities?.includes("word") ?? false),
+			language: request.language,
+			durationSeconds: audioSeconds,
+			provider: this.type,
+			model,
+			raw: output,
+			usage
+		};
+		await reportSpeechUsage(usage, this.onUsage, request.onUsage);
+		return result;
+	}
+	/** Waits for in-flight inference, then releases every loaded model session. */
+	async dispose() {
+		await this.queue;
+		const loaded = [...this.pipelines.values()];
+		this.pipelines.clear();
+		await Promise.all(loaded.map(async (entry) => {
+			const { pipeline } = await entry.catch(() => ({ pipeline: void 0 }));
+			await pipeline?.dispose?.();
+		}));
+	}
+	async run(pipeline, samples, audioSeconds, request) {
+		const { signal } = request;
+		signal?.throwIfAborted();
+		const transformers = await this.loadRuntime();
+		const options = {};
+		if (WHISPER_MODEL_TYPES.has(pipeline.model?.config?.model_type ?? "whisper")) {
+			const granularities = request.timestampGranularities ?? [];
+			if (granularities.includes("word")) options.return_timestamps = "word";
+			else if (granularities.includes("segment")) options.return_timestamps = true;
+			const chunkLength = this.options.chunkLengthSeconds ?? DEFAULT_CHUNK_LENGTH_SECONDS;
+			if (chunkLength > 0 && audioSeconds > WHISPER_WINDOW_SECONDS) options.chunk_length_s = chunkLength;
+			if (request.language) {
+				options.language = request.language;
+				options.task = "transcribe";
+			}
+		}
+		let stopping;
+		if (signal && transformers.InterruptableStoppingCriteria) {
+			stopping = new transformers.InterruptableStoppingCriteria();
+			options.stopping_criteria = stopping;
+		}
+		const onAbort = () => stopping?.interrupt();
+		signal?.addEventListener("abort", onAbort, { once: true });
+		try {
+			const output = await pipeline(samples, options);
+			return Array.isArray(output) ? output[0] ?? { text: "" } : output;
+		} catch (error) {
+			if (signal?.aborted) throw signal.reason;
+			const hint = options.return_timestamps === "word" && /cross attentions/i.test(errorMessage(error)) ? " (word timestamps need a model exported with cross attentions, e.g. onnx-community/whisper-base_timestamped)" : "";
+			throw new SpeechProviderError(this.type, `Local transcription failed: ${errorMessage(error)}${hint}`, { cause: error });
+		} finally {
+			signal?.removeEventListener("abort", onAbort);
+		}
+	}
+	enqueue(task) {
+		const next = this.queue.then(task, task);
+		this.queue = next.catch(() => void 0);
+		return next;
+	}
+	loadRuntime() {
+		if (!this.runtime) {
+			const { transformers, configureEnv, modelHost } = this.options;
+			this.runtime = loadTransformers(transformers).then((module) => {
+				if (module.env) {
+					if (modelHost) module.env.remoteHost = modelHost;
+					configureEnv?.(module.env);
+				}
+				return module;
+			});
+			this.runtime.catch(() => {
+				this.runtime = void 0;
+			});
+		}
+		return this.runtime;
+	}
+	loadPipeline(model) {
+		let loaded = this.pipelines.get(model);
+		if (!loaded) {
+			loaded = this.loadRuntime().then((transformers) => createAsrPipeline(transformers, {
+				model,
+				device: this.options.device ?? "auto",
+				dtype: this.options.dtype,
+				revision: this.options.revision,
+				cacheDir: this.options.cacheDir,
+				onProgress: this.options.onProgress
+			}).catch((error) => {
+				if (error instanceof SpeechConfigurationError) throw error;
+				throw new SpeechProviderError(this.type, `Failed to load local model '${model}': ${errorMessage(error)}`, { cause: error });
+			}));
+			this.pipelines.set(model, loaded);
+			loaded.catch(() => {
+				if (this.pipelines.get(model) === loaded) this.pipelines.delete(model);
+			});
+		}
+		return loaded;
+	}
+};
+/**
+* Maps transformers.js chunks onto `words` (when word timestamps were
+* requested) or `segments`.
+*/
+function mapAsrOutput(output, wordLevel) {
+	const result = { text: (output.text ?? "").trim() };
+	const chunks = output.chunks;
+	if (!chunks?.length) return result;
+	if (wordLevel) result.words = chunks.filter((chunk) => chunk.text.trim()).map((chunk) => ({
+		word: chunk.text.trim(),
+		startSeconds: chunk.timestamp[0],
+		endSeconds: chunk.timestamp[1] ?? chunk.timestamp[0]
+	}));
+	else result.segments = chunks.map((chunk) => ({
+		text: chunk.text.trim(),
+		startSeconds: chunk.timestamp[0],
+		endSeconds: chunk.timestamp[1] ?? void 0
+	}));
+	return result;
+}
+function pcmFormat(audio) {
+	if (audio && typeof audio === "object" && "data" in audio && !(audio instanceof Uint8Array)) return {
+		sampleRate: audio.sampleRate,
+		channels: audio.channels
+	};
+	return {};
+}
+function errorMessage(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+//#endregion
+//#region src/adapters/local/worker.ts
+/**
+* Web Worker support for the `local` transcriber.
+*
+* Inference runs in a worker (`serveLocalTranscriber`) so long recordings never
+* block the UI thread. The main-thread client (`LocalTranscriberWorkerClient`)
+* transfers WAV and raw PCM bytes to the worker, which parses, downmixes, and
+* resamples them there. Only formats that need `AudioContext` (which workers
+* lack) or the client's `decodeAudio` hook are decoded on the main thread;
+* their Float32 channels are then transferred and resampled in the worker.
+*/
+var PCM_MIME_TYPE = `audio/pcm;rate=${LOCAL_SAMPLE_RATE};encoding=f32le`;
+/**
+* Runs a {@link LocalTranscriber} inside a worker and answers client
+* requests. Call it from your worker module:
+*
+* ```ts
+* // transcriber.worker.ts
+* import { serveLocalTranscriber } from '@happyvertical/speech/local';
+* serveLocalTranscriber({ model: 'onnx-community/whisper-base' });
+* ```
+*
+* Returns a function that stops listening and disposes the model.
+*/
+function serveLocalTranscriber(options = {}, endpoint = globalThis) {
+	const userProgress = options.onProgress;
+	const transcriber = new LocalTranscriber({
+		...resolveLocalTranscriberOptions(options),
+		maxBytes: Number.POSITIVE_INFINITY,
+		onProgress: (progress) => {
+			userProgress?.(progress);
+			endpoint.postMessage({
+				kind: "progress",
+				progress: toCloneable(progress)
+			});
+		}
+	});
+	const pending = /* @__PURE__ */ new Map();
+	const reply = (message) => endpoint.postMessage(message);
+	const listener = (event) => {
+		const message = event.data;
+		if (!message || typeof message !== "object") return;
+		if (message.kind === "abort") {
+			pending.get(message.id)?.abort();
+			return;
+		}
+		const controller = new AbortController();
+		pending.set(message.id, controller);
+		(message.kind === "preload" ? transcriber.preload(message.model, controller.signal).then(() => {
+			reply({
+				kind: "result",
+				id: message.id
+			});
+		}) : Promise.resolve().then(() => transcriber.transcribe({
+			audio: toAudioInput(message.audio),
+			model: message.model,
+			language: message.language,
+			timestampGranularities: message.timestampGranularities,
+			signal: controller.signal
+		})).then((result) => {
+			reply({
+				kind: "result",
+				id: message.id,
+				result
+			});
+		})).catch((error) => {
+			reply({
+				kind: "error",
+				id: message.id,
+				error: serializeError(error)
+			});
+		}).finally(() => pending.delete(message.id));
+	};
+	endpoint.addEventListener("message", listener);
+	return async () => {
+		endpoint.removeEventListener("message", listener);
+		for (const controller of pending.values()) controller.abort();
+		await transcriber.dispose();
+	};
+}
+/**
+* Main-thread {@link Transcriber} that delegates inference to a worker running
+* {@link serveLocalTranscriber}.
+*
+* ```ts
+* const worker = new Worker(new URL('./transcriber.worker.ts', import.meta.url), { type: 'module' });
+* const transcriber = new LocalTranscriberWorkerClient(worker, { onProgress });
+* const { text } = await transcriber.transcribe({ audio: recordingBlob });
+* ```
+*/
+var LocalTranscriberWorkerClient = class {
+	type = "local";
+	endpoint;
+	options;
+	calls = /* @__PURE__ */ new Map();
+	nextId = 1;
+	closed = false;
+	/** Aborted by `close()` to reject calls still buffering or decoding. */
+	closing = new AbortController();
+	listener = (event) => this.onMessage(event.data);
+	constructor(endpoint, options = {}) {
+		this.endpoint = endpoint;
+		this.options = options;
+		endpoint.addEventListener("message", this.listener);
+	}
+	/** Loads the model in the worker ahead of the first transcription. */
+	async preload(model, signal) {
+		await this.call({
+			kind: "preload",
+			model
+		}, signal);
+	}
+	async transcribe(request) {
+		this.assertOpen();
+		const { signal } = request;
+		const { audio, bytes } = await raceAbort(this.prepare(request), this.closing.signal);
+		const result = await this.call({
+			kind: "transcribe",
+			audio,
+			model: request.model,
+			language: request.language,
+			timestampGranularities: request.timestampGranularities
+		}, signal, transferList(audio));
+		if (!result) throw new SpeechProviderError(this.type, "Worker returned no result");
+		const usage = {
+			...result.usage ?? {
+				operation: "transcription",
+				provider: this.type
+			},
+			bytes
+		};
+		await reportSpeechUsage(usage, this.options.onUsage, request.onUsage);
+		return {
+			...result,
+			usage
+		};
+	}
+	/**
+	* Stops listening, rejects in-flight and later calls, and asks the worker to
+	* abort posted work. Does not terminate the worker.
+	*/
+	close() {
+		if (this.closed) return;
+		this.closed = true;
+		this.endpoint.removeEventListener("message", this.listener);
+		this.closing.abort(closedError());
+		for (const [id, call] of this.calls) {
+			this.endpoint.postMessage({
+				kind: "abort",
+				id
+			});
+			call.reject(closedError());
+		}
+		this.calls.clear();
+	}
+	/** Buffers the input and, only when the worker cannot, decodes it here. */
+	async prepare(request) {
+		const { signal } = request;
+		const normalized = await normalizeAudioInput(request.audio, {
+			mimeType: request.mimeType,
+			maxBytes: request.maxBytes ?? this.options.maxBytes ?? 26214400,
+			adapter: this.type,
+			signal
+		});
+		const bytes = new Uint8Array(await normalized.blob.arrayBuffer());
+		if (!isInProcessDecodable(bytes, normalized.mimeType)) {
+			const decoded = await raceAbort(decodeExternally(bytes, {
+				mimeType: normalized.mimeType,
+				decodeAudio: this.options.decodeAudio,
+				signal
+			}), signal);
+			if (decoded) return {
+				audio: {
+					kind: "decoded",
+					samples: (decoded.samples instanceof Float32Array ? [decoded.samples] : decoded.samples).map(ownedCopy),
+					sampleRate: decoded.sampleRate
+				},
+				bytes: normalized.bytes
+			};
+		}
+		const wrapped = typeof request.audio === "object" && "data" in request.audio && !(request.audio instanceof Uint8Array) ? request.audio : void 0;
+		return {
+			audio: {
+				kind: "encoded",
+				bytes: ownedCopy(bytes),
+				mimeType: normalized.mimeType,
+				sampleRate: wrapped?.sampleRate,
+				channels: wrapped?.channels
+			},
+			bytes: normalized.bytes
+		};
+	}
+	assertOpen() {
+		if (this.closed) throw closedError();
+	}
+	call(message, signal, transfer = []) {
+		this.assertOpen();
+		signal?.throwIfAborted();
+		const id = this.nextId++;
+		return new Promise((resolve, reject) => {
+			const onAbort = () => {
+				this.calls.delete(id);
+				this.endpoint.postMessage({
+					kind: "abort",
+					id
+				});
+				reject(signal?.reason);
+			};
+			const settle = () => signal?.removeEventListener("abort", onAbort);
+			this.calls.set(id, {
+				resolve: (result) => {
+					settle();
+					resolve(result);
+				},
+				reject: (error) => {
+					settle();
+					reject(error);
+				}
+			});
+			signal?.addEventListener("abort", onAbort, { once: true });
+			this.endpoint.postMessage({
+				...message,
+				id
+			}, transfer);
+		});
+	}
+	onMessage(message) {
+		if (!message || typeof message !== "object") return;
+		if (message.kind === "progress") {
+			this.options.onProgress?.(message.progress);
+			return;
+		}
+		const call = this.calls.get(message.id);
+		if (!call) return;
+		this.calls.delete(message.id);
+		if (message.kind === "result") call.resolve(message.result);
+		else call.reject(deserializeError(message.error));
+	}
+};
+function closedError() {
+	return new SpeechConfigurationError("Worker client closed", "local");
+}
+/** Rebuilds the transcriber input from a worker message, resampling decoded channels here. */
+function toAudioInput(audio) {
+	if (audio.kind === "decoded") {
+		const pcm = toPcm16k({
+			samples: audio.samples,
+			sampleRate: audio.sampleRate
+		});
+		return {
+			data: new Uint8Array(pcm.buffer, pcm.byteOffset, pcm.byteLength),
+			mimeType: PCM_MIME_TYPE
+		};
+	}
+	return {
+		data: audio.bytes,
+		mimeType: audio.mimeType,
+		sampleRate: audio.sampleRate,
+		channels: audio.channels
+	};
+}
+/**
+* Returns `view` when it spans a whole ordinary `ArrayBuffer` (safe to
+* transfer), otherwise a copy. Views of a larger buffer would transfer
+* unrelated bytes, and a `SharedArrayBuffer` cannot be transferred at all.
+*/
+function ownedCopy(view) {
+	const { buffer } = view;
+	return isPlainArrayBuffer(buffer) && view.byteOffset === 0 && view.byteLength === buffer.byteLength ? view : view.slice();
+}
+function isPlainArrayBuffer(buffer) {
+	return Object.prototype.toString.call(buffer) === "[object ArrayBuffer]";
+}
+/** Distinct buffers to transfer (two channels may share one). */
+function transferList(audio) {
+	const views = audio.kind === "decoded" ? audio.samples : [audio.bytes];
+	return [...new Set(views.map((view) => view.buffer))];
+}
+function serializeError(error) {
+	if (error instanceof SpeechError) return {
+		name: error.name,
+		message: error.message,
+		code: error.code
+	};
+	if (error instanceof Error) return {
+		name: error.name,
+		message: error.message
+	};
+	return {
+		name: "Error",
+		message: String(error)
+	};
+}
+function deserializeError(error) {
+	switch (error.name) {
+		case "SpeechConfigurationError": return new SpeechConfigurationError(error.message, "local");
+		case "SpeechProviderError": return new SpeechProviderError("local", error.message);
+		case "AbortError": return new DOMException(error.message, "AbortError");
+		default: {
+			const restored = new Error(error.message);
+			restored.name = error.name;
+			return restored;
+		}
+	}
+}
+/** Progress objects cross `postMessage`, so drop anything not cloneable. */
+function toCloneable(progress) {
+	const clone = { status: progress.status };
+	for (const [key, value] of Object.entries(progress)) if (value === null || [
+		"string",
+		"number",
+		"boolean"
+	].includes(typeof value)) clone[key] = value;
+	return clone;
+}
+//#endregion
+//#region src/local.ts
+/**
+* @happyvertical/speech/local
+*
+* On-device speech-to-text with transformers.js (`@huggingface/transformers`,
+* an optional peer dependency loaded on first use). Importing this entry
+* registers `type: 'local'` with `getTranscriber()` and `getSpeech()`.
+*
+* @example
+* ```typescript
+* import { getTranscriber } from '@happyvertical/speech';
+* import '@happyvertical/speech/local';
+*
+* const transcriber = await getTranscriber({ type: 'local' });
+* const { text } = await transcriber.transcribe({ audio: wavBytes, mimeType: 'audio/wav' });
+* ```
+*
+* @packageDocumentation
+*/
+/**
+* Creates an on-device transcriber. Explicit options win over
+* `HAVE_SPEECH_TRANSCRIBER_*` environment variables (see
+* `LOCAL_TRANSCRIBER_ENV_KEYS`). The model loads on first use.
+*/
+function createLocalTranscriber(options = {}, context = {}) {
+	return new LocalTranscriber(resolveLocalTranscriberOptions(options, context));
+}
+/**
+* Resolves `true` when `@huggingface/transformers` can be imported in this
+* runtime. This imports the runtime, so call it only when you intend to use it.
+*/
+async function isLocalTranscriberAvailable() {
+	try {
+		await loadTransformers(void 0);
+		return true;
+	} catch {
+		return false;
+	}
+}
+registerOptionalTranscriber("local", (options, context) => createLocalTranscriber({
+	...options,
+	type: "local"
+}, context));
+//#endregion
+export { DEFAULT_LOCAL_MODEL, LOCAL_SAMPLE_RATE, LOCAL_TRANSCRIBER_ENV_KEYS, LocalTranscriber, LocalTranscriberWorkerClient, TRANSFORMERS_INSTALL_HINT, TRANSFORMERS_PACKAGE, createLocalTranscriber, decodeToPcm16k, isLocalTranscriberAvailable, serveLocalTranscriber };
+
+//# sourceMappingURL=local.js.map