@framers/agentos 0.1.120 → 0.1.121

package/dist/core/audio/FallbackAudioProxy.js

@@ -0,0 +1,236 @@
+/**
+ * @file FallbackAudioProxy.ts
+ * Automatic failover proxy for audio generation providers.
+ *
+ * Follows the same pattern established by {@link FallbackVideoProxy} in the
+ * video subsystem: an ordered chain of {@link IAudioGenerator} instances is
+ * tried left-to-right for each operation. The first provider that succeeds
+ * wins; earlier failures are caught, logged via an emitted event, and the
+ * next provider is tried.
+ *
+ * ## Sub-modality handling
+ *
+ * For the optional `generateSFX` operation the proxy skips providers whose
+ * {@link IAudioGenerator.supports} method returns `false` for `'sfx'`.
+ * Likewise, `generateMusic` skips providers that don't support `'music'`.
+ * Skipped providers are not counted as transient failures — the proxy simply
+ * advances to the next candidate.
+ *
+ * @see {@link FallbackVideoProxy} for the analogous video proxy.
+ * @see {@link FallbackImageProxy} for the analogous image proxy.
+ *
+ * @example
+ * ```ts
+ * import { EventEmitter } from 'events';
+ * import { FallbackAudioProxy } from './FallbackAudioProxy.js';
+ *
+ * const emitter = new EventEmitter();
+ * emitter.on('audio:generate:fallback', (evt) => {
+ *   console.warn(`Audio fallback: ${evt.from} -> ${evt.to} (${evt.reason})`);
+ * });
+ *
+ * const proxy = new FallbackAudioProxy(
+ *   [sunoProvider, stableAudioProvider, elevenLabsProvider],
+ *   emitter,
+ * );
+ *
+ * // If Suno fails, Stable Audio is tried, then ElevenLabs.
+ * const result = await proxy.generateMusic(request);
+ * ```
+ */
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Extracts a human-readable reason string from an unknown error value.
+ */
+function errorReason(err) {
+    if (err instanceof Error)
+        return err.message;
+    return String(err);
+}
+// ---------------------------------------------------------------------------
+// FallbackAudioProxy
+// ---------------------------------------------------------------------------
+/**
+ * An {@link IAudioGenerator} that wraps an ordered chain of audio providers
+ * and implements automatic failover for every operation.
+ *
+ * ## Retry chain logic
+ *
+ * Providers are tried left-to-right (index 0 first). The first provider
+ * that succeeds returns immediately. When a provider throws:
+ *
+ * - **If it is NOT the last provider:** an `audio:generate:fallback` event is
+ *   emitted and the next provider is tried.
+ * - **If it IS the last provider:** an `AggregateError` containing every
+ *   collected error is thrown.
+ * - **If the chain is empty:** an `Error('No providers in audio fallback chain')`
+ *   is thrown immediately.
+ *
+ * For `generateMusic`, providers whose {@link IAudioGenerator.supports} returns
+ * `false` for `'music'` are silently skipped. For `generateSFX`, providers
+ * that don't support `'sfx'` (or lack the method entirely) are skipped.
+ */
+export class FallbackAudioProxy {
+    /**
+     * Creates a new FallbackAudioProxy wrapping the given provider chain.
+     *
+     * @param chain - Ordered list of audio providers to try. Must contain at
+     *   least one entry for operations to succeed (an empty chain always throws).
+     * @param emitter - EventEmitter on which `audio:generate:fallback` events
+     *   are published so callers can observe the failover path.
+     *
+     * @example
+     * ```ts
+     * const proxy = new FallbackAudioProxy(
+     *   [sunoProvider, stableAudioProvider],
+     *   new EventEmitter(),
+     * );
+     * ```
+     */
+    constructor(chain, emitter) {
+        this.chain = chain;
+        this.emitter = emitter;
+        /** Always `true` — the proxy is ready as soon as it is constructed. */
+        this.isInitialized = true;
+        this.providerId = chain[0]?.providerId ?? 'fallback-audio';
+        this.defaultModelId = chain[0]?.defaultModelId;
+    }
+    // -----------------------------------------------------------------------
+    // IAudioGenerator — initialize (no-op for the proxy itself)
+    // -----------------------------------------------------------------------
+    /**
+     * No-op initialisation — individual providers in the chain should already
+     * be initialised before being passed to the proxy.
+     */
+    async initialize(_config) {
+        // Each provider in the chain is initialised independently before
+        // construction, so the proxy itself has nothing to set up.
+    }
+    // -----------------------------------------------------------------------
+    // IAudioGenerator — supports
+    // -----------------------------------------------------------------------
+    /**
+     * Returns `true` if at least one provider in the chain supports the
+     * given capability.
+     *
+     * @param capability - The capability to query (`'music'` or `'sfx'`).
+     */
+    supports(capability) {
+        return this.chain.some((provider) => provider.supports(capability));
+    }
+    // -----------------------------------------------------------------------
+    // IAudioGenerator — generateMusic
+    // -----------------------------------------------------------------------
+    /**
+     * Generate music from a text prompt, falling back through the provider
+     * chain on failure.
+     *
+     * Providers whose {@link IAudioGenerator.supports} returns `false` for
+     * `'music'` are silently skipped.
+     *
+     * @param request - The generation request forwarded to each provider.
+     * @returns The result from the first provider that succeeds.
+     * @throws {AggregateError} When every provider in the chain fails.
+     * @throws {Error} When the chain is empty.
+     */
+    async generateMusic(request) {
+        return this.runWithFallback('generateMusic', (provider) => {
+            if (!provider.supports('music')) {
+                throw Object.assign(new Error(`Provider "${provider.providerId}" does not support music generation.`), { name: 'MusicNotSupportedError' });
+            }
+            return provider.generateMusic(request);
+        });
+    }
+    // -----------------------------------------------------------------------
+    // IAudioGenerator — generateSFX (optional)
+    // -----------------------------------------------------------------------
+    /**
+     * Generate a sound effect from a text prompt, falling back through providers
+     * that support SFX.
+     *
+     * Providers whose {@link IAudioGenerator.supports} returns `false` for
+     * `'sfx'` or that lack the `generateSFX` method are silently skipped.
+     *
+     * @param request - The SFX request forwarded to each capable provider.
+     * @returns The result from the first provider that succeeds.
+     * @throws {AggregateError} When every provider fails or does not support SFX.
+     */
+    async generateSFX(request) {
+        return this.runWithFallback('generateSFX', (provider) => {
+            if (!provider.supports('sfx') || typeof provider.generateSFX !== 'function') {
+                throw Object.assign(new Error(`Provider "${provider.providerId}" does not support SFX generation.`), { name: 'SFXNotSupportedError' });
+            }
+            return provider.generateSFX(request);
+        });
+    }
+    // -----------------------------------------------------------------------
+    // IAudioGenerator — shutdown (optional)
+    // -----------------------------------------------------------------------
+    /**
+     * Shuts down all providers in the chain. Errors are caught per-provider
+     * so a single provider's failure does not prevent the others from
+     * cleaning up.
+     */
+    async shutdown() {
+        for (const provider of this.chain) {
+            if (typeof provider.shutdown === 'function') {
+                try {
+                    await provider.shutdown();
+                }
+                catch {
+                    // Swallow individual shutdown errors — best effort.
+                }
+            }
+        }
+    }
+    // -----------------------------------------------------------------------
+    // Core fallback loop
+    // -----------------------------------------------------------------------
+    /**
+     * Executes an operation against each provider in the chain until one
+     * succeeds or all have been exhausted.
+     *
+     * Providers that throw an error whose `name` ends with `NotSupportedError`
+     * are treated as structurally incapable — the reason is recorded as
+     * "not supported" rather than the raw error message.
+     *
+     * @param operationName - Human-readable name of the operation (for error messages).
+     * @param execute - Async callback that runs the operation on a single provider.
+     * @returns The result from the first successful provider.
+     * @throws {AggregateError} When every provider fails.
+     */
+    async runWithFallback(operationName, execute) {
+        if (this.chain.length === 0) {
+            throw new Error('No providers in audio fallback chain');
+        }
+        const errors = [];
+        for (let i = 0; i < this.chain.length; i++) {
+            const provider = this.chain[i];
+            try {
+                return await execute(provider);
+            }
+            catch (err) {
+                const isNotSupported = err instanceof Error && err.name.endsWith('NotSupportedError');
+                const reason = isNotSupported
+                    ? `${operationName} not supported`
+                    : errorReason(err);
+                errors.push(err instanceof Error ? err : new Error(String(err)));
+                // Emit a fallback event when there is a next provider to try.
+                if (i < this.chain.length - 1) {
+                    const event = {
+                        type: 'audio:generate:fallback',
+                        from: provider.providerId,
+                        to: this.chain[i + 1].providerId,
+                        reason,
+                    };
+                    this.emitter.emit('audio:generate:fallback', event);
+                }
+            }
+        }
+        // All providers exhausted — throw an aggregate error.
+        throw new AggregateError(errors, `All ${this.chain.length} audio providers failed for ${operationName}: ${errors.map((e) => e.message).join('; ')}`);
+    }
+}
+//# sourceMappingURL=FallbackAudioProxy.js.map

