@framers/agentos 0.1.120 → 0.1.122

package/dist/core/audio/providers/FalAudioProvider.d.ts

@@ -0,0 +1,207 @@
+/**
+ * @module core/audio/providers/FalAudioProvider
+ *
+ * Audio generation provider for the Fal.ai serverless GPU platform.
+ *
+ * Fal.ai hosts audio generation models (Stable Audio, etc.) behind a
+ * queue-based API. This provider implements the three-step pattern
+ * established by {@link FalVideoProvider}: submit to queue, poll for status,
+ * then fetch the completed result.
+ *
+ * ## Supported models
+ *
+ * | Model ID               | Description                          |
+ * |------------------------|--------------------------------------|
+ * | `fal-ai/stable-audio`  | Stable Audio on Fal.ai — default     |
+ *
+ * ## API flow (three-step queue)
+ *
+ * 1. **Submit** — `POST ${baseURL}/${model}` with prompt/params.
+ *    Returns `{ request_id }` immediately.
+ * 2. **Poll** — `GET ${baseURL}/${model}/requests/${request_id}/status`
+ *    until `status === 'COMPLETED'` or `'FAILED'`.
+ * 3. **Fetch** — `GET ${baseURL}/${model}/requests/${request_id}`
+ *    returns `{ audio: { url } }`.
+ *
+ * ## Authentication
+ *
+ * Requires a `FAL_API_KEY`. Sent as `Authorization: Key ${apiKey}`.
+ *
+ * @see {@link IAudioGenerator} for the provider interface contract.
+ * @see {@link FalVideoProvider} for the video counterpart.
+ * @see {@link FalImageProvider} for the image counterpart.
+ */
+import type { IAudioGenerator } from '../IAudioGenerator.js';
+import type { MusicGenerateRequest, SFXGenerateRequest, AudioResult } from '../types.js';
+/**
+ * Configuration for the Fal.ai audio generation provider.
+ *
+ * @example
+ * ```typescript
+ * const config: FalAudioProviderConfig = {
+ *   apiKey: process.env.FAL_API_KEY!,
+ *   defaultModelId: 'fal-ai/stable-audio',
+ * };
+ * ```
+ */
+export interface FalAudioProviderConfig {
+    /**
+     * Fal.ai API key. Sent as `Authorization: Key ${apiKey}`.
+     * Obtain from https://fal.ai/dashboard/keys
+     */
+    apiKey: string;
+    /**
+     * Base URL for the Fal.ai queue API. Override for testing or proxy setups.
+     * @default 'https://queue.fal.run'
+     */
+    baseURL?: string;
+    /**
+     * Default model to use when the request doesn't specify one.
+     * @default 'fal-ai/stable-audio'
+     */
+    defaultModelId?: string;
+    /**
+     * Milliseconds between status polls while waiting for generation.
+     * @default 2000
+     */
+    pollIntervalMs?: number;
+    /**
+     * Maximum milliseconds to wait for generation before timing out.
+     * @default 300000
+     */
+    timeoutMs?: number;
+}
+/**
+ * Audio generation provider connecting to the Fal.ai serverless platform.
+ *
+ * Implements the three-step queue pattern: submit a generation task,
+ * poll the status endpoint until completion, then fetch the result.
+ * This mirrors the flow used by {@link FalVideoProvider}.
+ *
+ * Supports both music and SFX generation through the same endpoint.
+ *
+ * @implements {IAudioGenerator}
+ *
+ * @example
+ * ```typescript
+ * const provider = new FalAudioProvider();
+ * await provider.initialize({ apiKey: process.env.FAL_API_KEY! });
+ *
+ * const result = await provider.generateMusic({
+ *   modelId: 'fal-ai/stable-audio',
+ *   prompt: 'A dreamy ambient track with reverb-heavy synths',
+ *   durationSec: 30,
+ * });
+ * console.log(result.audio[0].url);
+ * ```
+ */
+export declare class FalAudioProvider implements IAudioGenerator {
+    /** @inheritdoc */
+    readonly providerId = "fal-audio";
+    /** @inheritdoc */
+    isInitialized: boolean;
+    /** @inheritdoc */
+    defaultModelId?: string;
+    /** Internal resolved configuration. */
+    private _config;
+    /**
+     * Initialize the provider with API credentials and optional configuration.
+     *
+     * @param config - Configuration object. Must include `apiKey`.
+     * @throws {Error} If `apiKey` is missing or empty.
+     */
+    initialize(config: Record<string, unknown>): Promise<void>;
+    /**
+     * Generate music from a text prompt using the Fal.ai queue API.
+     *
+     * Submits the task, polls until complete, then fetches the result.
+     *
+     * @param request - Music generation request with prompt and optional params.
+     * @returns The generated audio result envelope.
+     *
+     * @throws {Error} If the provider is not initialized.
+     * @throws {Error} If the API returns an error or times out.
+     */
+    generateMusic(request: MusicGenerateRequest): Promise<AudioResult>;
+    /**
+     * Generate a sound effect from a text prompt using the Fal.ai queue API.
+     *
+     * Submits the task, polls until complete, then fetches the result.
+     *
+     * @param request - SFX generation request with prompt and optional params.
+     * @returns The generated audio result envelope.
+     *
+     * @throws {Error} If the provider is not initialized.
+     * @throws {Error} If the API returns an error or times out.
+     */
+    generateSFX(request: SFXGenerateRequest): Promise<AudioResult>;
+    /**
+     * Fal.ai audio supports both music and SFX generation.
+     *
+     * @param capability - The capability to check.
+     * @returns `true` for both `'music'` and `'sfx'`.
+     */
+    supports(capability: 'music' | 'sfx'): boolean;
+    /**
+     * Release any resources held by the provider. No-op for HTTP-only providers.
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Run the full three-step generation flow: submit, poll, fetch.
+     *
+     * @param prompt - Text description of the desired audio.
+     * @param durationSec - Desired duration in seconds.
+     * @param modelId - Optional model override.
+     * @returns Normalized audio result envelope.
+     *
+     * @throws {Error} If any step of the flow fails.
+     * @internal
+     */
+    private _generate;
+    /**
+     * Submit a generation task to the Fal.ai queue.
+     *
+     * @param model - Full model path (e.g. 'fal-ai/stable-audio').
+     * @param body - Request body with prompt and generation params.
+     * @returns The request_id for status polling.
+     *
+     * @throws {Error} If the submission request fails.
+     * @internal
+     */
+    private _submitTask;
+    /**
+     * Poll the Fal.ai status endpoint until the task completes or times out.
+     *
+     * @param model - Full model path.
+     * @param requestId - The request ID from submission.
+     *
+     * @throws {Error} If the generation fails or times out.
+     * @internal
+     */
+    private _pollStatus;
+    /**
+     * Fetch the completed generation result from the Fal.ai result endpoint.
+     *
+     * Called after polling confirms the task is COMPLETED.
+     *
+     * @param model - Full model path.
+     * @param requestId - The request ID from submission.
+     * @returns The generation result with audio URL.
+     *
+     * @throws {Error} If the result fetch fails.
+     * @internal
+     */
+    private _fetchResult;
+    /**
+     * Build an {@link AudioResult} from a completed Fal.ai result.
+     *
+     * @param result - The Fal.ai result response.
+     * @param model - Model ID used for the generation.
+     * @returns Normalized audio result envelope.
+     *
+     * @throws {Error} If the result has no audio URL.
+     * @internal
+     */
+    private _buildResult;
+}
+//# sourceMappingURL=FalAudioProvider.d.ts.map

