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

package/lib/API/minimax/music.generation.md

@@ -0,0 +1,346 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://platform.minimax.io/docs/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Music Generation
+
+> Use this API to generate a song from lyrics and a prompt.
+
+
+## OpenAPI
+
+````yaml POST /v1/music_generation
+openapi: 3.1.0
+info:
+  title: MiniMax Music Generation API
+  description: >-
+    MiniMax music generation API with support for creating music from text
+    prompts and lyrics
+  license:
+    name: MIT
+  version: 1.0.0
+servers:
+  - url: https://api.minimax.io
+security:
+  - bearerAuth: []
+paths:
+  /v1/music_generation:
+    post:
+      tags:
+        - Music
+      summary: Music Generation
+      operationId: generateMusic
+      parameters:
+        - name: Content-Type
+          in: header
+          required: true
+          description: >-
+            The media type of the request body. Must be set to
+            `application/json` to ensure the data is sent in JSON format.
+          schema:
+            type: string
+            enum:
+              - application/json
+            default: application/json
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/GenerateMusicReq'
+        required: true
+      responses:
+        '200':
+          description: ''
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/GenerateMusicResp'
+components:
+  schemas:
+    GenerateMusicReq:
+      type: object
+      required:
+        - model
+      properties:
+        model:
+          type: string
+          description: >-
+            The model name. Options:
+
+
+            - `music-2.6` (recommended): Text-to-music generation. Available to
+            Token Plan and paid users only, with higher RPM.
+
+            - `music-cover`: Cover generation from a reference audio. Available
+            to Token Plan and paid users only, with higher RPM.
+
+            - `music-2.6-free`: Free-tier version of `music-2.6`. Available to
+            all users via API Key, with lower RPM.
+
+            - `music-cover-free`: Free-tier version of `music-cover`. Available
+            to all users via API Key, with lower RPM.
+          enum:
+            - music-2.6
+            - music-cover
+            - music-2.6-free
+            - music-cover-free
+        prompt:
+          type: string
+          description: >-
+            A description of the music, specifying style, mood, and scenario.
+
+
+            For example: "`Pop, melancholic, perfect for a rainy night`".
+
+            <br>
+
+            Note:
+
+            - For `music-2.6` / `music-2.6-free` with `is_instrumental: true`:
+            Required. Length: 1–2000 characters.
+
+            - For `music-2.6` / `music-2.6-free` (non-instrumental): Optional.
+            Length: 0–2000 characters.
+
+            - For `music-cover` / `music-cover-free`: Required. Describes the
+            target cover style. Length: 10–300 characters.
+          maxLength: 2000
+        lyrics:
+          type: string
+          description: >-
+            Song lyrics, using `\n` to separate lines. Supports structure tags:
+            `[Intro]`, `[Verse]`, `[Pre Chorus]`, `[Chorus]`, `[Interlude]`,
+            `[Bridge]`, `[Outro]`, `[Post Chorus]`, `[Transition]`, `[Break]`,
+            `[Hook]`, `[Build Up]`, `[Inst]`, `[Solo]`.
+
+            <br>
+
+            Note:
+
+            - For `music-2.6` / `music-2.6-free` with `is_instrumental: true`:
+            Not required.
+
+            - For `music-2.6` / `music-2.6-free` (non-instrumental): Required.
+            Length: 1–3500 characters.
+
+            - For `music-cover` / `music-cover-free`: Optional. If omitted,
+            lyrics are automatically extracted from the reference audio via ASR.
+            Length: 10–1000 characters.
+
+            - When `lyrics_optimizer: true` and `lyrics` is empty, the system
+            will auto-generate lyrics from `prompt`.
+          minLength: 1
+          maxLength: 3500
+        stream:
+          type: boolean
+          description: Whether to use streaming output.
+          default: false
+        output_format:
+          type: string
+          description: |-
+            The output format of the audio. Options: `url` or `hex`.
+
+            When `stream` is `true`, only `hex` is supported.
+
+            ⚠️ Note: `url` links expire after 24 hours, so download promptly.
+          enum:
+            - url
+            - hex
+          default: hex
+        audio_setting:
+          $ref: '#/components/schemas/AudioSetting'
+        lyrics_optimizer:
+          type: boolean
+          description: >-
+            Whether to automatically generate lyrics based on the `prompt`
+            description. Only supported on `music-2.6` / `music-2.6-free`.
+
+
+            When set to `true` and `lyrics` is empty, the system will
+            automatically generate lyrics from the prompt. Default: `false`.
+          default: false
+        is_instrumental:
+          type: boolean
+          description: >-
+            Whether to generate instrumental music (no vocals). Only supported
+            on `music-2.6` / `music-2.6-free`.
+
+
+            When set to `true`, the `lyrics` field is not required. Default:
+            `false`.
+          default: false
+        audio_url:
+          type: string
+          description: >-
+            URL of the reference audio. Only used with `music-cover` /
+            `music-cover-free` model. Exactly one of `audio_url` or
+            `audio_base64` must be provided. Mutually exclusive with
+            `cover_feature_id`.
+
+
+            Reference audio constraints:
+
+            - Duration: 6 seconds to 6 minutes
+
+            - Size: max 50 MB
+
+            - Format: common audio formats (mp3, wav, flac, etc.)
+        audio_base64:
+          type: string
+          description: >-
+            Base64-encoded reference audio. Only used with `music-cover` /
+            `music-cover-free` model. Exactly one of `audio_url` or
+            `audio_base64` must be provided. Mutually exclusive with
+            `cover_feature_id`.
+
+
+            Reference audio constraints:
+
+            - Duration: 6 seconds to 6 minutes
+
+            - Size: max 50 MB
+
+            - Format: common audio formats (mp3, wav, flac, etc.)
+        cover_feature_id:
+          type: string
+          description: >-
+            Feature ID returned by the [Music Cover
+            Preprocess](/api-reference/music-cover-preprocess) API. Used in the
+            **two-step cover workflow** to generate a cover with modified
+            lyrics.
+
+
+            Only used with `music-cover` / `music-cover-free` model. Mutually
+            exclusive with `audio_url` and `audio_base64`.
+
+
+            - When provided, `lyrics` is required (length: 10–1000 characters)
+
+            - The `cover_feature_id` is valid for 24 hours
+
+            - Same audio content returns the same `cover_feature_id`
+      example:
+        model: music-2.6
+        prompt: >-
+          Indie folk, melancholic, introspective, longing, solitary walk, coffee
+          shop
+        lyrics: |-
+          [verse]
+          Streetlights flicker, the night breeze sighs
+          Shadows stretch as I walk alone
+          An old coat wraps my silent sorrow
+          Wandering, longing, where should I go
+          [chorus]
+          Pushing the wooden door, the aroma spreads
+          In a familiar corner, a stranger gazes
+        audio_setting:
+          sample_rate: 44100
+          bitrate: 256000
+          format: mp3
+    GenerateMusicResp:
+      type: object
+      properties:
+        data:
+          $ref: '#/components/schemas/MusicData'
+        base_resp:
+          $ref: '#/components/schemas/BaseResp'
+      example:
+        data:
+          audio: hex-encoded audio data
+          status: 2
+        trace_id: 04ede0ab069fb1ba8be5156a24b1e081
+        extra_info:
+          music_duration: 25364
+          music_sample_rate: 44100
+          music_channel: 2
+          bitrate: 256000
+          music_size: 813651
+        analysis_info: null
+        base_resp:
+          status_code: 0
+          status_msg: success
+    AudioSetting:
+      type: object
+      description: Audio output configuration
+      properties:
+        sample_rate:
+          type: integer
+          description: 'Sampling rate. Options: `16000`, `24000`, `32000`, `44100`.'
+        bitrate:
+          type: integer
+          description: 'Bitrate. Options: `32000`, `64000`, `128000`, `256000`.'
+        format:
+          type: string
+          description: 'Audio format. Options: `mp3`, `wav`, `pcm`.'
+          enum:
+            - mp3
+            - wav
+            - pcm
+    MusicData:
+      type: object
+      properties:
+        status:
+          type: integer
+          description: |-
+            Music generation status:
+
+            1: In progress
+
+            2: Completed
+        audio:
+          type: string
+          description: |-
+            Returned when `output_format` is `hex`.
+
+            Contains the audio file as a hexadecimal-encoded string.
+    BaseResp:
+      type: object
+      description: Status code and details
+      properties:
+        status_code:
+          type: integer
+          description: >-
+            Status codes and their meanings:
+
+
+            `0`: Success
+
+
+            `1002`: Rate limit triggered, retry later
+
+
+            `1004`: Authentication failed, check API key
+
+
+            `1008`: Insufficient balance
+
+
+            `1026`: Content flagged for sensitive material
+
+
+            `2013`: Invalid parameters, check input
+
+
+            `2049`: Invalid API key
+
+
+            For more information, please refer to the [Error Code
+            Reference](/api-reference/errorcode).
+        status_msg:
+          type: string
+          description: Detailed error message
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT
+      description: >-
+        `HTTP: Bearer Auth`
+
+        - Security Scheme Type: http
+
+        - HTTP Authorization Scheme: `Bearer API_key`, can be found in [Account
+        Management>API
+        Keys](https://platform.minimax.io/user-center/basic-information/interface-key).
+
+````

package/lib/API/minimax/music.js

@@ -0,0 +1,257 @@
+/**
+ * @file lib/API/minimax/music.js
+ * @module minimax/music
+ * @description Pure HTTP wrapper for the Minimax Music Generation API.
+ *              Fully aligned with the official documentation:
+ *              - lib/API/minimax/music.generation.md
+ *              - lib/API/minimax/music.cover.preprocess.md
+ *              - lib/API/minimax/music.lyrics.generation.md
+ *
+ *              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
+ *              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.
+ */
+
+import { request as doRequest } from '@j-o-r/apiserver';
+import fs from 'fs/promises';
+import path from 'path';
+
+const BASE_URL = 'https://api.minimax.io/v1';
+
+const TMP_DIR = path.join(process.cwd(), '.cache', 'minimax');
+
+const getHeaders = () => {
+  if (!process.env.MINIMAX_API_KEY) {
+    throw new Error('Missing MINIMAX_API_KEY! Please export MINIMAX_API_KEY=your_key');
+  }
+  return {
+    'Content-Type': 'application/json',
+    'Authorization': `Bearer ${process.env.MINIMAX_API_KEY}`
+  };
+};
+
+async function saveAudioToLocal(audioData, filenamePrefix = 'minimax-music') {
+  const tmpDir = path.join(process.cwd(), '.cache', 'minimax');
+  await fs.mkdir(tmpDir, { recursive: true });
+
+  const filename = `${filenamePrefix}-${Date.now()}.mp3`;
+  const localPath = path.join(tmpDir, filename);
+
+  if (audioData.startsWith('http')) {
+    const response = await fetch(audioData);
+    if (!response.ok) {
+      throw new Error(`Failed to download audio: ${response.status} ${response.statusText}`);
+    }
+    const buffer = Buffer.from(await response.arrayBuffer());
+    await fs.writeFile(localPath, buffer);
+  } else {
+    const buffer = Buffer.from(audioData, 'hex');
+    await fs.writeFile(localPath, buffer);
+  }
+
+  return localPath;
+}
+
+/* ============================================================
+   WORKFLOW 1: CREATE MUSIC (Text-to-Music)
+   ============================================================ */
+
+async function createMusic(prompt, options = {}) {
+  const model = options.model || 'music-2.6';
+
+  if (options.audio_url || options.audio_base64 || options.cover_feature_id) {
+    throw new Error(
+      'createMusic() does not support reference audio. ' +
+      'Use changeMusic() for covers or analyzeMusic() for preprocessing.'
+    );
+  }
+
+  if (!['music-2.6', 'music-2.6-free'].includes(model)) {
+    throw new Error(
+      `createMusic() expects model 'music-2.6' or 'music-2.6-free'. Got: ${model}. ` +
+      'Use changeMusic() for cover models.'
+    );
+  }
+
+  return requestMusicInternal(prompt, { ...options, model });
+}
+
+/* ============================================================
+   WORKFLOW 2: CHANGE MUSIC (Cover / Reference-based)
+   ============================================================ */
+
+async function changeMusic(prompt, options = {}) {
+  const model = options.model || 'music-cover';
+
+  if (!['music-cover', 'music-cover-free'].includes(model)) {
+    throw new Error(
+      `changeMusic() expects model 'music-cover' or 'music-cover-free'. Got: ${model}. ` +
+      'Use createMusic() for text-to-music.'
+    );
+  }
+
+  const hasAudioRef = !!(options.audio_url || options.audio_base64);
+  const hasFeatureId = !!options.cover_feature_id;
+
+  if (hasAudioRef && hasFeatureId) {
+    throw new Error(
+      'Invalid parameters for changeMusic(): audio_url/audio_base64 and cover_feature_id are mutually exclusive.\n' +
+      '• Use audio_url or audio_base64 for direct one-step cover.\n' +
+      '• Use cover_feature_id (from analyzeMusic()) for two-step cover with modified lyrics.'
+    );
+  }
+
+  if (!hasAudioRef && !hasFeatureId) {
+    throw new Error(
+      'changeMusic() requires a reference: provide either audio_url/audio_base64 or cover_feature_id.'
+    );
+  }
+
+  return requestMusicInternal(prompt, { ...options, model });
+}
+
+/* ============================================================
+   WORKFLOW 3: ANALYZE MUSIC (Preprocess for Cover)
+   ============================================================ */
+
+async function analyzeMusic(audioUrl, options = {}) {
+  return preprocessCoverInternal(audioUrl, options);
+}
+
+/* ============================================================
+   WORKFLOW 4: GENERATE LYRICS (New)
+   ============================================================ */
+
+/**
+ * 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]
+ *
+ * @returns {Promise<{song_title: string, style_tags: string, lyrics: string, raw: object}>}
+ */
+async function generateLyrics(prompt, options = {}) {
+  const headers = getHeaders();
+  const url = `${BASE_URL}/lyrics_generation`;
+
+  const body = {
+    mode: options.mode || 'write_full_song',
+    prompt: prompt || '',
+    ...(options.lyrics && { lyrics: options.lyrics }),
+    ...(options.title && { title: options.title })
+  };
+
+  const res = await doRequest(url, 'POST', headers, body);
+
+  if (res.status !== 200) {
+    throw new Error(`Minimax lyrics error ${res.status}: ${JSON.stringify(res.response)}`);
+  }
+
+  return {
+    song_title: res.response?.song_title,
+    style_tags: res.response?.style_tags,
+    lyrics: res.response?.lyrics,
+    raw: res.response
+  };
+}
+
+/* ============================================================
+   INTERNAL IMPLEMENTATION
+   ============================================================ */
+
+async function requestMusicInternal(prompt, options = {}) {
+  const headers = getHeaders();
+  const url = `${BASE_URL}/music_generation`;
+
+  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'
+    },
+    lyrics_optimizer: options.lyrics_optimizer ?? false,
+    is_instrumental: options.is_instrumental ?? false,
+    ...options.extra
+  };
+
+  if (options.lyrics && options.lyrics.trim() !== '') {
+    body.lyrics = options.lyrics;
+  }
+
+  if (options.audio_url) body.audio_url = options.audio_url;
+  if (options.audio_base64) body.audio_base64 = options.audio_base64;
+  if (options.cover_feature_id) body.cover_feature_id = options.cover_feature_id;
+
+  const start = Date.now();
+  const res = await doRequest(url, 'POST', headers, body);
+  const duration = Date.now() - start;
+
+  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 localPath = await saveAudioToLocal(audioData);
+
+  return {
+    audio_url: audioData,
+    local_path: localPath,
+    duration,
+    raw: res.response
+  };
+}
+
+async function preprocessCoverInternal(audioUrl, options = {}) {
+  const headers = getHeaders();
+  const url = `${BASE_URL}/music_cover_preprocess`;
+
+  const body = {
+    model: options.model || 'music-cover',
+    audio_url: audioUrl,
+    ...options
+  };
+
+  const start = Date.now();
+  const res = await doRequest(url, 'POST', headers, body);
+  const duration = Date.now() - start;
+
+  if (res.status !== 200) {
+    throw new Error(`Minimax preprocess error ${res.status}: ${JSON.stringify(res.response)}`);
+  }
+
+  return {
+    cover_feature_id: res.response?.cover_feature_id,
+    formatted_lyrics: res.response?.formatted_lyrics,
+    structure_result: res.response?.structure_result,
+    audio_duration: res.response?.audio_duration,
+    trace_id: res.response?.trace_id,
+    raw: res.response
+  };
+}
+
+export {
+  getHeaders,
+  saveAudioToLocal,
+  createMusic,
+  changeMusic,
+  analyzeMusic,
+  generateLyrics
+};