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

package/lib/API/mureka/index.js

@@ -0,0 +1,7 @@
+import * as music from './music.js';
+import musicToolset from './MusicToolset.js'
+
+export default {
+	music,
+	musicToolset
+}

package/lib/API/mureka/music.js

@@ -0,0 +1,658 @@
+/**
+ * @file lib/API/mureka/music.js
+ * @module mureka/music
+ * @description Comprehensive pure HTTP wrapper for the official Mureka AI Music API.
+ *
+ * This module provides typed, well-documented access to **all major Mureka operations**.
+ * Most generation methods support automatic polling and return rich results.
+ *
+ * @see https://platform.mureka.ai/docs/
+ */
+
+/* ============================================================
+   TYPE DEFINITIONS
+   ============================================================ */
+
+/**
+ * @typedef {Object} MurekaWord
+ * @property {number} start - Start time in milliseconds
+ * @property {number} end - End time in milliseconds
+ * @property {string} text - The word text
+ */
+
+/**
+ * @typedef {Object} MurekaLine
+ * @property {number} start - Start time in milliseconds
+ * @property {number} end - End time in milliseconds
+ * @property {string} text - Full line text
+ * @property {MurekaWord[]} [words] - Word-level timing (optional)
+ */
+
+/**
+ * @typedef {Object} MurekaLyricsSection
+ * @property {string} section_type - e.g. "intro", "verse", "chorus", "bridge"
+ * @property {number} [start] - Section start time (ms)
+ * @property {number} [end] - Section end time (ms)
+ * @property {MurekaLine[]} [lines] - Lines with timing
+ */
+
+/**
+ * @typedef {Object} MurekaChoice
+ * @property {string} url - Primary MP3 URL
+ * @property {string} [flac_url] - FLAC version
+ * @property {string} [wav_url] - WAV version
+ * @property {number} duration - Duration in milliseconds
+ * @property {string} [id] - Choice-specific ID
+ * @property {number} [index] - Choice index (0-based)
+ * @property {MurekaLyricsSection[]} [lyrics_sections] - Detailed timed lyrics
+ * @property {string} [local_path] - Locally saved MP3 path (added by wrapper)
+ * @property {string} [local_flac_path] - Locally saved FLAC path (added by wrapper)
+ * @property {string} [local_wav_path] - Locally saved WAV path (added by wrapper)
+ */
+
+/**
+ * @typedef {Object} MurekaGenerationResult
+ * @property {string} id - Main task/result ID
+ * @property {number} created_at - Unix timestamp (seconds)
+ * @property {number} [finished_at] - Unix timestamp when finished
+ * @property {string} [model] - Model used (e.g. "mureka-9")
+ * @property {string} status - "succeeded", "processing", "failed", etc.
+ * @property {MurekaChoice[]} [choices] - Array of generated audio variants (ALL auto-saved)
+ * @property {string} [trace_id] - Request trace ID for debugging
+ * @property {string} [mp3_url] - Legacy top-level MP3 (for backward compatibility)
+ * @property {string} [audio_url] - Legacy top-level audio URL
+ * @property {string[]} [local_paths] - Array of all locally saved MP3 paths (added by wrapper)
+ * @property {Object} [raw] - Original raw API response
+ */
+
+/* ============================================================
+   CONSTANTS & CORE HELPERS
+   ============================================================ */
+
+import { request as doRequest } from '@j-o-r/apiserver';
+import fs from 'fs/promises';
+import path from 'path';
+
+const BASE_URL = 'https://api.mureka.ai';
+const TMP_DIR = path.join(process.cwd(), '.cache', 'mureka');
+
+const POLL_INTERVAL_MS = 10000;
+const MAX_POLL_ATTEMPTS = 24;
+const MAX_RETRIES = 3;
+
+/**
+ * Official valid track generate types (Title Case).
+ * These are the only accepted values for `type` / `generate_type`.
+ */
+const TRACK_GENERATE_TYPES = [
+  'Vocals',
+  'Instrumental',
+  'Drums',
+  'Bass',
+  'Guitar',
+  'Keyboard',
+  'Percussion',
+  'Strings',
+  'Synth',
+  'FX',
+  'Brass',
+  'Woodwinds'
+];
+
+/**
+ * Validates a track generate type.
+ * Throws a clear error if the type is not in TRACK_GENERATE_TYPES.
+ *
+ * @param {string} type
+ */
+function validateTrackGenerateType(type) {
+  if (!type) {
+    throw new Error('track generate type is required');
+  }
+
+  const valid = TRACK_GENERATE_TYPES.find(t => t === type);
+
+  if (!valid) {
+    throw new Error(
+      `Invalid track generate type: "${type}". ` +
+      `Valid types: ${TRACK_GENERATE_TYPES.join(', ')}`
+    );
+  }
+
+  return valid; // return the correct Title Case version
+}
+
+
+/**
+ * Returns authentication headers for Mureka API requests.
+ * @returns {{'Authorization': string}}
+ * @throws {Error} If MUREKA_API_KEY is not set.
+ * @see https://platform.mureka.ai/docs/
+ */
+const getHeaders = () => {
+  if (!process.env.MUREKA_API_KEY) {
+    throw new Error('Missing MUREKA_API_KEY! Please export MUREKA_API_KEY=your_key');
+  }
+  return {
+    'Authorization': `Bearer ${process.env.MUREKA_API_KEY}`
+  };
+};
+
+/**
+ * Saves audio data (URL or base64) to a local file.
+ * @param {string|Buffer} audioData
+ * @param {string} [filenamePrefix='mureka']
+ * @returns {Promise<string>} Local file path
+ */
+/**
+ * Saves audio data (URL or base64) to a local file in the .cache/mureka directory.
+ * @param {string|Buffer} audioData - URL, base64 string, or Buffer of the audio.
+ * @param {string} [filenamePrefix="mureka"] - Prefix for the saved filename.
+ * @returns {Promise<string>} The local file path of the saved audio.
+ */
+async function saveAudioToLocal(audioData, filenamePrefix = 'mureka') {
+  await fs.mkdir(TMP_DIR, { recursive: true });
+  const filename = `${filenamePrefix}-${Date.now()}.mp3`;
+  const localPath = path.join(TMP_DIR, filename);
+
+  if (typeof audioData === 'string' && audioData.startsWith('http')) {
+    const response = await fetch(audioData);
+    if (!response.ok) throw new Error(`Download failed: ${response.status}`);
+    const buffer = Buffer.from(await response.arrayBuffer());
+    await fs.writeFile(localPath, buffer);
+  } else if (typeof audioData === 'string') {
+    const buffer = Buffer.from(audioData, 'base64');
+    await fs.writeFile(localPath, buffer);
+  } else {
+    await fs.writeFile(localPath, audioData);
+  }
+  return localPath;
+}
+
+/**
+ * Saves all audio variants (MP3, FLAC, WAV) from a generation result to local files.
+ * @private
+ * @param {Object} result - The API response containing choices.
+ * @returns {Promise<Object>} The result with local_path fields added.
+ */
+async function saveAllAudioChoices(result) {
+  const localPaths = [];
+  if (result.choices && Array.isArray(result.choices)) {
+    for (let i = 0; i < result.choices.length; i++) {
+      const choice = result.choices[i];
+      if (choice.url) {
+        choice.local_path = await saveAudioToLocal(choice.url, `choice-${i}`);
+        localPaths.push(choice.local_path);
+      }
+      if (choice.flac_url) choice.local_flac_path = await saveAudioToLocal(choice.flac_url, `choice-${i}-flac`);
+      if (choice.wav_url) choice.local_wav_path = await saveAudioToLocal(choice.wav_url, `choice-${i}-wav`);
+    }
+  }
+  if (localPaths.length > 0) result.local_paths = localPaths;
+  return result;
+}
+
+/**
+ * Internal request helper with retry logic on 429 rate limits.
+ * Always includes the full URL in error messages.
+ * @private
+ * @param {string} endpoint - API endpoint (e.g. "/v1/song/generate").
+ * @param {string} [method="POST"] - HTTP method.
+ * @param {Object} [body={}] - Request body.
+ * @param {number} [retryCount=0] - Current retry attempt.
+ * @returns {Promise<Object>} The API response.
+ */
+async function requestInternal(endpoint, method = 'POST', body = {}, retryCount = 0) {
+  const headers = getHeaders();
+  const url = `${BASE_URL}${endpoint}`;
+
+  const res = await doRequest(url, method, headers, body);
+
+  if (res.status === 429 && retryCount < MAX_RETRIES) {
+    const wait = Math.pow(2, retryCount) * 1000;
+    await new Promise(r => setTimeout(r, wait));
+    return requestInternal(endpoint, method, body, retryCount + 1);
+  }
+
+  if (res.status >= 400) {
+    const errMsg = JSON.stringify(res, null, 2);
+    throw new Error(`Mureka API error ${res.status} at ${url}:\n${errMsg}`);
+  }
+
+  return { ...res.response, duration: Date.now() - Date.now(), raw: res.response };
+}
+
+/**
+ * Poll until task completes.
+ * @param {string} taskId
+ * @param {string} [type='song']
+ * @returns {Promise<MurekaGenerationResult>}
+ */
+/**
+ * Polls a task until it completes or fails.
+ * @param {string} taskId - The task ID to poll.
+ * @param {string} [type="song"] - Task type (song, instrumental, tts, etc.).
+ * @returns {Promise<MurekaGenerationResult>} The completed result.
+ */
+async function pollUntilDone(taskId, type = 'song') {
+  for (let attempt = 0; attempt < MAX_POLL_ATTEMPTS; attempt++) {
+    await new Promise(r => setTimeout(r, POLL_INTERVAL_MS));
+    const status = await requestInternal(`/v1/${type}/query/${taskId}`, 'GET');
+    if (['completed', 'success', 'succeeded'].includes(status.status)) {
+      return await saveAllAudioChoices(status);
+    }
+    if (['failed', 'error'].includes(status.status)) {
+      throw new Error(`Task failed: ${status.error || status.message}`);
+    }
+  }
+  throw new Error(`Task ${taskId} timed out`);
+}
+
+/* ============================================================
+   AUTO-POLL HELPER
+   ============================================================ */
+/**
+ * Wrapper that automatically polls async generation tasks to completion.
+ * @private
+ * @param {Function} fn - The API call function.
+ * @param {Object} params - Parameters to pass.
+ * @param {string} [defaultType="song"] - Default task type for polling.
+ * @returns {Promise<MurekaGenerationResult>} Final result after polling.
+ */
+async function withAutoPoll(fn, params, defaultType = 'song') {
+  const result = await fn(params);
+  if (result.task_id || result.id) {
+    return await pollUntilDone(result.task_id || result.id, defaultType);
+  }
+  return await saveAllAudioChoices(result);
+}
+
+/* ============================================================
+   SONG OPERATIONS
+   ============================================================ */
+
+/**
+ * Generate a complete song with both lyrics and vocals (text-to-song).
+ * Supports reference_id, vocal_id, motif_id, etc.
+ * Automatically polls until completion and saves audio locally.
+ *
+ * @param {Object} [params={}] 
+ * @param {string} params.prompt - Style/mood/genre description (required).
+ * @param {string} [params.lyrics] - Structured lyrics with [Verse], [Chorus], etc.
+ * @param {string} [params.model="auto"] - Model to use.
+ * @param {string} [params.reference_id] - Reference audio file_id (purpose=reference).
+ * @param {string} [params.vocal_id] - Cloned voice ID.
+ * @param {string} [params.motif_id] - Melody motif file_id.
+ * @returns {Promise<MurekaGenerationResult>} Generation result with choices and local paths.
+ */
+async function generateSong(params = {}) {
+  return withAutoPoll((p) => requestInternal('/v1/song/generate', 'POST', p), params, 'song');
+}
+
+/**
+ * Generate pure instrumental music (no vocals).
+ *
+ * @param {Object} [params={}] 
+ * @param {string} params.prompt - Instrumental style/mood description (required).
+ * @param {string} [params.model="auto"]
+ * @param {string} [params.reference_id] - Reference audio (purpose=reference or instrumental).
+ * @returns {Promise<MurekaGenerationResult>}
+ */
+async function generateInstrumental(params = {}) {
+  return withAutoPoll((p) => requestInternal('/v1/instrumental/generate', 'POST', p), params, 'instrumental');
+}
+
+/**
+ * Generate a musical soundtrack matching an image or video.
+ *
+ * @param {Object} [params={}] 
+ * @param {string} [params.image] - Image URL or file_id.
+ * @param {string} [params.video] - Video URL or file_id.
+ * @param {string} [params.prompt] - Optional style guidance.
+ * @returns {Promise<MurekaGenerationResult>}
+ */
+async function generateSoundtrack(params = {}) {
+  return withAutoPoll((p) => requestInternal('/v1/soundtrack/generate', 'POST', p), params, 'soundtrack');
+}
+
+/**
+ * Analyze an existing audio file and return structured description (genre, mood, structure, etc.).
+ *
+ * @param {Object} [params={}] 
+ * @param {string} params.url - Audio URL or base64 (required).
+ * @returns {Promise<Object>} Description result.
+ */
+async function describeSong(params = {}) {
+  return withAutoPoll((p) => requestInternal('/v1/song/describe', 'POST', p), params, 'song');
+}
+
+/**
+ * Extend an existing song by adding more sections.
+ *
+ * @param {Object} [params={}] 
+ * @param {string} params.song_id - ID from previous generation (required).
+ * @param {string} [params.lyrics] - Additional lyrics.
+ * @returns {Promise<MurekaGenerationResult>}
+ */
+async function extendSong(params = {}) {
+  return withAutoPoll((p) => requestInternal('/v1/song/extend', 'POST', p), params, 'song');
+}
+
+/**
+ * Regenerate a song (or specific parts).
+ *
+ * @param {Object} [params={}] 
+ * @returns {Promise<MurekaGenerationResult>}
+ */
+async function regenerateSong(params = {}) {
+  return withAutoPoll((p) => requestInternal('/v1/song/regenerate', 'POST', p), params, 'song');
+}
+
+/**
+ * Separate a song into stems (vocals, drums, bass, etc.).
+ *
+ * @param {Object} [params={}] 
+ * @param {string} params.url - Audio URL or base64 (required).
+ * @param {string} [params.model] - Separation model.
+ * @returns {Promise<MurekaGenerationResult>}
+ */
+async function stemSong(params = {}) {
+  return withAutoPoll((p) => requestInternal('/v1/song/stem', 'POST', p), params, 'song');
+}
+
+/**
+ * Recognize/identify a song from audio.
+ *
+ * @param {Object} [params={}] 
+ * @param {string} params.url - Audio URL or base64 (required).
+ * @returns {Promise<Object>}
+ */
+async function recognizeSong(params = {}) {
+  return withAutoPoll((p) => requestInternal('/v1/song/recognize', 'POST', p), params, 'song');
+}
+
+/**
+ * Edit a specific time region of a song (replace lyrics/melody in a section).
+ *
+ * @param {Object} [params={}] 
+ * @param {string} params.song_id - Song ID (required).
+ * @param {number} params.start_milliseconds - Start time (ms).
+ * @param {number} params.end_milliseconds - End time (ms).
+ * @param {string} [params.lyrics] - New lyrics for the region.
+ * @returns {Promise<MurekaGenerationResult>}
+ */
+async function regionEditSong(params = {}) {
+  return withAutoPoll((p) => requestInternal('/v1/song/region-edit', 'POST', p), params, 'song');
+}
+
+/**
+ * Generate a lyrics video from lyrics and background image.
+ *
+ * @param {Object} [params={}] 
+ * @returns {Promise<MurekaGenerationResult>}
+ */
+async function generateLyricsVideo(params = {}) {
+  return withAutoPoll((p) => requestInternal('/v1/lyrics-video/generate', 'POST', p), params, 'lyrics-video');
+}
+
+/**
+ * Generate a specific track type (Vocals, Instrumental, Drums, etc.) from a song or uploaded audio.
+ *
+ * @param {Object} [params={}] 
+ * @param {string} [params.song_id] - Song ID (mutually exclusive with upload_audio_id).
+ * @param {string} [params.upload_audio_id] - Upload ID from purpose="audio".
+ * @param {string} params.type - Track type (Vocals, Instrumental, Drums, Bass, Guitar, Keyboard, Percussion, Strings, Synth, FX, Brass, Woodwinds).
+ * @param {string} [params.generate_type] - Legacy alias for type.
+ * @param {string} params.prompt - Control prompt (required).
+ * @param {number} [params.generate_start] - Start time (ms).
+ * @param {number} [params.generate_end] - End time (ms).
+ * @param {string} [params.lyrics] - Lyrics (for Vocals).
+ * @param {string} [params.vocal_gender] - "male" or "female".
+ * @returns {Promise<MurekaGenerationResult>}
+ */
+async function generateTrack(params = {}) {
+  console.log(JSON.stringify(params, null, '  ') );
+  // This will throw if invalid
+  // validateTrackGenerateType(params.generate_type);
+
+  return withAutoPoll((p) => requestInternal('/v1/track/generate', 'POST', p), params, 'song');
+}
+
+/**
+ * Create a remix of an existing song.
+ *
+ * @param {Object} [params={}] 
+ * @param {string} [params.song_id] - Song ID.
+ * @param {string} [params.upload_audio_id] - Upload ID from purpose="remix".
+ * @param {string} params.prompt - Remix style prompt (required).
+ * @param {string} params.lyrics - Full lyrics of the target song (required).
+ * @param {number} [params.n=2] - Number of variants.
+ * @param {string} [params.model="auto"]
+ * @returns {Promise<MurekaGenerationResult>}
+ */
+async function remixSong(params = {}) {
+  return withAutoPoll((p) => requestInternal('/v1/song/remix', 'POST', p), params, 'song');
+}
+
+/* ============================================================
+   LYRICS
+   ============================================================ */
+
+/**
+ * Generate brand new song lyrics from a theme or style prompt.
+ *
+ * @param {Object} [params={}] 
+ * @param {string} params.prompt - Theme/style instructions (required).
+ * @returns {Promise<Object>} Generated lyrics.
+ */
+async function generateLyrics(params = {}) {
+  return requestInternal('/v1/lyrics/generate', 'POST', params);
+}
+
+/**
+ * Extend or continue existing lyrics.
+ *
+ * @param {Object} [params={}] 
+ * @param {string} params.lyrics - Existing lyrics (required).
+ * @param {string} params.prompt - Instructions for extension (required).
+ * @returns {Promise<Object>}
+ */
+async function extendLyrics(params = {}) {
+  return requestInternal('/v1/lyrics/extend', 'POST', params);
+}
+
+/* ============================================================
+   TTS / SPEECH
+   ============================================================ */
+
+/**
+ * Convert text to natural-sounding speech (single-speaker or multi-speaker).
+ *
+ * @param {Object} [params={}] 
+ * @param {string} [params.text] - Text for single-speaker mode.
+ * @param {Array} [params.script] - Array of {speaker, text} for podcast mode.
+ * @param {string} [params.voice_id] - Voice ID for single-speaker.
+ * @param {Object} [params.voices] - Map of speaker -> voice_id for podcast.
+ * @param {number} [params.speed=1.0]
+ * @param {number} [params.pitch=0]
+ * @returns {Promise<MurekaGenerationResult>}
+ */
+async function generateTTS(params = {}) {
+  return withAutoPoll((p) => requestInternal('/v1/tts/generate', 'POST', p), params, 'tts');
+}
+
+/**
+ * Generate a multi-speaker podcast.
+ *
+ * @param {Object} [params={}] 
+ * @returns {Promise<MurekaGenerationResult>}
+ */
+async function generatePodcast(params = {}) {
+  return withAutoPoll((p) => requestInternal('/v1/tts/podcast', 'POST', p), params, 'tts');
+}
+
+/* ============================================================
+   VOCAL CLONING
+   ============================================================ */
+
+/**
+ * Create a custom voice clone from a short vocal sample.
+ *
+ * @param {Object} [params={}] 
+ * @param {string} params.file - URL or base64 of vocal sample (5-15s recommended).
+ * @param {string} [params.name] - Friendly name for the voice.
+ * @returns {Promise<Object>} Result containing voice_id.
+ */
+async function cloneVocal(params = {}) {
+  return withAutoPoll((p) => requestInternal('/v1/song/vocal-clone', 'POST', p), params, 'vocal');
+}
+
+/* ============================================================
+   FILE UPLOADS
+   ============================================================ */
+
+/**
+ * Upload a file for use as reference (audio, image, video, MIDI).
+ * Supports multiple purposes (reference, vocal, melody, audio, remix, soundtrack, lyrics-video, etc.).
+ *
+ * @param {Object} [params={}] 
+ * @param {string} params.url - Public URL of the file (required).
+ * @param {string} params.purpose - Purpose of upload (required).
+ * @returns {Promise<Object>} Upload result with file_id.
+ */
+async function uploadFile(params = {}) {
+  const formData = new FormData();
+  for (const [key, value] of Object.entries(params)) {
+    if (value !== undefined && value !== null) {
+      formData.append(key, value);
+    }
+  }
+  return requestInternal('/v1/files/upload', 'POST', formData);
+}
+
+/**
+ * Create a new upload session.
+ *
+ * @param {Object} [params={}] 
+ * @returns {Promise<Object>}
+ */
+async function uploadsCreate(params = {}) {
+  return requestInternal('/v1/uploads/create', 'POST', params);
+}
+
+/**
+ * Add data to an upload session.
+ *
+ * @param {Object} [params={}] 
+ * @returns {Promise<Object>}
+ */
+async function uploadsAdd(params = {}) {
+  return requestInternal('/v1/uploads/add', 'POST', params);
+}
+
+/**
+ * Complete an upload session.
+ *
+ * @param {Object} [params={}] 
+ * @returns {Promise<Object>}
+ */
+async function uploadsComplete(params = {}) {
+  return requestInternal('/v1/uploads/complete', 'POST', params);
+}
+
+/* ============================================================
+   TASK POLLING
+   ============================================================ */
+
+/**
+ * Manually query the status of a task.
+ *
+ * @param {string} taskId - Task ID.
+ * @param {string} [type="song"] - Task type.
+ * @returns {Promise<Object>} Task status.
+ */
+async function queryTask(taskId, type = 'song') {
+  return requestInternal(`/v1/${type}/query/${taskId}`, 'GET');
+}
+
+/* ============================================================
+   ACCOUNT & BILLING
+   ============================================================ */
+
+/**
+ * Retrieve current account billing information (balance, credits, usage).
+ *
+ * @returns {Promise<Object>}
+ */
+async function getBilling() {
+  return requestInternal('/v1/account/billing', 'GET');
+}
+
+/**
+ * Retrieve account profile information.
+ *
+ * @returns {Promise<Object>}
+ */
+async function getProfile() {
+  return requestInternal('/v1/account/profile', 'GET');
+}
+
+/* ============================================================
+   FINE-TUNING
+   ============================================================ */
+
+/**
+ * Create a fine-tuning task.
+ *
+ * @param {Object} [params={}] 
+ * @returns {Promise<MurekaGenerationResult>}
+ */
+async function createFineTune(params = {}) {
+  return withAutoPoll((p) => requestInternal('/v1/finetuning/create', 'POST', p), params, 'finetuning');
+}
+
+/**
+ * Query the status of a fine-tuning task.
+ *
+ * @param {string} taskId - Fine-tune task ID.
+ * @returns {Promise<Object>}
+ */
+async function queryFineTune(taskId) {
+  return requestInternal(`/v1/finetuning/query/${taskId}`, 'GET');
+}
+
+/* ============================================================
+   EXPORTS
+   ============================================================ */
+
+export {
+  getHeaders,
+  saveAudioToLocal,
+  pollUntilDone,
+  generateSong,
+  generateInstrumental,
+  generateSoundtrack,
+  describeSong,
+  extendSong,
+  regenerateSong,
+  stemSong,
+  recognizeSong,
+  regionEditSong,
+  generateLyricsVideo,
+  generateTrack,
+  remixSong,
+  generateLyrics,
+  extendLyrics,
+  generateTTS,
+  generatePodcast,
+  cloneVocal,
+  uploadFile,
+  uploadsCreate,
+  uploadsAdd,
+  uploadsComplete,
+  queryTask,
+  getBilling,
+  getProfile,
+  createFineTune,
+  queryFineTune
+};

package/lib/API/openai.com/index.js

@@ -0,0 +1,7 @@
+import * as video from './video.js';
+import videoToolset from './videoToolset.js'
+
+export default {
+	video,
+	videoToolset
+}