package/dist/core/audio/providers/FalAudioProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FalAudioProvider.d.ts","sourceRoot":"","sources":["../../../../src/core/audio/providers/FalAudioProvider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,KAAK,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAMzF;;;;;;;;;;GAUG;AACH,MAAM,WAAW,sBAAsB;IACrC;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AA4DD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,qBAAa,gBAAiB,YAAW,eAAe;IACtD,kBAAkB;IAClB,SAAgB,UAAU,eAAe;IAEzC,kBAAkB;IACX,aAAa,UAAS;IAE7B,kBAAkB;IACX,cAAc,CAAC,EAAE,MAAM,CAAC;IAE/B,uCAAuC;IACvC,OAAO,CAAC,OAAO,CAA0H;IAMzI;;;;;OAKG;IACG,UAAU,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAkChE;;;;;;;;;;OAUG;IACG,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,WAAW,CAAC;IAQxE;;;;;;;;;;OAUG;IACG,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,WAAW,CAAC;IAYpE;;;;;OAKG;IACH,QAAQ,CAAC,UAAU,EAAE,OAAO,GAAG,KAAK,GAAG,OAAO;IAI9C;;OAEG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAQ/B;;;;;;;;;;OAUG;YACW,SAAS;IAqBvB;;;;;;;;;OASG;YACW,WAAW;IAyBzB;;;;;;;;OAQG;YACW,WAAW;IAoCzB;;;;;;;;;;;OAWG;YACW,YAAY;IAiB1B;;;;;;;;;OASG;IACH,OAAO,CAAC,YAAY;CAsBrB"}

