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

package/lib/API/minimax/music.js

@@ -9,13 +9,18 @@
  *
  *              This is a clean library with four distinct workflows:
  *              1. createMusic()   → text-to-music (music-2.6 / music-2.6-free)
- *              2. changeMusic()   → cover generation (music-cover / music-cover-free)
- *              3. analyzeMusic()  → preprocess reference for two-step covers
+ *              2. changeMusic()   → cover generation (music-cover) — model fixed to 'music-cover'
+ *              3. analyzeMusic()  → preprocess reference for two-step covers (model fixed to 'music-cover')
  *              4. generateLyrics() → create or edit song lyrics
  *
  *              Notes on parameters:
  *              - Lyrics are optional for both instrumental and non-instrumental generation.
  *              - Streaming is not supported; stream is always false.
+ *              - All functions use environment variable MINIMAX_API_KEY for auth.
+ *              - Generated audio is automatically saved to .cache/minimax/ as MP3.
+ *              - For music-cover models: prompt max 300 characters (enforced).
+ *              - audio_setting is fixed internally (44100 Hz, 256 kbps, mp3) — no user override.
+ *              - Model for changeMusic() and analyzeMusic() is fixed to 'music-cover' (no free variant).
  */
 
 import { request as doRequest } from '@j-o-r/apiserver';
@@ -26,6 +31,12 @@ const BASE_URL = 'https://api.minimax.io/v1';
 
 const TMP_DIR = path.join(process.cwd(), '.cache', 'minimax');
 