package/dist/core/audio/FallbackAudioProxy.js.map

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

package/dist/core/audio/IAudioGenerator.d.ts

@@ -0,0 +1,103 @@
+/**
+ * @file IAudioGenerator.ts
+ * Provider interface for audio generation (music and sound effects).
+ *
+ * Follows the same pattern as {@link IVideoGenerator} in the video subsystem:
+ * each concrete provider implements this interface, and instances are composed
+ * into a {@link FallbackAudioProxy} chain for automatic failover.
+ *
+ * ## Sub-modality split
+ *
+ * Audio generation is split into two sub-modalities:
+ *
+ * - **Music** — full-length compositions ({@link generateMusic}).
+ * - **SFX** — short sound effects ({@link generateSFX}).
+ *
+ * A provider may support one or both. Capability negotiation is done via
+ * {@link supports} — the proxy uses this to skip structurally incapable
+ * providers rather than counting them as transient failures.
+ *
+ * @see {@link FallbackAudioProxy} for the failover wrapper.
+ * @see {@link IVideoGenerator} for the analogous video interface.
+ */
+import type { MusicGenerateRequest, SFXGenerateRequest, AudioResult } from './types.js';
+/**
+ * Abstraction over an audio generation backend (Suno, Udio, Stable Audio,
+ * ElevenLabs, Replicate, etc.).
+ *
+ * ## Capability negotiation
+ *
+ * Not every provider supports every sub-modality. The {@link supports} method
+ * lets callers (and the {@link FallbackAudioProxy}) query whether a given
+ * capability is available before invoking it.
+ *
+ * ## Lifecycle
+ *
+ * 1. Construct the provider.
+ * 2. Call {@link initialize} with provider-specific configuration (API keys,
+ *    base URLs, etc.).
+ * 3. Use {@link generateMusic} and/or {@link generateSFX}.
+ * 4. Optionally call {@link shutdown} to release resources.
+ *
+ * @example
+ * ```typescript
+ * const suno: IAudioGenerator = new SunoProvider();
+ * await suno.initialize({ apiKey: process.env.SUNO_API_KEY! });
+ *
+ * if (suno.supports('music')) {
+ *   const result = await suno.generateMusic({ prompt: 'Ambient piano loop' });
+ *   console.log(result.audio[0].url);
+ * }
+ *
+ * await suno.shutdown?.();
+ * ```
+ */
+export interface IAudioGenerator {
+    /** Unique identifier for this provider (e.g. `'suno'`, `'elevenlabs-sfx'`). */
+    readonly providerId: string;
+    /** Whether {@link initialize} has been called successfully. */
+    readonly isInitialized: boolean;
+    /** Default model used when the request omits `modelId`. */
+    readonly defaultModelId?: string;
+    /**
+     * Initialise the provider with runtime configuration.
+     *
+     * @param config - Provider-specific key/value pairs (API keys, endpoints,
+     *   model overrides, etc.).
+     */
+    initialize(config: Record<string, unknown>): Promise<void>;
+    /**
+     * Generate music from a text prompt.
+     *
+     * Providers that do not support music generation should throw an error
+     * and have {@link supports} return `false` for `'music'`.
+     *
+     * @param request - The music generation parameters.
+     * @returns A result envelope containing one or more generated audio clips.
+     */
+    generateMusic(request: MusicGenerateRequest): Promise<AudioResult>;
+    /**
+     * Generate a sound effect from a text prompt.
+     *
+     * This method is optional — providers that do not support SFX generation
+     * should either omit it or have {@link supports} return `false` for
+     * `'sfx'`.
+     *
+     * @param request - The SFX generation parameters.
+     * @returns A result envelope containing one or more generated audio clips.
+     */
+    generateSFX?(request: SFXGenerateRequest): Promise<AudioResult>;
+    /**
+     * Query whether this provider supports a given capability.
+     *
+     * @param capability - The capability to check (`'music'` or `'sfx'`).
+     * @returns `true` if the provider can handle the requested capability.
+     */
+    supports(capability: 'music' | 'sfx'): boolean;
+    /**
+     * Release any resources held by the provider (HTTP connections, polling
+     * loops, temp files, etc.).
+     */
+    shutdown?(): Promise<void>;
+}
+//# sourceMappingURL=IAudioGenerator.d.ts.map

