@polytts/core 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,230 @@
+# @polytts/core
+
+[![npm version](https://img.shields.io/npm/v/@polytts/core)](https://www.npmjs.com/package/@polytts/core)
+
+Core runtime and adapter contracts for [`polytts`](https://github.com/Dunqing/polytts).
+
+Use this package when you need custom adapters, custom catalogs, or direct runtime orchestration. Most app code should start with `polytts`, `@polytts/browser`, or `@polytts/node` instead.
+
+## Install
+
+```bash
+npm install @polytts/core
+```
+
+## Usage
+
+```ts
+import { createTTSRuntime } from "@polytts/core";
+import { officialAdapters } from "@polytts/browser-adapters";
+import { officialCatalog } from "@polytts/presets";
+
+const runtime = createTTSRuntime({
+  adapters: officialAdapters,
+  catalogs: [officialCatalog],
+  initialModelId: "browser-speech",
+});
+
+await runtime.prepare("browser-speech");
+await runtime.speak("Hello from the core runtime.");
+```
+
+## Custom models
+
+There are two ways to extend `polytts` with new models.
+
+### Add a model to an existing family
+
+If the model fits one of the built-in adapters (Piper, Kokoro, KittenTTS, Supertonic), add a catalog entry and keep using the official adapter. This is the normal path for another Piper bundle, KittenTTS checkpoint, or any ONNX export that matches an existing adapter contract.
+
+```ts
+import { createStaticCatalog, type ModelSpec } from "@polytts/core";
+import { createBrowserTTSRuntime } from "@polytts/browser";
+
+const myPiperVoice: ModelSpec = {
+  id: "piper-en_US-custom-medium",
+  adapterId: "piper",
+  name: "Piper Custom",
+  family: "piper",
+  revision: "v1.0.0",
+  license: "mit",
+  languages: ["en-US"],
+  voiceMode: "per-voice-model",
+  distribution: {
+    kind: "managed-assets",
+    sizeBytes: 63_000_000,
+    assets: [
+      {
+        name: "en_US-custom-medium.onnx",
+        url: "https://example.com/en_US-custom-medium.onnx",
+        size: 63_000_000,
+      },
+      {
+        name: "en_US-custom-medium.onnx.json",
+        url: "https://example.com/en_US-custom-medium.onnx.json",
+        size: 8_192,
+      },
+    ],
+  },
+  voices: [
+    {
+      id: "en_US-custom-medium",
+      name: "Custom",
+      language: "en-US",
+    },
+  ],
+  defaultVoiceId: "en_US-custom-medium",
+};
+
+const runtime = createBrowserTTSRuntime({
+  extraCatalogs: [createStaticCatalog([myPiperVoice])],
+});
+```
+
+#### Guidelines
+
+- Use the built-in adapter id (`piper`, `kokoro`, `kitten`, or `supertonic`)
+- Keep `family` stable if the model should appear in the same grouped family in the simple API
+- Use `voiceMode: "per-voice-model"` when each downloadable bundle is a separate voice model
+- Use `voiceMode: "multi"` when one model exposes multiple voices internally
+- For `per-voice-model` families such as Piper, switch variants by model id rather than assuming one shared multi-voice model
+
+### Add a new runtime family
+
+If the model needs a different inference path, create a new adapter and register it alongside the built-in ones.
+
+#### Model instance
+
+Every adapter creates model instances. There are two kinds:
+
+- **`SynthesizingModelInstance`** (`kind: "synthesizing"`) — returns audio data via `generate()`. Optionally supports `stream()` for incremental chunks. This is the most common type.
+- **`SpeakingModelInstance`** (`kind: "speaking"`) — plays audio directly via `speak()` (e.g. the Web Speech API). No audio data is returned.
+
+```ts
+import { type ModelSpec, type SynthesizingModelInstance } from "@polytts/core";
+
+class MyModel implements SynthesizingModelInstance {
+  readonly kind = "synthesizing" as const;
+  readonly modelId: string;
+  readonly adapterId: string;
+
+  constructor(private readonly spec: ModelSpec) {
+    this.modelId = spec.id;
+    this.adapterId = spec.adapterId;
+  }
+
+  async load(_signal: AbortSignal): Promise<void> {
+    // Initialize your runtime here (load ONNX, WASM, etc.).
+  }
+
+  async generate(
+    text: string,
+    _voiceId: string,
+    _signal: AbortSignal,
+  ): Promise<{ sampleRate: number; channels: Float32Array[] }> {
+    // Return PCM audio data for the synthesized speech.
+    throw new Error(`Not implemented for: ${text}`);
+  }
+
+  listVoices() {
+    return this.spec.voices ?? [];
+  }
+
+  dispose(): void {}
+}
+```
+
+#### Adapter
+
+The adapter tells the runtime how to create model instances and whether it can run on the current platform.
+
+```ts
+import {
+  createStaticCatalog,
+  createTTSRuntime,
+  type TTSAdapter,
+  type SynthesizingModelInstance,
+} from "@polytts/core";
+import { officialAdapters, officialCatalog } from "@polytts/browser";
+
+const myAdapter: TTSAdapter<SynthesizingModelInstance> = {
+  id: "my-runtime",
+  name: "My Runtime",
+  isSupported: (_spec) => typeof Worker !== "undefined",
+  createModel(spec) {
+    return new MyModel(spec);
+  },
+};
+```
+
+#### Catalog
+
+Register model metadata via a catalog. Use `distribution` to describe how assets are delivered:
+
+| `distribution.kind` | Meaning                                             |
+| ------------------- | --------------------------------------------------- |
+| `"managed-assets"`  | Runtime downloads and caches `assets` automatically |
+| `"adapter-managed"` | Adapter owns download logic via custom `install()`  |
+| `"none"` (or omit)  | No downloadable assets needed                       |
+
+```ts
+const myCatalog = createStaticCatalog([
+  {
+    id: "my-runtime-v1",
+    adapterId: "my-runtime",
+    name: "My Runtime V1",
+    family: "my-runtime",
+    revision: "v1",
+    license: "custom",
+    languages: ["en-US"],
+    voiceMode: "single",
+    distribution: { kind: "none" },
+  },
+]);
+```
+
+#### Wire it up
+
+```ts
+const runtime = createTTSRuntime({
+  adapters: [...officialAdapters, myAdapter],
+  catalogs: [officialCatalog, myCatalog],
+});
+```
+
+### ModelSpec reference
+
+Required fields for every `ModelSpec`:
+
+| Field       | Type                                       | Description                               |
+| ----------- | ------------------------------------------ | ----------------------------------------- |
+| `id`        | `string`                                   | Unique model identifier                   |
+| `adapterId` | `string`                                   | Which adapter runs this model             |
+| `name`      | `string`                                   | Human-readable display name               |
+| `family`    | `string`                                   | Grouping key (e.g. `"piper"`, `"kokoro"`) |
+| `revision`  | `string`                                   | Version string for cache invalidation     |
+| `license`   | `string`                                   | SPDX license identifier                   |
+| `languages` | `string[]`                                 | BCP-47 language codes                     |
+| `voiceMode` | `"single" \| "multi" \| "per-voice-model"` | How the model handles voices              |
+
+Optional fields:
+
+| Field            | Type                      | Description                                |
+| ---------------- | ------------------------- | ------------------------------------------ |
+| `distribution`   | `ModelDistribution`       | Asset delivery strategy (see above)        |
+| `voices`         | `Voice[]`                 | Pre-declared voice list                    |
+| `defaultVoiceId` | `string`                  | Default voice to select                    |
+| `requirements`   | `ModelRequirements`       | Runtime needs (`wasm`, `webgpu`, `worker`) |
+| `config`         | `Record<string, unknown>` | Adapter-specific configuration             |
+| `description`    | `string`                  | Model description                          |
+| `homepage`       | `string`                  | Project URL                                |
+| `tags`           | `string[]`                | Searchable tags                            |
+
+## Exports
+
+Key exports from `@polytts/core`:
+
+- `createTTSRuntime` — create a low-level runtime
+- `createStaticCatalog` — create a catalog from a model array
+- `MemoryAssetStore` — in-memory asset store (useful for testing)
+- Types: `TTSRuntime`, `TTSAdapter`, `TTSModelInstance`, `SynthesizingModelInstance`, `SpeakingModelInstance`, `ModelSpec`, `ModelCatalog`, `AssetStore`, `AudioData`, `Voice`

package/dist/index.d.ts

@@ -0,0 +1,381 @@
+//#region src/types.d.ts
+/** Unique identifier for a TTS model. */
+type ModelId = string;
+/** Unique identifier for a TTS adapter (engine backend). */
+type AdapterId = string;
+/** Unique identifier for a voice within a model. */
+type VoiceId = string;
+/** Default speaking speed multiplier (1x). */
+declare const DEFAULT_SPEAK_SPEED = 1;
+/** Minimum allowed speaking speed multiplier (0.5x). */
+declare const MIN_SPEAK_SPEED = 0.5;
+/** Maximum allowed speaking speed multiplier (2x). */
+declare const MAX_SPEAK_SPEED = 2;
+/**
+ * Clamps a speed value to the valid range, returning the default if the input is not a finite
+ * number.
+ */
+declare function normalizeSpeakSpeed(speed?: number): number;
+/** A voice available for speech synthesis, associated with a language and optional gender. */
+interface Voice {
+  id: VoiceId;
+  name: string;
+  language: string;
+  gender?: "male" | "female" | "neutral";
+  /** True if this voice was created via voice cloning rather than bundled with the model. */
+  isCloned?: boolean;
+}
+/** Raw audio output from synthesis, represented as per-channel float sample arrays. */
+interface AudioData {
+  sampleRate: number;
+  channels: Float32Array[];
+}
+/** Alias for {@link AudioData}; use when accepting audio data from external sources. */
+type AudioDataLike = AudioData;
+/** A downloadable file (weights, config, etc.) required by a model. */
+interface ModelAsset {
+  name: string;
+  url: string;
+  size: number;
+  sha256?: string;
+}
+/** Runtime capabilities a model needs from the browser environment. */
+interface ModelRequirements {
+  wasm?: boolean;
+  webgpu?: boolean;
+  worker?: boolean;
+}
+/**
+ * How a model handles voices: one fixed voice, multiple built-in voices, or a separate model per
+ * voice.
+ */
+type ModelVoiceMode = "single" | "multi" | "per-voice-model";
+/**
+ * How model assets are distributed: no assets needed, managed by the core asset store, or managed
+ * externally by the adapter.
+ */
+type ModelDistributionKind = "none" | "managed-assets" | "adapter-managed";
+/** Describes how a model's assets are packaged and delivered. */
+interface ModelDistribution {
+  kind: ModelDistributionKind;
+  /** Total download size of all assets in bytes. */
+  sizeBytes?: number;
+  assets?: ModelAsset[];
+}
+/**
+ * Full specification of a TTS model, including its identity, voices, licensing, distribution info,
+ * and runtime requirements.
+ */
+interface ModelSpec {
+  id: ModelId;
+  /** Identifier of the adapter (engine backend) that runs this model. */
+  adapterId: AdapterId;
+  name: string;
+  /** Model family grouping (e.g., "piper", "kokoro"). */
+  family: string;
+  /** Version string used to detect asset updates and cache invalidation. */
+  revision: string;
+  /** SPDX license identifier or descriptive license string. */
+  license: string;
+  /** BCP-47 language codes this model supports. */
+  languages: string[];
+  /** Whether the model uses a single fixed voice, multiple built-in voices, or one model per voice. */
+  voiceMode: ModelVoiceMode;
+  voices?: Voice[];
+  defaultVoiceId?: VoiceId;
+  description?: string;
+  /** URL to a remote manifest for dynamic model metadata updates. */
+  manifestUrl?: string;
+  homepage?: string;
+  /** Browser capabilities (WASM, WebGPU, Worker) the model needs at runtime. */
+  requirements?: ModelRequirements;
+  tags?: string[];
+  /** Adapter-specific configuration passed through to the model instance. */
+  config?: Record<string, unknown>;
+  distribution?: ModelDistribution;
+}
+/** Resolves a model's distribution info, defaulting to `{ kind: "none" }` when unset. */
+declare function resolveModelDistribution(model: Pick<ModelSpec, "distribution">): ModelDistribution;
+/** Returns the list of downloadable assets for a model. */
+declare function getModelAssets(model: Pick<ModelSpec, "distribution">): ModelAsset[];
+/** Returns the total download size in bytes for a model. */
+declare function getModelSizeBytes(model: Pick<ModelSpec, "distribution">): number;
+/** A collection of model specifications, optionally identified by a catalog id. */
+interface ModelCatalog {
+  id?: string;
+  models: ModelSpec[];
+}
+/** A model catalog provided either directly or via a factory function. */
+type CatalogSource = ModelCatalog | (() => ModelCatalog);
+/** Current status of a model's installation lifecycle. */
+type InstallStatus = "not-applicable" | "idle" | "installing" | "installed" | "error" | "unknown" | "ready";
+/** High-level phase of the TTS runtime lifecycle. */
+type RuntimePhase = "idle" | "installing" | "loading" | "speaking" | "error";
+/** Tracks the installation state of a specific model, including progress and error info. */
+interface InstallState {
+  modelId: ModelId;
+  adapterId: AdapterId;
+  revision: string;
+  /** Whether assets are managed by the core store, externally by the adapter, or not needed. */
+  kind: "not-applicable" | "managed" | "external";
+  /** True once all required assets are available locally. */
+  installed: boolean;
+  status: InstallStatus;
+  /** Download progress from 0 to 1, or null when not actively downloading. */
+  progress: number | null;
+  /** Human-readable error message if the install failed. */
+  error: string | null;
+}
+/** Diagnostic information about a loaded model's runtime environment (backend, worker usage, etc.). */
+interface ModelRuntimeInfo {
+  /** Execution backend in use (e.g., "webgpu", "wasm"). */
+  backend: string | null;
+  /** Runtime environment label (e.g., "onnx", "sherpa"). */
+  runtime: string | null;
+  /** Whether the model is running inside a Web Worker. */
+  worker: boolean | null;
+  /** Free-form diagnostic string for debugging. */
+  detail?: string | null;
+}
+/**
+ * Returns the install state for a model, inferring a default from its distribution if none is
+ * provided.
+ */
+declare function resolveInstallState(model: Pick<ModelSpec, "id" | "adapterId" | "revision" | "distribution">, installState?: InstallState): InstallState;
+/** Returns true if the model is ready to use (either installed or installation is not applicable). */
+declare function isInstallStateAvailable(installState: InstallState | null | undefined): boolean;
+/** Type guard that checks whether the install state is managed by the core asset store. */
+declare function isManagedInstallState(installState: InstallState | null | undefined): installState is InstallState & {
+  kind: "managed";
+};
+/** Type guard that checks whether the install state is managed externally by the adapter. */
+declare function isExternalInstallState(installState: InstallState | null | undefined): installState is InstallState & {
+  kind: "external";
+};
+/** Options for a speak or synthesize call, including model/voice selection and speed. */
+interface SpeakOptions {
+  modelId?: ModelId;
+  voiceId?: VoiceId;
+  /** Playback speed multiplier (clamped to 0.5–2x). */
+  speed?: number;
+  /** Models to try in order if the primary model fails or is unavailable. */
+  fallbackModelIds?: ModelId[];
+}
+/** Options for preparing (loading) a model before speaking. */
+interface PrepareOptions {
+  voiceId?: VoiceId;
+  onProgress?: (progress: number) => void;
+}
+/** Observable snapshot of the entire TTS runtime state, used by UI bindings and subscribers. */
+interface RuntimeState {
+  /** All registered model specs from loaded catalogs. */
+  models: ModelSpec[];
+  /** Model IDs that pass the adapter's `isSupported` check on this platform. */
+  supportedModelIds: ModelId[];
+  /** Currently selected model for speech synthesis. */
+  activeModelId: ModelId | null;
+  /** Currently selected voice within the active model. */
+  activeVoiceId: VoiceId | null;
+  /** Voices available for the active model. */
+  voices: Voice[];
+  /** True while a model is being loaded or prepared. */
+  isPreparing: boolean;
+  isSpeaking: boolean;
+  /** High-level lifecycle phase (idle, installing, loading, speaking, error). */
+  phase: RuntimePhase;
+  /** Model that the current phase activity relates to. */
+  phaseModelId: ModelId | null;
+  /** Progress (0–1) of the current phase activity, or null when indeterminate. */
+  phaseProgress: number | null;
+  error: string | null;
+  /** Per-model installation states keyed by model ID. */
+  installStates: Record<ModelId, InstallState>;
+  /** True once install states have been loaded from the asset store on startup. */
+  installStateHydrated: boolean;
+  /** Per-model runtime diagnostics (backend, worker status), keyed by model ID. */
+  runtimeInfoByModel: Record<ModelId, ModelRuntimeInfo | null>;
+}
+/** Composite key that uniquely identifies a versioned bundle of model assets in the asset store. */
+interface AssetBundleKey {
+  adapterId: AdapterId;
+  modelId: ModelId;
+  revision: string;
+}
+/** Persistent storage backend for model asset bundles (e.g., IndexedDB, filesystem). */
+interface AssetStore {
+  /** Write a single asset to temporary staging before the bundle is activated. */
+  stageAsset(bundle: AssetBundleKey, assetName: string, data: ArrayBuffer): Promise<void>;
+  /** Promote staged assets into the active bundle, making them available via `getAsset`. */
+  activateBundle(bundle: AssetBundleKey, assetNames: string[]): Promise<void>;
+  /** Check whether all required assets for a bundle are present in the store. */
+  isInstalled(bundle: AssetBundleKey, requiredAssetNames?: string[]): Promise<boolean>;
+  /** Retrieve a single asset's data from an activated bundle. */
+  getAsset(bundle: AssetBundleKey, assetName: string): Promise<ArrayBuffer | null>;
+  /** Delete an entire bundle and all its assets from the store. */
+  removeBundle(bundle: AssetBundleKey): Promise<void>;
+}
+/** Services provided to adapters by the runtime (asset storage, fetch, abort helpers). */
+interface TTSAdapterContext {
+  /** Persistent storage for downloading and caching model assets. */
+  assetStore: AssetStore;
+  /** Fetch implementation provided by the runtime (allows custom proxying or caching). */
+  fetch: typeof fetch;
+  /** Create a platform-appropriate `AbortError` for cancellation. */
+  createAbortError(): Error;
+}
+/**
+ * Declares which operations an adapter supports (install, speak, synthesize, stream, dynamic
+ * voices).
+ */
+interface TTSAdapterCapabilities {
+  /** Whether the adapter manages its own asset installation. */
+  install: boolean;
+  /** Whether the adapter can play audio directly (without returning AudioData). */
+  speak: boolean;
+  /** Whether the adapter can return a complete AudioData buffer. */
+  synthesize: boolean;
+  /** Whether the adapter supports streaming AudioData chunks incrementally. */
+  stream: boolean;
+  /** Whether the voice list can change at runtime (e.g., cloned voices). */
+  dynamicVoices: boolean;
+}
+/** Platform audio output interface used by the runtime to play synthesized speech. */
+interface RuntimeAudioPlayer {
+  /** Pre-initialize audio context to avoid first-play latency. */
+  warmup?(): void;
+  play(audio: AudioData, signal: AbortSignal, speed?: number): Promise<void>;
+  /** Play audio chunks as they arrive from a streaming source. */
+  playStream?(audio: AsyncIterable<AudioData>, signal: AbortSignal, speed?: number): Promise<void>;
+  stop(): void;
+  dispose(): void;
+}
+/** Discriminant for model instance types. */
+type ModelInstanceKind = "speaking" | "synthesizing";
+/**
+ * A loaded, ready-to-use model instance created by an adapter. The base interface provides
+ * lifecycle methods common to all models. Synthesis capabilities are declared via
+ * {@link SpeakingModelInstance} (direct audio playback) or {@link SynthesizingModelInstance}
+ * (generates audio data).
+ */
+interface TTSModelInstance {
+  /** Discriminant that identifies the model's capability type. */
+  readonly kind: ModelInstanceKind;
+  readonly modelId: ModelId;
+  readonly adapterId: AdapterId;
+  /** Load model weights and initialize the backend; reports progress via callback. */
+  load(signal: AbortSignal, onProgress?: (progress: number) => void): Promise<void>;
+  listVoices(): Voice[] | Promise<Voice[]>;
+  /** Cancel any in-flight generation without disposing the instance. */
+  abortActiveGeneration?(): void;
+  /** Return diagnostic info about the active backend and runtime environment. */
+  getRuntimeInfo?(): ModelRuntimeInfo | null;
+  dispose(): void;
+}
+/** A model that plays audio directly through the adapter's own audio output (e.g. Web Speech API). */
+interface SpeakingModelInstance extends TTSModelInstance {
+  readonly kind: "speaking";
+  speak(text: string, voiceId: VoiceId, signal: AbortSignal, speed?: number): Promise<void>;
+}
+/** A model that synthesizes audio data, optionally with streaming support. */
+interface SynthesizingModelInstance extends TTSModelInstance {
+  readonly kind: "synthesizing";
+  generate(text: string, voiceId: VoiceId, signal: AbortSignal, speed?: number): Promise<AudioData>;
+  /** Yield AudioData chunks as they are synthesized for low-latency playback. */
+  stream?(text: string, voiceId: VoiceId, signal: AbortSignal, speed?: number): AsyncIterable<AudioData>;
+}
+/**
+ * Backend engine that can create model instances and optionally manage installation. Each adapter
+ * corresponds to a specific TTS engine (e.g., Piper, Kokoro, Web Speech API).
+ */
+interface TTSAdapter<T extends TTSModelInstance = TTSModelInstance> {
+  readonly id: AdapterId;
+  readonly name: string;
+  /** Declares which operations this adapter supports; unset fields use defaults. */
+  readonly capabilities?: Partial<TTSAdapterCapabilities>;
+  /** Return false if the model cannot run on the current platform/browser. */
+  isSupported?(spec: ModelSpec): boolean;
+  /** Instantiate a model from its spec; may be async if initialization requires I/O. */
+  createModel(spec: ModelSpec, context: TTSAdapterContext): Promise<T> | T;
+  /** Download and store model assets; only called when `capabilities.install` is true. */
+  install?(spec: ModelSpec, context: TTSAdapterContext, signal: AbortSignal, onProgress?: (progress: number) => void): Promise<void>;
+  /** Remove previously installed model assets. */
+  uninstall?(spec: ModelSpec, context: TTSAdapterContext): Promise<void>;
+}
+/** Configuration for creating a {@link TTSRuntime} instance. */
+interface TTSRuntimeOptions {
+  /** Engine backends to register (at least one required). */
+  adapters: TTSAdapter[];
+  /** Model catalogs to load; can be static objects or factory functions. */
+  catalogs: CatalogSource[];
+  /** Persistent storage for model assets; defaults to an in-memory store if omitted. */
+  assetStore?: AssetStore;
+  /** Platform audio player; pass null to disable direct playback. */
+  audioPlayer?: RuntimeAudioPlayer | null;
+  /** Custom fetch implementation for asset downloads. */
+  fetch?: typeof fetch;
+  /** Model to select on startup before any user interaction. */
+  initialModelId?: ModelId;
+  /** Voice to select on startup before any user interaction. */
+  initialVoiceId?: VoiceId;
+}
+/**
+ * The main public API for polytts. Manages models, voices, installation, and speech synthesis.
+ * Subscribe to state changes for reactive UI updates.
+ */
+interface TTSRuntime {
+  getState(): RuntimeState;
+  subscribe(listener: (state: RuntimeState) => void): () => void;
+  listModels(): ModelSpec[];
+  getModel(modelId: ModelId): ModelSpec | null;
+  listVoices(modelId?: ModelId): Promise<Voice[]>;
+  install(modelId: ModelId, onProgress?: (progress: number) => void): Promise<void>;
+  uninstall(modelId: ModelId): Promise<void>;
+  prepare(modelId: ModelId, options?: PrepareOptions): Promise<void>;
+  speak(text: string, options?: SpeakOptions): Promise<void>;
+  synthesizeStream(text: string, options?: SpeakOptions): AsyncIterable<AudioData>;
+  synthesize(text: string, options?: SpeakOptions): Promise<AudioData>;
+  stop(): void;
+  dispose(): void;
+}
+/** Resolves an adapter's full capabilities, using sensible defaults for any unspecified fields. */
+declare function resolveAdapterCapabilities(adapter: Pick<TTSAdapter, "capabilities" | "install">): TTSAdapterCapabilities;
+//#endregion
+//#region src/audio.d.ts
+/** Creates an AudioData object from a sample rate and an array of channel buffers. */
+declare function createAudioData(sampleRate: number, channels: Float32Array[]): AudioData;
+/** Wraps a single-channel PCM Float32Array into an AudioData object. */
+declare function pcmToAudioData(data: Float32Array, sampleRate: number): AudioData;
+/** Creates a silent AudioData object, useful as a placeholder or for padding. */
+declare function createSilentAudioData(sampleRate?: number, frameCount?: number): AudioData;
+//#endregion
+//#region src/catalog.d.ts
+/** Creates a model catalog from a static array of model specs. */
+declare function createStaticCatalog(models: ModelSpec[]): ModelCatalog;
+/** Resolves a catalog source (static object or factory function) into a ModelCatalog. */
+declare function resolveCatalogSource(source: CatalogSource): ModelCatalog;
+/** Merges multiple catalog sources into a single catalog, throwing on duplicate model IDs. */
+declare function mergeCatalogs(...sources: CatalogSource[]): ModelCatalog;
+/** Validates that every model in the catalog references a registered adapter. */
+declare function validateCatalog(catalog: ModelCatalog, adapters: Map<string, TTSAdapter>): void;
+//#endregion
+//#region src/runtime.d.ts
+/** Creates a new TTS runtime instance, the main entry point for text-to-speech functionality. */
+declare function createTTSRuntime(options: TTSRuntimeOptions): TTSRuntime;
+//#endregion
+//#region src/storage/memory-asset-store.d.ts
+/**
+ * In-memory implementation of AssetStore, primarily useful for testing and environments without
+ * persistent storage.
+ */
+declare class MemoryAssetStore implements AssetStore {
+  private readonly staging;
+  private readonly active;
+  private readonly meta;
+  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>;
+}
+//#endregion
+export { AdapterId, AssetBundleKey, AssetStore, AudioData, AudioDataLike, CatalogSource, DEFAULT_SPEAK_SPEED, InstallState, InstallStatus, MAX_SPEAK_SPEED, MIN_SPEAK_SPEED, MemoryAssetStore, ModelAsset, ModelCatalog, ModelDistribution, ModelDistributionKind, ModelId, ModelInstanceKind, ModelRequirements, ModelRuntimeInfo, ModelSpec, ModelVoiceMode, PrepareOptions, RuntimeAudioPlayer, RuntimePhase, RuntimeState, SpeakOptions, SpeakingModelInstance, SynthesizingModelInstance, TTSAdapter, TTSAdapterCapabilities, TTSAdapterContext, TTSModelInstance, TTSRuntime, TTSRuntimeOptions, Voice, VoiceId, createAudioData, createSilentAudioData, createStaticCatalog, createTTSRuntime, getModelAssets, getModelSizeBytes, isExternalInstallState, isInstallStateAvailable, isManagedInstallState, mergeCatalogs, normalizeSpeakSpeed, pcmToAudioData, resolveAdapterCapabilities, resolveCatalogSource, resolveInstallState, resolveModelDistribution, validateCatalog };