+/**
+ * Get authentication headers for Minimax API.
+ *
+ * @returns {Object} Headers object with Authorization Bearer token.
+ * @throws {Error} If MINIMAX_API_KEY environment variable is not set.
+ */
 const getHeaders = () => {
   if (!process.env.MINIMAX_API_KEY) {
     throw new Error('Missing MINIMAX_API_KEY! Please export MINIMAX_API_KEY=your_key');
@@ -36,6 +47,13 @@ const getHeaders = () => {
   };
 };
 
+/**
+ * Saves audio data (URL or hex) to a local temporary MP3 file.
+ *
+ * @param {string} audioData - Either a URL or hex-encoded audio data.
+ * @param {string} [filenamePrefix='minimax-music'] - Prefix for the local filename.
+ * @returns {Promise<string>} Absolute path to the saved local file.
+ */
 async function saveAudioToLocal(audioData, filenamePrefix = 'minimax-music') {
   const tmpDir = path.join(process.cwd(), '.cache', 'minimax');
   await fs.mkdir(tmpDir, { recursive: true });
@@ -62,6 +80,47 @@ async function saveAudioToLocal(audioData, filenamePrefix = 'minimax-music') {
    WORKFLOW 1: CREATE MUSIC (Text-to-Music)
    ============================================================ */
 
+/**
+ * Generate music from a text prompt (text-to-music workflow).
+ *
+ * Uses models `music-2.6` or `music-2.6-free`.
+ * Does NOT support reference audio (use changeMusic() or analyzeMusic() instead).
+ *
+ * @param {string} prompt - Description of the music (style, mood, scenario). Max 2000 chars.
+ * @param {Object} [options={}] - Generation options.
+ *
+ * @param {string} [options.model='music-2.6'] - Model to use.
+ *   - 'music-2.6' (default, recommended, higher RPM)
+ *   - 'music-2.6-free' (free tier, lower RPM)
+ *
+ * @param {string} [options.lyrics] - Song lyrics with structure tags (e.g. [Verse], [Chorus]).
+ *   Required for non-instrumental. Max 3500 chars.
+ *
+ * @param {boolean} [options.is_instrumental=false] - Generate instrumental music (no vocals).
+ *   When true, lyrics are optional.
+ *
+ * @param {boolean} [options.lyrics_optimizer=false] - Auto-generate lyrics from prompt when lyrics is empty.
+ *
+ * @param {string} [options.output_format='url'] - 'url' or 'hex'. URL links expire after 24h.
+ *
+ * @param {Object} [options.extra] - Any additional undocumented parameters.
+ *
+ * @returns {Promise<{
+ *   audio_url: string,      // Original URL or hex data
+ *   local_path: string,     // Path in .cache/minimax/
+ *   duration: number,       // API call time in ms
+ *   raw: object             // Full API response
+ * }>}
+ *
+ * @throws {Error} If reference audio params are provided or invalid model.
+ *
+ * @example
+ * const result = await createMusic("Indie folk, melancholic", {
+ *   model: "music-2.6",
+ *   lyrics: "[Verse]\n...",
+ *   is_instrumental: false
+ * });
+ */
 async function createMusic(prompt, options = {}) {
   const model = options.model || 'music-2.6';
 
@@ -79,25 +138,85 @@ async function createMusic(prompt, options = {}) {
     );
   }
 
+  // Note: create allows up to 2000 chars; no strict enforcement here
   return requestMusicInternal(prompt, { ...options, model });
 }
 
 /* ============================================================
-   WORKFLOW 2: CHANGE MUSIC (Cover / Reference-based)
+   WORKFLOW 2: CHANGE MUSIC (Cover / Reference-based) — MODEL FIXED
    ============================================================ */
 
+/**
+ * Generate a cover version of reference music (music-cover workflow).
+ *
+ * **Model is fixed to 'music-cover'** (the recommended paid model).
+ * The free variant ('music-cover-free') is not supported for changeMusic().
+ *
+ * Requires either direct reference audio OR a preprocessed cover_feature_id.
+ *
+ * **Critical rule for two-step covers (cover_feature_id)**:
+ *   - When `cover_feature_id` is used **and** `is_instrumental` is false (non-instrumental),
+ *     the `lyrics` parameter is **mandatory**.
+ *   - When using direct `audio_url`/`audio_base64`, lyrics are optional (API can extract via ASR).
+ *
+ * **Prompt limit**: Max 300 characters (strictly enforced for music-cover models).
+ * **audio_setting**: Fixed internally to { sample_rate: 44100, bitrate: 256000, format: 'mp3' }.
+ *   User-provided audio_setting is ignored.
+ *
+ * @param {string} prompt - Description of the target cover style. Max 300 chars.
+ * @param {Object} [options={}] - Generation options (model is ignored — always 'music-cover').
+ *
+ * @param {string} [options.audio_url] - URL of reference audio (6s–6min, ≤50MB).
+ *   Mutually exclusive with cover_feature_id.
+ *
+ * @param {string} [options.audio_base64] - Base64 reference audio (alternative to audio_url).
+ *
+ * @param {string} [options.cover_feature_id] - Feature ID from analyzeMusic() for two-step covers.
+ *   **Requires lyrics** when is_instrumental=false. Valid for 24h. Mutually exclusive with audio refs.
+ *
+ * @param {string} [options.lyrics] - Lyrics for the cover (mandatory for cover_feature_id + non-instrumental).
+ *
+ * @param {boolean} [options.lyrics_optimizer=false] - Auto-generate lyrics from prompt.
+ *
+ * @param {string} [options.output_format='url'] - 'url' or 'hex'.
+ *
+ * @param {Object} [options.extra] - Additional parameters.
+ *
+ * @returns {Promise<{audio_url: string, local_path: string, duration: number, raw: object}>}
+ *
+ * @throws {Error} On missing reference, conflicting params, prompt > 300 chars, or missing lyrics for two-step non-instrumental.
+ *
+ * @example
+ * // One-step cover
+ * const result = await changeMusic("Pop cover style", {
+ *   audio_url: "https://example.com/reference.mp3"
+ * });
+ *
+ * @example
+ * // Two-step cover (after analyzeMusic) — lyrics REQUIRED
+ * const result = await changeMusic("New lyrics style", {
+ *   cover_feature_id: "abc123...",
+ *   lyrics: "[Verse]\nNew lyrics...",
+ *   is_instrumental: false
+ * });
+ */
 async function changeMusic(prompt, options = {}) {
-  const model = options.model || 'music-cover';
+  // Model is FIXED to 'music-cover' — ignore any provided value
+  const model = 'music-cover';
 
-  if (!['music-cover', 'music-cover-free'].includes(model)) {
+  // Enforce prompt length for cover models
+  if (prompt && typeof prompt === 'string' && prompt.length > 300) {
     throw new Error(
-      `changeMusic() expects model 'music-cover' or 'music-cover-free'. Got: ${model}. ` +
-      'Use createMusic() for text-to-music.'
+      `changeMusic() prompt too long: ${prompt.length} characters. ` +
+      'music-cover models require prompt ≤ 300 characters. ' +
+      'Shorten your prompt (e.g. remove extra fidelity instructions).'
     );
   }
 
   const hasAudioRef = !!(options.audio_url || options.audio_base64);
   const hasFeatureId = !!options.cover_feature_id;
+  const isInstrumental = options.is_instrumental === true;
+  const hasLyrics = !!(options.lyrics && options.lyrics.trim() !== '');
 
   if (hasAudioRef && hasFeatureId) {
     throw new Error(
@@ -113,13 +232,44 @@ async function changeMusic(prompt, options = {}) {
     );
   }
 
+  // NEW: Enforce mandatory lyrics for two-step non-instrumental covers
+  if (hasFeatureId && !isInstrumental && !hasLyrics) {
+    throw new Error(
+      'changeMusic() with cover_feature_id requires the "lyrics" parameter ' +
+      'when is_instrumental is false (non-instrumental cover). ' +
+      'Provide structured lyrics or set is_instrumental: true.'
+    );
+  }
+
   return requestMusicInternal(prompt, { ...options, model });
 }
 
 /* ============================================================
-   WORKFLOW 3: ANALYZE MUSIC (Preprocess for Cover)
+   WORKFLOW 3: ANALYZE MUSIC (Preprocess for Cover) — MODEL FIXED
    ============================================================ */
 
+/**
+ * Preprocess a reference audio to extract features and structured lyrics.
+ *
+ * Used for the two-step cover workflow (analyze → changeMusic with cover_feature_id).
+ * **Model is fixed to 'music-cover'**.
+ *
+ * @param {string} audioUrl - URL of the reference audio (6s–6min, ≤50MB).
+ * @param {Object} [options={}] - Optional parameters (model is ignored).
+ *
+ * @returns {Promise<{
+ *   cover_feature_id: string,   // Valid 24h, use in changeMusic()
+ *   formatted_lyrics: string,   // Structured lyrics with [Verse] etc.
+ *   structure_result: string,   // JSON song structure analysis
+ *   audio_duration: number,
+ *   trace_id: string,
+ *   raw: object
+ * }>}
+ *
+ * @example
+ * const analysis = await analyzeMusic("https://example.com/song.mp3");
+ * // Then pass analysis.cover_feature_id to changeMusic()
+ */
 async function analyzeMusic(audioUrl, options = {}) {
   return preprocessCoverInternal(audioUrl, options);
 }
@@ -131,13 +281,34 @@ async function analyzeMusic(audioUrl, options = {}) {
 /**
  * Generate complete song lyrics or edit/continue existing lyrics.
  *
- * @param {string} prompt - Theme, style, or editing instruction.
- * @param {Object} [options]
- * @param {'write_full_song'|'edit'} [options.mode='write_full_song']
- * @param {string} [options.lyrics] - Existing lyrics (required for edit mode)
- * @param {string} [options.title]
+ * @param {string} prompt - Theme, style, or editing instruction. Max 2000 chars.
+ * @param {Object} [options={}] - Lyrics options.
  *
- * @returns {Promise<{song_title: string, style_tags: string, lyrics: string, raw: object}>}
+ * @param {'write_full_song'|'edit'} [options.mode='write_full_song'] - Generation mode.
+ *   - 'write_full_song': Create a new complete song.
+ *   - 'edit': Edit or continue existing lyrics (requires options.lyrics).
+ *
+ * @param {string} [options.lyrics] - Existing lyrics (required for 'edit' mode). Max 3500 chars.
+ *
+ * @param {string} [options.title] - Desired song title (preserved if provided).
+ *
+ * @returns {Promise<{
+ *   song_title: string,
+ *   style_tags: string,     // Comma-separated tags
+ *   lyrics: string,         // Structured lyrics ready for music generation
+ *   raw: object
+ * }>}
+ *
+ * @example
+ * // Full song
+ * const lyrics = await generateLyrics("Cheerful love song about summer beach");
+ *
+ * @example
+ * // Edit mode
+ * const edited = await generateLyrics("Make it more upbeat", {
+ *   mode: "edit",
+ *   lyrics: existingLyrics
+ * });
  */
 async function generateLyrics(prompt, options = {}) {
   const headers = getHeaders();
@@ -168,20 +339,30 @@ async function generateLyrics(prompt, options = {}) {
    INTERNAL IMPLEMENTATION
    ============================================================ */
 
+/**
+ * Internal helper for music generation (used by createMusic and changeMusic).
+ * Builds the request body with explicit defaults and calls the API.
+ * audio_setting is ALWAYS the fixed value (no user override).
+ *
+ * @private
+ */
 async function requestMusicInternal(prompt, options = {}) {
   const headers = getHeaders();
   const url = `${BASE_URL}/music_generation`;
 
+  // Fixed audio_setting — user-provided values are ignored
+  const fixedAudioSetting = {
+    sample_rate: 44100,
+    bitrate: 256000,
+    format: 'mp3'
+  };
+
   const body = {
     model: options.model || 'music-2.6',
     prompt: prompt,
     stream: false, // Streaming is not supported; always false
     output_format: options.output_format || 'url',
-    audio_setting: options.audio_setting || {
-      sample_rate: 44100,
-      bitrate: 256000,
-      format: 'mp3'
-    },
+    audio_setting: fixedAudioSetting,
     lyrics_optimizer: options.lyrics_optimizer ?? false,
     is_instrumental: options.is_instrumental ?? false,
     ...options.extra
@@ -202,11 +383,11 @@ async function requestMusicInternal(prompt, options = {}) {
   if (res.status !== 200) {
     throw new Error(`Minimax API error ${res.status}: ${JSON.stringify(res.response)}`);
   }
-
   const audioData = res.response?.data?.audio;
 
   if (!audioData) {
-    throw new Error('No audio data found in data.audio of Minimax response');
+    const resStr = JSON.stringify(res.response, null, '  ');
+    throw new Error(`No audio data found in data.audio of Minimax response:\n${resStr}`);
   }
 
   const localPath = await saveAudioToLocal(audioData);
@@ -219,12 +400,18 @@ async function requestMusicInternal(prompt, options = {}) {
   };
 }
 
+/**
+ * Internal helper for music cover preprocessing.
+ *
+ * @private
+ */
 async function preprocessCoverInternal(audioUrl, options = {}) {
   const headers = getHeaders();
   const url = `${BASE_URL}/music_cover_preprocess`;
 
+  // Model is fixed to 'music-cover' for analyzeMusic
   const body = {
-    model: options.model || 'music-cover',
+    model: 'music-cover',
     audio_url: audioUrl,
     ...options
   };
@@ -254,4 +441,4 @@ export {
   changeMusic,
   analyzeMusic,
   generateLyrics
-};
+};