--- name: music-craft-minimax version: 1.5.0 description: Advanced music generation for OpenClaw, using the MiniMax Music 2.6 token plan. Use for cover and style transfer, two-song mashup, lyrics generation API, emotion-driven prompt engineering, and fine control via the `mmx` CLI. Extends `music-craft` with MiniMax-specific features. metadata: '{"openclaw":{"requires":{"env":["MINIMAX_API_KEY"],"bins":["python3","ffmpeg","mmx"]},"primaryEnv":"MINIMAX_API_KEY","emoji":"\ud83c\udfb6","homepage":"https://github.com/LuisCharro/skills/tree/main/publish/music-craft-minimax","envVars":[{"name":"MINIMAX_API_KEY","required":true,"description":"API key for the MiniMax Music 2.6 token plan. Required for cover, mashup, lyrics generation, and mmx flag control."}]}}' --- # Music Craft — MiniMax **Cloud duration is approximate.** Verified field run (2026-06-12): 18/18 cloud jobs saved an MP3, but output length ranged from 57-135% of requested duration (12 truncated, 3 close, 3 extended). Use `music-craft` with local ACE-Step when exact duration matters; use this skill when speed, MiniMax cover workflows, lyrics API, emotion analysis, or `mmx` flag control matter more. This is the **power-user upgrade** of [`music-craft`](../music-craft/). It does everything that skill does, plus the features that require the MiniMax Music 2.6 token plan: - **Cover and style transfer** from a reference audio file (preserves melody) - **Two-song mashup** (Song A's content and emotion + Song B's style) - **Lyrics generation** via the MiniMax API endpoint (with edit mode for iteration) - **Emotion analysis** on input audio to drive prompt construction (vocal speed, intensity curve, pitch bends) - **Fine control** over generation parameters (BPM, key, structure, avoid list as separate flags via `mmx`) For everything else (standard song generation, instrumentation, anti-sparse prompt engineering, structure tags, user preference flow), this skill uses the same workflow as `music-craft`. Read that skill first to understand the base, then come back here for the MiniMax-specific extensions. ## Data, Consent, and Local Side Effects This skill is allowed to process music media, but it should not surprise the user: - **Cloud generation:** prompts, lyrics, reference audio, and cover/mashup inputs may be sent to MiniMax through `mmx` or MiniMax API calls. Confirm consent before sending sensitive, private, or third-party-owned audio. - **Local files only:** audio input must be a local file path. URLs are not accepted in v1.5.0+; use the private `music-source-fetch` skill to fetch audio by title first. - **Lyrics:** Whisper transcription of the local audio file is the only lyrics source in this skill. LRCLib web lookup moved to `music-source-fetch`. - **Local outputs:** analysis JSON, lyrics, prompts, temporary media, and generated audio are written to user-selected paths or temporary directories. - **Overwrites:** helper scripts refuse to replace existing user-visible outputs unless the operator passes an explicit `--overwrite` flag. There is no image, face, OCR, or VLM pipeline in this skill. Album art, video frames, and similar visual inputs are not analyzed. ## Required MiniMax Workflow > **Operator rules for MiniMax generations:** > - Run MiniMax generations sequentially, not in parallel. > - Do not assume the CLI will honor a requested output path — pass `--out` to `mmx` and verify the file exists after each run. > - Treat requested duration as a target, not a guarantee. Verified range: 57-135% of requested duration. > - If `mmx` exits with SIGTERM/SIGKILL after saving, verify the file before rerunning; file existence is the source of truth. > - Before running multi-output MiniMax generations, load [`references/minimax-generation-caveats.md`](references/minimax-generation-caveats.md). For every cover, style-transfer, mashup, or precision `mmx` generation, follow this checklist in order: 1. **Analyze source audio** with `scripts/analysis_orchestrator.py` when audio is available. 2. **Build M1 + M2 prompts** from the analysis: M1 is the primary style, M2 is a strong contrast style. 3. **Lint both prompts and lyrics** with `scripts/lint_music_request.py` before generation. Use `--lyrics-file` when lyrics exist so invalid tags and duration density are caught. Stop on blockers. 4. **Generate with retry** via `scripts/generate_with_retry.py --output-path -- music generate ... --out ` or `-- music cover ... --out `. `--output-path` does not replace `mmx --out`. 5. **Verify outputs**: duration, LUFS/peak, file size, audible completeness, and lyrics alignment. When lyrics matter, listen or transcribe and use `scripts/verify_lyrics_alignment.py` before delivery. 6. **Finalize delivery copy** with `scripts/finalize_track.sh input.mp3 output.mp3` when the user wants production-ready loudness. 7. **Deliver both versions** with a short analysis summary and any caveats. Preserve the anti-sparse guard in prompts: fully arranged, instruments keep playing, no a cappella dropouts unless explicitly requested. ## Reliability Caveats Load [`references/minimax-generation-caveats.md`](references/minimax-generation-caveats.md) before any multi-output, long-duration, or quota-sensitive cloud run. - `--length` is a hint, not a contract. Cloud output can undershoot or overshoot the request; local ACE-Step is the exact-duration fallback. - A shell SIGTERM/SIGKILL after save can still be a successful generation. Check file existence, file size, and `ffprobe` duration before retrying. - Keep standard cloud generation prompts under about 500 characters when possible. Put detailed production sheets in the local ACE-Step route. - Treat `--references` as optional and potentially flaky. Inline concise references in the prompt when reliability matters. - Expected cloud output is MP3, stereo, 44.1 kHz, about 256 kbps. There are no documented flags for FLAC, 48 kHz, or bitrate selection. - There is no documented MiniMax batch API or preview/draft mode. For repeated covers, use `scripts/batch_cover.py` so runs remain sequential and verified. - Quota usage may not be visible from the CLI. Check the MiniMax dashboard when planning large batches. Short cloud prompt recipes: [`references/short-prompt-recipes.md`](references/short-prompt-recipes.md). ## Routing and Blocker Checks Classify the request before analysis or generation: - **Text-only style reference** means the user gave a song name, artist, era, or genre cue without source audio. Treat it as style inference, not cover analysis. - **Reference audio** means the user provided a local file that should be analyzed. URLs are not accepted; ask for a local file path. - **Cover** preserves melody and usually needs a source file plus a target style decision. - **Style transfer** uses a reference track or analyzed audio as style input, then changes the production direction. - **Mashup** needs Song A and Song B, plus a decision about which one contributes content and which one contributes style. - **Emotion prompt** means the user wants analysis turned into descriptive prompt language, not a full cover. The [`scripts/lint_music_request.py`](scripts/lint_music_request.py) helper emits one of these routes: | Route | When | |---|---| | `base_prompt` | Standard generation, no MiniMax-specific feature needed. | | `minimax_cover` | Melody-preserving cover from a local audio file. | | `minimax_mashup` | Two-song mashup (A + B, both identified). | | `minimax_style_transfer` | Style transfer that does not preserve the source melody. | | `minimax_emotion_prompt` | Emotion analysis, or precision `mmx` flag usage. | | `needs_clarification` | At least one blocker is unresolved; ask the user first. | Surface blockers before analysis: - no local source file (URLs are not accepted) - unclear which track is Song A versus Song B - missing target style - missing lyrics decision, such as original, translated, rewritten, or instrumental - conflicting cover/style-transfer intent: the user asked for both "cover" (preserve melody) and "style transfer" (reproduce style) at once. These are mutually exclusive. Ask the user to pick one. After you have prompt text and `mmx` flags, lint them together before generation: - compare prompt BPM with `--bpm` - compare prompt key with `--key` - compare prompt structure line with `--structure` - compare prompt duration with `--duration` (or implicit length expectation) - compare prompt vocal mode with `--vocals` - compare prompt language with `--language` - compare prompt avoid language with `--avoid` - stop when the prompt says one thing and the flags say another - warn when prompt text exceeds 1800 UTF-8 bytes - stop when prompt text exceeds 2000 UTF-8 bytes (observed API rejection at 2079 bytes) If the user only has a text reference, route to the free-tool path in `references/free-tool-inputs.md` first. If the user has audio, analyze first and only then build the prompt. The linter returns a `retry_guidance` array with one hint per conflict so the operator can re-align prompt and flags on the next attempt. ## When To Use Use this skill when the task involves: - generating a cover of an existing song with a different style (chanson version of a rock track, reggaeton version of a pop hit, and so on). Source must be a local file. - style transfer from a local audio file to a target genre - two-song mashup where Song A's lyrics and emotional arc are kept, but Song B's style is applied - emotion analysis on input audio to extract intensity curves, vocal speed, pitch bends, and emotion classifications - generating lyrics in a specific language and theme via the MiniMax `lyrics_generation` API - editing existing lyrics to match a target style or emotional arc (MiniMax `lyrics_generation` edit mode) - using `mmx` CLI directly for fine control over `--avoid`, `--bpm`, `--key`, `--structure`, `--vocals`, `--instruments` as separate flags - accessing MiniMax's `music-cover` or `music-cover-free` models for melody preservation ## Request Intake (adapted for MiniMax features) After the Routing and Blocker Checks classify the request, run this 2-pass intake to extract the full set of fields the user cares about. Label each field's confidence: **clear** (user said it), **inferred** (sensible default), **missing** (need to ask), or **conflicting** (user said two incompatible things — pause to resolve). ### Fields checklist (MiniMax-specific) | # | Field | What to look for | MiniMax-specific notes | |---|---|---|---| | 1 | Route | Cover / style transfer / mashup / standard / emotion prompt | From the Routing and Blocker Checks section. Determines which MiniMax features to use. | | 2 | Source audio | Local file path | Required for cover, mashup, style transfer. For standard, optional (text-only style reference is also fine). | | 3 | Song A identity | Name, artist, audio | For mashup: needed. For cover: this is the source. | | 4 | Song B identity | Name, artist, audio | For mashup only. | | 5 | Target style | Genre / mood / reference | The destination of the cover or style transfer. If user says "like Rosalía", that's clear. If user says "something good", that's missing. | | 6 | Lyrics decision | Original / translated / new / instrumental | For cover, default to original (translated if user requests it). For standard, default to new (or user-provided). | | 7 | Vocal mode | Solo / duet / choir / instrumental | Drives `--vocals` and `--language` flags. | | 8 | Language | BCP-47 code (en, fr, es, etc.) | For lyrics language AND vocal language. | | 9 | Duration | Approximate length (jingle ~30s, standard ~3min, epic ~6min) | `--length` is a hint in milliseconds, not a guarantee. Length is still driven mainly by lyrics + structure. | | 10 | BPM, key, structure | Exact values if user wants `--bpm`/`--key`/`--structure` | Optional. If provided, the prompt AND flags must agree (lint them). | | 11 | Emotion arc | For emotion-prompt workflows: which emotions to emphasize | Drives the analysis-to-prompt translation. | | 12 | **Output location** | Where the audio and analysis files go | Same as the base skill — per-song subfolder in `~/Music mix///`. | Confidence map example: [`references/examples.md`](references/examples.md). If any field is **missing** or **conflicting**, that's a question to ask. The `Ambiguity Questions` section below has specific patterns for each route. If everything is **clear** or **inferred**, the request is ready to translate. ## User Preference Flow (message patterns → action) The skill does not start with a questionnaire. It starts by reading and inferring from the user's natural-language request. | User says... | Skill does... | |---|---| | "Haz un cover de X en Y" | Route: `minimax_cover`. Ask: local source audio file path, target language for lyrics, vocal register. | | "Make this song sound like Rosalía" | Route: `minimax_style_transfer`. Ask: source audio, which album/era of Rosalía. | | "I have audio of A, mash with B, keep A's melody" | Route: `minimax_mashup`. Ask: A vs B confirmation, source audio for A, B can be name or audio. | | "Analyze the emotion curve of this track" | Route: `minimax_emotion_prompt` (analysis-only). Run `analysis_orchestrator.py --audio` first, then read the JSON. | | "I want the lyrics to be about X, in French, melancholic" | Route: `base_prompt` (standard). Use the lyrics API to generate, then pass to `mmx music generate --lyrics-file`. Ask: target BPM/key/structure or derive from analysis. | | "Recreate the song but in 90 BPM D minor" | Route: `base_prompt` with `mmx` flags. Lint prompt vs flags before generation. Verify BPM/key consistency. | | "I don't know, surprise me" | Pick a coherent default (e.g. upbeat indie pop, EN, ~3min, auto-lyrics, standard generation) and confirm with the user before generating. | | "Same song again but as a reggaeton version" | Route: `minimax_cover` with the existing song as source. Use the same project/song subfolder, suffix the MP3 (`M1_original.mp3` + `M2_reggaeton.mp3`). | This table is the **abstract** of `references/user-preference-flow.md` (which lives in the base skill). If you want a more detailed case, defer to the base skill's table and combine with this skill's route mapping. ## Output File Layout (Per-Song Subfolders) **MiniMax-specific additions** (drop these into the per-song subfolder alongside the base items): | File | Source | Notes | |---|---|---| | `_analysis.json` | `analysis_orchestrator.py --output` | MiniMax-specific analysis results (emotion, BPM, key, segments) | | `_lyrics.txt` | `mmx music generate --lyrics-file` | Optional if user provided lyrics inline | | `_

Music Craft — MiniMax

Description

Latest Changes

Install Music Craft — MiniMax with One Click