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

package/lib/API/mureka/MusicToolset.js

@@ -0,0 +1,646 @@
+/**
+ * @file lib/API/mureka/MusicToolset.js
+ * @module mureka/MusicToolset
+ * @description Comprehensive ToolSet for the Mureka AI Music API.
+ *
+ * This ToolSet is designed for AI agents / LLMs. Every tool has rich, detailed documentation
+ * so that language models understand exactly when and how to use each function.
+ *
+ * **Key behavior**: Most generation tools automatically wait for async tasks to complete
+ * and return the final result (including locally saved audio paths).
+ */
+
+import ToolSet from '../../ToolSet.js';
+import * as mureka from './music.js';
+
+const tools = new ToolSet('auto');
+
+/* ============================================================
+   HELPER: Merge extra params into top level (prevents 404s)
+   ============================================================ */
+function mergeExtra(params) {
+  const { extra = {}, ...rest } = params;
+  return { ...rest, ...extra };
+}
+
+/**
+ * Serialize a tool response as pretty JSON.
+ *
+ * @param {Record<string, unknown>} value Response payload to serialize.
+ * @returns {string} Pretty JSON response for function-calling output.
+ */
+function json(value) {
+  return JSON.stringify(value, null, 2);
+}
+
+/**
+ * Convert Mureka audio choices to compact durable references.
+ *
+ * @param {unknown} choices Possible Mureka choices array.
+ * @returns {Array<Record<string, unknown>>|undefined} Compact choice references, when present.
+ */
+function summarizeChoices(choices) {
+  if (!Array.isArray(choices)) return undefined;
+  return choices.map((choice, index) => ({
+    index: choice?.index ?? index,
+    choice_id: choice?.id,
+    id: choice?.id,
+    url: choice?.url,
+    audio_url: choice?.url,
+    flac_url: choice?.flac_url,
+    wav_url: choice?.wav_url,
+    duration: choice?.duration,
+    local_path: choice?.local_path,
+    localPath: choice?.local_path,
+    local_flac_path: choice?.local_flac_path,
+    local_wav_path: choice?.local_wav_path
+  }));
+}
+
+/**
+ * Build a self-describing tool response that preserves durable Mureka IDs,
+ * URLs, local paths, and status fields so the assistant can repeat them in a
+ * normal message before old raw function-call transcripts are pruned.
+ *
+ * @param {string} tool Tool name.
+ * @param {Record<string, unknown>} result Raw wrapper result.
+ * @param {Record<string, unknown>} [context={}] Request context worth preserving.
+ * @param {string} note Assistant-facing instruction for normal response content.
+ * @returns {Record<string, unknown>} Self-describing tool response payload.
+ */
+function murekaToolResponse(tool, result, context = {}, note) {
+  const choices = summarizeChoices(result?.choices);
+  const firstChoice = choices?.[0];
+  const localPaths = result?.local_paths || choices?.map(choice => choice.local_path).filter(Boolean);
+  const audioUrls = choices?.map(choice => choice.audio_url).filter(Boolean);
+
+  const songTools = new Set([
+    'generate_song',
+    'generate_instrumental',
+    'generate_soundtrack',
+    'extend_song',
+    'stem_song',
+    'region_edit_song',
+    'generate_track',
+    'remix_song',
+    'generate_speech',
+    'query_task'
+  ]);
+  const uploadId = tool === 'upload_file' ? result?.file_id || result?.id : result?.file_id;
+  const voiceId = tool === 'clone_voice' ? result?.voice_id || result?.vocal_id || result?.id : result?.voice_id || result?.vocal_id;
+
+  return {
+    tool,
+    success: true,
+    ...context,
+    id: result?.id,
+    song_id: songTools.has(tool) ? result?.id : undefined,
+    task_id: result?.task_id,
+    file_id: result?.file_id,
+    upload_audio_id: uploadId,
+    voice_id: voiceId,
+    vocal_id: voiceId,
+    status: result?.status,
+    model: result?.model,
+    trace_id: result?.trace_id,
+    local_path: result?.local_path || firstChoice?.local_path || localPaths?.[0],
+    localPath: result?.local_path || firstChoice?.local_path || localPaths?.[0],
+    local_paths: localPaths,
+    localPaths,
+    audio_url: result?.audio_url || result?.mp3_url || firstChoice?.audio_url || audioUrls?.[0],
+    mp3_url: result?.mp3_url || firstChoice?.audio_url || audioUrls?.[0],
+    audio_urls: audioUrls,
+    choices,
+    result,
+    note
+  };
+}
+
+/* ============================================================
+   SONG GENERATION
+   ============================================================ */
+
+tools.add(
+  'generate_song',
+  'Generate a complete song with both lyrics and vocals. This is the main "text-to-song" tool.\n\n' +
+  'Use this when you want a full vocal song. Provide a good `prompt` describing style/mood/genre. ' +
+  'You can optionally provide structured `lyrics`. If you omit lyrics, the model will generate them.\n\n' +
+  'You can also provide `reference_id`, `vocal_id`, or `motif_id` (obtained from upload_file or cloneVocal) ' +
+  'to guide the generation with existing audio or voices. After success, include exact song_id/id, local_path/local_paths, audio_url, and status in your normal response so follow-up calls can reference them.',
+  {
+    type: 'object',
+    properties: {
+      prompt: {
+        type: 'string',
+        description: 'Description of the desired style, mood, genre, and scenario. ' +
+          'Example: "Upbeat indie pop, energetic, summer road trip vibe, bright synths, driving drums". ' +
+          'This is the most important parameter. Be descriptive.'
+      },
+      lyrics: {
+        type: 'string',
+        description: 'Structured song lyrics. Use section tags like [Verse], [Chorus], [Bridge], [Intro], [Outro]. ' +
+          'Example: "[Verse]\\nWindows down, wind in my hair\\n[Chorus]\\nWe’re chasing the horizon". ' +
+          'Optional — the model can generate lyrics from the prompt if omitted.'
+      },
+      model: {
+        type: 'string',
+        default: 'auto',
+        description: 'Model to use. Default "auto" lets Mureka choose the best model. ' +
+          'Other values may be supported — check current documentation.'
+      },
+      reference_id: {
+        type: 'string',
+        description: 'File ID of a reference audio track (obtained via upload_file with purpose "reference"). ' +
+          'Use this to make the new song sound similar in style or arrangement to the reference.'
+      },
+      vocal_id: {
+        type: 'string',
+        description: 'Voice ID from a previously cloned voice (obtained via cloneVocal). ' +
+          'Use this if you want the song to be sung with a specific custom voice.'
+      },
+      motif_id: {
+        type: 'string',
+        description: 'Melody motif file ID. Use this to guide the melodic structure of the song.'
+      },
+      extra: {
+        type: 'object',
+        description: 'Additional advanced parameters passed directly to the API (rarely needed).'
+      }
+    },
+    required: ['prompt']
+  },
+  async (params) => {
+    const merged = mergeExtra(params);
+    const result = await mureka.generateSong(merged);
+    return json(murekaToolResponse('generate_song', result, { prompt: params.prompt, reference_id: params.reference_id, vocal_id: params.vocal_id, motif_id: params.motif_id }, 'Assistant: tell the user the exact song_id/id, status, local_path/local_paths, and audio_url/mp3_url. Use song_id for extend_song, region_edit_song, generate_track, remix_song, and query_task follow-up calls.'));
+  }
+);
+
+tools.add(
+  'generate_instrumental',
+  'Generate pure instrumental music with no vocals. ' +
+  'Use this when you explicitly want music without singing (background music, cinematic tracks, etc.). After success, include exact song_id/id, local_path/local_paths, audio_url, and status in your normal response.',
+  {
+    type: 'object',
+    properties: {
+      prompt: {
+        type: 'string',
+        description: 'Description of the instrumental style, mood, instrumentation, and feel. ' +
+          'Example: "Cinematic orchestral, epic brass, sweeping strings, building tension, 120 BPM".'
+      },
+      model: { type: 'string', default: 'auto', description: 'Model to use.' },
+      reference_id: {
+        type: 'string',
+        description: 'Reference audio file ID for style transfer (upload with purpose "reference" or "instrumental").'
+      },
+      extra: { type: 'object', description: 'Additional parameters.' }
+    },
+    required: ['prompt']
+  },
+  async (params) => {
+    const merged = mergeExtra(params);
+    const result = await mureka.generateInstrumental(merged);
+    return json(murekaToolResponse('generate_instrumental', result, { prompt: params.prompt, reference_id: params.reference_id }, 'Assistant: tell the user the exact song_id/id, status, local_path/local_paths, and audio_url/mp3_url for follow-up use.'));
+  }
+);
+
+tools.add(
+  'generate_soundtrack',
+  'Generate a musical soundtrack that matches the mood or content of an image or video. ' +
+  'Perfect for social media clips, film scenes, or visual content. After success, include exact song_id/id, local_path/local_paths, audio_url, and status in your normal response.',
+  {
+    type: 'object',
+    properties: {
+      image: {
+        type: 'string',
+        description: 'URL or file_id of a reference image. Mutually exclusive with video.'
+      },
+      video: {
+        type: 'string',
+        description: 'URL or file_id of a reference video. Mutually exclusive with image.'
+      },
+      prompt: {
+        type: 'string',
+        description: 'Optional additional guidance for the soundtrack style or mood.'
+      },
+      extra: { type: 'object', description: 'Additional parameters.' }
+    }
+  },
+  async (params) => {
+    const merged = mergeExtra(params);
+    const result = await mureka.generateSoundtrack(merged);
+    return json(murekaToolResponse('generate_soundtrack', result, { image: params.image, video: params.video, prompt: params.prompt }, 'Assistant: tell the user the exact song_id/id, status, local_path/local_paths, and audio_url/mp3_url. Preserve the source image/video reference if useful.'));
+  }
+);
+
+/* ============================================================
+   SONG EDITING & ANALYSIS
+   ============================================================ */
+
+tools.add(
+  'describe_song',
+  'Analyze an existing audio file and return a structured description (genre, mood, structure, timing, instruments, etc.). ' +
+  'Useful before editing or remixing a song. After success, preserve exact structural timings, ids, URLs, and any recommended song_id references in your normal response if needed for follow-up.',
+  {
+    type: 'object',
+    properties: {
+      url: {
+        type: 'string',
+        description: 'Audio URL or base64 of the song you want to analyze. Required.'
+      }
+    },
+    required: ['url']
+  },
+  async (params) => {
+    const result = await mureka.describeSong(params);
+    return json(murekaToolResponse('describe_song', result, { source_audio_url: params.url, url: params.url }, 'Assistant: summarize the song description and preserve exact timings, ids, URLs, and recommended song_id references if present.'));
+  }
+);
+
+tools.add(
+  'extend_song',
+  'Extend an existing song by adding more sections. ' +
+  'Requires the `song_id` returned by a previous generation call. After success, include the source song_id and the new returned song_id/id, local_path/local_paths, audio_url, and status in your normal response.',
+  {
+    type: 'object',
+    properties: {
+      song_id: {
+        type: 'string',
+        description: 'ID of the song you want to extend (from a previous generate_song call). Required.'
+      },
+      lyrics: {
+        type: 'string',
+        description: 'Additional lyrics for the new section(s).'
+      },
+      extra: { type: 'object', description: 'Additional parameters.' }
+    },
+    required: ['song_id']
+  },
+  async (params) => {
+    const merged = mergeExtra(params);
+    const result = await mureka.extendSong(merged);
+    return json(murekaToolResponse('extend_song', result, { source_song_id: params.song_id, song_id_input: params.song_id }, 'Assistant: tell the user the source_song_id and the new returned song_id/id exactly, plus status, local_path/local_paths, and audio_url/mp3_url. Use the new song_id for further operations.'));
+  }
+);
+
+tools.add(
+  'stem_song',
+  'Separate a song into individual stems (vocals, drums, bass, other, etc.).\n\n' +
+  'Provide the audio via `url` (public URL or base64 data URL, max 10MB). Supported formats: mp3, m4a.\n\n' +
+  'Optional `model` controls the separation quality and MIDI export support. After success, include exact stem ids, URLs, local_path/local_paths, and status in your normal response.',
+  {
+    type: 'object',
+    properties: {
+      url: {
+        type: 'string',
+        description: 'Audio URL or base64 data URL of the song to stem (required). Example: "https://...mp3" or "data:audio/mp3;base64,AAA...". Max 10MB for base64.'
+      },
+      model: {
+        type: 'string',
+        description: 'Stem separation model. "audio-separation-2" supports MIDI export; "audio-separation-1" does not.'
+      },
+      extra: { type: 'object', description: 'Additional parameters.' }
+    },
+    required: ['url']
+  },
+  async (params) => {
+    const merged = mergeExtra(params);
+    const result = await mureka.stemSong(merged);
+    return json(murekaToolResponse('stem_song', result, { source_audio_url: params.url, model: params.model }, 'Assistant: tell the user exact stem ids/URLs/local paths and status. Preserve local_path/local_paths for follow-up audio operations.'));
+  }
+);
+
+tools.add(
+  'region_edit_song',
+  'Edit only a specific time region of a song (replace lyrics or melody in a section). ' +
+  'Useful for targeted changes without regenerating the entire track. After success, include the source song_id, edited region, new returned song_id/id, local_path/local_paths, audio_url, and status in your normal response.',
+  {
+    type: 'object',
+    properties: {
+      song_id: { type: 'string', description: 'ID of the song. Required.' },
+      start_milliseconds: { type: 'number', description: 'Start time of the region in milliseconds. Required.' },
+      end_milliseconds: { type: 'number', description: 'End time of the region in milliseconds. Required.' },
+      lyrics: { type: 'string', description: 'New lyrics for the edited region.' },
+      extra: { type: 'object', description: 'Additional parameters.' }
+    },
+    required: ['song_id', 'start_milliseconds', 'end_milliseconds']
+  },
+  async (params) => {
+    const merged = mergeExtra(params);
+    const result = await mureka.regionEditSong(merged);
+    return json(murekaToolResponse('region_edit_song', result, { source_song_id: params.song_id, start_milliseconds: params.start_milliseconds, end_milliseconds: params.end_milliseconds }, 'Assistant: tell the user the source_song_id, edited region, new returned song_id/id, status, local_path/local_paths, and audio_url/mp3_url. Use the new song_id for further operations.'));
+  }
+);
+
+/* ============================================================
+   LYRICS
+   ============================================================ */
+
+tools.add(
+  'generate_lyrics',
+  'Generate brand new song lyrics from a theme or style prompt. ' +
+  'Use this when you need lyrics but don’t have any yet. After success, include the generated lyrics or durable lyric id fields exactly in your normal response.',
+  {
+    type: 'object',
+    properties: {
+      prompt: {
+        type: 'string',
+        description: 'Theme, style, mood, or specific instructions for the lyrics. ' +
+          'Example: "Write an emotional chorus about overcoming fear in the style of modern pop ballad". Required.'
+      },
+      extra: { type: 'object', description: 'Additional parameters.' }
+    },
+    required: ['prompt']
+  },
+  async (params) => {
+    const merged = mergeExtra(params);
+    const result = await mureka.generateLyrics(merged);
+    return json(murekaToolResponse('generate_lyrics', result, { prompt: params.prompt }, 'Assistant: include the generated lyrics exactly or preserve exact lyric ids/fields if returned.'));
+  }
+);
+
+tools.add(
+  'extend_lyrics',
+  'Extend or continue existing lyrics with new sections. ' +
+  'Use this when you already have some lyrics and want to build upon them. After success, include the extended lyrics exactly in your normal response.',
+  {
+    type: 'object',
+    properties: {
+      lyrics: {
+        type: 'string',
+        description: 'Existing lyrics that you want to extend. Required.'
+      },
+      prompt: {
+        type: 'string',
+        description: 'Instructions for how to extend the lyrics (e.g. "Add a bridge and final chorus"). Required.'
+      },
+      extra: { type: 'object', description: 'Additional parameters.' }
+    },
+    required: ['lyrics', 'prompt']
+  },
+  async (params) => {
+    const merged = mergeExtra(params);
+    const result = await mureka.extendLyrics(merged);
+    return json(murekaToolResponse('extend_lyrics', result, { prompt: params.prompt }, 'Assistant: include the extended lyrics exactly or preserve exact lyric ids/fields if returned.'));
+  }
+);
+
+/* ============================================================
+   FILE UPLOADS (Critical for many workflows)
+   ============================================================ */
+
+tools.add(
+  'upload_file',
+  `Upload an audio or media file so it can be used as a reference in generation calls.
+
+This is one of the most important tools. You must upload files before you can use \`reference_id\`, \`vocal_id\`, or \`motif_id\` in generate_song or oth
+er tools.
+
+**Supported purposes** (choose the most appropriate one):
+- \`reference\`: Supported format (mp3, m4a). The supported audio duration range is [30,30] seconds, excess will be trimmed.
+- \`vocal\`: Supported format (mp3, m4a). Utilizes vocal extracted from uploaded audio. The supported vocal duration range is [15,30] seconds, excess wil
+l be trimmed.
+- \`melody\`: Supported format (mp3, m4a, mid). Utilizes melody extracted from uploaded audio, uploading a MIDI file is recommended. The supported audio
+duration range is [5,60] seconds, excess will be trimmed.
+- \`instrumental\`: Supported format (mp3, m4a). The supported audio duration range is [30,30] seconds, excess will be trimmed.
+- \`voice\`: Supported format (mp3, m4a). The supported audio duration range is [5,15] seconds, excess will be trimmed.
+- \`audio\`: Supported format (mp3, m4a). A common audio file, used for song extension and similar purposes.
+- \`remix\`: Supported format (mp3, m4a). A common audio file, used for remix purposes.
+- \`soundtrack\`: Supports videos and images. Supported video format (.mp4, .mov, .avi, .mkv, .webm). Supported image format (.jpg, .jpeg, .png, .webp).
+- \`lyrics-video\`: Supported format (.jpg, .jpeg, .png). A common image file, used for lyrics video background images.
+
+After uploading, use the returned \`file_id\` in other tools. After success, include the exact file_id/upload_audio_id, original URL, and purpose in your normal response so follow-up calls can reference them.`,
+  {
+    type: 'object',
+    properties: {
+      url: {
+        type: 'string',
+        description: 'Public URL of the file you want to upload. Required.'
+      },
+      purpose: {
+        type: 'string',
+        description: 'Purpose of the upload. Must be one of the supported values listed above. Required.'
+      },
+      extra: { type: 'object', description: 'Additional parameters.' }
+    },
+    required: ['url', 'purpose']
+  },
+  async (params) => {
+    const merged = mergeExtra(params);
+    const result = await mureka.uploadFile(merged);
+    return json(murekaToolResponse('upload_file', result, { source_url: params.url, url: params.url, purpose: params.purpose }, 'Assistant: tell the user the exact file_id/upload_audio_id, source URL, and purpose. Use file_id/upload_audio_id for reference_id, vocal_id, motif_id, upload_audio_id, or other follow-up parameters as appropriate.'));
+  }
+);
+
+/* ============================================================
+   TRACK GENERATION (supports upload_audio_id from purpose=audio uploads)
+   ============================================================ */
+
+tools.add(
+  'generate_track',
+  'Generate a specific track type (Vocals, Instrumental, Drums, Bass, etc.) from a song.\n\n' +
+  'Supports either a previously generated `song_id` or an `upload_audio_id` (from upload_file with purpose="audio").\n\n' +
+  '**Required**: `type` (or `generate_type`) and `prompt`.\n' +
+  '`song_id` and `upload_audio_id` are mutually exclusive. After success, include exact source id, generated track id, local_path/local_paths, audio_url, and status in your normal response.',
+  {
+    type: 'object',
+    properties: {
+      song_id: {
+        type: 'string',
+        description: 'Song ID from a previous generate_song call (mutually exclusive with upload_audio_id). Only songs from the last 30 days are supported.'
+      },
+      upload_audio_id: {
+        type: 'string',
+        description: 'Upload ID returned by upload_file with purpose="audio" (mutually exclusive with song_id). Use this for generating tracks from your own uploaded audio.'
+      },
+      generate_type: {
+        type: 'string',
+        description: 'Type of track to generate (required). Valid values: Vocals, Instrumental, Drums, Bass, Guitar, Keyboard, Percussion, Strings, Synth, FX, Brass, Woodwinds. (Also accepts generate_type for backward compatibility)'
+      },
+      prompt: {
+        type: 'string',
+        description: 'Control prompt for track generation (required, max 1024 characters).'
+      },
+      generate_start: {
+        type: 'integer',
+        description: 'Start time of the input segment in milliseconds (optional).'
+      },
+      generate_end: {
+        type: 'integer',
+        description: 'End time of the input segment in milliseconds (optional).'
+      },
+      lyrics: {
+        type: 'string',
+        description: 'Lyrics for generated vocals (optional, max 3000 characters). Only relevant when type=Vocals.'
+      },
+      vocal_gender: {
+        type: 'string',
+        description: 'Gender of generated vocals ("male" or "female"). Only applicable when type=Vocals.'
+      },
+      extra: {
+        type: 'object',
+        description: 'Additional advanced parameters.'
+      }
+    },
+    required: ['generate_type', 'prompt']
+  },
+  async (params) => {
+    const merged = mergeExtra(params);
+    const result = await mureka.generateTrack(merged);
+    return json(murekaToolResponse('generate_track', result, { source_song_id: params.song_id, upload_audio_id_input: params.upload_audio_id, generate_type: params.generate_type, prompt: params.prompt }, 'Assistant: tell the user the source id, generated track song_id/id, status, local_path/local_paths, and audio_url/mp3_url exactly.'));
+  }
+);
+
+/* ============================================================
+   REMIX (supports upload_audio_id from purpose=remix uploads)
+   ============================================================ */
+
+tools.add(
+  'remix_song',
+  'Create a remix of an existing song using either a previously generated song_id or an upload_audio_id (from upload_file with purpose="remix").\n\n' +
+  'This is the official remix tool. Provide a strong `prompt` describing the desired style/arrangement changes and the full `lyrics` of the target song.\n\n' +
+  '**Important**: `song_id` and `upload_audio_id` are mutually exclusive. Use `upload_audio_id` when you have uploaded a song with purpose "remix". After success, include exact source id, remix song_id/id, local_path/local_paths, audio_url, and status in your normal response.',
+  {
+    type: 'object',
+    properties: {
+      song_id: {
+        type: 'string',
+        description: 'Song ID from a previous generate_song call (mutually exclusive with upload_audio_id). Only songs from the last 30 days are supported.'
+      },
+      upload_audio_id: {
+        type: 'string',
+        description: 'Upload ID returned by upload_file with purpose="remix" (mutually exclusive with song_id). Use this for remixing your own uploaded tracks.'
+      },
+      prompt: {
+        type: 'string',
+        description: 'Control prompt for the remix (required, max 1024 characters). Example: "Create a fresh, energetic 80s synth-pop remix...".'
+      },
+      lyrics: {
+        type: 'string',
+        description: 'Full lyrics for the remixed song (required, max 3000 characters). Must match the structure of the original.'
+      },
+      n: {
+        type: 'integer',
+        default: 2,
+        description: 'Number of remix variants to generate (1-3). You are charged per variant.'
+      },
+      model: {
+        type: 'string',
+        default: 'auto',
+        description: 'Model to use. Default "auto".'
+      },
+      extra: {
+        type: 'object',
+        description: 'Additional advanced parameters.'
+      }
+    },
+    required: ['prompt', 'lyrics']
+  },
+  async (params) => {
+    const merged = mergeExtra(params);
+    const result = await mureka.remixSong(merged);
+    return json(murekaToolResponse('remix_song', result, { source_song_id: params.song_id, upload_audio_id_input: params.upload_audio_id, prompt: params.prompt }, 'Assistant: tell the user the source id and new remix song_id/id exactly, plus status, local_path/local_paths, and audio_url/mp3_url. Use the new song_id for further operations.'));
+  }
+);
+
+/* ============================================================
+   VOICE & TTS
+   ============================================================ */
+
+tools.add(
+  'clone_voice',
+  'Create a custom voice clone from a short vocal sample. ' +
+  'The resulting `voice_id` can be used in generate_song (as vocal_id) or generate_speech. After success, include the exact voice_id/vocal_id in your normal response.',
+  {
+    type: 'object',
+    properties: {
+      file: {
+        type: 'string',
+        description: 'URL or base64 of the vocal sample. Best results with 5–15 seconds of clear singing or speech. Required.'
+      },
+      name: {
+        type: 'string',
+        description: 'Optional friendly name for the cloned voice.'
+      },
+      extra: { type: 'object', description: 'Additional parameters.' }
+    },
+    required: ['file']
+  },
+  async (params) => {
+    const merged = mergeExtra(params);
+    const result = await mureka.cloneVocal(merged);
+    return json(murekaToolResponse('clone_voice', result, { source_file: params.file, name: params.name }, 'Assistant: tell the user the exact voice_id/vocal_id. Use it as vocal_id in generate_song or voice_id in generate_speech.'));
+  }
+);
+
+tools.add(
+  'generate_speech',
+  'Convert text into natural-sounding speech. Supports both single-speaker TTS and multi-speaker podcasts. After success, include exact speech id, local_path/local_paths, audio_url, and status in your normal response.',
+  {
+    type: 'object',
+    properties: {
+      text: {
+        type: 'string',
+        description: 'Text to convert to speech (for single-speaker mode). Mutually exclusive with script.'
+      },
+      script: {
+        type: 'array',
+        description: 'Array of objects for podcast mode: [{ speaker: "Host", text: "..." }]. Mutually exclusive with text.'
+      },
+      voice_id: {
+        type: 'string',
+        description: 'Voice ID to use (from clone_voice or default voices). Required for single-speaker.'
+      },
+      voices: {
+        type: 'object',
+        description: 'Map of speaker names to voice_ids for podcast mode. Example: { "Host": "voice_123" }'
+      },
+      speed: { type: 'number', default: 1.0, description: 'Speech speed multiplier (0.5 – 2.0).' },
+      pitch: { type: 'number', default: 0, description: 'Pitch shift in semitones.' },
+      extra: { type: 'object', description: 'Additional parameters.' }
+    }
+  },
+  async (params) => {
+    const merged = mergeExtra(params);
+    const result = await mureka.generateTTS(merged);
+    return json(murekaToolResponse('generate_speech', result, { voice_id_input: params.voice_id, voices: params.voices }, 'Assistant: tell the user the exact speech id, status, local_path/local_paths, and audio_url/mp3_url. Preserve voice_id references used.'));
+  }
+);
+
+/* ============================================================
+   ACCOUNT & TASKS
+   ============================================================ */
+
+tools.add(
+  'get_billing',
+  'Retrieve current account billing information (balance, credits, usage). ' +
+  'Useful before starting large generation jobs.',
+  {
+    type: 'object',
+    properties: {}
+  },
+  async () => {
+    const result = await mureka.getBilling();
+    return json(murekaToolResponse('get_billing', result, {}, 'Assistant: report exact remaining balance/credits and any relevant limits from the billing result.'));
+  }
+);
+
+tools.add(
+  'query_task',
+  'Manually check the status of an async task. ' +
+  'Most tools now auto-wait, so this is mainly useful for manual control or debugging. After success, include exact task_id, status, local_path/local_paths, audio_url, and any final song_id/id in your normal response.',
+  {
+    type: 'object',
+    properties: {
+      task_id: { type: 'string', description: 'Task ID to query. Required.' },
+      type: { type: 'string', default: 'song', description: 'Task type (song, instrumental, tts, etc.).' }
+    },
+    required: ['task_id']
+  },
+  async (params) => {
+    const result = await mureka.queryTask(params.task_id, params.type || 'song');
+    return json(murekaToolResponse('query_task', result, { task_id_input: params.task_id, task_type: params.type || 'song' }, 'Assistant: tell the user the exact task_id, status, and any final song_id/id, local_path/local_paths, or audio_url/mp3_url returned.'));
+  }
+);
+
+export default tools;

package/lib/API/mureka/README.md

@@ -0,0 +1,41 @@
+# Mureka Music API Wrapper
+
+**`lib/API/mureka/music.js`** — A thin, production-ready JavaScript wrapper for the official Mureka AI Music API.
+
+## Important Notice
+
+**All local documentation has been removed.**
+
+This project now **only references the official online documentation**.
+
+**Official Documentation**: https://platform.mureka.ai/docs/
+
+Please refer to the official site for:
+
+- Complete API reference
+- All endpoint parameters and return values
+- Authentication, rate limits, and best practices
+- Supported models and features
+
+---
+
+## Quick Start
+
+```js
+import * as mureka from './lib/API/mureka/music.js';
+
+process.env.MUREKA_API_KEY = 'your_key_here';
+
+const result = await mureka.generateSong({
+  prompt: "Upbeat indie pop, energetic, summer road trip vibe"
+});
+
+console.log(result);
+```
+
+For full usage examples and parameter details, see the official documentation linked above.
+
+---
+
+**Source**: `lib/API/mureka/music.js`  
+**ToolSet**: `lib/API/mureka/MusicToolset.js` (for AI agents)