@j-o-r/hello-dave 0.1.1 → 0.1.5

package/lib/API/lalal.ai/lalal.js

@@ -0,0 +1,445 @@
+/**
+ * @file lib/API/lalal.ai/lalal.js
+ * @module lalal.ai/lalal
+ * @description Pure HTTP wrapper for the LALAL.AI API v1 (https://www.lalal.ai/api/v1/).
+ *
+ * Provides a clean, production-ready interface for:
+ * - File upload (/upload/)
+ * - Task management: split (stem_separator, demuser, voice_clean, multistem), voice change
+ * - Status checking and polling (/check/)
+ * - Cancellation, deletion, limits
+ * - Batch operations
+ * - Voice packs listing
+ *
+ * Authentication via `X-License-Key` header (env: LALAL_AI_LICENSE_KEY).
+ * All processing is asynchronous — use check/poll helpers.
+ *
+ * High-level methods handle upload → start task → poll → result processing.
+ * Supports local files, Buffers, Blobs, remote URLs (auto-download for upload).
+ *
+ * @see OpenAPI: lib/API/lalal.ai/openapi.json
+ * @see Official examples: https://github.com/OmniSaleGmbH/lalalai/tree/master/api-v1/python
+ */
+
+/* ============================================================
+   IMPORTS & CONSTANTS
+   ============================================================ */
+
+import { request as doRequest } from '@j-o-r/apiserver';
+import fs from 'fs/promises';
+import path from 'path';
+
+const BASE_URL = 'https://www.lalal.ai/api/v1';
+const TMP_DIR = path.join(process.cwd(), '.cache', 'lalalai');
+
+/* ============================================================
+   AUTHENTICATION & HEADERS
+   ============================================================ */
+
+/**
+ * Builds authenticated request headers for LALAL.AI API.
+ * Requires the `LALAL_AI_LICENSE_KEY` environment variable.
+ *
+ * @function getHeaders
+ * @param {Object} [extraHeaders={}] - Additional headers (e.g. Content-Disposition)
+ * @returns {Object} Headers with X-License-Key
+ * @throws {Error} If license key missing
+ */
+const getHeaders = (extraHeaders = {}) => {
+  if (!process.env.LALAL_AI_LICENSE_KEY) {
+    throw new Error('Missing LALAL_AI_LICENSE_KEY! Please export LALAL_AI_LICENSE_KEY=your_license_key');
+  }
+  return {
+    'X-License-Key': process.env.LALAL_AI_LICENSE_KEY,
+    ...extraHeaders
+  };
+};
+
+/* ============================================================
+   TEMPORARY FILE MANAGEMENT
+   ============================================================ */
+
+async function ensureTmpDir() {
+  await fs.mkdir(TMP_DIR, { recursive: true });
+}
+
+/**
+ * Downloads a remote file (audio) to temp dir.
+ *
+ * @async
+ * @function downloadRemoteToTemp
+ * @param {string} url - Remote URL
+ * @param {string} [prefix='lalal-download'] - Filename prefix
+ * @returns {Promise<string>} Local file path
+ */
+async function downloadRemoteToTemp(url, prefix = 'lalal-download') {
+  await ensureTmpDir();
+  const response = await fetch(url);
+  if (!response.ok) {
+    throw new Error(`Failed to download: ${response.status} ${response.statusText}`);
+  }
+  const buffer = Buffer.from(await response.arrayBuffer());
+  let filename = `${prefix}-${Date.now()}.mp3`;
+  try {
+    const urlObj = new URL(url);
+    const base = path.basename(urlObj.pathname);
+    if (base) filename = base;
+  } catch (_) {}
+  const localPath = path.join(TMP_DIR, filename);
+  await fs.writeFile(localPath, buffer);
+  return localPath;
+}
+
+/**
+ * Prepares upload payload: returns { body: Buffer, headers: { 'Content-Disposition': ... } }
+ *
+ * @async
+ * @function prepareUploadPayload
+ * @param {string|Buffer|Blob} input - File path, URL, Buffer or Blob
+ * @param {string} [filename] - Optional filename (required for Buffers/Blobs)
+ * @returns {Promise<{body: Buffer, contentDisposition: string}>}
+ */
+async function prepareUploadPayload(input, filename) {
+  let buffer;
+  let finalFilename = filename;
+
+  if (typeof input === 'string') {
+    if (input.startsWith('http://') || input.startsWith('https://')) {
+      const localPath = await downloadRemoteToTemp(input, 'upload-source');
+      buffer = await fs.readFile(localPath);
+      finalFilename = finalFilename || path.basename(localPath);
+    } else {
+      buffer = await fs.readFile(input);
+      finalFilename = finalFilename || path.basename(input);
+    }
+  } else if (input instanceof Buffer) {
+    buffer = input;
+    if (!finalFilename) throw new Error('filename required for Buffer input');
+  } else if (input instanceof Blob) {
+    buffer = Buffer.from(await input.arrayBuffer());
+    finalFilename = finalFilename || input.name || `upload-${Date.now()}.mp3`;
+  } else {
+    throw new Error('Unsupported input type for upload');
+  }
+
+  // Build Content-Disposition (simple version; production should handle RFC 6266/5987)
+  const disposition = `attachment; filename="${finalFilename.replace(/"/g, '')}"`;
+  return { body: buffer, contentDisposition: disposition };
+}
+
+/* ============================================================
+   CORE REQUEST HELPERS
+   ============================================================ */
+
+/**
+ * Generic POST helper with JSON body.
+ *
+ * @async
+ * @function postJson
+ * @param {string} endpoint - Relative path e.g. 'split/stem_separator/'
+ * @param {Object} body - JSON payload
+ * @param {Object} [extraHeaders={}] - Extra headers
+ * @returns {Promise<Object>} Response object from doRequest
+ */
+async function postJson(endpoint, body, extraHeaders = {}) {
+  const url = `${BASE_URL}/${endpoint}`;
+  const headers = getHeaders({ 'Content-Type': 'application/json', ...extraHeaders });
+  return doRequest(url, 'POST', headers, JSON.stringify(body));
+}
+
+/**
+ * Upload helper (binary octet-stream with Content-Disposition).
+ *
+ * @async
+ * @function uploadFile
+ * @param {string|Buffer|Blob} input
+ * @param {string} [filename]
+ * @returns {Promise<Object>} { id, name, size, duration, expires }
+ */
+async function uploadFile(input, filename) {
+  const { body, contentDisposition } = await prepareUploadPayload(input, filename);
+  const url = `${BASE_URL}/upload/`;
+  const headers = getHeaders({ 'Content-Disposition': contentDisposition, 'Content-Type': 'application/octet-stream' });
+
+  const res = await doRequest(url, 'POST', headers, body);
+
+  if (res.status === 200) {
+    return res.response;
+  }
+  throw new Error(`Upload failed: ${res.status} ${JSON.stringify(res.response)}`);
+}
+
+/* ============================================================
+   POLLING & CHECK HELPERS
+   ============================================================ */
+
+/**
+ * Checks task status.
+ *
+ * @async
+ * @function checkTasks
+ * @param {string|string[]} taskIds - Single ID or array
+ * @returns {Promise<Object>} CheckV1Response
+ */
+async function checkTasks(taskIds) {
+  const ids = Array.isArray(taskIds) ? taskIds : [taskIds];
+  const res = await postJson('check/', { task_ids: ids });
+  if (res.status === 200) {
+    return res.response;
+  }
+  throw new Error(`Check failed: ${res.status} ${JSON.stringify(res.response)}`);
+}
+
+/**
+ * Polls /check/ until task completes, errors, or times out.
+ *
+ * @async
+ * @function pollForTask
+ * @param {string} taskId
+ * @param {number} [maxAttempts=120] - ~10 minutes at 5s interval
+ * @param {number} [intervalMs=5000]
+ * @returns {Promise<Object>} The success result or throws on error/cancel/timeout
+ */
+async function pollForTask(taskId, maxAttempts = 120, intervalMs = 5000) {
+  for (let attempt = 0; attempt < maxAttempts; attempt++) {
+    const checkRes = await checkTasks(taskId);
+    const taskResult = checkRes.result?.[taskId];
+
+    if (!taskResult) {
+      throw new Error(`Task ${taskId} not found in check response`);
+    }
+
+    const status = taskResult.status;
+
+    if (status === 'success') {
+      return taskResult;
+    }
+    if (status === 'error' || status === 'server_error') {
+      throw new Error(`Task ${taskId} failed: ${JSON.stringify(taskResult.error || taskResult)}`);
+    }
+    if (status === 'cancelled') {
+      throw new Error(`Task ${taskId} was cancelled`);
+    }
+
+    // progress or queued
+    await new Promise(resolve => setTimeout(resolve, intervalMs));
+  }
+  throw new Error(`Timeout polling task ${taskId} after ${maxAttempts} attempts`);
+}
+
+/* ============================================================
+   SPLIT HELPERS (high-level)
+   ============================================================ */
+
+/**
+ * Starts a stem separator split task.
+ *
+ * @async
+ * @function splitStemSeparator
+ * @param {string} sourceId
+ * @param {Object} presets - StemSeparatorSplitterPresetsV1
+ * @param {string} [idempotencyKey]
+ * @returns {Promise<{task_id: string}>}
+ */
+async function splitStemSeparator(sourceId, presets, idempotencyKey = null) {
+  const body = { source_id: sourceId, presets };
+  if (idempotencyKey) body.idempotency_key = idempotencyKey;
+  const res = await postJson('split/stem_separator/', body);
+  if (res.status === 200) return res.response;
+  throw new Error(`Split failed: ${res.status} ${JSON.stringify(res.response)}`);
+}
+
+/**
+ * Starts a demuser (music removal) task.
+ */
+async function splitDemuser(sourceId, presets = {}, idempotencyKey = null) {
+  const body = { source_id: sourceId, presets: { stem: 'music', ...presets } };
+  if (idempotencyKey) body.idempotency_key = idempotencyKey;
+  const res = await postJson('split/demuser/', body);
+  if (res.status === 200) return res.response;
+  throw new Error(`Demuser split failed: ${res.status} ${JSON.stringify(res.response)}`);
+}
+
+/**
+ * Starts a voice clean task.
+ */
+async function splitVoiceClean(sourceId, presets = {}, idempotencyKey = null) {
+  const body = { source_id: sourceId, presets: { stem: 'voice', ...presets } };
+  if (idempotencyKey) body.idempotency_key = idempotencyKey;
+  const res = await postJson('split/voice_clean/', body);
+  if (res.status === 200) return res.response;
+  throw new Error(`Voice clean split failed: ${res.status} ${JSON.stringify(res.response)}`);
+}
+
+/**
+ * Starts a multistem split task.
+ */
+async function splitMultistem(sourceId, presets, idempotencyKey = null) {
+  const body = { source_id: sourceId, presets };
+  if (idempotencyKey) body.idempotency_key = idempotencyKey;
+  const res = await postJson('split/multistem/', body);
+  if (res.status === 200) return res.response;
+  throw new Error(`Multistem split failed: ${res.status} ${JSON.stringify(res.response)}`);
+}
+
+/* ============================================================
+   BATCH SPLIT
+   ============================================================ */
+
+async function batchSplitStemSeparator(items) {
+  const res = await postJson('split/batch/stem_separator/', { items });
+  if (res.status === 200) return res.response;
+  throw new Error(`Batch split failed: ${res.status}`);
+}
+// Similar batch functions can be added for demuser, voice_clean
+
+/* ============================================================
+   VOICE CHANGE & PACKS
+   ============================================================ */
+
+async function changeVoice(sourceId, presets, idempotencyKey = null) {
+  const body = { source_id: sourceId, presets };
+  if (idempotencyKey) body.idempotency_key = idempotencyKey;
+  const res = await postJson('change_voice/', body);
+  if (res.status === 200) return res.response;
+  throw new Error(`Voice change failed: ${res.status} ${JSON.stringify(res.response)}`);
+}
+
+async function listVoicePacks() {
+  const res = await postJson('voice_packs/list/');
+  if (res.status === 200) return res.response;
+  throw new Error(`List voice packs failed: ${res.status}`);
+}
+
+/* ============================================================
+   OTHER ENDPOINTS
+   ============================================================ */
+
+async function cancelTasks(taskIds) {
+  const res = await postJson('cancel/', { task_ids: Array.isArray(taskIds) ? taskIds : [taskIds] });
+  if (res.status === 200) return res.response;
+  throw new Error(`Cancel failed: ${res.status}`);
+}
+
+async function cancelAllTasks() {
+  const res = await postJson('cancel/all/');
+  if (res.status === 200) return res.response;
+  throw new Error(`Cancel all failed: ${res.status}`);
+}
+
+async function deleteSource(sourceId) {
+  const res = await postJson('delete/', { source_id: sourceId });
+  if (res.status === 200) return res.response;
+  throw new Error(`Delete failed: ${res.status}`);
+}
+
+async function getMinutesLeft() {
+  const res = await postJson('limits/minutes_left/');
+  if (res.status === 200) return res.response;
+  throw new Error(`Limits failed: ${res.status}`);
+}
+
+/* ============================================================
+   HIGH-LEVEL WORKFLOW HELPERS
+   ============================================================ */
+
+/**
+ * Full workflow: upload file → start split → poll → return result with tracks.
+ *
+ * @async
+ * @function processSplit
+ * @param {string|Buffer|Blob} input - Audio source
+ * @param {string} stem - 'vocals' | 'voice' | 'music' | etc. (determines endpoint)
+ * @param {Object} [options] - presets + other options
+ * @returns {Promise<Object>} Success result from check (with tracks)
+ */
+async function processSplit(input, stem, options = {}) {
+  const source = await uploadFile(input, options.filename);
+  const sourceId = source.id;
+
+  let task;
+  const presets = options.presets || {};
+
+  if (stem === 'voice') {
+    task = await splitVoiceClean(sourceId, { stem: 'voice', noise_cancelling_level: options.noise_cancelling_level ?? 1, ...presets });
+  } else if (stem === 'music') {
+    task = await splitDemuser(sourceId, { stem: 'music', ...presets });
+  } else {
+    task = await splitStemSeparator(sourceId, { stem, extraction_level: options.extraction_level ?? 'deep_extraction', ...presets });
+  }
+
+  const taskId = task.task_id;
+  const result = await pollForTask(taskId);
+
+  // Optionally auto-download tracks
+  if (options.autoDownload) {
+    // implement download logic here or return urls
+  }
+
+  return { sourceId, taskId, result };
+}
+
+/**
+ * Downloads a track URL to local file.
+ *
+ * @async
+ * @function downloadTrack
+ * @param {string} url - Track download URL from check result
+ * @param {string} [destDir] - Destination directory (defaults to TMP_DIR)
+ * @returns {Promise<string>} Local path
+ */
+async function downloadTrack(url, destDir = TMP_DIR) {
+  await ensureTmpDir();
+  const response = await fetch(url);
+  if (!response.ok) throw new Error(`Download failed: ${response.status}`);
+
+  const cdHeader = response.headers.get('content-disposition') || '';
+  let filename = `track-${Date.now()}.mp3`;
+  // Simple filename extraction (improve with email-message parser if needed)
+  const match = cdHeader.match(/filename="?([^"]+)"?/);
+  if (match) filename = match[1];
+
+  const localPath = path.join(destDir, filename);
+  const buffer = Buffer.from(await response.arrayBuffer());
+  await fs.writeFile(localPath, buffer);
+  return localPath;
+}
+
+/* ============================================================
+   EXPORTS
+   ============================================================ */
+
+export {
+  // Auth & utils
+  getHeaders,
+  uploadFile,
+  prepareUploadPayload,
+  downloadRemoteToTemp,
+  downloadTrack,
+
+  // Core
+  checkTasks,
+  pollForTask,
+
+  // Splits
+  splitStemSeparator,
+  splitDemuser,
+  splitVoiceClean,
+  splitMultistem,
+
+  // Batch
+  batchSplitStemSeparator,
+
+  // Voice
+  changeVoice,
+  listVoicePacks,
+
+  // Management
+  cancelTasks,
+  cancelAllTasks,
+  deleteSource,
+  getMinutesLeft,
+
+  // High-level
+  processSplit
+};