@framers/agentos 0.1.119 → 0.1.121

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

@@ -0,0 +1,305 @@
+/**
+ * @module core/audio/providers/UdioProvider
+ *
+ * Music generation provider for the Udio model via Replicate.
+ *
+ * Udio is hosted on Replicate and accessed through the predictions API
+ * using the submit-then-poll pattern. This provider is music-only; it
+ * does not support sound effect generation.
+ *
+ * ## API flow (Replicate submit-poll)
+ *
+ * 1. **Create prediction** — `POST ${baseURL}/predictions` with
+ *    `Prefer: wait=60`. If the model finishes within 60 seconds the
+ *    response already contains the output.
+ * 2. **Poll** (if needed) — `GET prediction.urls.get` until `status` is
+ *    `succeeded`, `failed`, or `canceled`.
+ * 3. **Result** — `output` is the audio URL (string or first array element).
+ *
+ * ## Authentication
+ *
+ * Requires a `REPLICATE_API_TOKEN`. Sent as `Authorization: Token ${apiKey}`.
+ *
+ * @see {@link IAudioGenerator} for the provider interface contract.
+ * @see {@link SunoProvider} for a similar Replicate-hosted music provider.
+ */
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Sleep for the specified number of milliseconds.
+ * @param ms - Duration in milliseconds.
+ * @internal
+ */
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Extract an audio URL from the Replicate prediction output.
+ *
+ * @param output - Raw output from the prediction.
+ * @returns The audio URL string, or `undefined` if not found.
+ * @internal
+ */
+function extractAudioUrl(output) {
+    if (typeof output === 'string')
+        return output;
+    if (Array.isArray(output)) {
+        for (const item of output) {
+            if (typeof item === 'string')
+                return item;
+        }
+        return undefined;
+    }
+    if (output && typeof output === 'object') {
+        const obj = output;
+        if (typeof obj.url === 'string')
+            return obj.url;
+        if (typeof obj.audio === 'string')
+            return obj.audio;
+    }
+    return undefined;
+}
+// ---------------------------------------------------------------------------
+// Implementation
+// ---------------------------------------------------------------------------
+/**
+ * Music generation provider connecting to the Udio model on Replicate.
+ *
+ * Follows the Replicate submit-then-poll pattern: create a prediction with
+ * `Prefer: wait=60`, then poll if the model takes longer than the wait window.
+ *
+ * @implements {IAudioGenerator}
+ *
+ * @example
+ * ```typescript
+ * const provider = new UdioProvider();
+ * await provider.initialize({ apiKey: process.env.REPLICATE_API_TOKEN! });
+ *
+ * const result = await provider.generateMusic({
+ *   prompt: 'Epic orchestral film score with dramatic strings',
+ *   durationSec: 120,
+ * });
+ * console.log(result.audio[0].url);
+ * ```
+ */
+export class UdioProvider {
+    constructor() {
+        /** @inheritdoc */
+        this.providerId = 'udio';
+        /** @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('Udio provider requires apiKey (REPLICATE_API_TOKEN).');
+        }
+        this._config = {
+            apiKey,
+            baseURL: typeof config.baseURL === 'string' && config.baseURL.trim()
+                ? config.baseURL.trim()
+                : 'https://api.replicate.com/v1',
+            defaultModelId: typeof config.defaultModelId === 'string' && config.defaultModelId.trim()
+                ? config.defaultModelId.trim()
+                : 'udio/udio',
+            pollIntervalMs: typeof config.pollIntervalMs === 'number' && config.pollIntervalMs > 0
+                ? config.pollIntervalMs
+                : 5000,
+            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 Udio model on Replicate.
+     *
+     * Creates a prediction, waits for synchronous completion (up to 60s), then
+     * polls if still in progress.
+     *
+     * @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('Udio provider is not initialized. Call initialize() first.');
+        }
+        const model = request.modelId || this.defaultModelId || 'udio/udio';
+        const input = {
+            prompt: request.prompt,
+        };
+        if (request.durationSec !== undefined)
+            input.duration = request.durationSec;
+        const prediction = await this._runPrediction(model, input);
+        return this._buildResult(prediction, model);
+    }
+    /**
+     * SFX generation is not supported by the Udio model.
+     *
+     * @throws {Error} Always throws — use an SFX-capable provider instead.
+     */
+    async generateSFX(_request) {
+        throw new Error('Udio provider does not support SFX generation. Use an SFX-capable provider.');
+    }
+    // -------------------------------------------------------------------------
+    // Capability query
+    // -------------------------------------------------------------------------
+    /**
+     * Udio supports music generation only.
+     *
+     * @param capability - The capability to check.
+     * @returns `true` only for `'music'`; `false` for `'sfx'`.
+     */
+    supports(capability) {
+        return capability === 'music';
+    }
+    /**
+     * Release any resources held by the provider. No-op for HTTP-only providers.
+     */
+    async shutdown() {
+        this.isInitialized = false;
+    }
+    // -------------------------------------------------------------------------
+    // Private helpers
+    // -------------------------------------------------------------------------
+    /**
+     * Create a prediction and wait for it to complete.
+     *
+     * Uses `Prefer: wait=60` to get synchronous completion for fast models.
+     * Falls back to polling if the prediction hasn't completed within the
+     * wait window.
+     *
+     * @param model - Model identifier (e.g. 'udio/udio').
+     * @param input - Model input parameters.
+     * @returns The completed prediction object.
+     *
+     * @throws {Error} If prediction creation fails, the prediction fails,
+     *   is canceled, or times out.
+     * @internal
+     */
+    async _runPrediction(model, input) {
+        let prediction = await this._createPrediction(model, input);
+        // If the prediction hasn't reached a terminal state, poll for it.
+        if (prediction.status
+            && !['succeeded', 'failed', 'canceled'].includes(prediction.status)
+            && prediction.urls?.get) {
+            prediction = await this._pollPrediction(prediction.urls.get);
+        }
+        if (prediction.status === 'failed') {
+            throw new Error(`Udio music generation failed: ${prediction.error ?? 'unknown error'}`);
+        }
+        if (prediction.status === 'canceled') {
+            throw new Error('Udio music generation was canceled.');
+        }
+        return prediction;
+    }
+    /**
+     * Create a new prediction via `POST /predictions`.
+     *
+     * @param model - Model identifier.
+     * @param input - Model input parameters.
+     * @returns The prediction response (may or may not be completed).
+     *
+     * @throws {Error} If the HTTP request fails.
+     * @internal
+     */
+    async _createPrediction(model, input) {
+        const body = {
+            model,
+            input,
+        };
+        const response = await fetch(`${this._config.baseURL}/predictions`, {
+            method: 'POST',
+            headers: {
+                Authorization: `Token ${this._config.apiKey}`,
+                'Content-Type': 'application/json',
+                Prefer: 'wait=60',
+            },
+            body: JSON.stringify(body),
+        });
+        if (!response.ok) {
+            const errorText = await response.text();
+            throw new Error(`Udio prediction submission failed (${response.status}): ${errorText}`);
+        }
+        return (await response.json());
+    }
+    /**
+     * Poll a prediction URL until it reaches a terminal state.
+     *
+     * @param url - The `prediction.urls.get` URL to poll.
+     * @returns The completed prediction object.
+     *
+     * @throws {Error} If polling fails or times out.
+     * @internal
+     */
+    async _pollPrediction(url) {
+        const startedAt = Date.now();
+        while (Date.now() - startedAt < this._config.timeoutMs) {
+            const response = await fetch(url, {
+                headers: {
+                    Authorization: `Token ${this._config.apiKey}`,
+                },
+            });
+            if (!response.ok) {
+                const errorText = await response.text();
+                throw new Error(`Udio prediction polling failed (${response.status}): ${errorText}`);
+            }
+            const prediction = (await response.json());
+            if (!prediction.status
+                || ['succeeded', 'failed', 'canceled'].includes(prediction.status)) {
+                return prediction;
+            }
+            await sleep(this._config.pollIntervalMs);
+        }
+        throw new Error(`Udio music generation timed out after ${this._config.timeoutMs}ms.`);
+    }
+    /**
+     * Build an {@link AudioResult} from a completed Replicate prediction.
+     *
+     * @param prediction - The succeeded prediction object.
+     * @param model - Model ID used for the generation.
+     * @returns Normalized audio result envelope.
+     *
+     * @throws {Error} If no audio URL could be extracted from the output.
+     * @internal
+     */
+    _buildResult(prediction, model) {
+        const audioUrl = extractAudioUrl(prediction.output);
+        if (!audioUrl) {
+            throw new Error('Udio prediction succeeded but returned no audio output.');
+        }
+        return {
+            created: Math.floor(Date.now() / 1000),
+            modelId: model,
+            providerId: this.providerId,
+            audio: [{
+                    url: audioUrl,
+                    mimeType: 'audio/mpeg',
+                    providerMetadata: {
+                        predictionId: prediction.id,
+                    },
+                }],
+            usage: {
+                totalAudioClips: 1,
+            },
+        };
+    }
+}
+//# sourceMappingURL=UdioProvider.js.map

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

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

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

@@ -0,0 +1,257 @@
+/**
+ * @file types.ts
+ * Core type definitions for the audio generation subsystem.
+ *
+ * These types are consumed by {@link IAudioGenerator}, {@link FallbackAudioProxy},
+ * and concrete provider implementations (Suno, Udio, Stable Audio,
+ * ElevenLabs SFX, etc.) to provide a unified audio pipeline across multiple
+ * provider backends.
+ *
+ * Audio generation is split into two sub-modalities:
+ *
+ * - **Music** — full-length musical compositions from text prompts (Suno, Udio,
+ *   Stable Audio).
+ * - **SFX** — short sound effects from text descriptions (ElevenLabs, Stable
+ *   Audio).
+ *
+ * Not all providers support both; capability negotiation is handled via
+ * {@link IAudioGenerator.supports}.
+ */
+/** Well-known audio provider identifiers. Extensible via `(string & {})`. */
+export type AudioProviderId = 'suno' | 'udio' | 'stable-audio' | 'elevenlabs-sfx' | 'replicate-audio' | 'fal-audio' | 'musicgen-local' | 'audiogen-local' | (string & {});
+/** Output audio container/codec format. */
+export type AudioOutputFormat = 'mp3' | 'wav' | 'flac' | 'ogg' | 'aac';
+/**
+ * Aggregated usage / billing counters for an audio generation session.
+ *
+ * Providers that report cost or timing information populate the optional
+ * fields; the minimum required field is {@link totalAudioClips}.
+ */
+export interface AudioProviderUsage {
+    /** Number of audio clips generated in this session. */
+    totalAudioClips: number;
+    /** Total cost in USD, if the provider reports it. */
+    totalCostUSD?: number;
+    /** Total processing time in milliseconds. */
+    processingTimeMs?: number;
+}
+/**
+ * Request payload for music generation from a text prompt.
+ *
+ * Passed to {@link IAudioGenerator.generateMusic} by the high-level
+ * orchestration layer after normalising user input.
+ *
+ * @example
+ * ```typescript
+ * const request: MusicGenerateRequest = {
+ *   prompt: 'Upbeat lo-fi hip hop beat with vinyl crackle and mellow piano',
+ *   durationSec: 60,
+ *   outputFormat: 'mp3',
+ * };
+ * ```
+ */
+export interface MusicGenerateRequest {
+    /**
+     * Text prompt describing the desired musical composition.
+     *
+     * Quality and specificity of the prompt directly influence output quality.
+     * Include genre, mood, instrumentation, and tempo for best results.
+     */
+    prompt: string;
+    /**
+     * Model identifier to use for generation.
+     *
+     * When omitted the provider falls back to its {@link IAudioGenerator.defaultModelId}.
+     */
+    modelId?: string;
+    /**
+     * Desired output duration in seconds.
+     *
+     * Provider limits vary: Suno caps at ~240s, Stable Audio at ~47s.
+     * Exceeding the limit may result in truncation or an error.
+     */
+    durationSec?: number;
+    /**
+     * Negative prompt describing musical elements to avoid.
+     *
+     * Not all providers support negative prompts — unsupported values are
+     * silently ignored by the adapter.
+     */
+    negativePrompt?: string;
+    /**
+     * Output audio format.
+     *
+     * @default 'mp3'
+     */
+    outputFormat?: AudioOutputFormat;
+    /**
+     * Seed for reproducible output.
+     *
+     * Not all providers honour seeds — check provider documentation.
+     */
+    seed?: number;
+    /**
+     * Number of audio clips to generate.
+     *
+     * @default 1
+     */
+    n?: number;
+    /** Identifier of the requesting user (for billing / rate limiting). */
+    userId?: string;
+    /** Arbitrary provider-specific options. */
+    providerOptions?: Record<string, unknown>;
+}
+/**
+ * Request payload for sound-effect generation from a text prompt.
+ *
+ * Passed to {@link IAudioGenerator.generateSFX} by the high-level
+ * orchestration layer after normalising user input.
+ *
+ * @example
+ * ```typescript
+ * const request: SFXGenerateRequest = {
+ *   prompt: 'Thunder crack followed by heavy rain on a tin roof',
+ *   durationSec: 5,
+ * };
+ * ```
+ */
+export interface SFXGenerateRequest {
+    /**
+     * Text prompt describing the desired sound effect.
+     *
+     * Be specific about the sound, its environment, and any layering
+     * (e.g. "glass breaking on a marble floor in a large hall with reverb").
+     */
+    prompt: string;
+    /**
+     * Model identifier to use for generation.
+     *
+     * When omitted the provider falls back to its {@link IAudioGenerator.defaultModelId}.
+     */
+    modelId?: string;
+    /**
+     * Desired output duration in seconds.
+     *
+     * SFX clips are typically short (1-15 seconds). Providers may enforce
+     * their own limits.
+     */
+    durationSec?: number;
+    /**
+     * Output audio format.
+     *
+     * @default 'mp3'
+     */
+    outputFormat?: AudioOutputFormat;
+    /**
+     * Seed for reproducible output.
+     *
+     * Not all providers honour seeds — check provider documentation.
+     */
+    seed?: number;
+    /**
+     * Number of audio clips to generate.
+     *
+     * @default 1
+     */
+    n?: number;
+    /** Identifier of the requesting user (for billing / rate limiting). */
+    userId?: string;
+    /** Arbitrary provider-specific options. */
+    providerOptions?: Record<string, unknown>;
+}
+/**
+ * A single generated audio artifact.
+ *
+ * At least one of {@link url} or {@link base64} will be populated depending
+ * on the provider's response format.
+ */
+export interface GeneratedAudio {
+    /** Public URL where the audio can be downloaded. */
+    url?: string;
+    /** Base64-encoded audio data. */
+    base64?: string;
+    /** MIME type of the audio (e.g. `'audio/mpeg'`, `'audio/wav'`). */
+    mimeType?: string;
+    /** Duration of the generated audio in seconds. */
+    durationSec?: number;
+    /** Sample rate in Hz (e.g. `44100`, `48000`). */
+    sampleRate?: number;
+    /** Provider-specific metadata (job ID, generation params, etc.). */
+    providerMetadata?: Record<string, unknown>;
+}
+/**
+ * Result envelope returned by {@link IAudioGenerator.generateMusic} and
+ * {@link IAudioGenerator.generateSFX}.
+ *
+ * Follows the same envelope pattern used by {@link VideoResult} in the video
+ * subsystem: a timestamp, model/provider IDs, the generated artifact(s), and
+ * optional usage/billing information.
+ *
+ * @example
+ * ```typescript
+ * const result: AudioResult = {
+ *   created: Math.floor(Date.now() / 1000),
+ *   modelId: 'suno-v3.5',
+ *   providerId: 'suno',
+ *   audio: [{ url: 'https://cdn.suno.ai/abc123.mp3', mimeType: 'audio/mpeg' }],
+ *   usage: { totalAudioClips: 1 },
+ * };
+ * ```
+ */
+export interface AudioResult {
+    /** Unix timestamp (seconds) when the result was created. */
+    created: number;
+    /** Model identifier that produced the result. */
+    modelId: string;
+    /** Provider identifier that produced the result. */
+    providerId: string;
+    /** The generated audio clip(s). */
+    audio: GeneratedAudio[];
+    /** Usage / billing information, if available. */
+    usage?: AudioProviderUsage;
+}
+/**
+ * Typed progress event emitted during audio generation.
+ *
+ * The generation lifecycle flows through these statuses in order:
+ * `queued` -> `processing` -> `downloading` -> `complete` (or `failed`
+ * at any point).
+ *
+ * Not all providers emit all statuses — synchronous providers (Stable Audio,
+ * ElevenLabs) may jump directly from `processing` to `complete`.
+ *
+ * @example
+ * ```typescript
+ * emitter.on('audio:progress', (evt: AudioProgressEvent) => {
+ *   console.log(`[${evt.status}] ${evt.progress ?? '?'}% — ${evt.message}`);
+ * });
+ * ```
+ */
+export interface AudioProgressEvent {
+    /**
+     * Current status of the generation job.
+     *
+     * - `'queued'`      — Request accepted, waiting for processing slot
+     * - `'processing'`  — Actively generating audio
+     * - `'downloading'` — Generation complete, downloading result
+     * - `'complete'`    — Fully done, result available
+     * - `'failed'`      — Terminal error, see {@link message}
+     */
+    status: 'queued' | 'processing' | 'downloading' | 'complete' | 'failed';
+    /**
+     * Estimated progress percentage (0-100).
+     *
+     * Not all providers report granular progress; may remain `undefined`
+     * until the final status transition.
+     */
+    progress?: number;
+    /**
+     * Estimated time remaining in milliseconds.
+     *
+     * Only available when the provider reports ETA information.
+     */
+    estimatedRemainingMs?: number;
+    /** Human-readable status message or error description. */
+    message?: string;
+}
+//# sourceMappingURL=types.d.ts.map

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

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

package/dist/core/audio/types.js

@@ -0,0 +1,21 @@
+/**
+ * @file types.ts
+ * Core type definitions for the audio generation subsystem.
+ *
+ * These types are consumed by {@link IAudioGenerator}, {@link FallbackAudioProxy},
+ * and concrete provider implementations (Suno, Udio, Stable Audio,
+ * ElevenLabs SFX, etc.) to provide a unified audio pipeline across multiple
+ * provider backends.
+ *
+ * Audio generation is split into two sub-modalities:
+ *
+ * - **Music** — full-length musical compositions from text prompts (Suno, Udio,
+ *   Stable Audio).
+ * - **SFX** — short sound effects from text descriptions (ElevenLabs, Stable
+ *   Audio).
+ *
+ * Not all providers support both; capability negotiation is handled via
+ * {@link IAudioGenerator.supports}.
+ */
+export {};
+//# sourceMappingURL=types.js.map

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

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