@polytts/browser 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DengQing dengqing0821@gmail.com
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,94 @@
+# @polytts/browser
+
+[![npm version](https://img.shields.io/npm/v/@polytts/browser)](https://www.npmjs.com/package/@polytts/browser)
+
+Explicit browser entrypoint for [`polytts`](https://github.com/Dunqing/polytts).
+
+Use this package when you want the structured scoped package layout for browser apps, PWAs, or Electron renderers.
+
+## Install
+
+```bash
+npm install @polytts/browser
+```
+
+## Usage
+
+```ts
+import { createBrowserTTS } from "@polytts/browser";
+
+const tts = createBrowserTTS({
+  initialModelId: "browser-speech",
+});
+
+await tts.ready();
+await tts.speak("Hello from the browser runtime.");
+```
+
+For progressive audio:
+
+```ts
+for await (const chunk of tts.synthesizeStream("Hello from a streaming browser model.")) {
+  console.log(chunk.sampleRate, chunk.channels[0]?.length ?? 0);
+}
+```
+
+The high-level controller also exposes `getInstallState(modelId)` and `isInstalled(modelId)` for quick download checks without reading raw runtime state.
+
+If you do not want IndexedDB, pass a custom `assetStore`:
+
+```ts
+import { MemoryAssetStore } from "@polytts/core";
+import { createBrowserTTS } from "@polytts/browser";
+
+const tts = createBrowserTTS({
+  assetStore: new MemoryAssetStore(),
+});
+```
+
+`@polytts/browser` also exports `LocalStorageAssetStore`, but it is only suitable for tiny assets, demos, and tests. `localStorage` is usually capped around 5 MB and base64 storage adds roughly 33% overhead, so do not use it for real ONNX bundles.
+
+## Lifecycle
+
+The browser controller keeps three separate concepts:
+
+- selected model and voice
+- downloaded assets
+- loaded runtime instance
+
+Important behavior:
+
+- `initialModelId` and `initialVoiceId` only set the starting selection
+- `download(modelId)` caches assets, but does not prepare the runtime instance
+- `ready()`, `selectModel()`, `selectFamily()`, and `selectVoice()` prepare the selected model
+- `speak()`, `synthesize()`, and `synthesizeStream()` prepare on demand if needed
+
+If your UI needs explicit install vs load states, use `getInstallState()`, `isInstalled()`, `status`, `phase`, and `phaseProgress` together instead of assuming they mean the same thing.
+
+## Voices
+
+Catalog voice metadata and runtime-resolved voices are not always identical.
+
+- Models such as Piper usually expose stable voices from catalog metadata.
+- Models such as Kokoro may populate their final voice list only after the model is prepared.
+
+If your UI renders a voice picker, expect some models to show no resolved voices until after `ready()` or `selectModel()` completes.
+
+## Platform notes
+
+- `browser-speech` has no download step and depends entirely on the host browser engine.
+- ONNX-backed models may download large bundles and should usually expose progress UI.
+- Piper uses a safer main-thread ONNX path on iOS. That path is broadly compatible, but stop/cancel can only be observed before or after the current inference call returns.
+- Worker-backed models stop more aggressively because the worker can be recycled on abort.
+
+## SSR
+
+`@polytts/browser` is a browser entrypoint. The React providers can render on the server, but `createBrowserTTS()` and `createBrowserTTSRuntime()` should still be created in browser/client code.
+
+## Exports
+
+- `createBrowserTTS()`
+- `createBrowserTTSRuntime()`
+- browser audio and storage helpers
+- official browser adapters
+- official catalogs from `@polytts/presets`

package/dist/index.d.ts

@@ -0,0 +1,265 @@
+import { AssetBundleKey, AssetStore, AssetStore as AssetStore$1, AudioData, AudioData as AudioData$1, CatalogSource, InstallState, InstallState as InstallState$1, InstallStatus, ModelId, ModelId as ModelId$1, ModelRuntimeInfo, ModelSpec, RuntimeAudioPlayer, RuntimePhase, TTSAdapter, TTSRuntime, TTSRuntimeOptions, Voice, Voice as Voice$1, VoiceId, VoiceId as VoiceId$1, resolveModelDistribution } from "@polytts/core";
+export * from "@polytts/browser-adapters";
+export * from "@polytts/presets";
+
+//#region src/audio.d.ts
+/** The audio output strategy used for playback. */
+type BrowserAudioPlaybackMode = "buffer" | "stream" | "audio-element";
+/** Event emitted when audio reaches a playback milestone (ready or queued). */
+interface BrowserAudioPlaybackEvent {
+  /** The playback strategy used (buffer, stream, or audio-element). */
+  mode: BrowserAudioPlaybackMode;
+  /** Timestamp (from `performance.now()`) when the event occurred. */
+  at: number;
+}
+/** Callbacks for observing audio playback lifecycle events. */
+interface BrowserAudioPlayerOptions {
+  /** Called when audio data has been decoded and is ready to play. */
+  onAudioReady?: (event: BrowserAudioPlaybackEvent) => void;
+  /** Called when audio has been scheduled for playback on the output device. */
+  onPlaybackQueued?: (event: BrowserAudioPlaybackEvent) => void;
+}
+/** Convert a polytts AudioData object to a Web Audio API AudioBuffer. */
+declare function audioDataToAudioBuffer(audio: AudioData$1): AudioBuffer;
+/**
+ * Browser audio player that uses Web Audio API (or an HTMLAudioElement fallback on iOS) to play
+ * synthesized speech.
+ */
+declare class BrowserAudioPlayer implements RuntimeAudioPlayer {
+  private readonly options;
+  private ctx;
+  private source;
+  private activeSources;
+  private pendingPlayback;
+  private _isPlaying;
+  constructor(options?: BrowserAudioPlayerOptions);
+  get isPlaying(): boolean;
+  warmup(): void;
+  play(audio: AudioData$1, signal: AbortSignal, speed?: number): Promise<void>;
+  playStream(audioStream: AsyncIterable<AudioData$1>, signal: AbortSignal, speed?: number): Promise<void>;
+  stop(): void;
+  dispose(): void;
+  private getContext;
+  private playViaAudioElement;
+  private isIOS;
+}
+//#endregion
+//#region src/browser-tts.d.ts
+/** Options for creating a browser TTS runtime, with sensible defaults for adapters and catalogs. */
+interface BrowserTTSRuntimeOptions extends Omit<TTSRuntimeOptions, "adapters" | "catalogs" | "initialModelId" | "initialVoiceId"> {
+  /** Model to activate on startup. */
+  initialModelId?: ModelId$1;
+  /** Voice to activate on startup. */
+  initialVoiceId?: VoiceId$1;
+  /** Additional TTS adapters merged with the official browser adapters. */
+  extraAdapters?: TTSAdapter[];
+  /** Additional catalog sources merged with the official catalog. */
+  extraCatalogs?: CatalogSource[];
+}
+/** Describes a single TTS model with its capabilities, download state, and browser support status. */
+interface BrowserTTSModel {
+  id: ModelId$1;
+  name: string;
+  family: string;
+  languages: string[];
+  /** Whether the model supports single or multiple voices. */
+  voiceMode: ModelSpec["voiceMode"];
+  /** How model assets are distributed (e.g. managed download vs inline). */
+  distributionKind: ReturnType<typeof resolveModelDistribution>["kind"];
+  /** Number of available voices, or null if unknown. */
+  voiceCount: number | null;
+  /** Total size of model assets in bytes. */
+  bundleSizeBytes: number;
+  /** Whether the current browser environment supports this model. */
+  supported: boolean;
+  /** Whether the model requires a separate download before use. */
+  requiresDownload: boolean;
+  /** Whether model assets have been fully downloaded. */
+  downloaded: boolean;
+  /** Current download/install status. */
+  downloadStatus: InstallStatus;
+  /** Download progress from 0 to 1, or null if not downloading. */
+  downloadProgress: number | null;
+  description?: string;
+  /** URL of the model's asset manifest, if applicable. */
+  manifestUrl?: string;
+  /** URL of the model's project homepage. */
+  homepage?: string;
+}
+/** A specific model/voice combination within a model family. */
+interface BrowserTTSFamilyVariant {
+  modelId: ModelId$1;
+  modelName: string;
+  /** Representative voice for this variant, if the model supports voices. */
+  voiceId?: VoiceId$1;
+  /** Display name of the representative voice. */
+  voiceName?: string;
+  downloaded: boolean;
+  downloadStatus: InstallStatus;
+  /** Download progress from 0 to 1, or null if not downloading. */
+  downloadProgress: number | null;
+}
+/** A group of related TTS models (e.g. different sizes or languages) under a shared family name. */
+interface BrowserTTSFamily {
+  id: string;
+  name: string;
+  languages: string[];
+  supported: boolean;
+  /** Currently active model within this family, or null if none is selected. */
+  selectedModelId: ModelId$1 | null;
+  /** All model IDs belonging to this family. */
+  modelIds: ModelId$1[];
+  /** Individual model/voice combinations within the family. */
+  variants: BrowserTTSFamilyVariant[];
+}
+/**
+ * Snapshot of the entire BrowserTTS state including models, families, selection, and playback
+ * status.
+ */
+interface BrowserTTSState {
+  /** All registered models with their current state. */
+  models: BrowserTTSModel[];
+  /** Models grouped by family. */
+  families: BrowserTTSFamily[];
+  /** Family of the currently selected model, or null. */
+  selectedFamilyId: string | null;
+  /** Voices available for the currently active model. */
+  voices: Voice$1[];
+  /** Currently active model, or null if none selected. */
+  selectedModelId: ModelId$1 | null;
+  /** Currently active voice, or null if none selected. */
+  selectedVoiceId: VoiceId$1 | null;
+  /** High-level playback status derived from the runtime phase. */
+  status: "idle" | "preparing" | "speaking" | "error";
+  /** Granular runtime phase (e.g. installing, loading, speaking). */
+  phase: ReturnType<TTSRuntime["getState"]>["phase"];
+  /** Model that the current phase applies to, if any. */
+  phaseModelId: ModelId$1 | null;
+  /** Progress of the current phase from 0 to 1, or null. */
+  phaseProgress: number | null;
+  /** Per-model runtime information (e.g. WebGPU availability). */
+  runtimeInfoByModel: ReturnType<TTSRuntime["getState"]>["runtimeInfoByModel"];
+  error: string | null;
+}
+/** Options for selecting a model or voice in the BrowserTTS facade. */
+interface BrowserTTSSelectionOptions {
+  modelId?: ModelId$1;
+  voiceId?: VoiceId$1;
+  /** Callback invoked with download/load progress from 0 to 1. */
+  onProgress?: (progress: number) => void;
+}
+/** Options for speech synthesis, including model/voice overrides and playback speed. */
+interface BrowserTTSSpeakOptions {
+  modelId?: ModelId$1;
+  voiceId?: VoiceId$1;
+  /** Playback speed multiplier (e.g. 1.5 for 1.5x). */
+  speed?: number;
+  /** Models to try in order if the primary model fails. */
+  fallbackModelIds?: ModelId$1[];
+}
+/**
+ * High-level browser TTS facade that adds model family grouping, selection, and audio playback over
+ * the core TTSRuntime.
+ */
+interface BrowserTTS {
+  /** The underlying core TTS runtime. */
+  readonly runtime: TTSRuntime;
+  /** Returns a snapshot of the current state. */
+  getState(): BrowserTTSState;
+  /** Subscribes to state changes; returns an unsubscribe function. */
+  subscribe(listener: (state: BrowserTTSState) => void): () => void;
+  listModels(): BrowserTTSModel[];
+  listFamilies(): BrowserTTSFamily[];
+  /** Returns the model for the given ID, or the currently active model if omitted. */
+  getModel(modelId?: ModelId$1 | null): BrowserTTSModel | null;
+  /** Returns the family for the given ID, or the currently active family if omitted. */
+  getFamily(familyId?: string | null): BrowserTTSFamily | null;
+  getSelectedModel(): BrowserTTSModel | null;
+  getSelectedFamily(): BrowserTTSFamily | null;
+  /** Returns the install state for the given or active model. */
+  getInstallState(modelId?: ModelId$1 | null): InstallState$1 | null;
+  /** Returns true if the given or active model's assets are fully available. */
+  isInstalled(modelId?: ModelId$1 | null): boolean;
+  listVoices(modelId?: ModelId$1): Promise<Voice$1[]>;
+  getSelectedVoice(): Voice$1 | null;
+  /** Activates a model, downloading assets if necessary. */
+  selectModel(modelId: ModelId$1, options?: Omit<BrowserTTSSelectionOptions, "modelId">): Promise<void>;
+  /** Activates a model family, picking the best supported variant. */
+  selectFamily(familyId: string, options?: BrowserTTSSelectionOptions & {
+    /** Preferred model variant within the family. */variantModel?: ModelId$1;
+  }): Promise<void>;
+  /** Activates a voice, resolving its parent model automatically. */
+  selectVoice(voiceId: VoiceId$1, options?: Omit<BrowserTTSSelectionOptions, "voiceId">): Promise<void>;
+  /** Ensures the selected (or specified) model is loaded and ready to speak. */
+  ready(options?: BrowserTTSSelectionOptions): Promise<void>;
+  /** Downloads model assets without activating the model. */
+  download(modelId?: ModelId$1, onProgress?: (progress: number) => void): Promise<void>;
+  /** Removes previously downloaded model assets. */
+  removeDownload(modelId?: ModelId$1): Promise<void>;
+  /** Synthesizes and plays text through the browser audio player. */
+  speak(text: string, options?: BrowserTTSSpeakOptions): Promise<void>;
+  /** Returns an async iterable of audio chunks for streaming playback. */
+  synthesizeStream(text: string, options?: BrowserTTSSpeakOptions): AsyncIterable<AudioData$1>;
+  /** Synthesizes text and returns the complete audio data. */
+  synthesize(text: string, options?: BrowserTTSSpeakOptions): Promise<AudioData$1>;
+  /** Stops any in-progress playback. */
+  stop(): void;
+  /** Releases all resources held by this instance. */
+  dispose(): void;
+}
+/**
+ * Create a TTSRuntime pre-configured with official browser adapters, catalog, and IndexedDB
+ * storage.
+ */
+declare function createBrowserTTSRuntime(options?: BrowserTTSRuntimeOptions): TTSRuntime;
+/** Create a fully configured BrowserTTS instance ready for model selection and speech synthesis. */
+declare function createBrowserTTS(options?: BrowserTTSRuntimeOptions): BrowserTTS;
+//#endregion
+//#region src/storage/indexeddb-asset-store.d.ts
+/** IndexedDB-backed asset store for caching downloaded TTS model bundles in the browser. */
+declare class IndexedDbAssetStore implements AssetStore$1 {
+  private readonly dbName;
+  private dbPromise;
+  constructor(prefix?: string);
+  stageAsset(bundle: AssetBundleKey, assetName: string, data: ArrayBuffer): Promise<void>;
+  activateBundle(bundle: AssetBundleKey, assetNames: string[]): Promise<void>;
+  isInstalled(bundle: AssetBundleKey, requiredAssetNames?: string[]): Promise<boolean>;
+  getAsset(bundle: AssetBundleKey, assetName: string): Promise<ArrayBuffer | null>;
+  removeBundle(bundle: AssetBundleKey): Promise<void>;
+  private openDb;
+  private idbGet;
+  private txWrite;
+}
+//#endregion
+//#region src/storage/localstorage-asset-store.d.ts
+/** Minimal synchronous key-value storage interface compatible with `window.localStorage`. */
+interface StorageLike {
+  getItem(key: string): string | null;
+  setItem(key: string, value: string): void;
+  removeItem(key: string): void;
+}
+/**
+ * LocalStorage-backed asset store for tiny assets, tests, and demos only.
+ *
+ * This store base64-encodes binary assets into synchronous `localStorage`, which is typically
+ * capped around 5 MB and adds roughly 33% storage overhead. It is not suitable for real ONNX model
+ * bundles; use `IndexedDbAssetStore` or a custom async store for production caches.
+ */
+declare class LocalStorageAssetStore implements AssetStore$1 {
+  private readonly prefix;
+  private readonly storage;
+  constructor(prefix?: string, storage?: StorageLike);
+  stageAsset(bundle: AssetBundleKey, assetName: string, data: ArrayBuffer): Promise<void>;
+  activateBundle(bundle: AssetBundleKey, assetNames: string[]): Promise<void>;
+  isInstalled(bundle: AssetBundleKey, requiredAssetNames?: string[]): Promise<boolean>;
+  getAsset(bundle: AssetBundleKey, assetName: string): Promise<ArrayBuffer | null>;
+  removeBundle(bundle: AssetBundleKey): Promise<void>;
+  private assetKey;
+  private metaKey;
+  private stagingMetaKey;
+  private readMeta;
+  private removeAssetSet;
+  private setItem;
+}
+//#endregion
+export { type AssetStore, type AudioData, BrowserAudioPlaybackEvent, BrowserAudioPlaybackMode, BrowserAudioPlayer, BrowserAudioPlayerOptions, BrowserTTS, BrowserTTSFamily, BrowserTTSFamilyVariant, BrowserTTSModel, BrowserTTSRuntimeOptions, BrowserTTSSelectionOptions, BrowserTTSSpeakOptions, BrowserTTSState, IndexedDbAssetStore, type InstallState, LocalStorageAssetStore, type ModelId, type ModelRuntimeInfo, type RuntimePhase, type StorageLike, type Voice, type VoiceId, audioDataToAudioBuffer, createBrowserTTS, createBrowserTTSRuntime };

package/dist/index.js

@@ -0,0 +1,873 @@
+import { createTTSRuntime, getModelSizeBytes, isInstallStateAvailable, normalizeSpeakSpeed, resolveInstallState, resolveModelDistribution } from "@polytts/core";
+import { officialAdapters } from "@polytts/browser-adapters";
+import { officialCatalog } from "@polytts/presets";
+export * from "@polytts/browser-adapters";
+export * from "@polytts/presets";
+//#region src/audio.ts
+/** Convert a polytts AudioData object to a Web Audio API AudioBuffer. */
+function audioDataToAudioBuffer(audio) {
+	const frameCount = audio.channels[0]?.length ?? 0;
+	const numberOfChannels = Math.max(audio.channels.length, 1);
+	const buffer = new OfflineAudioContext(numberOfChannels, Math.max(frameCount, 1), audio.sampleRate).createBuffer(numberOfChannels, Math.max(frameCount, 1), audio.sampleRate);
+	for (let channelIndex = 0; channelIndex < numberOfChannels; channelIndex += 1) buffer.getChannelData(channelIndex).set(audio.channels[channelIndex] ?? new Float32Array(frameCount || 1));
+	return buffer;
+}
+function audioDataToWavBytes(audio) {
+	const channelCount = Math.max(audio.channels.length, 1);
+	const frameCount = audio.channels[0]?.length ?? 0;
+	const bytesPerSample = 2;
+	const blockAlign = channelCount * bytesPerSample;
+	const byteRate = audio.sampleRate * blockAlign;
+	const dataSize = frameCount * blockAlign;
+	const buffer = new ArrayBuffer(44 + dataSize);
+	const view = new DataView(buffer);
+	const writeString = (offset, value) => {
+		for (let index = 0; index < value.length; index += 1) view.setUint8(offset + index, value.charCodeAt(index));
+	};
+	writeString(0, "RIFF");
+	view.setUint32(4, 36 + dataSize, true);
+	writeString(8, "WAVE");
+	writeString(12, "fmt ");
+	view.setUint32(16, 16, true);
+	view.setUint16(20, 1, true);
+	view.setUint16(22, channelCount, true);
+	view.setUint32(24, audio.sampleRate, true);
+	view.setUint32(28, byteRate, true);
+	view.setUint16(32, blockAlign, true);
+	view.setUint16(34, 16, true);
+	writeString(36, "data");
+	view.setUint32(40, dataSize, true);
+	let offset = 44;
+	for (let frameIndex = 0; frameIndex < frameCount; frameIndex += 1) for (let channelIndex = 0; channelIndex < channelCount; channelIndex += 1) {
+		const sample = Math.max(-1, Math.min(1, audio.channels[channelIndex]?.[frameIndex] ?? 0));
+		view.setInt16(offset, sample < 0 ? sample * 32768 : sample * 32767, true);
+		offset += bytesPerSample;
+	}
+	return buffer;
+}
+/**
+* Browser audio player that uses Web Audio API (or an HTMLAudioElement fallback on iOS) to play
+* synthesized speech.
+*/
+var BrowserAudioPlayer = class {
+	ctx = null;
+	source = null;
+	activeSources = /* @__PURE__ */ new Set();
+	pendingPlayback = null;
+	_isPlaying = false;
+	constructor(options = {}) {
+		this.options = options;
+	}
+	get isPlaying() {
+		return this._isPlaying;
+	}
+	warmup() {
+		const ctx = this.getContext();
+		if (ctx.state === "suspended") ctx.resume();
+		try {
+			const silent = ctx.createBuffer(1, 1, ctx.sampleRate);
+			const source = ctx.createBufferSource();
+			source.buffer = silent;
+			source.connect(ctx.destination);
+			source.start();
+		} catch {}
+	}
+	async play(audio, signal, speed) {
+		this.stop();
+		if (signal.aborted) throw new DOMException("Aborted", "AbortError");
+		if (this.isIOS()) return this.playViaAudioElement(audio, signal, speed);
+		this.options.onAudioReady?.({
+			mode: "buffer",
+			at: performance.now()
+		});
+		const buffer = audioDataToAudioBuffer(audio);
+		const ctx = this.getContext();
+		if (ctx.state === "suspended") await ctx.resume();
+		const source = ctx.createBufferSource();
+		source.buffer = buffer;
+		source.playbackRate.value = normalizeSpeakSpeed(speed);
+		source.connect(ctx.destination);
+		source.start();
+		this.options.onPlaybackQueued?.({
+			mode: "buffer",
+			at: performance.now()
+		});
+		this.activeSources.add(source);
+		this.source = source;
+		this._isPlaying = true;
+		await new Promise((resolve, reject) => {
+			const cleanup = () => {
+				source.removeEventListener?.("ended", onEnded);
+				signal.removeEventListener("abort", onAbort);
+				if (this.pendingPlayback?.cleanup === cleanup) this.pendingPlayback = null;
+			};
+			const onEnded = () => {
+				cleanup();
+				this.activeSources.delete(source);
+				if (this.source === source) this.source = null;
+				this._isPlaying = false;
+				resolve();
+			};
+			const onAbort = () => {
+				cleanup();
+				this.activeSources.delete(source);
+				if (this.source === source) this.source = null;
+				this._isPlaying = false;
+				try {
+					source.stop();
+				} catch {}
+				reject(new DOMException("Aborted", "AbortError"));
+			};
+			this.pendingPlayback = {
+				cleanup,
+				reject
+			};
+			source.addEventListener("ended", onEnded);
+			signal.addEventListener("abort", onAbort);
+		});
+	}
+	async playStream(audioStream, signal, speed) {
+		this.stop();
+		if (signal.aborted) throw new DOMException("Aborted", "AbortError");
+		const ctx = this.getContext();
+		if (ctx.state === "suspended") await ctx.resume();
+		const playbackRate = normalizeSpeakSpeed(speed);
+		let settled = false;
+		let streamFinished = false;
+		let queuedSources = 0;
+		let scheduledAt = ctx.currentTime;
+		const scheduledSources = /* @__PURE__ */ new Set();
+		let sawFirstChunk = false;
+		let reportedPlaybackStart = false;
+		await new Promise((resolve, reject) => {
+			const cleanup = () => {
+				signal.removeEventListener("abort", onAbort);
+				if (this.pendingPlayback?.cleanup === cleanup) this.pendingPlayback = null;
+			};
+			const rejectPlayback = (reason) => {
+				if (settled) return;
+				settled = true;
+				cleanup();
+				this._isPlaying = false;
+				reject(reason);
+			};
+			const resolvePlayback = () => {
+				if (settled) return;
+				settled = true;
+				cleanup();
+				this._isPlaying = false;
+				resolve();
+			};
+			const stopScheduledSources = () => {
+				const sources = [...scheduledSources];
+				scheduledSources.clear();
+				for (const source of sources) {
+					this.activeSources.delete(source);
+					if (this.source === source) this.source = null;
+					try {
+						source.stop();
+					} catch {}
+				}
+			};
+			const maybeResolve = () => {
+				if (streamFinished && queuedSources === 0) resolvePlayback();
+			};
+			const onAbort = () => {
+				stopScheduledSources();
+				rejectPlayback(new DOMException("Aborted", "AbortError"));
+			};
+			this.pendingPlayback = {
+				cleanup,
+				reject: rejectPlayback
+			};
+			signal.addEventListener("abort", onAbort);
+			this._isPlaying = true;
+			(async () => {
+				try {
+					for await (const audio of audioStream) {
+						if (settled || signal.aborted) throw new DOMException("Aborted", "AbortError");
+						if (!sawFirstChunk) {
+							sawFirstChunk = true;
+							this.options.onAudioReady?.({
+								mode: "stream",
+								at: performance.now()
+							});
+						}
+						const buffer = audioDataToAudioBuffer(audio);
+						const source = ctx.createBufferSource();
+						source.buffer = buffer;
+						source.playbackRate.value = playbackRate;
+						source.connect(ctx.destination);
+						const onEnded = () => {
+							source.removeEventListener?.("ended", onEnded);
+							if (settled) return;
+							scheduledSources.delete(source);
+							this.activeSources.delete(source);
+							if (this.source === source) this.source = null;
+							queuedSources--;
+							maybeResolve();
+						};
+						scheduledSources.add(source);
+						this.activeSources.add(source);
+						this.source = source;
+						queuedSources++;
+						source.addEventListener("ended", onEnded);
+						const startAt = Math.max(scheduledAt, ctx.currentTime);
+						scheduledAt = startAt + buffer.duration / playbackRate;
+						source.start(startAt);
+						if (!reportedPlaybackStart) {
+							reportedPlaybackStart = true;
+							this.options.onPlaybackQueued?.({
+								mode: "stream",
+								at: performance.now() + Math.max(0, startAt - ctx.currentTime) * 1e3
+							});
+						}
+					}
+					streamFinished = true;
+					maybeResolve();
+				} catch (error) {
+					if (error.name === "AbortError") {
+						onAbort();
+						return;
+					}
+					stopScheduledSources();
+					rejectPlayback(error);
+				}
+			})();
+		});
+	}
+	stop() {
+		const sources = [...this.activeSources];
+		const pendingPlayback = this.pendingPlayback;
+		this.source = null;
+		this.activeSources.clear();
+		this.pendingPlayback = null;
+		this._isPlaying = false;
+		pendingPlayback?.cleanup();
+		for (const source of sources) try {
+			source.stop();
+		} catch {}
+		pendingPlayback?.reject(new DOMException("Aborted", "AbortError"));
+	}
+	dispose() {
+		this.stop();
+		if (this.ctx) {
+			this.ctx.close();
+			this.ctx = null;
+		}
+	}
+	getContext() {
+		if (!this.ctx) this.ctx = new AudioContext();
+		return this.ctx;
+	}
+	playViaAudioElement(audioData, signal, speed) {
+		return new Promise((resolve, reject) => {
+			this.options.onAudioReady?.({
+				mode: "audio-element",
+				at: performance.now()
+			});
+			const wavBuffer = audioDataToWavBytes(audioData);
+			const blob = new Blob([wavBuffer], { type: "audio/wav" });
+			const url = URL.createObjectURL(blob);
+			const audio = new Audio(url);
+			audio.playbackRate = normalizeSpeakSpeed(speed);
+			this._isPlaying = true;
+			const cleanup = () => {
+				audio.pause();
+				audio.removeAttribute("src");
+				URL.revokeObjectURL(url);
+				signal.removeEventListener("abort", onAbort);
+				this._isPlaying = false;
+			};
+			const onAbort = () => {
+				cleanup();
+				reject(new DOMException("Aborted", "AbortError"));
+			};
+			audio.onended = () => {
+				cleanup();
+				resolve();
+			};
+			audio.onerror = () => {
+				cleanup();
+				reject(/* @__PURE__ */ new Error("Audio playback failed"));
+			};
+			audio.play().then(() => {
+				this.options.onPlaybackQueued?.({
+					mode: "audio-element",
+					at: performance.now()
+				});
+			}).catch((error) => {
+				cleanup();
+				reject(error);
+			});
+			signal.addEventListener("abort", onAbort);
+		});
+	}
+	isIOS() {
+		if (typeof navigator === "undefined") return false;
+		return /iPad|iPhone|iPod/.test(navigator.userAgent) || navigator.platform === "MacIntel" && navigator.maxTouchPoints > 1;
+	}
+};
+//#endregion
+//#region src/storage/indexeddb-asset-store.ts
+function bundleId$1(bundle) {
+	return `${bundle.adapterId}/${bundle.modelId}`;
+}
+function revisionPrefix$1(bundle) {
+	return `${bundle.adapterId}/${bundle.modelId}/${bundle.revision}`;
+}
+/** IndexedDB-backed asset store for caching downloaded TTS model bundles in the browser. */
+var IndexedDbAssetStore = class {
+	dbName;
+	dbPromise = null;
+	constructor(prefix = "polytts") {
+		this.dbName = `${prefix}-asset-cache`;
+	}
+	async stageAsset(bundle, assetName, data) {
+		const db = await this.openDb();
+		const key = `${revisionPrefix$1(bundle)}/${assetName}`;
+		await this.txWrite(db, ["staging"], (tx) => {
+			tx.objectStore("staging").put(data, key);
+		});
+	}
+	async activateBundle(bundle, assetNames) {
+		const db = await this.openDb();
+		const stagedAssets = /* @__PURE__ */ new Map();
+		for (const assetName of assetNames) {
+			const key = `${revisionPrefix$1(bundle)}/${assetName}`;
+			const data = await this.idbGet(db, "staging", key);
+			if (!data) throw new Error(`Missing staged asset: ${assetName}`);
+			stagedAssets.set(assetName, data);
+		}
+		await this.txWrite(db, [
+			"active",
+			"meta",
+			"staging"
+		], (tx) => {
+			const active = tx.objectStore("active");
+			const meta = tx.objectStore("meta");
+			const staging = tx.objectStore("staging");
+			for (const [assetName, data] of stagedAssets) active.put(data, `${revisionPrefix$1(bundle)}/${assetName}`);
+			meta.put({
+				adapterId: bundle.adapterId,
+				modelId: bundle.modelId,
+				revision: bundle.revision,
+				activatedAt: Date.now(),
+				assetNames
+			}, bundleId$1(bundle));
+			for (const assetName of assetNames) staging.delete(`${revisionPrefix$1(bundle)}/${assetName}`);
+		});
+	}
+	async isInstalled(bundle, requiredAssetNames) {
+		const db = await this.openDb();
+		const meta = await this.idbGet(db, "meta", bundleId$1(bundle));
+		if (!meta || meta.revision !== bundle.revision) return false;
+		if (!requiredAssetNames?.length) return true;
+		return requiredAssetNames.every((assetName) => meta.assetNames.includes(assetName));
+	}
+	async getAsset(bundle, assetName) {
+		const db = await this.openDb();
+		return this.idbGet(db, "active", `${revisionPrefix$1(bundle)}/${assetName}`);
+	}
+	async removeBundle(bundle) {
+		const db = await this.openDb();
+		const meta = await this.idbGet(db, "meta", bundleId$1(bundle));
+		if (!meta) return;
+		await this.txWrite(db, ["active", "meta"], (tx) => {
+			const active = tx.objectStore("active");
+			const metaStore = tx.objectStore("meta");
+			for (const assetName of meta.assetNames) active.delete(`${bundle.adapterId}/${bundle.modelId}/${meta.revision}/${assetName}`);
+			metaStore.delete(bundleId$1(bundle));
+		});
+	}
+	async openDb() {
+		if (this.dbPromise) return this.dbPromise;
+		this.dbPromise = new Promise((resolve, reject) => {
+			const req = indexedDB.open(this.dbName, 1);
+			req.onupgradeneeded = () => {
+				const db = req.result;
+				if (!db.objectStoreNames.contains("staging")) db.createObjectStore("staging");
+				if (!db.objectStoreNames.contains("active")) db.createObjectStore("active");
+				if (!db.objectStoreNames.contains("meta")) db.createObjectStore("meta");
+			};
+			req.onsuccess = () => resolve(req.result);
+			req.onerror = () => {
+				this.dbPromise = null;
+				reject(req.error);
+			};
+		});
+		return this.dbPromise;
+	}
+	idbGet(db, storeName, key) {
+		return new Promise((resolve, reject) => {
+			const req = db.transaction(storeName, "readonly").objectStore(storeName).get(key);
+			req.onsuccess = () => resolve(req.result ?? null);
+			req.onerror = () => reject(req.error);
+		});
+	}
+	txWrite(db, stores, callback) {
+		return new Promise((resolve, reject) => {
+			const tx = db.transaction(stores, "readwrite");
+			callback(tx);
+			tx.oncomplete = () => resolve();
+			tx.onerror = () => reject(tx.error);
+		});
+	}
+};
+//#endregion
+//#region src/storage/localstorage-asset-store.ts
+function bundleId(bundle) {
+	return `${bundle.adapterId}/${bundle.modelId}`;
+}
+function revisionPrefix(bundle) {
+	return `${bundle.adapterId}/${bundle.modelId}/${bundle.revision}`;
+}
+function chunkBytes(value, size) {
+	const chunks = [];
+	for (let index = 0; index < value.length; index += size) chunks.push(value.slice(index, index + size));
+	return chunks;
+}
+function arrayBufferToBase64(data) {
+	const bytes = new Uint8Array(data);
+	let binary = "";
+	for (const chunk of chunkBytes(bytes, 32768)) binary += String.fromCharCode(...chunk);
+	return btoa(binary);
+}
+function base64ToArrayBuffer(value) {
+	const binary = atob(value);
+	const bytes = new Uint8Array(binary.length);
+	for (let index = 0; index < binary.length; index += 1) bytes[index] = binary.charCodeAt(index);
+	return bytes.buffer;
+}
+function getDefaultStorage() {
+	if (!("localStorage" in globalThis) || !globalThis.localStorage) throw new Error("LocalStorageAssetStore requires a localStorage-compatible storage implementation");
+	return globalThis.localStorage;
+}
+function isQuotaExceededError(error) {
+	return error instanceof DOMException ? error.name === "QuotaExceededError" || error.name === "NS_ERROR_DOM_QUOTA_REACHED" : error instanceof Error && /quota/i.test(error.name);
+}
+/**
+* LocalStorage-backed asset store for tiny assets, tests, and demos only.
+*
+* This store base64-encodes binary assets into synchronous `localStorage`, which is typically
+* capped around 5 MB and adds roughly 33% storage overhead. It is not suitable for real ONNX model
+* bundles; use `IndexedDbAssetStore` or a custom async store for production caches.
+*/
+var LocalStorageAssetStore = class {
+	prefix;
+	storage;
+	constructor(prefix = "polytts", storage = getDefaultStorage()) {
+		this.prefix = prefix;
+		this.storage = storage;
+	}
+	async stageAsset(bundle, assetName, data) {
+		const existingMeta = this.readMeta(this.stagingMetaKey(bundle));
+		if (existingMeta && existingMeta.revision !== bundle.revision) {
+			this.removeAssetSet("staging", {
+				adapterId: bundle.adapterId,
+				modelId: bundle.modelId,
+				revision: existingMeta.revision
+			}, existingMeta.assetNames);
+			this.storage.removeItem(this.stagingMetaKey(bundle));
+		}
+		const assetKey = this.assetKey("staging", bundle, assetName);
+		this.setItem(assetKey, arrayBufferToBase64(data), `staging asset "${assetName}"`);
+		const updatedMeta = {
+			adapterId: bundle.adapterId,
+			modelId: bundle.modelId,
+			revision: bundle.revision,
+			activatedAt: Date.now(),
+			assetNames: [...new Set([...existingMeta?.revision === bundle.revision ? existingMeta.assetNames : [], assetName])]
+		};
+		try {
+			this.setItem(this.stagingMetaKey(bundle), JSON.stringify(updatedMeta), "staging metadata");
+		} catch (error) {
+			this.storage.removeItem(assetKey);
+			throw error;
+		}
+	}
+	async activateBundle(bundle, assetNames) {
+		const stagedAssets = /* @__PURE__ */ new Map();
+		const previousMeta = this.readMeta(this.metaKey(bundle));
+		const stagingMeta = this.readMeta(this.stagingMetaKey(bundle));
+		for (const assetName of assetNames) {
+			const value = this.storage.getItem(this.assetKey("staging", bundle, assetName));
+			if (!value) throw new Error(`Missing staged asset: ${assetName}`);
+			stagedAssets.set(assetName, value);
+		}
+		if (previousMeta && previousMeta.revision !== bundle.revision) this.removeAssetSet("active", {
+			adapterId: bundle.adapterId,
+			modelId: bundle.modelId,
+			revision: previousMeta.revision
+		}, previousMeta.assetNames);
+		for (const [assetName, value] of stagedAssets) {
+			this.setItem(this.assetKey("active", bundle, assetName), value, `active asset "${assetName}"`);
+			this.storage.removeItem(this.assetKey("staging", bundle, assetName));
+		}
+		const meta = {
+			adapterId: bundle.adapterId,
+			modelId: bundle.modelId,
+			revision: bundle.revision,
+			activatedAt: Date.now(),
+			assetNames
+		};
+		this.setItem(this.metaKey(bundle), JSON.stringify(meta), "active metadata");
+		for (const assetName of stagingMeta?.assetNames ?? assetNames) this.storage.removeItem(this.assetKey("staging", bundle, assetName));
+		this.storage.removeItem(this.stagingMetaKey(bundle));
+	}
+	async isInstalled(bundle, requiredAssetNames) {
+		const meta = this.readMeta(this.metaKey(bundle));
+		if (!meta || meta.revision !== bundle.revision) return false;
+		if (!requiredAssetNames?.length) return true;
+		return requiredAssetNames.every((assetName) => meta.assetNames.includes(assetName));
+	}
+	async getAsset(bundle, assetName) {
+		const value = this.storage.getItem(this.assetKey("active", bundle, assetName));
+		return value ? base64ToArrayBuffer(value) : null;
+	}
+	async removeBundle(bundle) {
+		const activeMeta = this.readMeta(this.metaKey(bundle));
+		if (activeMeta) {
+			this.removeAssetSet("active", {
+				adapterId: bundle.adapterId,
+				modelId: bundle.modelId,
+				revision: activeMeta.revision
+			}, activeMeta.assetNames);
+			this.storage.removeItem(this.metaKey(bundle));
+		}
+		const stagingMeta = this.readMeta(this.stagingMetaKey(bundle));
+		if (stagingMeta) {
+			this.removeAssetSet("staging", {
+				adapterId: bundle.adapterId,
+				modelId: bundle.modelId,
+				revision: stagingMeta.revision
+			}, stagingMeta.assetNames);
+			this.storage.removeItem(this.stagingMetaKey(bundle));
+		}
+	}
+	assetKey(kind, bundle, assetName) {
+		return `${this.prefix}:${kind}:${revisionPrefix(bundle)}/${assetName}`;
+	}
+	metaKey(bundle) {
+		return `${this.prefix}:meta:${bundleId(bundle)}`;
+	}
+	stagingMetaKey(bundle) {
+		return `${this.prefix}:staging-meta:${bundleId(bundle)}`;
+	}
+	readMeta(key) {
+		const value = this.storage.getItem(key);
+		return value ? JSON.parse(value) : null;
+	}
+	removeAssetSet(kind, bundle, assetNames) {
+		for (const assetName of assetNames) this.storage.removeItem(this.assetKey(kind, bundle, assetName));
+	}
+	setItem(key, value, label) {
+		try {
+			this.storage.setItem(key, value);
+		} catch (error) {
+			if (isQuotaExceededError(error)) throw new Error(`LocalStorageAssetStore ran out of browser storage while writing ${label}. This store is only suitable for tiny assets, demos, and tests; use IndexedDbAssetStore or another async store for real model bundles.`, { cause: error });
+			throw error;
+		}
+	}
+};
+//#endregion
+//#region src/browser-tts.ts
+function titleCase(value) {
+	return value.split(/[-_\s]+/).filter(Boolean).map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join(" ");
+}
+function getVoiceCount(model) {
+	if (model.voices?.length) return model.voices.length;
+	return model.voiceMode === "multi" ? null : 1;
+}
+function toBrowserTTSModel(model, runtimeState) {
+	const installState = resolveInstallState(model, runtimeState.installStates[model.id]);
+	const distribution = resolveModelDistribution(model);
+	const requiresDownload = distribution.kind === "managed-assets";
+	const downloaded = isInstallStateAvailable(installState);
+	return {
+		id: model.id,
+		name: model.name,
+		family: model.family,
+		languages: model.languages,
+		voiceMode: model.voiceMode,
+		distributionKind: distribution.kind,
+		voiceCount: getVoiceCount(model),
+		bundleSizeBytes: getModelSizeBytes(model),
+		supported: runtimeState.supportedModelIds.includes(model.id),
+		requiresDownload,
+		downloaded,
+		downloadStatus: installState.status,
+		downloadProgress: installState.progress,
+		description: model.description,
+		manifestUrl: model.manifestUrl,
+		homepage: model.homepage
+	};
+}
+function getFamilyDisplayName(family, models) {
+	if (models.length === 1) return models[0].name;
+	return titleCase(family);
+}
+function toBrowserTTSFamilies(models, runtimeState) {
+	const groups = /* @__PURE__ */ new Map();
+	for (const model of models) {
+		const familyModels = groups.get(model.family);
+		if (familyModels) familyModels.push(model);
+		else groups.set(model.family, [model]);
+	}
+	return [...groups.entries()].map(([familyId, familyModels]) => {
+		const modelIds = familyModels.map((model) => model.id);
+		const activeModelInFamily = runtimeState.activeModelId && modelIds.includes(runtimeState.activeModelId) ? runtimeState.activeModelId : null;
+		const languages = [...new Set(familyModels.flatMap((model) => model.languages))];
+		const variants = familyModels.map((model) => {
+			const installState = resolveInstallState(model, runtimeState.installStates[model.id]);
+			const downloaded = isInstallStateAvailable(installState);
+			const representativeVoice = model.voices?.find((voice) => voice.id === model.defaultVoiceId) ?? model.voices?.[0];
+			return {
+				modelId: model.id,
+				modelName: model.name,
+				voiceId: representativeVoice?.id ?? model.defaultVoiceId,
+				voiceName: representativeVoice?.name,
+				downloaded,
+				downloadStatus: installState.status,
+				downloadProgress: installState.progress
+			};
+		});
+		return {
+			id: familyId,
+			name: getFamilyDisplayName(familyId, familyModels),
+			languages,
+			supported: familyModels.some((model) => runtimeState.supportedModelIds.includes(model.id)),
+			selectedModelId: activeModelInFamily,
+			modelIds,
+			variants
+		};
+	});
+}
+function toBrowserTTSState(runtime) {
+	const runtimeState = runtime.getState();
+	return {
+		models: runtimeState.models.map((model) => toBrowserTTSModel(model, runtimeState)),
+		families: toBrowserTTSFamilies(runtimeState.models, runtimeState),
+		selectedFamilyId: runtimeState.activeModelId != null ? runtimeState.models.find((model) => model.id === runtimeState.activeModelId)?.family ?? null : null,
+		voices: runtimeState.voices,
+		selectedModelId: runtimeState.activeModelId,
+		selectedVoiceId: runtimeState.activeVoiceId,
+		status: runtimeState.error || runtimeState.phase === "error" ? "error" : runtimeState.phase === "speaking" || runtimeState.isSpeaking ? "speaking" : runtimeState.phase === "installing" || runtimeState.phase === "loading" || runtimeState.isPreparing ? "preparing" : "idle",
+		phase: runtimeState.phase,
+		phaseModelId: runtimeState.phaseModelId,
+		phaseProgress: runtimeState.phaseProgress,
+		runtimeInfoByModel: runtimeState.runtimeInfoByModel,
+		error: runtimeState.error
+	};
+}
+var BrowserTTSImpl = class {
+	state;
+	listeners = /* @__PURE__ */ new Set();
+	unsubscribeRuntime;
+	constructor(runtime) {
+		this.runtime = runtime;
+		this.state = toBrowserTTSState(runtime);
+		this.unsubscribeRuntime = this.runtime.subscribe(() => {
+			this.state = toBrowserTTSState(this.runtime);
+			for (const listener of this.listeners) listener(this.state);
+		});
+	}
+	getState() {
+		return this.state;
+	}
+	subscribe(listener) {
+		this.listeners.add(listener);
+		return () => {
+			this.listeners.delete(listener);
+		};
+	}
+	listModels() {
+		return this.getState().models;
+	}
+	listFamilies() {
+		return this.getState().families;
+	}
+	getModel(modelId) {
+		const targetModelId = modelId ?? this.runtime.getState().activeModelId;
+		if (!targetModelId) return null;
+		return this.listModels().find((model) => model.id === targetModelId) ?? null;
+	}
+	getFamily(familyId) {
+		const targetFamilyId = familyId ?? (this.runtime.getState().activeModelId ? this.runtime.getState().models.find((model) => model.id === this.runtime.getState().activeModelId)?.family ?? null : null);
+		if (!targetFamilyId) return null;
+		return this.listFamilies().find((family) => family.id === targetFamilyId) ?? null;
+	}
+	getSelectedModel() {
+		return this.getModel();
+	}
+	getSelectedFamily() {
+		return this.getFamily();
+	}
+	getInstallState(modelId) {
+		const resolvedModelId = modelId ?? this.runtime.getState().activeModelId;
+		if (!resolvedModelId) return null;
+		const model = this.runtime.getModel(resolvedModelId);
+		if (!model) return null;
+		return resolveInstallState(model, this.runtime.getState().installStates[model.id]);
+	}
+	isInstalled(modelId) {
+		return isInstallStateAvailable(this.getInstallState(modelId));
+	}
+	async listVoices(modelId) {
+		return this.runtime.listVoices(modelId ?? this.resolveModelId());
+	}
+	getSelectedVoice() {
+		const state = this.runtime.getState();
+		if (!state.activeVoiceId) return null;
+		return state.voices.find((voice) => voice.id === state.activeVoiceId) ?? null;
+	}
+	async selectModel(modelId, options) {
+		const selection = this.resolveModelSelection({
+			modelId,
+			voiceId: options?.voiceId
+		});
+		await this.runtime.prepare(selection.modelId, {
+			voiceId: selection.voiceId,
+			onProgress: options?.onProgress
+		});
+	}
+	async selectFamily(familyId, options) {
+		const family = this.getFamily(familyId);
+		if (!family) throw new Error(`Unknown model family: ${familyId}`);
+		const requestedVoice = options?.voiceId;
+		const modelId = (options?.variantModel && family.modelIds.includes(options.variantModel) && options.variantModel) ?? (requestedVoice ? this.findModelIdForVoice(requestedVoice, familyId) : null) ?? family.selectedModelId ?? family.modelIds.find((candidate) => {
+			return this.getModel(candidate)?.supported;
+		}) ?? family.modelIds[0];
+		if (!modelId) throw new Error(`Model family "${familyId}" has no registered models`);
+		await this.selectModel(modelId, {
+			voiceId: requestedVoice,
+			onProgress: options?.onProgress
+		});
+	}
+	async selectVoice(voiceId, options) {
+		const selection = this.resolveModelSelection({
+			modelId: options?.modelId,
+			voiceId
+		});
+		await this.runtime.prepare(selection.modelId, {
+			voiceId: selection.voiceId,
+			onProgress: options?.onProgress
+		});
+	}
+	async ready(options) {
+		const selection = this.resolveModelSelection({
+			modelId: options?.modelId,
+			voiceId: options?.voiceId
+		});
+		await this.runtime.prepare(selection.modelId, {
+			voiceId: selection.voiceId,
+			onProgress: options?.onProgress
+		});
+	}
+	async download(modelId, onProgress) {
+		await this.runtime.install(this.resolveModelId(modelId), onProgress);
+	}
+	async removeDownload(modelId) {
+		await this.runtime.uninstall(this.resolveModelId(modelId));
+	}
+	async speak(text, options) {
+		const selection = this.resolveModelSelection({
+			modelId: options?.modelId,
+			voiceId: options?.voiceId
+		});
+		await this.runtime.speak(text, {
+			modelId: selection.modelId,
+			voiceId: selection.voiceId,
+			speed: options?.speed,
+			fallbackModelIds: options?.fallbackModelIds
+		});
+	}
+	async synthesize(text, options) {
+		const selection = this.resolveModelSelection({
+			modelId: options?.modelId,
+			voiceId: options?.voiceId
+		});
+		return this.runtime.synthesize(text, {
+			modelId: selection.modelId,
+			voiceId: selection.voiceId,
+			speed: options?.speed,
+			fallbackModelIds: options?.fallbackModelIds
+		});
+	}
+	synthesizeStream(text, options) {
+		const selection = this.resolveModelSelection({
+			modelId: options?.modelId,
+			voiceId: options?.voiceId
+		});
+		return this.runtime.synthesizeStream(text, {
+			modelId: selection.modelId,
+			voiceId: selection.voiceId,
+			speed: options?.speed,
+			fallbackModelIds: options?.fallbackModelIds
+		});
+	}
+	stop() {
+		this.runtime.stop();
+	}
+	dispose() {
+		this.unsubscribeRuntime();
+		this.listeners.clear();
+		this.runtime.dispose();
+	}
+	resolveModelId(modelId) {
+		const runtimeState = this.runtime.getState();
+		const resolved = modelId ?? runtimeState.activeModelId ?? runtimeState.supportedModelIds[0] ?? runtimeState.models[0]?.id;
+		if (!resolved) throw new Error("No models are registered in this BrowserTTS instance");
+		return resolved;
+	}
+	resolveModelSelection(options) {
+		const modelId = this.resolveModelId(options?.modelId);
+		const voiceId = options?.voiceId;
+		if (!voiceId) return { modelId };
+		const model = this.runtime.getModel(modelId);
+		if (!model) return {
+			modelId,
+			voiceId
+		};
+		if (this.modelHasVoice(model, voiceId)) return {
+			modelId,
+			voiceId
+		};
+		const matchingFamilyModelId = this.findModelIdForVoice(voiceId, model.family);
+		if (matchingFamilyModelId) return {
+			modelId: matchingFamilyModelId,
+			voiceId
+		};
+		return {
+			modelId,
+			voiceId
+		};
+	}
+	findModelIdForVoice(voiceId, familyId) {
+		return this.runtime.getState().models.find((model) => (familyId == null || model.family === familyId) && this.modelHasVoice(model, voiceId))?.id ?? null;
+	}
+	modelHasVoice(model, voiceId) {
+		return model.defaultVoiceId === voiceId || model.voices?.some((voice) => voice.id === voiceId) === true;
+	}
+};
+/**
+* Create a TTSRuntime pre-configured with official browser adapters, catalog, and IndexedDB
+* storage.
+*/
+function createBrowserTTSRuntime(options = {}) {
+	return createTTSRuntime({
+		assetStore: options.assetStore ?? new IndexedDbAssetStore("polytts"),
+		audioPlayer: options.audioPlayer ?? new BrowserAudioPlayer(),
+		fetch: options.fetch,
+		initialModelId: options.initialModelId,
+		initialVoiceId: options.initialVoiceId,
+		adapters: [...officialAdapters, ...options.extraAdapters ?? []],
+		catalogs: [officialCatalog, ...options.extraCatalogs ?? []]
+	});
+}
+/** Create a fully configured BrowserTTS instance ready for model selection and speech synthesis. */
+function createBrowserTTS(options = {}) {
+	return new BrowserTTSImpl(createBrowserTTSRuntime(options));
+}
+//#endregion
+export { BrowserAudioPlayer, IndexedDbAssetStore, LocalStorageAssetStore, audioDataToAudioBuffer, createBrowserTTS, createBrowserTTSRuntime };

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@polytts/browser",
+  "version": "0.1.0",
+  "description": "Browser entrypoint for polytts text-to-speech runtimes.",
+  "keywords": [
+    "browser",
+    "onnx",
+    "polytts",
+    "text-to-speech",
+    "tts",
+    "web"
+  ],
+  "homepage": "https://github.com/Dunqing/polytts/tree/main/packages/browser#readme",
+  "bugs": {
+    "url": "https://github.com/Dunqing/polytts/issues"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Dunqing/polytts.git",
+    "directory": "packages/browser"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@polytts/browser-adapters": "0.1.0",
+    "@polytts/core": "0.1.0",
+    "@polytts/presets": "0.1.0"
+  },
+  "devDependencies": {
+    "fake-indexeddb": "latest",
+    "vite-plus": "latest"
+  },
+  "scripts": {
+    "build": "vp pack",
+    "test": "vp test",
+    "test:run": "vp test run",
+    "test:browser": "vp test run --config vitest.browser.config.ts"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts"
+}