package/dist/core/audio/providers/FalAudioProvider.js

@@ -0,0 +1,315 @@
+/**
+ * @module core/audio/providers/FalAudioProvider
+ *
+ * Audio generation provider for the Fal.ai serverless GPU platform.
+ *
+ * Fal.ai hosts audio generation models (Stable Audio, etc.) behind a
+ * queue-based API. This provider implements the three-step pattern
+ * established by {@link FalVideoProvider}: submit to queue, poll for status,
+ * then fetch the completed result.
+ *
+ * ## Supported models
+ *
+ * | Model ID               | Description                          |
+ * |------------------------|--------------------------------------|
+ * | `fal-ai/stable-audio`  | Stable Audio on Fal.ai — default     |
+ *
+ * ## API flow (three-step queue)
+ *
+ * 1. **Submit** — `POST ${baseURL}/${model}` with prompt/params.
+ *    Returns `{ request_id }` immediately.
+ * 2. **Poll** — `GET ${baseURL}/${model}/requests/${request_id}/status`
+ *    until `status === 'COMPLETED'` or `'FAILED'`.
+ * 3. **Fetch** — `GET ${baseURL}/${model}/requests/${request_id}`
+ *    returns `{ audio: { url } }`.
+ *
+ * ## Authentication
+ *
+ * Requires a `FAL_API_KEY`. Sent as `Authorization: Key ${apiKey}`.
+ *
+ * @see {@link IAudioGenerator} for the provider interface contract.
+ * @see {@link FalVideoProvider} for the video counterpart.
+ * @see {@link FalImageProvider} for the image counterpart.
+ */
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Sleep for the specified number of milliseconds.
+ * Used between poll requests to avoid rate-limiting.
+ * @param ms - Duration in milliseconds.
+ * @internal
+ */
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+// ---------------------------------------------------------------------------
+// Implementation
+// ---------------------------------------------------------------------------
+/**
+ * Audio generation provider connecting to the Fal.ai serverless platform.
+ *
+ * Implements the three-step queue pattern: submit a generation task,
+ * poll the status endpoint until completion, then fetch the result.
+ * This mirrors the flow used by {@link FalVideoProvider}.
+ *
+ * Supports both music and SFX generation through the same endpoint.
+ *
+ * @implements {IAudioGenerator}
+ *
+ * @example
+ * ```typescript
+ * const provider = new FalAudioProvider();
+ * await provider.initialize({ apiKey: process.env.FAL_API_KEY! });
+ *
+ * const result = await provider.generateMusic({
+ *   modelId: 'fal-ai/stable-audio',
+ *   prompt: 'A dreamy ambient track with reverb-heavy synths',
+ *   durationSec: 30,
+ * });
+ * console.log(result.audio[0].url);
+ * ```
+ */
+export class FalAudioProvider {
+    constructor() {
+        /** @inheritdoc */
+        this.providerId = 'fal-audio';
+        /** @inheritdoc */
+        this.isInitialized = false;
+    }
+    // -------------------------------------------------------------------------
+    // Lifecycle
+    // -------------------------------------------------------------------------
+    /**
+     * Initialize the provider with API credentials and optional configuration.
+     *
+     * @param config - Configuration object. Must include `apiKey`.
+     * @throws {Error} If `apiKey` is missing or empty.
+     */
+    async initialize(config) {
+        const apiKey = typeof config.apiKey === 'string' ? config.apiKey.trim() : '';
+        if (!apiKey) {
+            throw new Error('Fal.ai audio provider requires apiKey (FAL_API_KEY).');
+        }
+        this._config = {
+            apiKey,
+            baseURL: typeof config.baseURL === 'string' && config.baseURL.trim()
+                ? config.baseURL.trim()
+                : 'https://queue.fal.run',
+            defaultModelId: typeof config.defaultModelId === 'string' && config.defaultModelId.trim()
+                ? config.defaultModelId.trim()
+                : 'fal-ai/stable-audio',
+            pollIntervalMs: typeof config.pollIntervalMs === 'number' && config.pollIntervalMs > 0
+                ? config.pollIntervalMs
+                : 2000,
+            timeoutMs: typeof config.timeoutMs === 'number' && config.timeoutMs > 0
+                ? config.timeoutMs
+                : 300000,
+        };
+        this.defaultModelId = this._config.defaultModelId;
+        this.isInitialized = true;
+    }
+    // -------------------------------------------------------------------------
+    // Generation
+    // -------------------------------------------------------------------------
+    /**
+     * Generate music from a text prompt using the Fal.ai queue API.
+     *
+     * Submits the task, polls until complete, then fetches the result.
+     *
+     * @param request - Music generation request with prompt and optional params.
+     * @returns The generated audio result envelope.
+     *
+     * @throws {Error} If the provider is not initialized.
+     * @throws {Error} If the API returns an error or times out.
+     */
+    async generateMusic(request) {
+        if (!this.isInitialized) {
+            throw new Error('Fal.ai audio provider is not initialized. Call initialize() first.');
+        }
+        return this._generate(request.prompt, request.durationSec, request.modelId);
+    }
+    /**
+     * Generate a sound effect from a text prompt using the Fal.ai queue API.
+     *
+     * Submits the task, polls until complete, then fetches the result.
+     *
+     * @param request - SFX generation request with prompt and optional params.
+     * @returns The generated audio result envelope.
+     *
+     * @throws {Error} If the provider is not initialized.
+     * @throws {Error} If the API returns an error or times out.
+     */
+    async generateSFX(request) {
+        if (!this.isInitialized) {
+            throw new Error('Fal.ai audio provider is not initialized. Call initialize() first.');
+        }
+        return this._generate(request.prompt, request.durationSec, request.modelId);
+    }
+    // -------------------------------------------------------------------------
+    // Capability query
+    // -------------------------------------------------------------------------
+    /**
+     * Fal.ai audio supports both music and SFX generation.
+     *
+     * @param capability - The capability to check.
+     * @returns `true` for both `'music'` and `'sfx'`.
+     */
+    supports(capability) {
+        return capability === 'music' || capability === 'sfx';
+    }
+    /**
+     * Release any resources held by the provider. No-op for HTTP-only providers.
+     */
+    async shutdown() {
+        this.isInitialized = false;
+    }
+    // -------------------------------------------------------------------------
+    // Private helpers
+    // -------------------------------------------------------------------------
+    /**
+     * Run the full three-step generation flow: submit, poll, fetch.
+     *
+     * @param prompt - Text description of the desired audio.
+     * @param durationSec - Desired duration in seconds.
+     * @param modelId - Optional model override.
+     * @returns Normalized audio result envelope.
+     *
+     * @throws {Error} If any step of the flow fails.
+     * @internal
+     */
+    async _generate(prompt, durationSec, modelId) {
+        const model = modelId || this.defaultModelId || 'fal-ai/stable-audio';
+        const body = {
+            prompt,
+        };
+        if (durationSec !== undefined)
+            body.duration = durationSec;
+        // Three-step flow: submit -> poll -> fetch
+        const requestId = await this._submitTask(model, body);
+        await this._pollStatus(model, requestId);
+        const result = await this._fetchResult(model, requestId);
+        return this._buildResult(result, model);
+    }
+    /**
+     * Submit a generation task to the Fal.ai queue.
+     *
+     * @param model - Full model path (e.g. 'fal-ai/stable-audio').
+     * @param body - Request body with prompt and generation params.
+     * @returns The request_id for status polling.
+     *
+     * @throws {Error} If the submission request fails.
+     * @internal
+     */
+    async _submitTask(model, body) {
+        const url = `${this._config.baseURL}/${model}`;
+        const response = await fetch(url, {
+            method: 'POST',
+            headers: {
+                Authorization: `Key ${this._config.apiKey}`,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify(body),
+        });
+        if (!response.ok) {
+            const errorText = await response.text();
+            throw new Error(`Fal.ai audio generation submission failed (${response.status}): ${errorText}`);
+        }
+        const data = (await response.json());
+        if (!data.request_id) {
+            throw new Error('Fal.ai audio submission response missing request_id.');
+        }
+        return data.request_id;
+    }
+    /**
+     * Poll the Fal.ai status endpoint until the task completes or times out.
+     *
+     * @param model - Full model path.
+     * @param requestId - The request ID from submission.
+     *
+     * @throws {Error} If the generation fails or times out.
+     * @internal
+     */
+    async _pollStatus(model, requestId) {
+        const startedAt = Date.now();
+        while (Date.now() - startedAt < this._config.timeoutMs) {
+            const url = `${this._config.baseURL}/${model}/requests/${requestId}/status`;
+            const response = await fetch(url, {
+                headers: {
+                    Authorization: `Key ${this._config.apiKey}`,
+                },
+            });
+            if (!response.ok) {
+                const errorText = await response.text();
+                throw new Error(`Fal.ai audio status polling failed (${response.status}): ${errorText}`);
+            }
+            const data = (await response.json());
+            if (data.status === 'COMPLETED') {
+                return;
+            }
+            if (data.status === 'FAILED') {
+                throw new Error(`Fal.ai audio generation failed for request ${requestId}.`);
+            }
+            // 'IN_QUEUE' or 'IN_PROGRESS' — wait before next poll
+            await sleep(this._config.pollIntervalMs);
+        }
+        throw new Error(`Fal.ai audio generation timed out after ${this._config.timeoutMs}ms for request ${requestId}.`);
+    }
+    /**
+     * Fetch the completed generation result from the Fal.ai result endpoint.
+     *
+     * Called after polling confirms the task is COMPLETED.
+     *
+     * @param model - Full model path.
+     * @param requestId - The request ID from submission.
+     * @returns The generation result with audio URL.
+     *
+     * @throws {Error} If the result fetch fails.
+     * @internal
+     */
+    async _fetchResult(model, requestId) {
+        const url = `${this._config.baseURL}/${model}/requests/${requestId}`;
+        const response = await fetch(url, {
+            headers: {
+                Authorization: `Key ${this._config.apiKey}`,
+            },
+        });
+        if (!response.ok) {
+            const errorText = await response.text();
+            throw new Error(`Fal.ai audio result fetch failed (${response.status}): ${errorText}`);
+        }
+        return (await response.json());
+    }
+    /**
+     * Build an {@link AudioResult} from a completed Fal.ai result.
+     *
+     * @param result - The Fal.ai result response.
+     * @param model - Model ID used for the generation.
+     * @returns Normalized audio result envelope.
+     *
+     * @throws {Error} If the result has no audio URL.
+     * @internal
+     */
+    _buildResult(result, model) {
+        if (!result.audio?.url) {
+            throw new Error('Fal.ai audio generation completed but returned no audio output.');
+        }
+        return {
+            created: Math.floor(Date.now() / 1000),
+            modelId: model,
+            providerId: this.providerId,
+            audio: [{
+                    url: result.audio.url,
+                    mimeType: result.audio.content_type ?? 'audio/mpeg',
+                    durationSec: result.audio.duration,
+                    providerMetadata: {
+                        seed: result.seed,
+                    },
+                }],
+            usage: {
+                totalAudioClips: 1,
+            },
+        };
+    }
+}
+//# sourceMappingURL=FalAudioProvider.js.map

package/dist/core/audio/providers/FalAudioProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"FalAudioProvider.js","sourceRoot":"","sources":["../../../../src/core/audio/providers/FalAudioProvider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AA4FH,8EAA8E;AAC9E,UAAU;AACV,8EAA8E;AAE9E;;;;;GAKG;AACH,SAAS,KAAK,CAAC,EAAU;IACvB,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC;AAC3D,CAAC;AAED,8EAA8E;AAC9E,iBAAiB;AACjB,8EAA8E;AAE9E;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,OAAO,gBAAgB;IAA7B;QACE,kBAAkB;QACF,eAAU,GAAG,WAAW,CAAC;QAEzC,kBAAkB;QACX,kBAAa,GAAG,KAAK,CAAC;IAgS/B,CAAC;IAxRC,4EAA4E;IAC5E,YAAY;IACZ,4EAA4E;IAE5E;;;;;OAKG;IACH,KAAK,CAAC,UAAU,CAAC,MAA+B;QAC9C,MAAM,MAAM,GAAG,OAAO,MAAM,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC7E,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,IAAI,KAAK,CAAC,sDAAsD,CAAC,CAAC;QAC1E,CAAC;QAED,IAAI,CAAC,OAAO,GAAG;YACb,MAAM;YACN,OAAO,EACL,OAAO,MAAM,CAAC,OAAO,KAAK,QAAQ,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,EAAE;gBACzD,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,EAAE;gBACvB,CAAC,CAAC,uBAAuB;YAC7B,cAAc,EACZ,OAAO,MAAM,CAAC,cAAc,KAAK,QAAQ,IAAI,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE;gBACvE,CAAC,CAAC,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE;gBAC9B,CAAC,CAAC,qBAAqB;YAC3B,cAAc,EACZ,OAAO,MAAM,CAAC,cAAc,KAAK,QAAQ,IAAI,MAAM,CAAC,cAAc,GAAG,CAAC;gBACpE,CAAC,CAAC,MAAM,CAAC,cAAc;gBACvB,CAAC,CAAC,IAAI;YACV,SAAS,EACP,OAAO,MAAM,CAAC,SAAS,KAAK,QAAQ,IAAI,MAAM,CAAC,SAAS,GAAG,CAAC;gBAC1D,CAAC,CAAC,MAAM,CAAC,SAAS;gBAClB,CAAC,CAAC,MAAO;SACd,CAAC;QAEF,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC,OAAO,CAAC,cAAc,CAAC;QAClD,IAAI,CAAC,aAAa,GAAG,IAAI,CAAC;IAC5B,CAAC;IAED,4EAA4E;IAC5E,aAAa;IACb,4EAA4E;IAE5E;;;;;;;;;;OAUG;IACH,KAAK,CAAC,aAAa,CAAC,OAA6B;QAC/C,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,CAAC;YACxB,MAAM,IAAI,KAAK,CAAC,oEAAoE,CAAC,CAAC;QACxF,CAAC;QAED,OAAO,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,WAAW,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;IAC9E,CAAC;IAED;;;;;;;;;;OAUG;IACH,KAAK,CAAC,WAAW,CAAC,OAA2B;QAC3C,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,CAAC;YACxB,MAAM,IAAI,KAAK,CAAC,oEAAoE,CAAC,CAAC;QACxF,CAAC;QAED,OAAO,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,WAAW,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;IAC9E,CAAC;IAED,4EAA4E;IAC5E,mBAAmB;IACnB,4EAA4E;IAE5E;;;;;OAKG;IACH,QAAQ,CAAC,UAA2B;QAClC,OAAO,UAAU,KAAK,OAAO,IAAI,UAAU,KAAK,KAAK,CAAC;IACxD,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,QAAQ;QACZ,IAAI,CAAC,aAAa,GAAG,KAAK,CAAC;IAC7B,CAAC;IAED,4EAA4E;IAC5E,kBAAkB;IAClB,4EAA4E;IAE5E;;;;;;;;;;OAUG;IACK,KAAK,CAAC,SAAS,CACrB,MAAc,EACd,WAAoB,EACpB,OAAgB;QAEhB,MAAM,KAAK,GAAG,OAAO,IAAI,IAAI,CAAC,cAAc,IAAI,qBAAqB,CAAC;QAEtE,MAAM,IAAI,GAA4B;YACpC,MAAM;SACP,CAAC;QAEF,IAAI,WAAW,KAAK,SAAS;YAAE,IAAI,CAAC,QAAQ,GAAG,WAAW,CAAC;QAE3D,2CAA2C;QAC3C,MAAM,SAAS,GAAG,MAAM,IAAI,CAAC,WAAW,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;QACtD,MAAM,IAAI,CAAC,WAAW,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC;QACzC,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,YAAY,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC;QAEzD,OAAO,IAAI,CAAC,YAAY,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IAC1C,CAAC;IAED;;;;;;;;;OASG;IACK,KAAK,CAAC,WAAW,CAAC,KAAa,EAAE,IAA6B;QACpE,MAAM,GAAG,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,IAAI,KAAK,EAAE,CAAC;QAE/C,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE;YAChC,MAAM,EAAE,MAAM;YACd,OAAO,EAAE;gBACP,aAAa,EAAE,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE;gBAC3C,cAAc,EAAE,kBAAkB;aACnC;YACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;SAC3B,CAAC,CAAC;QAEH,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;YACjB,MAAM,SAAS,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;YACxC,MAAM,IAAI,KAAK,CAAC,8CAA8C,QAAQ,CAAC,MAAM,MAAM,SAAS,EAAE,CAAC,CAAC;QAClG,CAAC;QAED,MAAM,IAAI,GAAG,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAsB,CAAC;QAC1D,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,CAAC;YACrB,MAAM,IAAI,KAAK,CAAC,sDAAsD,CAAC,CAAC;QAC1E,CAAC;QAED,OAAO,IAAI,CAAC,UAAU,CAAC;IACzB,CAAC;IAED;;;;;;;;OAQG;IACK,KAAK,CAAC,WAAW,CAAC,KAAa,EAAE,SAAiB;QACxD,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAE7B,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,CAAC;YACvD,MAAM,GAAG,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,IAAI,KAAK,aAAa,SAAS,SAAS,CAAC;YAE5E,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE;gBAChC,OAAO,EAAE;oBACP,aAAa,EAAE,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE;iBAC5C;aACF,CAAC,CAAC;YAEH,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;gBACjB,MAAM,SAAS,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;gBACxC,MAAM,IAAI,KAAK,CAAC,uCAAuC,QAAQ,CAAC,MAAM,MAAM,SAAS,EAAE,CAAC,CAAC;YAC3F,CAAC;YAED,MAAM,IAAI,GAAG,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAsB,CAAC;YAE1D,IAAI,IAAI,CAAC,MAAM,KAAK,WAAW,EAAE,CAAC;gBAChC,OAAO;YACT,CAAC;YAED,IAAI,IAAI,CAAC,MAAM,KAAK,QAAQ,EAAE,CAAC;gBAC7B,MAAM,IAAI,KAAK,CAAC,8CAA8C,SAAS,GAAG,CAAC,CAAC;YAC9E,CAAC;YAED,sDAAsD;YACtD,MAAM,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC;QAC3C,CAAC;QAED,MAAM,IAAI,KAAK,CACb,2CAA2C,IAAI,CAAC,OAAO,CAAC,SAAS,kBAAkB,SAAS,GAAG,CAChG,CAAC;IACJ,CAAC;IAED;;;;;;;;;;;OAWG;IACK,KAAK,CAAC,YAAY,CAAC,KAAa,EAAE,SAAiB;QACzD,MAAM,GAAG,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,IAAI,KAAK,aAAa,SAAS,EAAE,CAAC;QAErE,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE;YAChC,OAAO,EAAE;gBACP,aAAa,EAAE,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE;aAC5C;SACF,CAAC,CAAC;QAEH,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;YACjB,MAAM,SAAS,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;YACxC,MAAM,IAAI,KAAK,CAAC,qCAAqC,QAAQ,CAAC,MAAM,MAAM,SAAS,EAAE,CAAC,CAAC;QACzF,CAAC;QAED,OAAO,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAA2B,CAAC;IAC3D,CAAC;IAED;;;;;;;;;OASG;IACK,YAAY,CAAC,MAA8B,EAAE,KAAa;QAChE,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,GAAG,EAAE,CAAC;YACvB,MAAM,IAAI,KAAK,CAAC,iEAAiE,CAAC,CAAC;QACrF,CAAC;QAED,OAAO;YACL,OAAO,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC;YACtC,OAAO,EAAE,KAAK;YACd,UAAU,EAAE,IAAI,CAAC,UAAU;YAC3B,KAAK,EAAE,CAAC;oBACN,GAAG,EAAE,MAAM,CAAC,KAAK,CAAC,GAAG;oBACrB,QAAQ,EAAE,MAAM,CAAC,KAAK,CAAC,YAAY,IAAI,YAAY;oBACnD,WAAW,EAAE,MAAM,CAAC,KAAK,CAAC,QAAQ;oBAClC,gBAAgB,EAAE;wBAChB,IAAI,EAAE,MAAM,CAAC,IAAI;qBAClB;iBACF,CAAC;YACF,KAAK,EAAE;gBACL,eAAe,EAAE,CAAC;aACnB;SACF,CAAC;IACJ,CAAC;CACF"}

package/dist/core/audio/providers/MusicGenLocalProvider.d.ts

@@ -0,0 +1,136 @@
+/**
+ * @module core/audio/providers/MusicGenLocalProvider
+ *
+ * Local music generation provider using Meta's MusicGen model via
+ * the `@huggingface/transformers` library.
+ *
+ * MusicGen runs entirely on the local machine without any API keys or
+ * network requests. The model is loaded lazily on first use through the
+ * `pipeline('text-to-audio', ...)` API from HuggingFace Transformers.js.
+ *
+ * ## Requirements
+ *
+ * - `@huggingface/transformers` must be installed as a peer dependency.
+ *   If not installed, the provider throws a helpful error message.
+ * - Sufficient RAM/VRAM for model inference (Xenova/musicgen-small ~1GB).
+ *
+ * ## Supported models
+ *
+ * | Model ID                   | Description                       |
+ * |----------------------------|-----------------------------------|
+ * | `Xenova/musicgen-small`    | MusicGen Small — default, ~1GB    |
+ *
+ * ## API flow (local inference)
+ *
+ * 1. **Load** — `pipeline('text-to-audio', modelId)` (lazy, cached).
+ * 2. **Generate** — `pipeline(prompt, { max_new_tokens })` returns audio tensor.
+ * 3. **Encode** — Convert raw audio data to WAV format.
+ *
+ * @see {@link IAudioGenerator} for the provider interface contract.
+ * @see {@link AudioGenLocalProvider} for the SFX counterpart.
+ */
+import type { IAudioGenerator } from '../IAudioGenerator.js';
+import type { MusicGenerateRequest, SFXGenerateRequest, AudioResult } from '../types.js';
+/**
+ * Configuration for the MusicGen local provider.
+ *
+ * @example
+ * ```typescript
+ * const config: MusicGenLocalProviderConfig = {
+ *   modelId: 'Xenova/musicgen-small',
+ * };
+ * ```
+ */
+export interface MusicGenLocalProviderConfig {
+    /**
+     * HuggingFace model ID for the MusicGen model.
+     * @default 'Xenova/musicgen-small'
+     */
+    modelId?: string;
+}
+/**
+ * Local music generation provider using Meta's MusicGen model.
+ *
+ * Runs inference entirely on the local machine via `@huggingface/transformers`.
+ * The model is loaded lazily on first call to `generateMusic()` or
+ * explicitly via `initialize()`.
+ *
+ * @implements {IAudioGenerator}
+ *
+ * @example
+ * ```typescript
+ * const provider = new MusicGenLocalProvider();
+ * await provider.initialize({ modelId: 'Xenova/musicgen-small' });
+ *
+ * const result = await provider.generateMusic({
+ *   prompt: 'A calm ambient soundscape with synth pads',
+ *   durationSec: 10,
+ * });
+ * console.log(result.audio[0].base64?.substring(0, 50) + '...');
+ * ```
+ */
+export declare class MusicGenLocalProvider implements IAudioGenerator {
+    /** @inheritdoc */
+    readonly providerId = "musicgen-local";
+    /** @inheritdoc */
+    isInitialized: boolean;
+    /** @inheritdoc */
+    defaultModelId?: string;
+    /** The loaded text-to-audio pipeline instance. */
+    private _pipeline;
+    /** The resolved model ID. */
+    private _modelId;
+    /**
+     * Initialize the provider and optionally pre-load the model.
+     *
+     * The model is loaded lazily on first generation call. Calling initialize
+     * sets the configuration but does not load the model unless the pipeline
+     * was already created.
+     *
+     * @param config - Configuration object with optional `modelId`.
+     */
+    initialize(config: Record<string, unknown>): Promise<void>;
+    /**
+     * Generate music from a text prompt using the local MusicGen model.
+     *
+     * On first call, loads the model pipeline (may take several seconds).
+     * Subsequent calls reuse the cached pipeline instance.
+     *
+     * @param request - Music generation request with prompt and optional params.
+     * @returns The generated audio result envelope with base64-encoded WAV data.
+     *
+     * @throws {Error} If the provider is not initialized.
+     * @throws {Error} If `@huggingface/transformers` is not installed.
+     */
+    generateMusic(request: MusicGenerateRequest): Promise<AudioResult>;
+    /**
+     * SFX generation is not supported by MusicGen.
+     *
+     * @throws {Error} Always throws — use {@link AudioGenLocalProvider} instead.
+     */
+    generateSFX(_request: SFXGenerateRequest): Promise<AudioResult>;
+    /**
+     * MusicGen supports music generation only.
+     *
+     * @param capability - The capability to check.
+     * @returns `true` only for `'music'`; `false` for `'sfx'`.
+     */
+    supports(capability: 'music' | 'sfx'): boolean;
+    /**
+     * Release model resources and reset initialization state.
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Ensure the text-to-audio pipeline is loaded, creating it lazily if needed.
+     *
+     * Uses dynamic `import()` to load `@huggingface/transformers` as an optional
+     * peer dependency. Throws a helpful error if the package is not installed.
+     *
+     * @returns The loaded pipeline callable.
+     *
+     * @throws {Error} If `@huggingface/transformers` is not installed.
+     * @internal
+     */
+    private _ensurePipeline;
+}
+//# sourceMappingURL=MusicGenLocalProvider.d.ts.map

package/dist/core/audio/providers/MusicGenLocalProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MusicGenLocalProvider.d.ts","sourceRoot":"","sources":["../../../../src/core/audio/providers/MusicGenLocalProvider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,KAAK,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAMzF;;;;;;;;;GASG;AACH,MAAM,WAAW,2BAA2B;IAC1C;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AA4DD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,qBAAsB,YAAW,eAAe;IAC3D,kBAAkB;IAClB,SAAgB,UAAU,oBAAoB;IAE9C,kBAAkB;IACX,aAAa,UAAS;IAE7B,kBAAkB;IACX,cAAc,CAAC,EAAE,MAAM,CAAC;IAE/B,kDAAkD;IAClD,OAAO,CAAC,SAAS,CAAiB;IAElC,6BAA6B;IAC7B,OAAO,CAAC,QAAQ,CAA2B;IAM3C;;;;;;;;OAQG;IACG,UAAU,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAahE;;;;;;;;;;;OAWG;IACG,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,WAAW,CAAC;IAsCxE;;;;OAIG;IACG,WAAW,CAAC,QAAQ,EAAE,kBAAkB,GAAG,OAAO,CAAC,WAAW,CAAC;IAUrE;;;;;OAKG;IACH,QAAQ,CAAC,UAAU,EAAE,OAAO,GAAG,KAAK,GAAG,OAAO;IAI9C;;OAEG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAS/B;;;;;;;;;;OAUG;YACW,eAAe;CAgB9B"}