{"id":"88082afa-cae0-421e-a164-64ce18640e2a","entityType":"agent","slug":"clawhub-luischarro-music-craft","name":"music-craft","canonicalUrl":"https://www.xpersona.co/agent/clawhub-luischarro-music-craft","canonicalPath":"/agent/clawhub-luischarro-music-craft","generatedAt":"2026-10-11T10:52:12.120Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T08:23:16.095Z","emptyReason":null},"description":"Generate songs, instrumentals, or lyrics-driven tracks through a structured OpenClaw-native workflow with anti-sparse prompt engineering and quality verification. Provider-agnostic — works with any music backend the runtime exposes (ACE-Step, MusicGen, Stable Audio, mmx).","descriptionLabel":"Source description","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 1.1K downloads reported by the source. Last updated 10/11/2026.","installCommand":"clawhub skill install s171padhas9w52sdjc3110vhss83j8jp:music-craft","sourceUrl":"https://clawhub.ai/luischarro/music-craft","homepage":"https://clawhub.ai/luischarro/skills/music-craft","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/luischarro/music-craft","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/luischarro/skills/music-craft","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":61,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"music-craft technical dossier on Xpersona with agent coverage, OPENCLEW support, and live trust metadata."},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-11T08:23:16.095Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T08:23:16.095Z","emptyReason":null},"stars":null,"forks":null,"downloads":1113,"packageName":null,"latestVersion":"1.6.0","tractionLabel":"1.1K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T08:23:16.082Z","emptyReason":null},"lastUpdatedAt":"2026-10-11T08:23:16.095Z","lastCrawledAt":"2026-10-11T08:23:16.082Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-12T08:23:16.082Z","lastVerifiedAt":null,"highlights":[{"version":"1.6.0","createdAt":"2026-07-30T11:36:34.536Z","changelog":"v1.6.0: discoverability reorder — hero sections (What is / Key Capabilities / Why use / Quick Start) at top of SKILL.md, licensing/Commercial-use gate moved to bottom. No behaviour, no env vars, no bins.","fileCount":36,"zipByteSize":175864},{"version":"1.5.1","createdAt":"2026-07-28T13:06:18.009Z","changelog":"v1.5.1: document ClawHub MIT-0 scope, mark MusicGen weights non-commercial, and add backend licensing and commercial-use gates","fileCount":28,"zipByteSize":117153},{"version":"1.5.0","createdAt":"2026-06-14T05:44:55.608Z","changelog":"v1.5.0: BREAKING — local audio files only, image pipeline removed, LRCLib moved to music-source-fetch","fileCount":28,"zipByteSize":115624},{"version":"1.4.1","createdAt":"2026-06-13T15:20:13.854Z","changelog":"v1.4.1: add lyrics tag whitelist linting, transcript-vs-lyrics verification, and safer delivery guidance","fileCount":27,"zipByteSize":117697},{"version":"1.4.0","createdAt":"2026-06-13T11:46:35.024Z","changelog":"v1.4.0: clarify local arranger workflows, generalize Windows guidance, and remove maintainer-specific/private details from published docs","fileCount":25,"zipByteSize":113330},{"version":"1.3.0","createdAt":"2026-06-13T05:05:27.759Z","changelog":"v1.3.0: tighten exact-duration ACE-Step guidance, expand local workflow references, and sharpen source-intake and structure-tag instructions","fileCount":21,"zipByteSize":104853},{"version":"1.1.0","createdAt":"2026-06-11T16:44:07.636Z","changelog":"v1.1.0: add vocal-confirm and target-length gates, clarify exact-duration routing, and tighten source-audio intake guidance","fileCount":18,"zipByteSize":98415},{"version":"1.0.1","createdAt":"2026-06-09T22:51:17.768Z","changelog":"v1.0.1: Rename display name from 'OpenClaw Music Workflow' to 'Music Craft' for slug consistency. Bundle body unchanged from v1.0.0 (1649-line SKILL.md, 9 reference docs, 12 files, 209 KB).","fileCount":13,"zipByteSize":89535}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s171padhas9w52sdjc3110vhss83j8jp:music-craft","setupComplexity":"low","setupSteps":["Install using `clawhub skill install s171padhas9w52sdjc3110vhss83j8jp:music-craft` in an isolated environment before connecting it to live workloads.","No published capability contract is available yet, so validate auth and request/response behavior manually.","Review the upstream CLAWHUB listing at https://clawhub.ai/luischarro/music-craft before using production credentials."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-luischarro-music-craft/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-luischarro-music-craft/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-luischarro-music-craft/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-luischarro-music-craft/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-luischarro-music-craft/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-luischarro-music-craft/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-11T10:52:12.116Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-luischarro-music-craft/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-luischarro-music-craft/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-luischarro-music-craft/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-luischarro-music-craft/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T08:23:16.095Z","emptyReason":null},"readme":"Skill: music-craft\n\nOwner: luischarro\n\nSummary: Generate songs, instrumentals, or lyrics-driven tracks through a structured OpenClaw-native workflow with anti-sparse prompt engineering and quality verification. Provider-agnostic — works with any music backend the runtime exposes (ACE-Step, MusicGen, Stable Audio, mmx).\n\nTags: latest:1.6.0\n\nVersion history:\n\nv1.6.0 | 2026-07-30T11:36:34.536Z | user\n\nv1.6.0: discoverability reorder — hero sections (What is / Key Capabilities / Why use / Quick Start) at top of SKILL.md, licensing/Commercial-use gate moved to bottom. No behaviour, no env vars, no bins.\n\nv1.5.1 | 2026-07-28T13:06:18.009Z | user\n\nv1.5.1: document ClawHub MIT-0 scope, mark MusicGen weights non-commercial, and add backend licensing and commercial-use gates\n\nv1.5.0 | 2026-06-14T05:44:55.608Z | user\n\nv1.5.0: BREAKING — local audio files only, image pipeline removed, LRCLib moved to music-source-fetch\n\nv1.4.1 | 2026-06-13T15:20:13.854Z | user\n\nv1.4.1: add lyrics tag whitelist linting, transcript-vs-lyrics verification, and safer delivery guidance\n\nv1.4.0 | 2026-06-13T11:46:35.024Z | user\n\nv1.4.0: clarify local arranger workflows, generalize Windows guidance, and remove maintainer-specific/private details from published docs\n\nv1.3.0 | 2026-06-13T05:05:27.759Z | user\n\nv1.3.0: tighten exact-duration ACE-Step guidance, expand local workflow references, and sharpen source-intake and structure-tag instructions\n\nv1.1.0 | 2026-06-11T16:44:07.636Z | user\n\nv1.1.0: add vocal-confirm and target-length gates, clarify exact-duration routing, and tighten source-audio intake guidance\n\nv1.0.1 | 2026-06-09T22:51:17.768Z | user\n\nv1.0.1: Rename display name from 'OpenClaw Music Workflow' to 'Music Craft' for slug consistency. Bundle body unchanged from v1.0.0 (1649-line SKILL.md, 9 reference docs, 12 files, 209 KB).\n\nv1.0.0 | 2026-06-09T22:40:43.264Z | user\n\nFirst stable release. Provider-agnostic music generation workflow with anti-sparse prompt engineering, request intake checklist, 5 worked examples, 6 retry recipes, ACE-Step 1.5 (3 quality tiers: fast/standard/xl-mixed) with 4 verified output tracks on 24GB M3, Windows/WSL2 + corporate-proxy setup walkthrough, audio-conditioned generation (cover, repaint, reference audio), and a Dependency Consent Protocol for REQUIRED/OPTIONAL installs.\n\nArchive index:\n\nArchive v1.6.0: 36 files, 175864 bytes\n\nFiles: README.md (4331b), references/acestep-generation.md (30458b), references/acestep-shift-schedule.md (29463b), references/acestep-task-types.md (34522b), references/acestep-xl-models.md (18403b), references/advanced-diffusion-controls.md (6982b), references/audio-format-selection.md (6176b), references/audition-rubric.md (9625b), references/changelog.md (2159b), references/error-handling.md (26912b), references/examples.md (10077b), references/free-tool-inputs.md (16582b), references/input-workflows.md (17275b), references/local-ace-step-curl-template.md (2486b), references/lrc-generation.md (30982b), references/lyrics-cleanup.md (2590b), references/mps-bf16-acceleration.md (6252b), references/other-backends.md (9817b), references/prompt-formula.md (13390b), references/quality-and-revision.md (6279b), references/request-intake.md (8792b), references/setup-and-preflight.md (20709b), references/structure-tags.md (14374b), references/style-categories.md (6418b), references/user-preference-flow.md (7172b), references/wait-and-collect.md (3136b), references/windows-wsl-setup.md (11456b), scripts/extract_stems.py (4873b), scripts/lint_lyrics.py (4425b), scripts/remix_stems.py (2417b), scripts/smoke_test.py (5107b), scripts/verify_lyrics_alignment.py (3768b), scripts/wait_for_acestep.py (4564b), skill-card.md (3029b), SKILL.md (40484b), _meta.json (130b)\n\nFile v1.6.0:SKILL.md\n\n---\nname: music-craft\nversion: 1.6.0\ndescription: Generate songs, instrumentals, or lyrics-driven tracks through a structured OpenClaw-native workflow with anti-sparse prompt engineering and quality verification. Provider-agnostic — works with any music backend the runtime exposes (ACE-Step, MusicGen, Stable Audio, mmx).\nmetadata: {\"openclaw\":{\"requires\":{\"anyBins\":[\"python3\",\"python\"]},\"emoji\":\"\\ud83c\\udfb5\",\"homepage\":\"https://github.com/LuisCharro/skills/tree/main/publish/music-craft\",\"envVars\":[{\"name\":\"MUSIC_PROVIDER_API_KEY\",\"required\":false,\"description\":\"Generic API key for any music provider.\"},{\"name\":\"STABILITY_API_KEY\",\"required\":false,\"description\":\"Stability AI API key. Only needed if using Stable Audio as backend.\"}]}}\n---\n# Music Craft\n\n## What is Music Craft?\n\nMusic Craft is the **provider-agnostic entry point** for music generation in OpenClaw. It guides the model end-to-end — from intake, through a structured production-sheet prompt, to quality verification and delivery — so you get songs, instrumentals, or lyrics-driven tracks that sound complete (no sparse dropouts, no silent sections), in your chosen length, with vocals that match your lyrics.\n\n**It picks the right backend for the job.** Local ACE-Step for exact-duration vocal tracks with lyrics. MusicGen for local instrumental experiments. Stable Audio for production-friendly instrumentals. The `mmx` CLI for fast cloud generation. You pick the outcome; the skill routes.\n\n## Key Capabilities\n\n- **Production-sheet prompt engineering** — every prompt is a structured brief with genre, mood, BPM, key, instruments, structure, vocals, and an avoid list.\n- **Anti-sparse guards by default** — instruments stay playing, no a cappella dropouts, no silent mid-sections.\n- **Exact-duration vocal tracks** — local ACE-Step returns requested length to the millisecond (verified 18/18 local jobs).\n- **Structure-tagged lyrics** — canonical `[Verse]`, `[Chorus]`, `[Break]`, etc., so the model sings the song you wrote.\n- **Pre-generation linting** — duration density, tag whitelist, prompt/flag conflicts caught before you spend a generation.\n- **Quality verification on every output** — duration, loudness, file size, audible completeness, lyrics alignment.\n- **Provider-agnostic** — local ACE-Step, MusicGen, Stable Audio, or the MiniMax cloud CLI; same workflow, same verification.\n\n## Why use this skill?\n\nMost music models treat \"sparse\" as \"remove everything\" or \"3 minutes\" as \"however long the model wants\". Music Craft encodes the rules once, so every generation runs through the same loop with the same anti-sparse guard, the same prompt validation, the same post-generation verification. You get coherent, full, audibly correct songs — not first-draft lottery tickets.\n\n## Quick Start\n\n1. Say what you want — e.g. _\"Make a sad love song in Spanish, ~3 minutes.\"_\n2. The skill auto-detects language, genre, mood, duration, and asks only the 1-3 things that aren't recoverable from your message.\n3. It builds a production-sheet prompt and routes to the right backend.\n4. It lints the prompt + lyrics, generates, then verifies duration/loudness/completeness before delivering.\n5. If quality fails, it adjusts the prompt and retries once — never the same payload twice.\n\n## When To Use\n\nUse this skill when the task involves:\n\n- generating a song from a user description (genre, mood, language, theme)\n- producing structured lyrics with section tags\n- turning prose, a poem, or a list of themes into song lyrics\n- making an instrumental track with explicit style and instrument control\n- iterating on a generated song with controlled prompt adjustments\n- verifying that generated music has no sparse, a cappella, or clipped sections\n- **needing a specific song length (e.g. 3:30)** — this skill's ACE-Step backend takes `audio_duration` as a parameter and is the exact-duration route. Verified field run: ACE-Step returned exact requested duration for 18/18 local jobs; MiniMax cloud returned 57-135% of requested duration.\n\n**Routing:**\n\n- Prefer this skill when exact duration matters more than generation speed.\n- Prefer this skill when the user wants a full-length local vocal track.\n- Redirect to `music-craft-minimax` only for MiniMax-native workflows or when the user explicitly wants the MiniMax path.\n\n## When NOT To Use\n\nDo not use this skill when:\n\n- the user only needs lyrics as text with no audio — use a writing skill instead\n- the user wants a fast cloud cover, upload-based style transfer, emotion analysis, or a mashup — use `music-craft-minimax`\n- the user wants a local cover/repaint experiment but cannot accept ACE-Step's hardware, timeout, and queue constraints — use `music-craft-minimax` or a cloud backend instead\n- the user has specific BPM, key, or per-section structure requirements that need separate flags — use `music-craft-minimax`\n- a deterministic, single-shot generation with no iteration is sufficient and the user already has the right prompt\n- the user wants to mutate a specific existing audio file (pitch shift, time stretch, stem split) — that is post-production, not generation\n\n## Decision Tree\n\nUse this skill unless the request explicitly needs a MiniMax-only path:\n\n1. If the user wants a fast cloud cover, advanced audio/emotion analysis, a mashup, or per-flag control for `--avoid`, `--bpm`, `--key`, or `--structure`, switch to `music-craft-minimax`.\n2. If the user wants a local source-audio restyle and accepts slower, experimental ACE-Step behavior, stay here and use the ACE-Step audio-conditioned guide.\n3. If the user wants a standard song, instrumental, jingle, or lyrics-driven track, stay here.\n4. If the request is vague but still about generation, stay here and infer defaults before asking anything.\n5. If the user is asking to edit or mutate an existing audio file, treat it as post-production, not base generation.\n6. **If ACE-Step is detected and no models are downloaded:** run memory safety check → present download options (fast/standard/xl-mixed/skip to cloud) → wait for user consent → NEVER auto-download.\n7. **If ACE-Step is detected with models loaded:** check available RAM → offer appropriate tiers (fast/standard/xl-mixed based on RAM) → default to `standard` unless user requests otherwise.\n8. **If user says \"best quality\" on 24GB machine:** offer `xl-mixed` with the caveat that the 50-step sft model output quality is currently poor on 24 GB M3 (high-frequency noise, unclear vocals). Recommend `standard` tier for known-good output unless the user wants to experiment with the fix list in the next section.\n9. **Before submitting any ACE-Step request:** fill in the 6 metas (BPM, key, time signature, vocal language, duration, genre) explicitly in the request body, even if `thinking=true` is set. The LM will use these as anchors. If the user hasn't provided them, infer sensible defaults (e.g. 96 BPM for dream pop, \"D major\" if the prompt mentions a key) before submitting. For `xl-sft` (xl-mixed tier), detailed metas are essential; for the standard `v15-turbo` they're optional but improve consistency.\n10. **For exact-duration vocal tracks on Apple Silicon:** prefer the local ACE-Step route. It is slower than cloud but verified exact to the millisecond in the 2026-06-12 field run.\n\n## Core Philosophy\n\nThis skill is **provider-agnostic** by design. It works with whatever music backend is available: a native `music_generate` tool exposed by the runtime, or a CLI like `mmx` invoked via bash. It does not assume any specific provider, model, or API.\n\nThree rules drive every generation:\n\n1. **Production-sheet prompts.** Every prompt reads like a mini production brief, not a vague description.\n2. **Anti-sparse guards.** Every prompt includes explicit instruments, the \"always playing\" rule, and an avoid list.\n3. **Structure-tagged lyrics.** Every lyric body uses `[Verse]`, `[Chorus]`, `[Break]`, and similar tags to give the generator a clear shape.\n\n## Runtime Adapters\n\nThis skill is agent-neutral. It uses whatever music backend is available — a native tool or a CLI — in the active runtime.\n\nIt does not require:\n\n- any specific music provider\n- any CLI (`mmx` or other)\n- any external API key beyond what the runtime already needs\n- any audio analysis library (librosa, parselmouth, ffmpeg)\n\nIf a more capable backend is installed, the `music-craft-minimax` skill unlocks fast cloud cover workflow, separate parameter flags, and emotion-driven mashups. This skill is the entry point; that one is the power-user upgrade.\n\n## Free Tool Augmentation\n\nThe OpenClaw runtime exposes several free tools that enrich the music generation workflow. None of these require user-side installation — they are part of the runtime, and the skill can call them directly to gather more context about the user's request before building the prompt.\n\n| Tool | Purpose | When to use |\n| --- | --- | --- |\n| `web_fetch` | Fetch readable content from any URL | Lyrics pages, Wikipedia, artist bios, music blogs |\n| `web_search` | Search the web with a query | Find lyrics when only the title is known, find artist info, find genre descriptions |\n| `memory_search` / `memory_get` | Recall from the user's durable memory | Previous music preferences, prior generation issues, typical genres |\n| `browser` | Drive a real browser | JS-heavy lyrics sites (genius.com dynamic loading) — fallback when `web_fetch` returns only chrome |\n\n### Quick decision: which tool to reach for\n\n- **The user gave a URL** → `web_fetch`\n- **The user gave just a name or vague reference** → `web_search`, then `web_fetch` the top result\n- **The user has prior music preferences in memory** → `memory_search` first\n- **`web_fetch` returns only chrome (no content)** → `browser` as fallback\n\nDo not surface copyrighted lyrics verbatim in the final song unless the user provided them. Use fetched lyrics as inspiration for style and structure, not as the song's body.\n\nWorked examples, privacy rules, and scope: [`references/free-tool-inputs.md`](references/free-tool-inputs.md).\n\n## Pre-Flight Check\n\nBefore starting the workflow loop, verify the runtime can do the work. This\nskill has **zero external dependencies** — the only requirement is a music\ngeneration backend (native tool or CLI). Before the first generation in a\nsession, run the full pre-flight protocol (including the Required check) in\n[`references/setup-and-preflight.md`](references/setup-and-preflight.md).\n\nNon-negotiable rules that always apply:\n\n- Never install anything without explicit user consent (Dependency Consent\n Protocol). Show the exact command and its rough size/impact before asking.\n- Detect the platform first (POSIX vs PowerShell vs cmd) and use matching\n command syntax for everything that follows.\n- Ask hardware/setup questions once per session, then remember the answers.\n- When a required dependency is missing, ask the user — do not silently\n degrade or skip.\n\n### When to redirect to `music-craft-minimax`\n\nIf the user's request implies any of:\n\n- fast cloud cover or style transfer from a reference audio file\n- emotion analysis on input audio\n- two-song mashup\n- separate `--avoid`, `--bpm`, `--key`, or `--structure` flags\n\nStop the pre-flight and tell the user: \"That needs ``, which is in `music-craft-minimax`. Switch to that skill and I will run the same pre-flight with the extended check list.\" Do not try to fake these features with the tools this skill has.\n\nIf the user specifically wants a local source-audio restyle and can accept a slow experimental path, stay in this skill and load [`references/acestep-generation.md`](references/acestep-generation.md). ACE-Step cover/repaint is local, melody-aware, and queue-bound; it is not the fast/default cloud cover path.\n\n**Audio source:** the user must provide a local audio file path. URLs are not accepted in either music skill in v1.5.0+; if the user wants to fetch audio by title from the internet, point them at the private `music-source-fetch` skill (not published on ClawHub).\n\n## Local Models\n\nThree local music models are supported by this skill. **License must be named and accepted before any model is downloaded** — the skill never auto-downloads (inherited hard rule from `setup-and-preflight.md`). License decides whether the output is fit for monetized channels, paid work, or advertising; pick the model that matches the distribution intent before installing.\n\n| Model | License | Size | Commercial? | Purpose | Install guide |\n| --- | --- | ---: | --- | --- | --- |\n| **ACE-Step** (`acestep-v15-xl-base-diffusers`) | MIT | ~11 GB | ✅ Yes | Vocals + lyrics, local, exact-duration | [`§ 1`][acestep-install] |\n| **MusicGen** (`facebook/musicgen-large`) | CC-BY-NC 4.0 | ~3.3 GB | ❌ No | Instrumental only, non-commercial | [`§ 2`][musicgen-install] |\n| **Stable Audio Open** (`stabilityai/stable-audio-open-1.0`) | Stability AI Community | ~1.2 GB | ⚠️ Only if revenue < $1M/yr | Instrumental only, commercial-OK under cap | [`§ 3`][stable-audio-install] |\n\nHardware floor: Apple Silicon MPS gives 5–10× speed-up (CPU works but ~15 min / 30 s). NVIDIA CUDA is the reference. Apple Silicon requires `ACESTEP_LM_BACKEND=mlx`; on macOS, `PYTORCH_MPS_HIGH_WATERMARK_RATIO=0.0` is mandatory for XL DiTs. Memory probe protocol and per-model ML-budget rules: [`references/setup-and-preflight.md`](references/setup-and-preflight.md).\n\nFull installation protocol (download paths, environment setup, verify commands, license click-through notes): [Local Models Install Guide](/Users/luis/Repos/skills/publish/LOCAL-MODELS-INSTALL-GUIDE.md).\n\n[acestep-install]: /Users/luis/Repos/skills/publish/LOCAL-MODELS-INSTALL-GUIDE.md#1-ace-step-mit--11-gb\n[musicgen-install]: /Users/luis/Repos/skills/publish/LOCAL-MODELS-INSTALL-GUIDE.md#2-musicgen-cc-by-nc-40--33-gb\n[stable-audio-install]: /Users/luis/Repos/skills/publish/LOCAL-MODELS-INSTALL-GUIDE.md#3-stable-audio-open-stability-ai-community-license--12-gb\n\n## Backend Generation\n\nSelect the backend from the need, then load only that backend's reference:\n\n| Need | Backend | Reference |\n| --- | --- | --- |\n| Vocals + lyrics, local, best local quality | ACE-Step 1.5 | [`references/acestep-generation.md`](references/acestep-generation.md) |\n| Instrumental, local, no API key, non-commercial | MusicGen | [`references/other-backends.md`](references/other-backends.md) |\n| Simple cloud generation (API key, no local model) | mmx CLI | [`references/other-backends.md`](references/other-backends.md) |\n| Local source-audio cover/repaint, experimental | ACE-Step 1.5 | [`references/acestep-generation.md`](references/acestep-generation.md) |\n| Fast cloud cover, style transfer, mashup, fine flag control | `music-craft-minimax` skill | switch skills — see **When to redirect to music-craft-minimax** above |\n| Instrumental via REST API | Stable Audio | [`references/other-backends.md`](references/other-backends.md) |\n| Anything else the runtime exposes | Generic CLI | [`references/other-backends.md`](references/other-backends.md) |\n\nRules that always apply regardless of backend:\n\n- Validate the prompt against the backend's format before generating\n (MusicGen wants 1–2 natural-language sentences; ACE-Step wants a detailed\n multi-dimensional caption; see the backend reference).\n- Never retry an identical failing payload; change prompt, parameters, or\n backend between attempts.\n- Verify the output file (duration, loudness, completeness) before delivery.\n\n## ACE-Step Operational Caveats\n\nLoad [`references/acestep-generation.md`](references/acestep-generation.md)\nand the focused local references before submitting a local ACE-Step job:\n\n- The ACE-Step API server processes one job at a time; queue multiple versions\n sequentially and collect each output before submitting the next.\n- `GET /v1/stats` exposes only top-level queue state. For long jobs, tail the\n server log (`/tmp/acestep-api.log`) for DiT/VAE progress.\n- The cache directory accumulates generated files. Clean old files deliberately;\n never assume the API cleans them for you.\n- There is no cancel endpoint. Lint prompt, lyrics, duration, and metas before\n submitting a long job.\n- `thinking: true` is the quality default and may produce two cache files for a\n single request; collect and label both when they exist.\n- For source-audio cover/repaint, use multipart upload and the `wait_for_acestep.py`\n helper when available. The local API can return empty `/query_result` data\n while work is still running, so cache-file detection is part of the workflow.\n- For audio-conditioned tasks beyond cover/repaint (`extract`, `lego`, `complete`),\n the BASE-only DiT is required — load [`references/acestep-task-types.md`](references/acestep-task-types.md)\n before submitting. For XL (4B) DiT checkpoints (`xl-base`, `xl-sft`, `xl-turbo`,\n `xl-mixed`), the `num_inference_steps=50` (Diffusers path) / `inference_steps=50` (REST path) and `shift=3.0`\n footguns apply — load [`references/acestep-xl-models.md`](references/acestep-xl-models.md) before\n touching XL.\n\nCopy-pasteable local commands and collection workflow:\n[`references/local-ace-step-curl-template.md`](references/local-ace-step-curl-template.md)\nand [`references/wait-and-collect.md`](references/wait-and-collect.md).\n\n## Operating Rules\n\n### 1. Read and auto-detect\n\nBefore asking anything, infer language, genre, mood, duration, and theme from the user's message. Default duration is about 3 minutes; only ask if the user is explicit about length.\n\nFull auto-detect cheat sheet and edge cases: [`references/user-preference-flow.md`](references/user-preference-flow.md) and [`references/input-workflows.md`](references/input-workflows.md).\n\n### First response defaults\n\nUse these deterministic first responses before asking follow-up questions:\n\n- **Standard song request** -> infer language, genre, mood, and duration; ask only for the missing lyric source, voice, or reference if it is not already implied.\n- **User-provided lyrics** -> keep the lyrics intact, add section tags, and ask only for any missing voice or length detail.\n- **Instrumental or jingle** -> set instrumental mode immediately; ask for duration only if the length is still unclear.\n- **Vague style reference** -> use the reference as a style cue, infer the closest genre family, and ask only for lyrics source or voice if those are not recoverable from context.\n- **Image or URL input enrichment** -> fetch or analyze the input first, turn the result into style cues, then ask only for anything that still cannot be inferred.\n\n### 2. Analyze source material when available\n\nIf the user provides source audio or an analysis file, extract the reusable facts before writing the prompt. If there is no source material, continue with the request text and inferred defaults.\n\nFull analysis options, tool choices, and the decision tree: [`references/input-workflows.md`](references/input-workflows.md).\n\n#### Vocal confirmation gate\n\nIf source analysis returns `language=unknown`, suggests instrumental, or does not clearly confirm vocals, ask one targeted question before prompt construction:\n\n> Is this instrumental, or does it have vocals? If vocals, what language, and should I use provided lyrics or extract them?\n\n#### Target-length confirmation gate\n\nIf source audio exists and the user did not explicitly set the output length, confirm one of: same as source, standard 3:00, standard 3:30, or a specific length.\n\n### 3. Ask only the ambiguous parts\n\nAfter auto-detect, ask 1–3 questions max. Do not ask about language, genre, mood, or duration if the request already makes them obvious.\n\nQuestion patterns and worked examples: [`references/user-preference-flow.md`](references/user-preference-flow.md).\n\n### 4. Translate to a production-sheet prompt\n\nThe prompt you pass to `music_generate` is not a restatement of the user's words. It is a structured brief with ten required slots: genre/subgenre, mood, voice, instruments, anti-sparse instruction, BPM/key, structure, dynamics, production quality, and avoid list.\n\nFull formula, slot-by-slot guide, and worked examples: [`references/prompt-formula.md`](references/prompt-formula.md).\n\n### 5. Validate the prompt\n\nBefore generating, validate prompt length, structure, duration, lyrics tags, and backend-specific conflicts. Run `scripts/lint_lyrics.py --bpm --target-seconds ` for any provided/generated lyrics before spending a generation. If `music-craft-minimax` is installed, its `scripts/lint_music_request.py` is the canonical guard for mmx prompt size, missing fields, and conflicts.\n\nPer-backend byte limits, length-reduction techniques, and lint rules: [`references/prompt-formula.md`](references/prompt-formula.md).\n\n### 6. Structure the lyrics\n\nIf the user provides lyrics, add canonical section tags (`[Verse]`, `[Chorus]`, and so on) without altering the words. If the skill writes the lyrics, structure them from the start. Do not invent descriptive bracket tags such as `[Guitar Solo - distorted]` or `[Lyrics]`; bracket text can be sung by the model. ASR-extracted lyrics are unverified — cross-check and clean them before building the prompt.\n\nFull tag reference, Whisper verification rules, transcript cleanup, and emotion-specific lyrics patterns: [`references/structure-tags.md`](references/structure-tags.md) and [`references/lyrics-cleanup.md`](references/lyrics-cleanup.md).\n\n### 7. Generate and verify raw output\n\nCall the detected backend with the production-sheet prompt and structured lyrics. Use the backend-specific generation command from the backend's reference file (routed via the **Backend Generation** table). Adapt the prompt format to the backend (e.g., MusicGen needs prompt + lyrics combined into one text block; mmx accepts them separately). After the tool returns, verify that audio is non-empty, has no sparse or a cappella drops, lyrics alignment is plausible, and structure matches the plan. When lyrics matter, listen or transcribe before delivery; `scripts/verify_lyrics_alignment.py` can compare expected lyrics against a transcript.\n\nBackend commands and output verification details: backend reference files via the **Backend Generation** table above; quality checks: [`references/quality-and-revision.md`](references/quality-and-revision.md).\n\n### 8. Finalize delivery copy\n\nNormalize loudness with `ffmpeg loudnorm` (target -16 LUFS, -1 dBTP true peak), then verify duration, loudness, file size, and absence of silence drops or artifacts.\n\nLoudnorm command, verify checklist, and request-fit checks: [`references/quality-and-revision.md`](references/quality-and-revision.md).\n\n### 9. Iterate, do not retry the same payload\n\nIdentify the failure mode, adjust the prompt or lyrics to target it, and try once with a different seed if available. After 2 failed retries, ask the user to clarify or accept the best attempt. Never retry the same prompt plus lyrics combination twice in a row.\n\nIteration loop, adjustment recipes, and retry patterns: [`references/error-handling.md`](references/error-handling.md).\n\n## Request Intake\n\nCollect the required fields before generating: language, genre/subgenre, mood,\ntheme, vocal mode, lyric source, duration, structure, references, output location.\nAsk the output location once, then reuse it for the whole session.\nBuild a confidence map for what was auto-detected vs assumed, and confirm\nonly the low-confidence slots with the user.\n\nFull checklists, confidence-map examples, language-consistency checks,\nambiguous-phrase routing, and the per-song output layout and slug rules:\n[`references/request-intake.md`](references/request-intake.md).\n\n## Anti-Sparse Rules (Critical)\n\nThe single most common failure mode of music generators: interpreting \"sparse\", \"quiet\", or \"minimal\" as \"remove all instruments and vocals\".\n\n### Always include in the prompt\n\n1. **List every instrument by name.** Example: `accordion, upright bass, orchestral strings, piano, light percussion`.\n2. **The always-playing rule.** `ALL instruments ALWAYS playing throughout, NEVER a cappella or silent`.\n3. **The avoid list.** `AVOID sparse minimal arrangements, AVOID a cappella sections`.\n4. **Explicit treatment of quiet sections.** `quiet sections: reduced to accordion and bass only, still fully played`.\n\n### Never use alone\n\n- `sparse arrangement`\n- `minimal instrumentation`\n- `stripped back`\n- `a cappella section`\n- `quiet with no instruments`\n\nIf the user asks for any of these, translate them into the explicit-instrument form.\n\n### Ground every mood word\n\nEvery mood, energy, or emotion word in the prompt must be tied to at least one concrete production detail. A mood word with no grounding will be ignored — the model defaults to a \"neutral pleasant\" register.\n\n| Mood word | Required grounding (pick at least one) |\n| --- | --- |\n| `sad` | minor key, slow BPM, breathy vocal, sparse chord pattern, low strings |\n| `energetic` | fast BPM, driving drums, sharp synth hits, strong rhythm guitar |\n| `romantic` | warm strings, soft vocal register, sustained pads, slow harmonic rhythm |\n| `dark` | minor key, low register, distorted bass, low-pass mix, breathy vocal |\n| `dreamy` | reverb-heavy mix, soft attack, layered pads, sustained vocal |\n| `aggressive` | distorted guitars, fast BPM, shouted vocal, heavy drums |\n| `triumphant` | major key, building dynamic, brass hits, declarative vocal |\n| `intimate` | close-mic vocal, low dynamic range, soft attack, single voice |\n\nIf a mood word cannot be grounded, drop it. A grounded prompt with five moods beats an ungrounded prompt with fifteen. For the full emotion quick reference (21 emotions with prompt + lyrics + arrangement templates), see [`references/prompt-formula.md`](references/prompt-formula.md).\n\n## Rate Limits\n\nRespect backend rate limits; on a limit error, wait at least 60 seconds and reduce request rate rather than hammering. Details and per-backend behavior: [`references/quality-and-revision.md`](references/quality-and-revision.md).\n\n## Quality Verification Checklist\n\nVerification has two levels. **Technical generation success** means the file exists, is non-empty, and has audible content. **User-fit confirmed** means the output actually fits the user's intent (genre, language, length, structure, lyrics alignment). Always check both.\n\nBefore delivering a generated song to the user, walk this list mentally. If 3 or more items fail, the prompt needs adjustment and a regeneration. If 1–2 fail, you can either accept the result and warn the user, or make a targeted fix and regenerate.\n\n1. **Audio is non-empty and plays.** Sample the first 5 seconds and the midpoint. If the file is empty or silent, regenerate.\n2. **No sparse or a cappella drops.** Check the midpoint specifically — sparse drops are most common in quiet sections.\n3. **No clipped vocals or distortion.** Listen for sudden loudness spikes or harshness.\n4. **Lyrics alignment is plausible.** If the user provided lyrics, the output should hit the key phrases recognizably.\n5. **Structure matches the plan.** If you asked for intro-verse-chorus-verse-chorus-bridge-chorus-outro, the song should have 7–8 distinct sections.\n6. **Genre and mood are recognisable.** A \"French chanson ballad\" should sound like French chanson, not generic acoustic.\n7. **Language is correct.** If the user asked for Spanish, the vocals should be in Spanish, not accented English.\n8. **Energy arc is coherent.** The song should build, peak, and resolve. If it stays at the same energy for 3 minutes, the prompt was likely too vague.\n\nFor the request-fit checklist and revision patterns, see [`references/quality-and-revision.md`](references/quality-and-revision.md).\n\n## Revision Prompts\n\nWhen the output is close but not right, do not regenerate from scratch. Keep 80% of the original prompt. Add a single `REVISION:` block at the end that targets the specific failure.\n\nWorked examples and the full retry recipe library: [`references/quality-and-revision.md`](references/quality-and-revision.md).\n\n## Lyrics Optimizer Behavior\n\nWhen `music_generate` is called **without explicit lyrics** and the request implies a vocal track (not instrumental), the runtime may auto-generate lyrics from the prompt.\n\nPer-provider behavior, the web lyrics lookup option, and handling user surprise at AI-written lyrics: [`references/quality-and-revision.md`](references/quality-and-revision.md).\n\n## User Preference Flow\n\nThe skill does not start with a questionnaire. It starts by reading and inferring.\n\n| User says... | Skill does... |\n| --- | --- |\n| \"Make a sad love song in Spanish\" | Auto-detect: ES, romantic, ~3 min. Ask: lyrics source and vocal register. |\n| \"Instrumental lofi for studying\" | Auto-detect: lofi, no vocals, ~3 min. Ask: nothing. Generate. |\n| \"Here are the lyrics, make it pop\" | Auto-detect: pop, user-lyrics. Ask: tempo and energy preference. |\n| \"Something that sounds like Rosalía\" | Auto-detect: modern Latin pop, female vocal. Ask: lyrics source and theme. |\n| \"I don't know, surprise me\" | Pick a coherent default (for example upbeat indie pop, EN, ~3 min, auto-lyrics) and confirm with the user before generating. |\n\nFor the full decision table and edge cases, see [`references/user-preference-flow.md`](references/user-preference-flow.md).\n\n## Output File Layout\n\nOne subfolder per song under the user's chosen output root; analysis JSON,\nprompt file, and versioned audio files (`A_`, `B_`, `C_`, `M1_`/`M2_`,\n`N1_`/`N2_`, `v2_`/`v3_` prefixes) live together in that subfolder. Slug and version rules: [`references/request-intake.md`](references/request-intake.md).\n\nIf the runtime needs a `MEDIA:` delivery path, use a path without spaces or\ncopy the final file into a workspace media folder first. Keep the archival copy\nin the per-song output folder.\n\n## Reference Map\n\n- [`references/setup-and-preflight.md`](references/setup-and-preflight.md) — pre-flight protocol: dependency consent, platform detection, user and hardware setup, required/optional dependencies, install details\n- [`references/windows-wsl-setup.md`](references/windows-wsl-setup.md) — Windows/WSL setup: certificate/proxy handling, WSL distro setup for local generation\n- [`references/acestep-generation.md`](references/acestep-generation.md) — complete ACE-Step 1.5 guide: API workflow, full-song generation, quality tiers and memory-safe selection, audio-conditioned generation (cover, repaint, reference audio)\n- [`references/local-ace-step-curl-template.md`](references/local-ace-step-curl-template.md) — JSON-safe `/release_task` curl template for direct ACE-Step submission\n- [`references/wait-and-collect.md`](references/wait-and-collect.md) — M1 -> wait -> collect -> M2 local sequencing, log watching, cache collection, and duration verification\n- [`references/lyrics-cleanup.md`](references/lyrics-cleanup.md) — cleanup recipe for Whisper/ASR transcripts, canonical section tags, `info.txt`, and `lyrics_whisper_medium.json`\n- [`references/other-backends.md`](references/other-backends.md) — MusicGen, mmx CLI, Stable Audio, and generic CLI backend guides\n- [`references/request-intake.md`](references/request-intake.md) — full intake protocol and per-song output layout (slugs, version prefixes)\n- [`references/prompt-formula.md`](references/prompt-formula.md) — full production-sheet formula, worked examples across genres, prompt lint, and the emotion quick reference\n- [`references/structure-tags.md`](references/structure-tags.md) — all section tags with rules, effects, and timing hints\n- [`references/user-preference-flow.md`](references/user-preference-flow.md) — the auto-detect plus ask decision table and edge cases\n- [`references/examples.md`](references/examples.md) — five worked examples (Spanish pop, English instrumental jingle, user-provided lyrics, image-inspired track, text-only style reference) with intake → prompt → verification for each\n- [`references/style-categories.md`](references/style-categories.md) — 10 style categories with default instruments, BPM range, and mood\n- [`references/input-workflows.md`](references/input-workflows.md) — 10 input types (description, user-lyrics, audio file, YouTube audio, song name, lyrics URL, YouTube metadata, JioSaavn metadata, image, genre/cultural), plus the signal-extraction rubric and confidence levels\n- [`references/quality-and-revision.md`](references/quality-and-revision.md) — rate limits, request-fit checklist, revision prompts, delivery copy, lyrics-optimizer behavior\n- [`references/error-handling.md`](references/error-handling.md) — error table, retry recipes (wrong language, weak chorus, sparse, vocals in instrumental, missing genre, too generic), and recovery patterns\n- [`references/free-tool-inputs.md`](references/free-tool-inputs.md) — web_fetch, web_search, image, and memory tools for enriching inputs without scripts\n- [`music-craft-minimax/scripts/lint_music_request.py`](../music-craft-minimax/scripts/lint_music_request.py) — optional standard-library helper for routing, blockers, missing fields, prompt, and `mmx` flag linting. Run it before generating to catch missing required slots, conflicting language signals, and vague mood words without grounding.\n- [`scripts/lint_lyrics.py`](scripts/lint_lyrics.py) — standard-library lyrics preflight for section-tag whitelist checks and syllable/BPM duration estimates.\n- [`scripts/verify_lyrics_alignment.py`](scripts/verify_lyrics_alignment.py) — standard-library post-generation transcript-vs-lyrics overlap check for semantic delivery.\n- [`scripts/wait_for_acestep.py`](scripts/wait_for_acestep.py) — standard-library helper for ACE-Step task polling plus cache-file completion detection.\n- [`scripts/extract_stems.py`](scripts/extract_stems.py) — optional Demucs wrapper that writes normalized stem paths and `stems.json` for local arranger experiments.\n- [`scripts/remix_stems.py`](scripts/remix_stems.py) — preview-quality `ffmpeg amix` helper for recombining validated stems.\n- [`scripts/smoke_test.py`](scripts/smoke_test.py) — pure-Python smoke tests for local helper behavior.\n- For emotion-driven generation (vocal speed, intensity, pitch bends, emotion recipes, iteration loop), see the quick reference in [`references/prompt-formula.md`](references/prompt-formula.md) under \"Mood\" and the full shared emotion recipes in [`music-craft-minimax/references/emotion-delivery.md`](../music-craft-minimax/references/emotion-delivery.md)\n- [`references/acestep-task-types.md`](references/acestep-task-types.md) — per-task reference for the five ACE-Step audio-conditioned tasks (`cover`, `repaint`, `extract`, `lego`, `complete`): inputs, outputs, parameters, BASE-only footguns, and a routing tree\n- [`references/acestep-xl-models.md`](references/acestep-xl-models.md) — XL (4B) DiT family: `xl-base` vs `xl-mixed` deployment shapes, hardware floor (≥12 GB VRAM, 24 GB M3 reference, 32 GB+ for `xl-mixed`), the two silent-regression footguns (`num_inference_steps=50` MUST be explicit, `shift=3.0` default), and an XL-vs-standard decision tree\n- [`references/mps-bf16-acceleration.md`](references/mps-bf16-acceleration.md) — honest Apple Silicon (MPS) reference: which env vars actually work (`PYTORCH_MPS_HIGH_WATERMARK_RATIO=0.0`, `ACESTEP_LM_BACKEND=mlx`), and the verifiable fact that ACE-Step currently forces fp32 on MPS (no bf16 escape valve — `ACESTEP_USE_BF16` is NOT consumed)\n- [`references/lrc-generation.md`](references/lrc-generation.md) — backend-neutral LRC (synced lyrics) workflow: WhisperX/Whisper transcription → lyrics alignment → LRC format → validator\n- [`references/audition-rubric.md`](references/audition-rubric.md) — 5-dimension quality scoring (Musicality, Production, Prompt Adherence, Vocal, Technical) for accept/revise/regenerate/reject decisions\n- [`references/acestep-shift-schedule.md`](references/acestep-shift-schedule.md) — full `shift` parameter taxonomy (shift=1.0 turbo, shift=3.0 base/sft, continuous shift) with tier-to-shift mapping table and decision tree\n- [`references/audio-format-selection.md`](references/audio-format-selection.md) — when to use wav vs flac vs mp3 vs ogg\n- [`references/advanced-diffusion-controls.md`](references/advanced-diffusion-controls.md) — `guidance_scale`, `infer_method`, `scheduler`, and `eta` parameter reference\n- [Local Models Install Guide](/Users/luis/Repos/skills/publish/LOCAL-MODELS-INSTALL-GUIDE.md) — cross-cutting install protocol shared with `music-craft-minimax`: license-acceptance gate, where to download, exact sizes, install commands, and verify steps for ACE-Step, MusicGen, and Stable Audio Open\n\n## Data, Consent, and Local Side Effects\n\nThis skill may use local or cloud music backends depending on what the user asks for and what is installed. Keep the workflow user-visible:\n\n- **Cloud backends:** prompts, lyrics, reference URLs, and generated/derived music instructions may be sent to the selected provider.\n- **Local backends:** model downloads, local analysis, temporary files, and generated audio may be written on the user's machine.\n- **Reference material:** fetched webpages and lyrics pages are used only to enrich the music prompt unless the user explicitly chooses an audio/cover workflow.\n- **Output files:** ask where to save generated files and avoid overwriting user-visible outputs without explicit confirmation.\n\nBefore uploading user-owned or third-party media to a cloud backend, state what will be sent and why, then wait for confirmation if the user has not already clearly requested that cloud workflow.\n\n## Licensing and commercial-use gate\n\nThe published skill bundle is MIT-0 under ClawHub's publishing rules: it may\nbe used, modified, and redistributed commercially without attribution. That\nlicense applies to these skill instructions and bundled helper code; it does\nnot grant a license to any third-party model, software package, input audio,\nlyrics, voice, or generated output. Every operator must install the selected\nbackend under its own applicable terms and keep the required notices. Terms\nand model cards can change, so check them before commercial release.\n\n- **ACE-Step 1.5 local:** the project and published model card currently state\n an MIT license and commercial-ready use. Verify the exact model checkpoint\n and its current license before shipping a commercial track.\n- **MusicGen local:** the code is MIT, but the MusicGen model weights are\n CC-BY-NC 4.0. Do not use MusicGen-generated audio for commercial work,\n monetized channels, client deliverables, paid products, or advertising.\n- **Provider-agnostic/runtime backends:** do not assume commercial rights.\n Identify the actual provider, model, account/product tier, and output terms\n before generating for commercial use. If these are unknown, stop and ask.\n- **Inputs:** the user must own or have permission for uploaded/reference\n audio, lyrics, samples, and voices. A model license does not legalize a\n copyrighted cover, lyric transcription, or unauthorized voice.\n\nGenerated audio may also lack copyright protection or exclusivity under the\nlaw of the user's jurisdiction. Commercial permission from a provider is not\nthe same as a guarantee of exclusive copyright or zero similarity risk.\n\nTreat music generation as a small, controlled iteration loop, not a single \"press button, get song\" call.\n\nThe required generation loop is:\n\n1. Clarify goal and source material.\n2. Analyze source audio if available, or accept user-provided analysis.\n3. Build a production-sheet prompt with genre, mood, BPM, key, instruments, structure, vocals/lyrics, and constraints.\n4. Select backend based on need: exact-duration vocals/lyrics -> ACE-Step; local melody-aware cover/repaint experiments -> ACE-Step if hardware and time budget allow; instrumental/local -> Stable Audio 3 or MusicGen; fast cloud cover, mashup, or MiniMax-specific flags -> `music-craft-minimax` / mmx.\n5. Validate prompt length, structure, backend-specific conflicts, and expected duration.\n6. Generate with the selected backend.\n7. Verify duration, loudness/peak, file size, audible completeness, lyrics alignment, and structure.\n8. Deliver files with a short analysis summary and caveats. If quality fails, adjust the prompt and retry; do not retry the same payload twice.\n\nFor deep prompt engineering, lyrics structure, and the full user-preference decision table, see the linked references at the end.\n\nFile v1.6.0:README.md\n\n# Music Craft\n\nGenerate songs, instrumentals, and lyrics-driven tracks through a disciplined OpenClaw-native workflow.\n\nCurrent release: v1.6.0.\n\nThis skill is **provider-agnostic**. It works with any music backend the OpenClaw runtime exposes via the `music_generate` tool — no special CLI, API, or library required.\n\n## Data and consent\n\nDepending on the chosen backend, prompts, lyrics, reference URLs, or generated/derived music instructions may be sent to a cloud provider. Local backends may download models and write temporary/generated audio files on the user's machine. Ask before installing/downloading large dependencies, uploading user-owned media, or overwriting existing outputs.\n\n## Licensing and commercial use\n\nClawHub publishes this skill bundle under MIT-0, so the skill instructions\nand bundled helper code may be used, modified, and redistributed commercially\nwithout attribution. MIT-0 does not grant rights to third-party models,\nsoftware, source material, or generated music. The operator must accept the\nselected backend's current terms on their own computer and use their own\nprovider account. ACE-Step 1.5\nis currently documented by its project as MIT/commercial-ready. MusicGen's\ncode is MIT, but its model weights are CC-BY-NC 4.0 and must not be used for\ncommercial output. For any other backend, identify and verify its model,\naccount tier, and output terms before commercial use. Source audio, lyrics,\nsamples, and voices must also be owned or properly licensed.\n\n## Platform support\n\nThis base workflow is effectively OS-neutral: it should work on macOS, Linux, and Windows as long as the active OpenClaw runtime exposes the `music_generate` tool. Platform differences only matter if the runtime provider itself needs local setup.\n\n## What it does\n\n- Translates your request into a production-sheet prompt with anti-sparse guards\n- Structures your lyrics (or auto-generated lyrics) with whitelisted section tags\n- Calls the runtime's `music_generate` tool\n- Verifies duration, loudness, structure, lyrics alignment, and audible quality before delivery\n- Documents prompt-length, lyrics-transcription, direct ACE-Step submission, wait-and-collect, and post-generation finalization safeguards\n\n## When to use\n\nUse this skill for any music generation task that does not require:\n\n- cover or style transfer from a reference audio file\n- emotion analysis or two-song mashup\n- separate `--avoid`, `--bpm`, `--key`, or `--structure` flags\n\nFor those, see [`music-craft-minimax`](../music-craft-minimax/) (requires MiniMax Token Plan). Audio input must be a local file path. URLs are not accepted in v1.5.0+; if you want to fetch audio by title from the internet, use the private `music-source-fetch` skill first (not published on ClawHub).\n\nIf the request is a standard song, instrumental, jingle, or lyrics-driven track, stay here and infer defaults first.\n\nFor exact-duration vocal tracks, prefer the local ACE-Step path documented in\n[`references/acestep-generation.md`](references/acestep-generation.md). The\n2026-06-12 field run verified 18/18 local ACE-Step jobs at exact requested\nduration; MiniMax cloud is faster but approximate.\n\n## Quickstart\n\nThis skill should load automatically when the task is clearly music generation. Typical flows:\n\n> \"Make an upbeat summer pop song in English, ~3 minutes, with original lyrics about road trips.\"\n\n> \"Here's a poem I wrote. Turn it into a rock ballad with male vocals in Spanish.\"\n\n> \"I need a 30-second lofi jingle for a YouTube intro, no vocals.\"\n\nThe skill reads, auto-detects what it can, asks at most 1–3 targeted questions for the ambiguous parts, then generates.\n\n## Workflow loop\n\n1. Clarify the goal and source material\n2. Analyze source audio if available, or accept user-provided analysis\n3. Build a production-sheet prompt\n4. Select the backend based on vocals, lyrics, length, local/cloud preference, speed, and hardware\n5. Validate prompt length, structure, conflicts, and expected duration\n6. Generate\n7. Verify duration, loudness/peak, file size, audible quality, lyrics alignment, and structure\n8. Deliver with a short analysis summary, or iterate with a targeted prompt adjustment\n\n## Reference\n\nFor full details, see [`SKILL.md`](SKILL.md).\n\nFor practical routing examples, see [`references/examples.md`](references/examples.md).\n\nFile v1.6.0:_meta.json\n\n{\n \"ownerId\": \"kn7fkh362pnj2zckq8pcxfaxr9821zv8\",\n \"slug\": \"music-craft\",\n \"version\": \"1.6.0\",\n \"publishedAt\": 1785411394536\n}\n\nFile v1.6.0:references/acestep-generation.md\n\n# ACE-Step Generation\n\nComplete ACE-Step 1.5 operating guide: API workflow (submit, poll, copy),\nfull-song generation, quality tiers with memory-safe selection, and\naudio-conditioned generation (cover, repaint, reference audio). Load this\nwhen the selected backend is ACE-Step.\n\n## ACE-Step 1.5 (local — free, vocals + lyrics, best local quality)\n\n**Best for:** local generation with real vocals, separate lyrics, song structure, up to 10 minutes (600s). No API key, no quota. Runs natively on Apple Silicon via MLX.\n\n**Verified routing note (2026-06-12):** ACE-Step is the exact-duration route.\nIn a 9-song field run, local M1+M2 generations returned the requested\n`audio_duration` exactly for 18/18 jobs. MiniMax cloud was faster but returned\n57-135% of requested duration for the paired cloud jobs.\n\n**Prerequisites:** REST API must be running on `http://127.0.0.1:8001`. Install with:\n```bash\ngit clone https://github.com/ace-step/ACE-Step-1.5.git \"${ACE_STEP_PATH}\"\ncd \"${ACE_STEP_PATH}\" && uv sync\nuv run acestep-api --port 8001 # or: ./start_api_server_macos.sh\n```\n\n(See [`setup-and-preflight.md`](setup-and-preflight.md) for how `ACE_STEP_PATH` is determined.)\n\n**Generation (3-step async):**\n\n```bash\n# 1. Submit task\nTASK_ID=$(curl -s -X POST http://127.0.0.1:8001/release_task \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"prompt\": \"\",\n \"lyrics\": \"[Verse]\\n\\n\\n[Chorus]\\n\",\n \"audio_duration\": 210,\n \"bpm\": 96,\n \"key_scale\": \"D major\",\n \"time_signature\": \"4/4\",\n \"vocal_language\": \"en\",\n \"thinking\": true,\n \"inference_steps\": 8,\n \"guidance_scale\": 7.0\n }' | python3 -c \"import json,sys; print(json.load(sys.stdin).get('data',{}).get('task_id',''))\")\n\n# 2. Poll for completion. Treat empty `data` as pending, not failed.\n# Wait, then check:\ncurl -s -X POST http://127.0.0.1:8001/query_result \\\n -H \"Content-Type: application/json\" \\\n -d \"{\\\"task_ids\\\": [\\\"$TASK_ID\\\"]}\"\n\n# 3. Copy audio from cache dir when done\n# Files saved to: ${ACE_STEP_PATH}/.cache/acestep/tmp/api_audio/\n```\n\n**Polling caveat:** The `/query_result` endpoint may return `{\"data\": [], \"code\": 200}` even while the task is actively running. This is a known server-side quirk. Don't treat empty data as \"task failed\" — instead, check for new MP3 files in the cache directory, or look at the server log (`/tmp/acestep-api.log`) for actual progress markers (e.g. `MLX DiT diffusion: 24/50`). If available, use `scripts/wait_for_acestep.py` because it reconciles `/query_result` with cache-file detection.\n\n**Stats caveat:** `GET /v1/stats` exposes top-level state such as queued,\nrunning, succeeded, failed, `queue_size`, and `avg_job_seconds`. It does not\nshow current sub-stage progress. For long jobs, use `/tmp/acestep-api.log` as\nthe source of truth for LM, DiT, CFG, and VAE progress.\n\n**Cache caveat:** generated audio accumulates under\n`${ACE_STEP_PATH}/.cache/acestep/tmp/api_audio/`. Review old files before\ndeleting them:\n\n```bash\nfind \"${ACE_STEP_PATH:-$HOME/ACE-Step-1.5}/.cache/acestep/tmp/api_audio\" \\\n -type f -name '*.mp3' -mtime +7 -print\n```\n\nReplace `-print` with `-delete` only after confirming the files are no longer\nneeded.\n\n**Cancel caveat:** there is no documented cancel endpoint for a queued or\nrunning local job. Lint prompt, lyrics, duration, and metas before submitting.\n\nFor a JSON-safe direct submission template, see\n[`local-ace-step-curl-template.md`](local-ace-step-curl-template.md). For the\nM1 -> wait -> collect -> M2 pattern, see\n[`wait-and-collect.md`](wait-and-collect.md).\n\n**Prompt format:** Prefer a **detailed, multi-dimensional caption** — ACE-Step's own docs call the caption \"the most important factor affecting generated music\", and the project's example prompts are rich 1–3 sentence descriptions, not bare tags. Cover, in order: **genre, key instruments, vocal character, mood, and production/texture** words. A short 2–6 word tag still works (and the LM expands it when `thinking=true`), but specificity measurably improves results. The earlier \"keep it to short tags\" advice was wrong for ACE-Step 1.5.\n\nTwo rules that matter:\n- **Resolve style conflicts temporally, don't stack them.** The model handles \"starts soft strings, builds to driving synth-rock, ends ambient\" far better than \"classical + hardcore metal\" jammed into one static caption.\n- **Keep the caption consistent with the lyrics' section tags** (a \"solo violin, classical\" caption fighting a `[Guitar Solo - distorted]` tag degrades output).\n\n## Full-song generation workflow (3:30 default)\n\nThe default `audio_duration` is **210s (3:30)** — the typical user expectation for a \"song\". Use 210s as the reference default only when the user has not specified a target length and no source-duration expectation needs to be matched. If source audio exists, confirm the target output length before submission rather than assuming the 210s default.\n\n**Inputs to prepare (set up once, reuse for every song):**\n1. **Lyrics** — write or obtain the full song lyrics with `[Verse 1]`, `[Pre-Chorus]`, `[Chorus]`, `[Verse 2]`, `[Bridge]`, `[Outro]` tags. ~150-200 words fits a 3:30 song comfortably.\n2. **Detailed caption** — see \"Prompt format\" above. ~500-1000 chars covering genre, instruments, vocal character, mood, production, emotional arc, and avoid list.\n3. **The 6 metas** — fill in `bpm`, `key_scale`, `time_signature`, `vocal_language`, `audio_duration: 210`, plus the prompt and lyrics.\n\n**Request body template for a full song (copy/paste and fill in):**\n\n```bash\nTASK_ID=$(curl -s -X POST http://127.0.0.1:8001/release_task \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"prompt\": \"\",\n \"lyrics\": \"[Verse 1]\\n\\n\\n\\n[Pre-Chorus]\\n\\n\\n\\n[Chorus]\\n\\n\\n\\n[Verse 2]\\n\\n\\n\\n[Bridge]\\n\\n\\n\\n[Outro]\\n\\n\\n\",\n \"audio_duration\": 210,\n \"bpm\": 96,\n \"key_scale\": \"D major\",\n \"time_signature\": \"4/4\",\n \"vocal_language\": \"en\",\n \"thinking\": true,\n \"inference_steps\": 8,\n \"guidance_scale\": 7.0\n }' | python3 -c \"import json,sys; print(json.load(sys.stdin).get('data',{}).get('task_id',''))\")\n```\n\n**Expected wall-clock on M3 24GB (standard tier, 2B turbo, 8 steps):**\n- LM thinking: ~6s (1.7B model, ~50 tok/s)\n- DiT diffusion: ~4-6 min (scales linearly with audio length)\n- VAE decode: ~40s\n- **Total: ~5-7 min per 3:30 song**\n\nSave each reference output in a per-song folder such as `~/Music mix///M1_