@happyvertical/speech 0.96.1 → 0.97.0

package/dist/index.js

@@ -24,22 +24,416 @@ var InvalidSpeechAdapterError = class extends SpeechError {
 var SpeechProviderError = class extends SpeechError {
 	status;
 	responseBody;
+	/** Parsed `Retry-After` delay in milliseconds, when the provider sent one. */
+	retryAfterMs;
 	constructor(adapter, message, options = {}) {
 		super(message, "SPEECH_PROVIDER_ERROR", adapter);
 		this.name = "SpeechProviderError";
 		this.status = options.status;
 		this.responseBody = options.responseBody;
+		this.retryAfterMs = options.retryAfterMs;
 		if (options.cause !== void 0) this.cause = options.cause;
 	}
 };
 //#endregion
+//#region src/shared/audio.ts
+/**
+* Audio input normalisation shared by speech adapters: accepts the input
+* shapes callers actually have (Blob, Buffer, Uint8Array, ArrayBuffer,
+* ReadableStream), enforces byte limits while buffering, and derives a
+* multipart filename whose extension matches the MIME type.
+*/
+/** OpenAI caps `/audio/transcriptions` uploads at 25 MB. */
+var DEFAULT_MAX_AUDIO_BYTES = 25 * 1024 * 1024;
+var MIME_EXTENSIONS = {
+	"audio/webm": "webm",
+	"video/webm": "webm",
+	"audio/mp4": "m4a",
+	"audio/m4a": "m4a",
+	"audio/x-m4a": "m4a",
+	"video/mp4": "mp4",
+	"audio/wav": "wav",
+	"audio/wave": "wav",
+	"audio/x-wav": "wav",
+	"audio/vnd.wave": "wav",
+	"audio/ogg": "ogg",
+	"application/ogg": "ogg",
+	"audio/mpeg": "mp3",
+	"audio/mp3": "mp3",
+	"audio/mpga": "mp3",
+	"audio/flac": "flac",
+	"audio/x-flac": "flac"
+};
+/**
+* Strips parameters (e.g. `;codecs=opus`) and lower-cases a MIME type.
+* Returns `undefined` for blank input.
+*/
+function normalizeMimeType(mimeType) {
+	const essence = mimeType?.split(";")[0]?.trim().toLowerCase();
+	return essence ? essence : void 0;
+}
+/**
+* Maps an audio MIME type to the file extension OpenAI-compatible servers use
+* to detect the container format. Codec parameters are ignored, so
+* `audio/webm;codecs=opus` maps to `webm`. Returns `undefined` when unknown.
+*/
+function mimeTypeToAudioExtension(mimeType) {
+	const essence = normalizeMimeType(mimeType);
+	return essence ? MIME_EXTENSIONS[essence] : void 0;
+}
+/**
+* Accepts either an {@link AudioInput} wrapper or a bare {@link AudioSource}
+* and returns a size-checked Blob plus the metadata needed for multipart
+* uploads.
+*/
+async function normalizeAudioInput(input, options = {}) {
+	const wrapped = isAudioInput(input) ? input : { data: input };
+	const { adapter, signal } = options;
+	signal?.throwIfAborted();
+	const maxBytes = resolveMaxBytes(options.maxBytes, adapter);
+	const data = wrapped.data;
+	const blobType = typeof Blob !== "undefined" && data instanceof Blob ? data.type : void 0;
+	const mimeType = options.mimeType ?? wrapped.mimeType ?? wrapped.contentType ?? (blobType || void 0) ?? "application/octet-stream";
+	let blob;
+	if (typeof Blob !== "undefined" && data instanceof Blob) {
+		assertWithinLimit(data.size, maxBytes, adapter);
+		blob = data.type === mimeType ? data : new Blob([data], { type: mimeType });
+	} else if (data instanceof Uint8Array) {
+		assertWithinLimit(data.byteLength, maxBytes, adapter);
+		blob = new Blob([copyBytes(data)], { type: mimeType });
+	} else if (data instanceof ArrayBuffer) {
+		assertWithinLimit(data.byteLength, maxBytes, adapter);
+		blob = new Blob([data], { type: mimeType });
+	} else if (isReadableStream(data)) {
+		const chunks = await readStreamWithLimit(data, maxBytes, adapter, signal);
+		blob = new Blob(chunks, { type: mimeType });
+	} else throw new SpeechConfigurationError("Unsupported audio input: expected Blob, Buffer, Uint8Array, ArrayBuffer, or ReadableStream", adapter);
+	if (blob.size === 0) throw new SpeechConfigurationError("Audio input is empty", adapter);
+	const extension = options.deriveExtension === false ? void 0 : mimeTypeToAudioExtension(mimeType);
+	const basename = options.defaultBasename ?? "audio";
+	const filename = wrapped.filename ?? (extension ? `${basename}.${extension}` : basename);
+	return {
+		blob,
+		mimeType,
+		bytes: blob.size,
+		filename,
+		durationSeconds: wrapped.durationSeconds
+	};
+}
+function isAudioInput(value) {
+	return typeof value === "object" && value !== null && "data" in value && !(typeof Blob !== "undefined" && value instanceof Blob) && !(value instanceof Uint8Array) && !(value instanceof ArrayBuffer) && !isReadableStream(value);
+}
+function isReadableStream(value) {
+	return typeof value === "object" && value !== null && typeof value.getReader === "function";
+}
+function resolveMaxBytes(maxBytes, adapter) {
+	if (maxBytes === void 0) return Number.POSITIVE_INFINITY;
+	if (Number.isNaN(maxBytes) || maxBytes <= 0) throw new SpeechConfigurationError("maxBytes must be a positive number", adapter);
+	return maxBytes;
+}
+function assertWithinLimit(bytes, maxBytes, adapter) {
+	if (bytes > maxBytes) throw new SpeechConfigurationError(`Audio input exceeds maxBytes (${bytes} > ${maxBytes} bytes)`, adapter);
+}
+async function readStreamWithLimit(stream, maxBytes, adapter, signal) {
+	const reader = stream.getReader();
+	const chunks = [];
+	let total = 0;
+	const onAbort = () => {
+		reader.cancel(signal?.reason).catch(() => void 0);
+	};
+	signal?.addEventListener("abort", onAbort, { once: true });
+	try {
+		for (;;) {
+			const { done, value } = await reader.read();
+			signal?.throwIfAborted();
+			if (done) break;
+			total += chunkByteLength(value, adapter);
+			if (total > maxBytes) {
+				await reader.cancel().catch(() => void 0);
+				throw new SpeechConfigurationError(`Audio stream exceeds maxBytes (more than ${maxBytes} bytes)`, adapter);
+			}
+			chunks.push(toBytes(value));
+		}
+	} finally {
+		signal?.removeEventListener("abort", onAbort);
+		reader.releaseLock();
+	}
+	return chunks;
+}
+function chunkByteLength(value, adapter) {
+	if (value instanceof Uint8Array || value instanceof ArrayBuffer) return value.byteLength;
+	throw new SpeechConfigurationError("Audio stream chunks must be Uint8Array or ArrayBuffer", adapter);
+}
+function toBytes(value) {
+	return value instanceof Uint8Array ? copyBytes(value) : new Uint8Array(value.slice(0));
+}
+function copyBytes(bytes) {
+	const copy = new Uint8Array(bytes.byteLength);
+	copy.set(bytes);
+	return copy;
+}
+//#endregion
+//#region src/shared/env.ts
+/**
+* Environment configuration for speech adapters.
+*
+* Transcriber settings resolve in this order (first wins):
+* explicit options → factory context → `HAVE_SPEECH_TRANSCRIBER_*` →
+* legacy `HAVE_SPEECH_STT_*` → gateway `STT_*` aliases.
+*/
+/** Environment variable names read for each transcriber setting, in priority order. */
+var TRANSCRIBER_ENV_KEYS = {
+	type: [
+		"HAVE_SPEECH_TRANSCRIBER_TYPE",
+		"HAVE_SPEECH_STT_TYPE",
+		"HAVE_SPEECH_STT_ADAPTER",
+		"STT_ADAPTER"
+	],
+	baseUrl: [
+		"HAVE_SPEECH_TRANSCRIBER_BASE_URL",
+		"HAVE_SPEECH_STT_BASE_URL",
+		"STT_BASE_URL"
+	],
+	model: [
+		"HAVE_SPEECH_TRANSCRIBER_MODEL",
+		"HAVE_SPEECH_STT_MODEL",
+		"STT_MODEL"
+	],
+	apiKey: [
+		"HAVE_SPEECH_TRANSCRIBER_API_KEY",
+		"HAVE_SPEECH_STT_API_KEY",
+		"STT_API_KEY",
+		"SPEECH_API_KEY"
+	],
+	timeoutMs: [
+		"HAVE_SPEECH_TRANSCRIBER_TIMEOUT",
+		"HAVE_SPEECH_TRANSCRIBER_TIMEOUT_MS",
+		"HAVE_SPEECH_STT_TIMEOUT_MS",
+		"STT_TIMEOUT_MS"
+	],
+	maxBytes: ["HAVE_SPEECH_TRANSCRIBER_MAX_BYTES", "STT_MAX_BYTES"],
+	headers: ["HAVE_SPEECH_TRANSCRIBER_HEADERS", "STT_HEADERS"],
+	path: [
+		"HAVE_SPEECH_TRANSCRIBER_PATH",
+		"HAVE_SPEECH_STT_PATH",
+		"STT_PATH"
+	]
+};
+function readTranscriberEnv(env) {
+	return {
+		type: readEnv(env, ...TRANSCRIBER_ENV_KEYS.type),
+		baseUrl: readEnv(env, ...TRANSCRIBER_ENV_KEYS.baseUrl),
+		model: readEnv(env, ...TRANSCRIBER_ENV_KEYS.model),
+		apiKey: readEnv(env, ...TRANSCRIBER_ENV_KEYS.apiKey),
+		timeoutMs: parseOptionalInteger(readEnv(env, ...TRANSCRIBER_ENV_KEYS.timeoutMs)),
+		maxBytes: parseOptionalInteger(readEnv(env, ...TRANSCRIBER_ENV_KEYS.maxBytes)),
+		headers: parseHeadersEnv(env, TRANSCRIBER_ENV_KEYS.headers),
+		path: readEnv(env, ...TRANSCRIBER_ENV_KEYS.path)
+	};
+}
+function hasTranscriberEnv(env) {
+	return hasAnyEnv(env, ...TRANSCRIBER_ENV_KEYS.type, ...TRANSCRIBER_ENV_KEYS.baseUrl);
+}
+/**
+* Merges explicit transcriber options with the factory context and the
+* environment. Explicit options always win; headers are merged so a
+* per-deployment env header (e.g. a gateway virtual key) can be combined with
+* explicit ones.
+*/
+function resolveTranscriberConfig(options = {}, context = {}) {
+	const fromEnv = readTranscriberEnv(context.env ?? defaultEnv());
+	const headers = mergeHeaderInits(fromEnv.headers, context.headers, options.headers);
+	return {
+		type: options.type ?? fromEnv.type,
+		baseUrl: (options.baseUrl ?? fromEnv.baseUrl)?.trim(),
+		model: options.model ?? fromEnv.model,
+		apiKey: options.apiKey ?? fromEnv.apiKey,
+		timeoutMs: options.timeoutMs ?? fromEnv.timeoutMs,
+		maxBytes: options.maxBytes ?? fromEnv.maxBytes,
+		headers,
+		fetch: options.fetch ?? context.fetch,
+		path: fromEnv.path
+	};
+}
+/** Merges header sets left to right; later sets win per header name. */
+function mergeHeaderInits(...sets) {
+	const present = sets.filter((set) => Boolean(set));
+	if (present.length === 0) return;
+	const merged = new Headers();
+	for (const set of present) new Headers(set).forEach((value, key) => {
+		merged.set(key, value);
+	});
+	return merged;
+}
+function readEnv(env, ...keys) {
+	for (const key of keys) {
+		const value = env[key];
+		if (value?.trim()) return value.trim();
+	}
+}
+function hasAnyEnv(env, ...keys) {
+	return keys.some((key) => Boolean(env[key]?.trim()));
+}
+function parseOptionalInteger(value) {
+	if (!value) return;
+	const parsed = Number.parseInt(value, 10);
+	return Number.isFinite(parsed) ? parsed : void 0;
+}
+function defaultEnv() {
+	return globalThis.process?.env ?? {};
+}
+/**
+* Parses a JSON object of header names to string values. The raw value is
+* never echoed in errors because it may carry credentials.
+*/
+function parseHeadersEnv(env, keys) {
+	for (const key of keys) {
+		const raw = env[key]?.trim();
+		if (!raw) continue;
+		let parsed;
+		try {
+			parsed = JSON.parse(raw);
+		} catch {
+			throw new SpeechConfigurationError(`${key} must be a JSON object of header names to string values`);
+		}
+		if (!parsed || typeof parsed !== "object" || Array.isArray(parsed) || !Object.values(parsed).every((value) => typeof value === "string")) throw new SpeechConfigurationError(`${key} must be a JSON object of header names to string values`);
+		return parsed;
+	}
+}
+//#endregion
+//#region src/shared/retry.ts
+/**
+* Retry with exponential backoff for speech provider calls. Retries only
+* rate-limit (429) and server (5xx) responses, honours `Retry-After`, and
+* stops immediately when the caller aborts.
+*/
+var DEFAULT_SPEECH_RETRY = {
+	maxRetries: 2,
+	initialDelayMs: 500,
+	maxDelayMs: 3e4
+};
+function resolveRetryOptions(retry, defaults = DEFAULT_SPEECH_RETRY) {
+	if (retry === false) return false;
+	if (retry === void 0) return defaults;
+	const base = defaults || DEFAULT_SPEECH_RETRY;
+	return {
+		maxRetries: Math.floor(finiteRetryValue("maxRetries", retry.maxRetries, base.maxRetries)),
+		initialDelayMs: finiteRetryValue("initialDelayMs", retry.initialDelayMs, base.initialDelayMs),
+		maxDelayMs: finiteRetryValue("maxDelayMs", retry.maxDelayMs, base.maxDelayMs)
+	};
+}
+/**
+* Rejects non-finite values (`NaN`, `Infinity`): they would make the retry
+* budget or delay cap unbounded. Negative values clamp to `0`.
+*/
+function finiteRetryValue(name, value, fallback) {
+	if (value === void 0) return Math.max(0, fallback);
+	if (typeof value !== "number" || !Number.isFinite(value)) throw new SpeechConfigurationError(`Speech retry option ${name} must be a finite number`);
+	return Math.max(0, value);
+}
+function isRetryableStatus(status) {
+	return status === 429 || status !== void 0 && status >= 500;
+}
+/**
+* Parses a `Retry-After` header (delta-seconds or HTTP-date) into
+* milliseconds. Returns `undefined` when absent or unparseable.
+*/
+function parseRetryAfter(value, now = Date.now()) {
+	if (!value?.trim()) return;
+	const trimmed = value.trim();
+	if (/^\d+(\.\d+)?$/.test(trimmed)) return Math.round(Number(trimmed) * 1e3);
+	const date = Date.parse(trimmed);
+	return Number.isNaN(date) ? void 0 : Math.max(0, date - now);
+}
+/**
+* Runs `attempt` until it succeeds, throws a non-retryable error, or the
+* retry budget is exhausted. Retryable errors are {@link SpeechProviderError}
+* instances whose `status` is 429 or 5xx.
+*/
+async function withSpeechRetry(attempt, retry, signal) {
+	const maxRetries = retry ? retry.maxRetries : 0;
+	for (let attemptNumber = 0;; attemptNumber += 1) try {
+		return await attempt(attemptNumber);
+	} catch (error) {
+		if (!retry || attemptNumber >= maxRetries || signal?.aborted || !(error instanceof SpeechProviderError) || !isRetryableStatus(error.status)) throw error;
+		const backoff = Math.min(retry.maxDelayMs, retry.initialDelayMs * 2 ** attemptNumber);
+		const retryAfterMs = error.retryAfterMs;
+		if (retryAfterMs !== void 0 && retryAfterMs > retry.maxDelayMs) throw error;
+		await sleep(Math.max(backoff, retryAfterMs ?? 0), signal);
+	}
+}
+function sleep(ms, signal) {
+	return new Promise((resolve, reject) => {
+		if (signal?.aborted) {
+			reject(signal.reason);
+			return;
+		}
+		const onAbort = () => {
+			clearTimeout(timer);
+			reject(signal?.reason);
+		};
+		const timer = setTimeout(() => {
+			signal?.removeEventListener("abort", onAbort);
+			resolve();
+		}, ms);
+		signal?.addEventListener("abort", onAbort, { once: true });
+	});
+}
+//#endregion
 //#region src/shared/http.ts
+/**
+* Parses a base URL, dropping any fragment and keeping any query string.
+* Throws {@link SpeechConfigurationError} for a blank or unparseable value.
+* The value is not echoed in the error because it may carry credentials.
+*/
+function parseBaseUrl(baseUrl) {
+	const trimmed = baseUrl.trim();
+	if (!trimmed) throw new SpeechConfigurationError("Speech adapter baseUrl is required");
+	let url;
+	try {
+		url = new URL(trimmed);
+	} catch {
+		throw new SpeechConfigurationError("Speech adapter baseUrl is not a valid absolute URL");
+	}
+	url.hash = "";
+	return url;
+}
+/**
+* Returns `baseUrl` with a trailing `/` on its path so relative paths resolve
+* beneath it. The query string is preserved and any fragment is dropped.
+*/
 function normalizeBaseUrl(baseUrl) {
-	if (!baseUrl.trim()) throw new SpeechConfigurationError("Speech adapter baseUrl is required");
-	return baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`;
+	const url = parseBaseUrl(baseUrl);
+	if (!url.pathname.endsWith("/")) url.pathname = `${url.pathname}/`;
+	return url.toString();
 }
+/**
+* Resolves `path` against `baseUrl`. A relative path without its own query
+* inherits the base URL's query (for example a gateway `api-version`); an
+* absolute URL is returned unchanged.
+*/
 function resolveSpeechUrl(baseUrl, path) {
-	return new URL(path.replace(/^\//, ""), normalizeBaseUrl(baseUrl)).toString();
+	const base = new URL(normalizeBaseUrl(baseUrl));
+	const isAbsolute = /^[a-z][a-z\d+.-]*:/i.test(path);
+	const resolved = new URL(isAbsolute ? path : path.replace(/^\//, ""), base);
+	if (!isAbsolute && !resolved.search && base.search) resolved.search = base.search;
+	return resolved.toString();
+}
+/**
+* Resolves an OpenAI-compatible endpoint from a base URL. Accepts a server
+* root (`https://api.openai.com` → `/v1/<resource>`), an API root ending in a
+* version segment (`http://gateway/stt/v1` → `/<resource>`), or the full
+* endpoint URL (used as-is). Only the path is rewritten: the query string is
+* preserved and any fragment is dropped.
+*/
+function resolveOpenAICompatibleUrl(baseUrl, resource) {
+	const trimmedResource = resource.replace(/^\/+|\/+$/g, "");
+	const url = parseBaseUrl(baseUrl);
+	const pathname = url.pathname.replace(/\/+$/, "");
+	if (pathname.endsWith(`/${trimmedResource}`)) url.pathname = pathname;
+	else if (/\/v\d+$/.test(pathname)) url.pathname = `${pathname}/${trimmedResource}`;
+	else url.pathname = `${pathname}/v1/${trimmedResource}`;
+	return url.toString();
 }
 function resolveFetch(fetchOverride) {
 	if (fetchOverride) return fetchOverride;
@@ -68,11 +462,21 @@ var HttpSpeechAdapter = class {
 		this.headers = options.headers;
 		this.timeoutMs = options.timeoutMs;
 	}
-	async post(adapterName, path, init, readResponse) {
+	/**
+	* POSTs to `path` (relative to `baseUrl`, or an absolute URL). The optional
+	* `retry` policy retries 429/5xx responses; `timeoutMs` applies per attempt.
+	* The request body must be re-sendable (string, Blob, FormData) when
+	* retries are enabled.
+	*/
+	async post(adapterName, path, init, readResponse, retry = false) {
+		return withSpeechRetry(() => this.postOnce(adapterName, path, init, readResponse), retry, init.signal ?? void 0);
+	}
+	async postOnce(adapterName, path, init, readResponse) {
 		const timeoutController = this.timeoutMs && this.timeoutMs > 0 ? new AbortController() : void 0;
 		const timeout = timeoutController && this.timeoutMs ? setTimeout(() => timeoutController.abort(), this.timeoutMs) : void 0;
 		const requestSignal = composeAbortSignals(init.signal, timeoutController?.signal);
 		try {
+			requestSignal.signal?.throwIfAborted();
 			const response = await this.fetchImpl(resolveSpeechUrl(this.baseUrl, path), {
 				...init,
 				method: "POST",
@@ -82,7 +486,7 @@ var HttpSpeechAdapter = class {
 				}, init.headers),
 				signal: requestSignal.signal
 			});
-			await assertOk(response, adapterName);
+			await assertOk(response, adapterName, this.apiKey);
 			return await readResponse(response);
 		} finally {
 			if (timeout) clearTimeout(timeout);
@@ -122,26 +526,19 @@ function composeAbortSignals(...signals) {
 		cleanup
 	};
 }
-async function assertOk(response, adapterName) {
+async function assertOk(response, adapterName, apiKey) {
 	if (response.ok) return;
 	const responseBody = await response.text().catch(() => void 0);
 	throw new SpeechProviderError(adapterName, `${adapterName} speech request failed with HTTP ${response.status}`, {
 		status: response.status,
-		responseBody
+		responseBody: redactSecret(responseBody, apiKey),
+		retryAfterMs: parseRetryAfter(response.headers.get("retry-after"))
 	});
 }
-function appendAudioInput(form, audio, fieldName = "audio") {
-	const filename = audio.filename ?? "audio";
-	const data = audio.data;
-	if (typeof Blob !== "undefined" && data instanceof Blob) {
-		const contentType = audio.contentType ?? (data.type || "application/octet-stream");
-		const blob = data.type === contentType ? data : new Blob([data], { type: contentType });
-		form.append(fieldName, blob, filename);
-		return;
-	}
-	const contentType = audio.contentType ?? "application/octet-stream";
-	const blobPart = data instanceof Uint8Array ? arrayBufferFromBytes(data) : data;
-	form.append(fieldName, new Blob([blobPart], { type: contentType }), filename);
+/** Removes an API key from provider-supplied text before it is surfaced. */
+function redactSecret(text, secret) {
+	if (!text || !secret) return text;
+	return text.split(secret).join("[REDACTED]");
 }
 function appendOptionalFormValue(form, name, value) {
 	if (value === void 0 || value === null) return;
@@ -314,6 +711,137 @@ var OpenAICompatibleSpeechSynthesizer = class extends HttpSpeechAdapter {
 	}
 };
 //#endregion
+//#region src/shared/usage.ts
+/**
+* Invokes every configured usage callback in order (adapter-level first, then
+* request-level). Callback errors propagate to the caller so that billing
+* hooks never fail silently.
+*/
+async function reportSpeechUsage(usage, ...callbacks) {
+	for (const callback of callbacks) if (callback) await callback(usage);
+}
+/**
+* Extracts audio seconds from an OpenAI-style `usage` block
+* (`{ type: 'duration', seconds }`).
+*/
+function audioSecondsFromProviderUsage(providerUsage) {
+	if (!providerUsage) return;
+	const seconds = providerUsage.seconds;
+	return typeof seconds === "number" && Number.isFinite(seconds) ? seconds : void 0;
+}
+//#endregion
+//#region src/adapters/openai-compatible-transcriber.ts
+var DEFAULT_MODEL = "whisper-1";
+/**
+* Models that only accept `json`/`text` and reject `verbose_json` and
+* `timestamp_granularities[]` (e.g. `gpt-4o-transcribe`,
+* `gpt-4o-mini-transcribe`, optionally gateway-prefixed like
+* `openai/gpt-4o-transcribe`).
+*/
+var JSON_ONLY_MODEL = /(^|\/)gpt-4o[\w.-]*-transcribe/i;
+/** Provider 400/422 bodies that indicate an unsupported format option. */
+var UNSUPPORTED_FORMAT_ERROR = /verbose_json|response_format|timestamp_granularit/i;
+function isJsonOnlyTranscriptionModel(model) {
+	return JSON_ONLY_MODEL.test(model);
+}
+/**
+* OpenAI-compatible speech-to-text adapter (`POST <base>/audio/transcriptions`).
+* Works with OpenAI, Groq, Fireworks, LiteLLM/Bifrost gateways, vLLM,
+* speaches/faster-whisper-server, and whisper.cpp server.
+*
+* Server-side only: the adapter holds the API key.
+*/
+var OpenAICompatibleTranscriber = class extends HttpSpeechAdapter {
+	type = "openai-compatible";
+	endpoint;
+	model;
+	responseFormat;
+	maxBytes;
+	retry;
+	onUsage;
+	constructor(options) {
+		super(options);
+		this.endpoint = resolveOpenAICompatibleUrl(options.baseUrl, "audio/transcriptions");
+		this.model = options.model?.trim() || DEFAULT_MODEL;
+		this.responseFormat = options.responseFormat;
+		this.maxBytes = options.maxBytes ?? 26214400;
+		this.retry = resolveRetryOptions(options.retry);
+		this.onUsage = options.onUsage;
+	}
+	async transcribe(request) {
+		const audio = await normalizeAudioInput(request.audio, {
+			mimeType: request.mimeType,
+			maxBytes: request.maxBytes ?? this.maxBytes,
+			adapter: this.type,
+			signal: request.signal
+		});
+		const wire = this.resolveWireOptions(request);
+		const send = (options) => {
+			const form = new FormData();
+			form.append("file", audio.blob, audio.filename);
+			form.set("model", options.model);
+			appendOptionalFormValue(form, "language", request.language);
+			appendOptionalFormValue(form, "prompt", request.prompt);
+			appendOptionalFormValue(form, "temperature", request.temperature);
+			form.set("response_format", options.responseFormat);
+			for (const granularity of options.timestampGranularities ?? []) form.append("timestamp_granularities[]", granularity);
+			return this.post(this.type, this.endpoint, {
+				body: form,
+				headers: request.headers,
+				signal: request.signal
+			}, (response) => readTranscriptResponse(response, this.type), this.retry);
+		};
+		let transcript;
+		try {
+			transcript = await send(wire);
+		} catch (error) {
+			if (!isUnsupportedFormatError(error, wire)) throw error;
+			transcript = await send({
+				model: wire.model,
+				responseFormat: "json"
+			});
+		}
+		const providerUsage = extractProviderUsage(transcript.raw);
+		const usage = {
+			operation: "transcription",
+			provider: this.type,
+			model: transcript.model ?? wire.model,
+			audioSeconds: transcript.durationSeconds ?? audioSecondsFromProviderUsage(providerUsage) ?? audio.durationSeconds,
+			bytes: audio.bytes,
+			providerUsage
+		};
+		const result = {
+			...transcript,
+			text: transcript.raw === void 0 ? transcript.text.trim() : transcript.text,
+			provider: this.type,
+			model: transcript.model ?? wire.model,
+			usage
+		};
+		await reportSpeechUsage(usage, this.onUsage, request.onUsage);
+		return result;
+	}
+	resolveWireOptions(request) {
+		const model = request.model?.trim() || this.model;
+		const jsonOnly = isJsonOnlyTranscriptionModel(model);
+		let responseFormat = request.responseFormat ?? this.responseFormat ?? (jsonOnly ? "json" : "verbose_json");
+		if (jsonOnly && responseFormat === "verbose_json") responseFormat = "json";
+		const timestampGranularities = responseFormat === "verbose_json" && request.timestampGranularities?.length ? [...new Set(request.timestampGranularities)] : void 0;
+		return {
+			model,
+			responseFormat,
+			timestampGranularities
+		};
+	}
+};
+function isUnsupportedFormatError(error, wire) {
+	return error instanceof SpeechProviderError && (error.status === 400 || error.status === 422) && (wire.responseFormat === "verbose_json" || Boolean(wire.timestampGranularities?.length)) && UNSUPPORTED_FORMAT_ERROR.test(error.responseBody ?? "");
+}
+function extractProviderUsage(raw) {
+	if (!raw || typeof raw !== "object") return;
+	const usage = raw.usage;
+	return usage && typeof usage === "object" && !Array.isArray(usage) ? usage : void 0;
+}
+//#endregion
 //#region src/adapters/qwen3.ts
 var Qwen3SpeechSynthesizer = class extends HttpSpeechAdapter {
 	type = "qwen3-tts";
@@ -349,11 +877,19 @@ var StudioServerTranscriber = class extends HttpSpeechAdapter {
 		this.transcribePath = options.transcribePath ?? "/v1/transcribe";
 	}
 	async transcribe(request) {
+		const audio = await normalizeAudioInput(request.audio, {
+			mimeType: request.mimeType,
+			maxBytes: request.maxBytes,
+			adapter: this.type,
+			signal: request.signal,
+			deriveExtension: false
+		});
 		const form = new FormData();
-		appendAudioInput(form, request.audio);
+		form.append("audio", audio.blob, audio.filename);
 		appendOptionalFormValue(form, "language", request.language);
 		return this.post(this.type, this.transcribePath, {
 			body: form,
+			headers: request.headers,
 			signal: request.signal
 		}, (response) => readTranscriptResponse(response, this.type));
 	}
@@ -404,6 +940,7 @@ async function getTranscriber(options = {}, context = {}) {
 	const resolved = normalizeTranscriberOptions(options, context);
 	switch (resolved.type) {
 		case "studio-server": return new StudioServerTranscriber(resolved);
+		case "openai-compatible": return new OpenAICompatibleTranscriber(resolved);
 		default: throw new InvalidSpeechAdapterError(resolved.type ?? "unknown", "STT");
 	}
 }
@@ -418,7 +955,7 @@ async function getSpeechSynthesizer(options, context = {}) {
 }
 function getAvailableSpeechAdapters() {
 	return {
-		transcribers: ["studio-server"],
+		transcribers: ["studio-server", "openai-compatible"],
 		synthesizers: [
 			"studio-server",
 			"qwen3-tts",
@@ -435,20 +972,30 @@ async function getOptionalSpeechSynthesizer(options, context) {
 	return getSpeechSynthesizer(options, context);
 }
 function normalizeTranscriberOptions(options = {}, context) {
-	const env = context.env ?? defaultEnv();
-	const type = options.type ?? readEnv(env, "HAVE_SPEECH_STT_TYPE", "HAVE_SPEECH_STT_ADAPTER", "STT_ADAPTER") ?? "studio-server";
-	const baseUrl = options.baseUrl ?? readEnv(env, "HAVE_SPEECH_STT_BASE_URL", "STT_BASE_URL");
-	if (type !== "studio-server") throw new InvalidSpeechAdapterError(type, "STT");
-	if (!baseUrl?.trim()) throw new SpeechConfigurationError("STT baseUrl is required", type);
+	const resolved = resolveTranscriberConfig(options, context);
+	const type = resolved.type ?? "studio-server";
+	if (type !== "studio-server" && type !== "openai-compatible") throw new InvalidSpeechAdapterError(type, "STT");
+	if (!resolved.baseUrl) throw new SpeechConfigurationError("STT baseUrl is required", type);
+	const shared = {
+		baseUrl: resolved.baseUrl,
+		fetch: resolved.fetch,
+		headers: resolved.headers,
+		apiKey: resolved.apiKey,
+		timeoutMs: resolved.timeoutMs
+	};
+	if (type === "openai-compatible") return {
+		...shared,
+		type,
+		model: resolved.model,
+		responseFormat: options.responseFormat,
+		maxBytes: resolved.maxBytes,
+		retry: options.retry,
+		onUsage: options.onUsage
+	};
 	return {
-		...options,
+		...shared,
 		type,
-		baseUrl: baseUrl.trim(),
-		fetch: options.fetch ?? context.fetch,
-		headers: options.headers ?? context.headers,
-		apiKey: options.apiKey ?? readEnv(env, "HAVE_SPEECH_STT_API_KEY", "STT_API_KEY", "SPEECH_API_KEY"),
-		timeoutMs: options.timeoutMs ?? parseOptionalInteger(readEnv(env, "HAVE_SPEECH_STT_TIMEOUT_MS", "STT_TIMEOUT_MS")),
-		transcribePath: options.transcribePath ?? readEnv(env, "HAVE_SPEECH_STT_PATH", "STT_PATH")
+		transcribePath: options.transcribePath ?? resolved.path
 	};
 }
 function normalizeSpeechSynthesizerOptions(options, context) {
@@ -488,30 +1035,10 @@ function normalizeSpeechSynthesizerOptions(options, context) {
 	};
 	throw new InvalidSpeechAdapterError(type, "TTS");
 }
-function hasTranscriberEnv(env) {
-	return hasAnyEnv(env, "HAVE_SPEECH_STT_TYPE", "HAVE_SPEECH_STT_ADAPTER", "HAVE_SPEECH_STT_BASE_URL", "STT_ADAPTER", "STT_BASE_URL");
-}
 function hasSynthesizerEnv(env) {
 	return hasAnyEnv(env, "HAVE_SPEECH_TTS_TYPE", "HAVE_SPEECH_TTS_ADAPTER", "HAVE_SPEECH_TTS_BASE_URL", "TTS_ADAPTER", "TTS_BASE_URL");
 }
-function readEnv(env, ...keys) {
-	for (const key of keys) {
-		const value = env[key];
-		if (value?.trim()) return value.trim();
-	}
-}
-function hasAnyEnv(env, ...keys) {
-	return keys.some((key) => Boolean(env[key]?.trim()));
-}
-function parseOptionalInteger(value) {
-	if (!value) return;
-	const parsed = Number.parseInt(value, 10);
-	return Number.isFinite(parsed) ? parsed : void 0;
-}
-function defaultEnv() {
-	return globalThis.process?.env ?? {};
-}
 //#endregion
-export { InvalidSpeechAdapterError, SpeechConfigurationError, SpeechError, SpeechProviderError, getAvailableSpeechAdapters, getSpeech, getSpeechSynthesizer, getTranscriber };
+export { DEFAULT_MAX_AUDIO_BYTES, InvalidSpeechAdapterError, SpeechConfigurationError, SpeechError, SpeechProviderError, TRANSCRIBER_ENV_KEYS, getAvailableSpeechAdapters, getSpeech, getSpeechSynthesizer, getTranscriber, mimeTypeToAudioExtension };
 
 //# sourceMappingURL=index.js.map