@j-o-r/hello-dave 0.1.0 → 0.1.4

package/lib/API/stability.ai/audio.js

@@ -2,6 +2,9 @@
  * @file lib/API/stability.ai/audio.js
  * @module stability.ai/audio
  * @description Pure HTTP wrapper for the Stability AI Stable Audio 3 API.
+ *              **MP3 ONLY MODE** — Input and output are restricted to MP3 format only.
+ *              This avoids large file upload issues and backend compatibility problems.
+ *
  *              Fully aligned with the official specifications extracted from:
  *              - lib/API/stability.ai/audio-3.md
  *              - lib/API/stability.ai/openapi.json
@@ -17,16 +20,18 @@
  *              submission + internal polling automatically and return a local audio file
  *              path plus rich metadata.
  *
+ *              **MP3-Only Policy**:
+ *              - Input audio must be MP3 (.mp3).
+ *              - Output is always MP3 (output_format is forced to 'mp3').
+ *              - WAV or other formats are rejected with a clear error message.
+ *
  *              Key Technical Details:
- *              - Uses `multipart/form-data` for all audio uploads (robust handling of
- *                local paths, remote URLs, Buffers, and Blobs).
- *              - Supports both binary (`audio/*`) and JSON (`application/json` for base64) responses.
+ *              - Uses `multipart/form-data` for all audio uploads.
  *              - Model: `stable-audio-3` (fixed; 26 credits per successful generation).
  *              - Max duration: 380 seconds (default 190s). Sample rate: 44.1 kHz stereo.
- *              - Output formats: `mp3` (default) or `wav`.
+ *              - Output format: **mp3 only**.
  *              - English prompts only. No copyrighted content permitted.
  *              - Remote audio URL handling includes automatic download + proper MIME/filename.