package/dist/core/audio/IAudioGenerator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IAudioGenerator.d.ts","sourceRoot":"","sources":["../../../src/core/audio/IAudioGenerator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAMxF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,WAAW,eAAe;IAC9B,+EAA+E;IAC/E,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAE5B,+DAA+D;IAC/D,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAEhC,2DAA2D;IAC3D,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IAEjC;;;;;OAKG;IACH,UAAU,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE3D;;;;;;;;OAQG;IACH,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IAEnE;;;;;;;;;OASG;IACH,WAAW,CAAC,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IAEhE;;;;;OAKG;IACH,QAAQ,CAAC,UAAU,EAAE,OAAO,GAAG,KAAK,GAAG,OAAO,CAAC;IAE/C;;;OAGG;IACH,QAAQ,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5B"}

package/dist/core/audio/IAudioGenerator.js

@@ -0,0 +1,24 @@
+/**
+ * @file IAudioGenerator.ts
+ * Provider interface for audio generation (music and sound effects).
+ *
+ * Follows the same pattern as {@link IVideoGenerator} in the video subsystem:
+ * each concrete provider implements this interface, and instances are composed
+ * into a {@link FallbackAudioProxy} chain for automatic failover.
+ *
+ * ## Sub-modality split
+ *
+ * Audio generation is split into two sub-modalities:
+ *
+ * - **Music** — full-length compositions ({@link generateMusic}).
+ * - **SFX** — short sound effects ({@link generateSFX}).
+ *
+ * A provider may support one or both. Capability negotiation is done via
+ * {@link supports} — the proxy uses this to skip structurally incapable
+ * providers rather than counting them as transient failures.
+ *
+ * @see {@link FallbackAudioProxy} for the failover wrapper.
+ * @see {@link IVideoGenerator} for the analogous video interface.
+ */
+export {};
+//# sourceMappingURL=IAudioGenerator.js.map

package/dist/core/audio/IAudioGenerator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IAudioGenerator.js","sourceRoot":"","sources":["../../../src/core/audio/IAudioGenerator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG"}

package/dist/core/audio/index.d.ts

@@ -1,5 +1,59 @@
+/**
+ * @file index.ts
+ * Barrel export for the audio generation and processing subsystem.
+ *
+ * Re-exports all public types, interfaces, processing utilities, and the
+ * fallback proxy so consumers can import from `@agentos/core/audio` (or the
+ * relative path) without reaching into individual files.
+ *
+ * Also provides a provider factory registry (modelled on the video
+ * subsystem's pattern) so that built-in and third-party audio providers
+ * can be registered and instantiated by provider ID.
+ */
+import type { IAudioGenerator } from './IAudioGenerator.js';
 export * from './AdaptiveVAD.js';
 export * from './AudioProcessor.js';
 export * from './EnvironmentalCalibrator.js';
 export * from './SilenceDetector.js';
+export * from './types.js';
+export * from './IAudioGenerator.js';
+export * from './FallbackAudioProxy.js';
+/** A factory function that creates an uninitialised audio provider instance. */
+export type AudioProviderFactory = () => IAudioGenerator;
+/**
+ * Register an audio provider factory for a given provider ID.
+ *
+ * Use this to add third-party or custom audio providers at runtime.
+ * Built-in providers (suno, udio, stable-audio, elevenlabs-sfx,
+ * musicgen-local, audiogen-local, replicate-audio, fal-audio) are
+ * pre-registered.
+ *
+ * @param providerId - Unique identifier for the provider (lowercased for matching).
+ * @param factory - Factory function that creates a new uninitialised provider instance.
+ */
+export declare function registerAudioProviderFactory(providerId: string, factory: AudioProviderFactory): void;
+/**
+ * Create an audio provider instance by provider ID.
+ *
+ * Looks up the factory in the registry and returns a new uninitialised
+ * provider. The caller must call `provider.initialize(config)` before use.
+ *
+ * @param providerId - Provider identifier (e.g. `"suno"`, `"stable-audio"`, `"elevenlabs-sfx"`).
+ * @returns A new uninitialised {@link IAudioGenerator} instance.
+ * @throws {Error} When no factory is registered for the given provider ID.
+ */
+export declare function createAudioProvider(providerId: string): IAudioGenerator;
+/**
+ * Check whether an audio provider factory is registered for the given ID.
+ *
+ * @param providerId - Provider identifier to check.
+ * @returns `true` if a factory exists for this provider.
+ */
+export declare function hasAudioProviderFactory(providerId: string): boolean;
+/**
+ * List all registered audio provider factory IDs, sorted alphabetically.
+ *
+ * @returns Sorted array of registered provider identifiers.
+ */
+export declare function listAudioProviderFactories(): string[];
 //# sourceMappingURL=index.d.ts.map