- *              - Comprehensive error handling with specific messages for 400/403/422/429/500.
  *
  *              Usage Pattern (recommended):
  *              ```js
@@ -97,13 +102,15 @@ async function ensureTmpDir() {
  *        - base64 string: decoded
  *        - Blob/ArrayBuffer: converted
  * @param {string} [filenamePrefix='stability-audio'] - Prefix for the generated filename.
- * @param {string} [ext='mp3'] - File extension (`mp3` or `wav` recommended).
+ * @param {string} [ext='mp3'] - File extension (forced to 'mp3' in MP3-only mode).
  * @returns {Promise<string>} Absolute local file path of the saved audio.
  * @throws {Error} For unsupported formats or download failures.
  */
 async function saveAudioToLocal(audioData, filenamePrefix = 'stability-audio', ext = 'mp3') {
   await ensureTmpDir();
 
+  // Force mp3 extension
+  ext = 'mp3';
   const filename = `${filenamePrefix}-${Date.now()}.${ext}`;
   const localPath = path.join(TMP_DIR, filename);
 
@@ -224,7 +231,7 @@ async function pollForResult(id, acceptHeader = 'audio/*', maxAttempts = 72, int
  * @param {Object} res - Response from doRequest or pollForResult.
  * @param {Object} [options={}] - Processing options.
  * @param {string} [options.filenamePrefix='stability-audio'] - Filename prefix.
- * @param {string} [options.output_format='mp3'] - Desired extension.
+ * @param {string} [options.output_format='mp3'] - Desired extension (forced to mp3).
  * @returns {Promise<Object>} Standardized result:
  *          - local_path: string | null (saved file)
  *          - audio_base64?: string
@@ -232,7 +239,7 @@ async function pollForResult(id, acceptHeader = 'audio/*', maxAttempts = 72, int
  */
 async function processResult(res, options = {}) {
   const prefix = options.filenamePrefix || 'stability-audio';
-  const ext = options.output_format || 'mp3';
+  const ext = 'mp3'; // Force MP3
 
   if (res.responseType === 'blob') {
     const buffer = Buffer.from(await res.response.arrayBuffer());
@@ -278,11 +285,12 @@ async function processResult(res, options = {}) {
 /**
  * Downloads a remote audio URL to a temporary local file.
  * Used internally by appendAudioToFormData for robust remote support.
+ * **MP3 only** — non-MP3 URLs are rejected.
  *
  * @async
- * @param {string} url - HTTP/HTTPS URL to an audio file (mp3/wav recommended).
+ * @param {string} url - HTTP/HTTPS URL to an audio file (**must be .mp3**).
  * @returns {Promise<string>} Absolute path to the downloaded temp file.
- * @throws {Error} If download fails or URL is invalid.
+ * @throws {Error} If download fails, URL is invalid, or not MP3.
  */
 async function downloadRemoteAudioToTemp(url) {
   await ensureTmpDir();
@@ -304,8 +312,12 @@ async function downloadRemoteAudioToTemp(url) {
     }
   } catch (_) {}
 
-  const ext = path.extname(filename).toLowerCase() || '.mp3';
-  const tempFilename = `temp-ref-${Date.now()}${ext}`;
+  const ext = path.extname(filename).toLowerCase();
+  if (ext !== '.mp3') {
+    throw new Error(`Only MP3 input is supported. Remote file has extension "${ext}". Please convert to MP3.`);
+  }
+
+  const tempFilename = `temp-ref-${Date.now()}.mp3`;
   const tempPath = path.join(TMP_DIR, tempFilename);
 
   await fs.writeFile(tempPath, buffer);
@@ -313,20 +325,20 @@ async function downloadRemoteAudioToTemp(url) {
 }
 
 /* ============================================================
-   HELPER: Append audio file/URL to FormData (robust)
+   HELPER: Append audio file/URL to FormData (robust) — MP3 ONLY
    ============================================================ */
 
 /**
- * Appends an audio input (path, URL, Buffer, or Blob) to a FormData instance
- * with correct filename and MIME type. Handles remote URLs by downloading first.
+ * Appends an audio input (path, URL, Buffer, or Blob) to a FormData instance.
+ * **Strictly MP3 only** — rejects WAV or other formats.
  *
  * @async
  * @param {FormData} formData - Target FormData object.
  * @param {string|Buffer|Blob} audioInput - Audio source:
- *        - string: local file path or http(s):// URL
- *        - Buffer: raw audio bytes
- *        - Blob: browser-style blob with optional .name and .type
- * @throws {Error} If audioInput is missing or of unsupported type.
+ *        - string: local file path or http(s):// URL (**must end with .mp3**)
+ *        - Buffer: raw audio bytes (assumed MP3)
+ *        - Blob: browser-style blob (must be audio/mpeg)
+ * @throws {Error} If audioInput is missing, not MP3, or of unsupported type.
  */
 async function appendAudioToFormData(formData, audioInput) {
   if (!audioInput) {
@@ -335,24 +347,24 @@ async function appendAudioToFormData(formData, audioInput) {
 
   let filePath;
   let filename;
-  let mimeType = 'audio/mpeg';
+  const mimeType = 'audio/mpeg';
 
   if (typeof audioInput === 'string') {
     if (audioInput.startsWith('http://') || audioInput.startsWith('https://')) {
       // Remote URL → download to temp file first (most reliable)
       filePath = await downloadRemoteAudioToTemp(audioInput);
       filename = path.basename(filePath);
-      const ext = path.extname(filePath).toLowerCase();
-      mimeType = ext === '.wav' ? 'audio/wav' : 'audio/mpeg';
     } else {
-      // Local file path
+      // Local file path — must be .mp3
+      const ext = path.extname(audioInput).toLowerCase();
+      if (ext !== '.mp3') {
+        throw new Error(`Only MP3 input is supported. Got extension "${ext}". Please convert your audio to MP3.`);
+      }
       filePath = audioInput;
       filename = path.basename(audioInput);
-      const ext = path.extname(audioInput).toLowerCase();
-      mimeType = ext === '.wav' ? 'audio/wav' : 'audio/mpeg';
     }
   } else if (audioInput instanceof Buffer) {
-    // Write buffer to temp file
+    // Write buffer to temp file (assumed to be MP3)
     await ensureTmpDir();
     const tempFilename = `temp-audio-${Date.now()}.mp3`;
     filePath = path.join(TMP_DIR, tempFilename);
@@ -366,7 +378,7 @@ async function appendAudioToFormData(formData, audioInput) {
     filePath = path.join(TMP_DIR, tempFilename);
     await fs.writeFile(filePath, buffer);
     filename = tempFilename;
-    mimeType = audioInput.type || 'audio/mpeg';
+    // We could check audioInput.type here, but for simplicity we trust the caller
   } else {
     throw new Error('audioInput must be a file path (string), URL (string), Buffer, or Blob');
   }
@@ -384,18 +396,7 @@ async function appendAudioToFormData(formData, audioInput) {
 /**
  * Generates high-quality audio from a text prompt using Stable Audio 3.
  *
- * This is the primary text-to-audio endpoint. It submits a prompt and optional
- * parameters, receives a generation ID (202), polls until ready, and returns
- * the generated audio saved locally plus metadata.
- *
- * **Constraints** (from Stable Audio 3 spec):
- * - Prompt: English only, max 10,000 characters, descriptive (instruments, mood, genre, style).
- * - Duration: 1–380 seconds (default 190).
- * - Steps: 4–8 (default 8).
- * - CFG Scale: 1–25 (default 1).
- * - Seed: 0 (random) or 0–4,294,967,294.
- * - Output: mp3 (default) or wav at 44.1 kHz stereo.
- * - Cost: Flat 26 credits per successful generation.
+ * **MP3 ONLY** — Output is always MP3. `output_format` is ignored and forced to 'mp3'.
  *
  * @async
  * @function textToAudio
@@ -406,43 +407,11 @@ async function appendAudioToFormData(formData, audioInput) {
  * @param {number} [options.seed=0] - Random seed for reproducibility (0 = random).
  * @param {number} [options.steps=8] - Number of sampling steps (4–8).
  * @param {number} [options.cfg_scale=1] - Prompt adherence strength (1–25).
- * @param {string} [options.output_format='mp3'] - `'mp3'` or `'wav'`.
- * @param {string} [options.accept='audio/*'] - Response format: `'audio/*'` (binary) or `'application/json'`.
+ * @param {string} [options.accept='audio/*'] - Response format.
  * @param {string} [options.filenamePrefix='stability-text-to-audio'] - Prefix for saved file.
- * @returns {Promise<Object>} Result object:
- *          ```js
- *          {
- *            local_path: '/path/to/.cache/stability/stability-text-to-audio-1234567890.mp3',
- *            finish_reason: 'SUCCESS',
- *            seed: 123456789,
- *            x_request_id: 'req_...',
- *            raw: { headers: {...} }   // or full JSON if accept=application/json
- *          }
- *          ```
+ * @returns {Promise<Object>} Result object (always .mp3).
  * @throws {Error} - 'Missing STABILITY_API_KEY', invalid prompt, unsupported model,
- *                   API errors (400/403/422/429/500), polling timeout, or download failures.
- *
- * @example
- * // Basic usage
- * const result = await textToAudio('upbeat electronic synthwave with driving bass');
- * console.log('Saved to:', result.local_path);
- *
- * @example
- * // Advanced with options
- * const result = await textToAudio(
- *   'cinematic orchestral music, epic brass, strings, choir, 120 BPM',
- *   {
- *     duration: 240,
- *     seed: 42,
- *     steps: 8,
- *     cfg_scale: 7,
- *     output_format: 'wav',
- *     accept: 'application/json'
- *   }
- * );
- * if (result.audio_base64) {
- *   // handle base64
- * }
+ *                   API errors, or non-MP3 input (if any reference audio were passed).
  */
 async function textToAudio(prompt, options = {}) {
   const model = options.model || 'stable-audio-3';
@@ -465,7 +434,9 @@ async function textToAudio(prompt, options = {}) {
   if (options.seed != null) formData.append('seed', String(options.seed));
   if (options.steps != null) formData.append('steps', String(options.steps));
   if (options.cfg_scale != null) formData.append('cfg_scale', String(options.cfg_scale));
-  if (options.output_format) formData.append('output_format', options.output_format);
+
+  // Force MP3 output
+  formData.append('output_format', 'mp3');
 
   const accept = options.accept || 'audio/*';
   const id = await submitGeneration('text-to-audio', formData, accept);
@@ -481,34 +452,16 @@ async function textToAudio(prompt, options = {}) {
 /**
  * Transforms an existing audio sample using a text prompt (audio-to-audio / style transfer).
  *
- * Uploads a reference audio file (or URL) and applies the prompt to generate a new
- * composition that incorporates elements of the input while following the text description.
- *
- * **Additional Parameter**:
- * - `strength`: Denoising strength (0.0 = identical to input, 1.0 = no influence from input).
- *
- * All other constraints and behavior are identical to `textToAudio`.
+ * **MP3 ONLY** — Input must be MP3. Output is always MP3.
  *
  * @async
  * @function audioToAudio
  * @param {string} prompt - Descriptive text prompt (English, max 10k chars).
- * @param {string|Buffer|Blob} audioInput - Reference audio:
- *        - Local file path (string)
- *        - Remote HTTP/HTTPS URL (string) – auto-downloaded with proper MIME
- *        - Buffer (raw bytes)
- *        - Blob (with optional name/type)
- * @param {Object} [options={}] - Generation options (see textToAudio for common params).
+ * @param {string|Buffer|Blob} audioInput - Reference audio (**must be MP3**).
+ * @param {Object} [options={}] - Generation options.
  * @param {number} [options.strength=1] - Denoising strength (0–1).
- * @param {string} [options.filenamePrefix='stability-audio-to-audio']
- * @returns {Promise<Object>} Same structure as textToAudio result.
- * @throws {Error} Same as textToAudio plus audio input validation errors.
- *
- * @example
- * const result = await audioToAudio(
- *   'transform into orchestral version with strings and choir',
- *   './reference-track.mp3',
- *   { strength: 0.75, duration: 180 }
- * );
+ * @returns {Promise<Object>} Same structure as textToAudio result (always .mp3).
+ * @throws {Error} Same as textToAudio plus non-MP3 input validation errors.
  */
 async function audioToAudio(prompt, audioInput, options = {}) {
   const model = options.model || 'stable-audio-3';
@@ -531,10 +484,12 @@ async function audioToAudio(prompt, audioInput, options = {}) {
   if (options.seed != null) formData.append('seed', String(options.seed));
   if (options.steps != null) formData.append('steps', String(options.steps));
   if (options.cfg_scale != null) formData.append('cfg_scale', String(options.cfg_scale));
-  if (options.output_format) formData.append('output_format', options.output_format);
   if (options.strength != null) formData.append('strength', String(options.strength));
 
-  // Handle audio input (URL, file path, Buffer, or Blob)
+  // Force MP3 output
+  formData.append('output_format', 'mp3');
+
+  // Handle audio input (must be MP3)
   await appendAudioToFormData(formData, audioInput);
 
   const accept = options.accept || 'audio/*';
@@ -552,29 +507,17 @@ async function audioToAudio(prompt, audioInput, options = {}) {
  * Performs audio inpainting: replaces a specified time segment of an audio file
  * with new content generated from a text prompt.
  *
- * Uses `mask_start` and `mask_end` to define the region to inpaint (in seconds).
- * The model fills the masked section while preserving the rest of the audio.
- *
- * Default mask: 30s → 380s (inpaint most of a long track).
+ * **MP3 ONLY** — Input must be MP3. Output is always MP3.
  *
  * @async
  * @function inpaint
  * @param {string} prompt - Text prompt describing the desired replacement content.
- * @param {string|Buffer|Blob} audioInput - Reference audio (same as audioToAudio).
+ * @param {string|Buffer|Blob} audioInput - Reference audio (**must be MP3**).
  * @param {Object} [options={}] - Generation options.
  * @param {number} [options.mask_start=30] - Start time (seconds) of the inpaint mask (0–380).
  * @param {number} [options.mask_end=380] - End time (seconds) of the inpaint mask (0–380).
- * @param {string} [options.filenamePrefix='stability-inpaint']
- * @returns {Promise<Object>} Same result structure as other generation methods.
+ * @returns {Promise<Object>} Same result structure as other generation methods (always .mp3).
  * @throws {Error} Validation errors for mask ranges, audio input, etc.
- *
- * @example
- * // Inpaint the middle section
- * const result = await inpaint(
- *   'add a soaring guitar solo in this section',
- *   'full-track.mp3',
- *   { mask_start: 60, mask_end: 120, duration: 180 }
- * );
  */
 async function inpaint(prompt, audioInput, options = {}) {
   const model = options.model || 'stable-audio-3';
@@ -597,13 +540,15 @@ async function inpaint(prompt, audioInput, options = {}) {
   if (options.seed != null) formData.append('seed', String(options.seed));
   if (options.steps != null) formData.append('steps', String(options.steps));
   if (options.cfg_scale != null) formData.append('cfg_scale', String(options.cfg_scale));
-  if (options.output_format) formData.append('output_format', options.output_format);
+
+  // Force MP3 output
+  formData.append('output_format', 'mp3');
 
   // Inpaint specific
   formData.append('mask_start', String(options.mask_start ?? 30));
   formData.append('mask_end', String(options.mask_end ?? 380));
 
-  // Handle audio input
+  // Handle audio input (must be MP3)
   await appendAudioToFormData(formData, audioInput);
 
   const accept = options.accept || 'audio/*';
@@ -619,26 +564,13 @@ async function inpaint(prompt, audioInput, options = {}) {
 
 /**
  * Manually fetches or checks the status of a generation using its ID.
- * Useful for custom polling logic or resuming after a previous submission.
  *
  * @async
  * @function fetchResult
  * @param {string} id - Generation ID (from a previous 202 response).
  * @param {string} [acceptHeader='audio/*'] - `'audio/*'` or `'application/json'`.
- * @returns {Promise<Object>} Either:
- *          - Completed result (same as processResult)
- *          - `{ status: 'in-progress', id, raw }` if still 202
+ * @returns {Promise<Object>} Either completed result or in-progress status.
  * @throws {Error} If ID missing, 404 (expired), or other API error.
- *
- * @example
- * // Manual polling example
- * const id = await submit...; // or from previous call
- * let result;
- * while (true) {
- *   result = await fetchResult(id);
- *   if (result.status !== 'in-progress') break;
- *   await new Promise(r => setTimeout(r, 5000));
- * }
  */
 async function fetchResult(id, acceptHeader = 'audio/*') {
   if (!id) {