package/dist/core/audio/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/audio/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,sBAAsB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/audio/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAa5D,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,sBAAsB,CAAC;AAKrC,cAAc,YAAY,CAAC;AAC3B,cAAc,sBAAsB,CAAC;AACrC,cAAc,yBAAyB,CAAC;AAMxC,gFAAgF;AAChF,MAAM,MAAM,oBAAoB,GAAG,MAAM,eAAe,CAAC;AAmBzD;;;;;;;;;;GAUG;AACH,wBAAgB,4BAA4B,CAC1C,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,oBAAoB,GAC5B,IAAI,CAEN;AAED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,MAAM,GAAG,eAAe,CAMvE;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAEnE;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,IAAI,MAAM,EAAE,CAErD"}

package/dist/core/audio/index.js

@@ -1,5 +1,98 @@
+/**
+ * @file index.ts
+ * Barrel export for the audio generation and processing subsystem.
+ *
+ * Re-exports all public types, interfaces, processing utilities, and the
+ * fallback proxy so consumers can import from `@agentos/core/audio` (or the
+ * relative path) without reaching into individual files.
+ *
+ * Also provides a provider factory registry (modelled on the video
+ * subsystem's pattern) so that built-in and third-party audio providers
+ * can be registered and instantiated by provider ID.
+ */
+import { AudioGenLocalProvider } from './providers/AudioGenLocalProvider.js';
+import { ElevenLabsSFXProvider } from './providers/ElevenLabsSFXProvider.js';
+import { FalAudioProvider } from './providers/FalAudioProvider.js';
+import { MusicGenLocalProvider } from './providers/MusicGenLocalProvider.js';
+import { ReplicateAudioProvider } from './providers/ReplicateAudioProvider.js';
+import { StableAudioProvider } from './providers/StableAudioProvider.js';
+import { SunoProvider } from './providers/SunoProvider.js';
+import { UdioProvider } from './providers/UdioProvider.js';
+// ---------------------------------------------------------------------------
+// Audio processing (VAD, silence detection, calibration)
+// ---------------------------------------------------------------------------
 export * from './AdaptiveVAD.js';
 export * from './AudioProcessor.js';
 export * from './EnvironmentalCalibrator.js';
 export * from './SilenceDetector.js';
+// ---------------------------------------------------------------------------
+// Audio generation (types, interface, fallback proxy)
+// ---------------------------------------------------------------------------
+export * from './types.js';
+export * from './IAudioGenerator.js';
+export * from './FallbackAudioProxy.js';
+/**
+ * Internal registry mapping provider IDs to provider constructors.
+ *
+ * Built-in providers are pre-registered here so the public
+ * `createAudioProvider()` API remains synchronous and ESM-safe.
+ */
+const audioProviderFactories = new Map([
+    ['suno', () => new SunoProvider()],
+    ['udio', () => new UdioProvider()],
+    ['stable-audio', () => new StableAudioProvider()],
+    ['elevenlabs-sfx', () => new ElevenLabsSFXProvider()],
+    ['musicgen-local', () => new MusicGenLocalProvider()],
+    ['audiogen-local', () => new AudioGenLocalProvider()],
+    ['replicate-audio', () => new ReplicateAudioProvider()],
+    ['fal-audio', () => new FalAudioProvider()],
+]);
+/**
+ * Register an audio provider factory for a given provider ID.
+ *
+ * Use this to add third-party or custom audio providers at runtime.
+ * Built-in providers (suno, udio, stable-audio, elevenlabs-sfx,
+ * musicgen-local, audiogen-local, replicate-audio, fal-audio) are
+ * pre-registered.
+ *
+ * @param providerId - Unique identifier for the provider (lowercased for matching).
+ * @param factory - Factory function that creates a new uninitialised provider instance.
+ */
+export function registerAudioProviderFactory(providerId, factory) {
+    audioProviderFactories.set(providerId.toLowerCase(), factory);
+}
+/**
+ * Create an audio provider instance by provider ID.
+ *
+ * Looks up the factory in the registry and returns a new uninitialised
+ * provider. The caller must call `provider.initialize(config)` before use.
+ *
+ * @param providerId - Provider identifier (e.g. `"suno"`, `"stable-audio"`, `"elevenlabs-sfx"`).
+ * @returns A new uninitialised {@link IAudioGenerator} instance.
+ * @throws {Error} When no factory is registered for the given provider ID.
+ */
+export function createAudioProvider(providerId) {
+    const factory = audioProviderFactories.get(providerId.toLowerCase());
+    if (!factory) {
+        throw new Error(`Audio generation is not supported for provider "${providerId}".`);
+    }
+    return factory();
+}
+/**
+ * Check whether an audio provider factory is registered for the given ID.
+ *
+ * @param providerId - Provider identifier to check.
+ * @returns `true` if a factory exists for this provider.
+ */
+export function hasAudioProviderFactory(providerId) {
+    return audioProviderFactories.has(providerId.toLowerCase());
+}
+/**
+ * List all registered audio provider factory IDs, sorted alphabetically.
+ *
+ * @returns Sorted array of registered provider identifiers.
+ */
+export function listAudioProviderFactories() {
+    return Array.from(audioProviderFactories.keys()).sort();
+}
 //# sourceMappingURL=index.js.map

package/dist/core/audio/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/core/audio/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,sBAAsB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/core/audio/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,EAAE,qBAAqB,EAAE,MAAM,sCAAsC,CAAC;AAC7E,OAAO,EAAE,qBAAqB,EAAE,MAAM,sCAAsC,CAAC;AAC7E,OAAO,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AACnE,OAAO,EAAE,qBAAqB,EAAE,MAAM,sCAAsC,CAAC;AAC7E,OAAO,EAAE,sBAAsB,EAAE,MAAM,uCAAuC,CAAC;AAC/E,OAAO,EAAE,mBAAmB,EAAE,MAAM,oCAAoC,CAAC;AACzE,OAAO,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAC3D,OAAO,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAE3D,8EAA8E;AAC9E,yDAAyD;AACzD,8EAA8E;AAC9E,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,sBAAsB,CAAC;AAErC,8EAA8E;AAC9E,sDAAsD;AACtD,8EAA8E;AAC9E,cAAc,YAAY,CAAC;AAC3B,cAAc,sBAAsB,CAAC;AACrC,cAAc,yBAAyB,CAAC;AASxC;;;;;GAKG;AACH,MAAM,sBAAsB,GAAG,IAAI,GAAG,CAA+B;IACnE,CAAC,MAAM,EAAE,GAAG,EAAE,CAAC,IAAI,YAAY,EAAE,CAAC;IAClC,CAAC,MAAM,EAAE,GAAG,EAAE,CAAC,IAAI,YAAY,EAAE,CAAC;IAClC,CAAC,cAAc,EAAE,GAAG,EAAE,CAAC,IAAI,mBAAmB,EAAE,CAAC;IACjD,CAAC,gBAAgB,EAAE,GAAG,EAAE,CAAC,IAAI,qBAAqB,EAAE,CAAC;IACrD,CAAC,gBAAgB,EAAE,GAAG,EAAE,CAAC,IAAI,qBAAqB,EAAE,CAAC;IACrD,CAAC,gBAAgB,EAAE,GAAG,EAAE,CAAC,IAAI,qBAAqB,EAAE,CAAC;IACrD,CAAC,iBAAiB,EAAE,GAAG,EAAE,CAAC,IAAI,sBAAsB,EAAE,CAAC;IACvD,CAAC,WAAW,EAAE,GAAG,EAAE,CAAC,IAAI,gBAAgB,EAAE,CAAC;CAC5C,CAAC,CAAC;AAEH;;;;;;;;;;GAUG;AACH,MAAM,UAAU,4BAA4B,CAC1C,UAAkB,EAClB,OAA6B;IAE7B,sBAAsB,CAAC,GAAG,CAAC,UAAU,CAAC,WAAW,EAAE,EAAE,OAAO,CAAC,CAAC;AAChE,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,mBAAmB,CAAC,UAAkB;IACpD,MAAM,OAAO,GAAG,sBAAsB,CAAC,GAAG,CAAC,UAAU,CAAC,WAAW,EAAE,CAAC,CAAC;IACrE,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CAAC,mDAAmD,UAAU,IAAI,CAAC,CAAC;IACrF,CAAC;IACD,OAAO,OAAO,EAAE,CAAC;AACnB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,uBAAuB,CAAC,UAAkB;IACxD,OAAO,sBAAsB,CAAC,GAAG,CAAC,UAAU,CAAC,WAAW,EAAE,CAAC,CAAC;AAC9D,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,0BAA0B;IACxC,OAAO,KAAK,CAAC,IAAI,CAAC,sBAAsB,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;AAC1D,CAAC"}