@ericdisero/aurora-shared 0.1.0 → 0.2.0

package/dist/providers/suno.d.ts

@@ -20,6 +20,16 @@ export interface GenerationParams {
     vocalGender?: 'male' | 'female';
     /** Comma-separated styles to exclude (the docs type this as ONE string). */
     negativeTags?: string;
+    /** 0..1 — style guidance intensity. */
+    styleWeight?: number;
+    /** 0..1 — creative deviation / novelty. */
+    weirdnessConstraint?: number;
+    /** 0..1 — input-audio influence (audio-conditioned tasks). */
+    audioWeight?: number;
+    /** Persona id (Generate Persona) or a Suno Voice voiceId. Custom mode only. */
+    personaId?: string;
+    /** 'style_persona' (default) | 'voice_persona' (voiceId on V5/V5_5). */
+    personaModel?: 'style_persona' | 'voice_persona';
 }
 /** Submit a generation task. Returns the provider taskId. */
 export declare function createGeneration(params: GenerationParams): Promise<string>;
@@ -31,6 +41,8 @@ export interface SoundsParams {
     /** BPM 1-300; omit for auto. */
     soundTempo?: number;
     soundLoop?: boolean;
+    /** Capture lyric subtitles alongside the audio. */
+    grabLyrics?: boolean;
 }
 /** Submit a Sounds Generation task. sunoapi.org ONLY — kie.ai does not expose
  *  the endpoint. Model locked to V5 by the docs. */
@@ -51,10 +63,55 @@ export interface CoverParams {
     negativeTags?: string;
     /** 0..1 — how strongly the output hews to the input audio. */
     audioWeight?: number;
+    styleWeight?: number;
+    weirdnessConstraint?: number;
+    personaId?: string;
+    personaModel?: 'style_persona' | 'voice_persona';
 }
 /** Submit an upload-and-cover (style transform) task. Poll the returned taskId
  *  with the generation record fetchers (same record-info endpoint). */
 export declare function createCover(params: CoverParams): Promise<string>;
+export interface AddVocalsParams {
+    /** Hosted instrumental URL from uploadAudioFile. */
+    uploadUrl: string;
+    /** Vocal content + stylistic direction (lyrics-style text works). */
+    prompt: string;
+    /** Genre / vocal approach, e.g. 'epic film choir, massed choral harmonies'. */
+    style: string;
+    /** Track title (≤100 chars). */
+    title: string;
+    /** Vocal styles to exclude, ONE comma-separated string (required by the docs). */
+    negativeTags: string;
+    vocalGender?: 'male' | 'female';
+    styleWeight?: number;
+    weirdnessConstraint?: number;
+    audioWeight?: number;
+    /** V4_5PLUS (default) | V5 | V5_5 — this endpoint supports only these three. */
+    model?: string;
+}
+/** Submit an add-vocals task: generates vocals over the uploaded instrumental,
+ *  harmonized with it. Poll with the generation record fetchers. */
+export declare function createAddVocals(params: AddVocalsParams): Promise<string>;
+export interface AddInstrumentalParams {
+    /** Hosted audio URL (usually vocals or a stem) from uploadAudioFile. */
+    uploadUrl: string;
+    /** Track title (≤100 chars). */
+    title: string;
+    /** Desired instrumental style/mood/instruments — this endpoint names the field
+     *  `tags`, NOT `style`. */
+    tags: string;
+    /** Styles/instruments to exclude, ONE comma-separated string. */
+    negativeTags: string;
+    vocalGender?: 'male' | 'female';
+    styleWeight?: number;
+    weirdnessConstraint?: number;
+    audioWeight?: number;
+    /** V4_5PLUS (default) | V5 | V5_5. */
+    model?: string;
+}
+/** Submit an add-instrumental task: generates backing instrumentation
+ *  complementary to the uploaded audio. Poll with the generation fetchers. */
+export declare function createAddInstrumental(params: AddInstrumentalParams): Promise<string>;
 export interface PolledVariation {
     /** Per-variation audio id — the WAV-conversion stage needs it. */
     id?: string;

package/dist/providers/suno.js

@@ -46,6 +46,24 @@ const POLL_DELAY_MS = 5000;
 const MAX_POLL_ATTEMPTS = 120; // ~10 min ceiling
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 const wireVocalGender = (v) => (v === 'male' ? 'm' : 'f');
+/** Append the shared optional knobs (full wire surface, param-table contract:
+ *  docs/suno-param-surface.md) onto a create body. */
+function applySharedKnobs(body, p) {
+    if (p.vocalGender)
+        body.vocalGender = wireVocalGender(p.vocalGender);
+    if (p.negativeTags)
+        body.negativeTags = p.negativeTags;
+    if (p.styleWeight !== undefined)
+        body.styleWeight = p.styleWeight;
+    if (p.weirdnessConstraint !== undefined)
+        body.weirdnessConstraint = p.weirdnessConstraint;
+    if (p.audioWeight !== undefined)
+        body.audioWeight = p.audioWeight;
+    if (p.personaId) {
+        body.personaId = p.personaId;
+        body.personaModel = p.personaModel ?? 'style_persona';
+    }
+}
 /** Submit a generation task. Returns the provider taskId. */
 export async function createGeneration(params) {
     const body = {
@@ -58,10 +76,7 @@ export async function createGeneration(params) {
         body.style = params.style;
     if (params.title)
         body.title = params.title;
-    if (params.vocalGender)
-        body.vocalGender = wireVocalGender(params.vocalGender);
-    if (params.negativeTags)
-        body.negativeTags = params.negativeTags;
+    applySharedKnobs(body, params);
     const res = await fetch(api('/api/v1/generate'), {
         method: 'POST',
         headers: authHeaders(),
@@ -84,6 +99,8 @@ export async function createSoundsGeneration(params) {
         body.soundTempo = params.soundTempo;
     if (params.soundLoop)
         body.soundLoop = true;
+    if (params.grabLyrics)
+        body.grabLyrics = true;
     const res = await fetch(api('/api/v1/generate/sounds'), {
         method: 'POST',
         headers: authHeaders(),
@@ -153,12 +170,7 @@ export async function createCover(params) {
             body.style = params.style;
         if (params.title)
             body.title = params.title;
-        if (params.vocalGender)
-            body.vocalGender = wireVocalGender(params.vocalGender);
-        if (params.negativeTags)
-            body.negativeTags = params.negativeTags;
-        if (params.audioWeight !== undefined)
-            body.audioWeight = params.audioWeight;
+        applySharedKnobs(body, params);
         if (withCallback)
             body.callBackUrl = CALLBACK_PLACEHOLDER;
         const res = await fetch(api('/api/v1/generate/upload-cover'), {
@@ -180,6 +192,73 @@ export async function createCover(params) {
         return attempt(true);
     }
 }
+/** Submit an add-vocals task: generates vocals over the uploaded instrumental,
+ *  harmonized with it. Poll with the generation record fetchers. */
+export async function createAddVocals(params) {
+    const attempt = async (withCallback) => {
+        const body = {
+            uploadUrl: params.uploadUrl,
+            prompt: params.prompt,
+            style: params.style,
+            title: params.title,
+            negativeTags: params.negativeTags,
+            model: params.model ?? 'V4_5PLUS'
+        };
+        applySharedKnobs(body, { ...params, negativeTags: undefined });
+        if (withCallback)
+            body.callBackUrl = CALLBACK_PLACEHOLDER;
+        const res = await fetch(api('/api/v1/generate/add-vocals'), {
+            method: 'POST',
+            headers: authHeaders(),
+            body: JSON.stringify(body)
+        });
+        const json = (await res.json());
+        const taskId = json.data?.taskId ?? json.data?.task_id;
+        if (!res.ok || (json.code !== undefined && json.code !== 200) || !taskId) {
+            throw new Error(`${host()} add-vocals failed (HTTP ${res.status}, code ${json.code ?? 'n/a'}): ${json.msg || 'no taskId returned'}`);
+        }
+        return taskId;
+    };
+    try {
+        return await attempt(false);
+    }
+    catch {
+        return attempt(true);
+    }
+}
+/** Submit an add-instrumental task: generates backing instrumentation
+ *  complementary to the uploaded audio. Poll with the generation fetchers. */
+export async function createAddInstrumental(params) {
+    const attempt = async (withCallback) => {
+        const body = {
+            uploadUrl: params.uploadUrl,
+            title: params.title,
+            tags: params.tags,
+            negativeTags: params.negativeTags,
+            model: params.model ?? 'V4_5PLUS'
+        };
+        applySharedKnobs(body, { ...params, negativeTags: undefined });
+        if (withCallback)
+            body.callBackUrl = CALLBACK_PLACEHOLDER;
+        const res = await fetch(api('/api/v1/generate/add-instrumental'), {
+            method: 'POST',
+            headers: authHeaders(),
+            body: JSON.stringify(body)
+        });
+        const json = (await res.json());
+        const taskId = json.data?.taskId ?? json.data?.task_id;
+        if (!res.ok || (json.code !== undefined && json.code !== 200) || !taskId) {
+            throw new Error(`${host()} add-instrumental failed (HTTP ${res.status}, code ${json.code ?? 'n/a'}): ${json.msg || 'no taskId returned'}`);
+        }
+        return taskId;
+    };
+    try {
+        return await attempt(false);
+    }
+    catch {
+        return attempt(true);
+    }
+}
 /** ONE record-info fetch (no waiting). The background-job model's poll unit. */
 export async function fetchGenerationRecord(taskId) {
     const res = await fetch(`${api('/api/v1/generate/record-info')}?taskId=${encodeURIComponent(taskId)}`, { headers: authHeaders() });

package/dist/skills/content.js

@@ -1,9 +1,9 @@
 // GENERATED — do not edit. Source: packages/shared/skills/*.md
 // Regenerated by scripts/embed-skills.mjs on every build.
 export const SKILLS = {
-    "aurora-cost-discipline": "---\nname: aurora-cost-discipline\ndescription: Credit and spend discipline for every paid Aurora operation (Suno generation/cover/sounds/WAV, MVSEP splits). Fires before any aurora_generate, aurora_cover, aurora_sounds, aurora_split, or aurora_fetch_wav call.\n---\n\n# Aurora Cost Discipline\n\nTwo metered providers sit behind Aurora's cloud ops. Spend is real money. The rules:\n\n## Always\n\n1. **`aurora_get_credits` BEFORE the first paid call of a session** — and after a batch, to log actual spend.\n2. **Never re-split.** `aurora_split` burns real MVSEP credits; the op refuses when 7 stems already exist — don't work around it. Check `aurora_list_assets` first.\n3. **Batch authorization, not per-call nagging.** When the user approves a multi-generation plan (\"make me 4 braams and a riser\"), that approval covers the enumerated batch — don't re-confirm each call. NEW spend beyond the approved batch needs a fresh ask.\n\n## Known costs (sunoapi.org credits, measured 2026-06-10)\n\n| Op | Cost |\n|---|---|\n| `aurora_sounds` | ~2.5 credits (~$0.0125) — the cheap verification + layer tool |\n| `aurora_cover` | ~12 credits + ~0.4 per WAV fetch |\n| `aurora_fetch_wav` | ~0.4 credits per conversion |\n| `aurora_generate` | not yet measured — check credits before/after and report the delta |\n| `aurora_split` | MVSEP credits, priced by audio duration (separate balance) |\n| `aurora_get_credits`, all local ffmpeg/stack/project ops | FREE |\n\n## Cheap-first ladder\n\n- Verifying a pipeline or experimenting? `aurora_sounds` first (2.5 credits), full `aurora_generate` only when the user wants a track.\n- Audition MP3s before paying for WAV upgrades; `aurora_fetch_wav` only the keepers.\n- Local ops (`aurora_pitch_shift`, `aurora_convert`, stack everything) cost nothing — prefer them over regenerating.\n",
+    "aurora-cost-discipline": "---\nname: aurora-cost-discipline\ndescription: Credit and spend discipline for every paid Aurora operation (Suno generation/cover/sounds/layering/WAV, MVSEP splits and extractions). Fires before any aurora_generate, aurora_cover, aurora_add_vocals, aurora_add_instrumental, aurora_sounds, aurora_split, aurora_extract, or aurora_fetch_wav call.\n---\n\n# Aurora Cost Discipline\n\nTwo metered providers sit behind Aurora's cloud ops. Spend is real money. The rules:\n\n## Always\n\n1. **`aurora_get_credits` BEFORE the first paid call of a session** — and after a batch, to log actual spend.\n2. **Never re-split.** `aurora_split` burns real MVSEP credits; the op refuses when 7 stems already exist — don't work around it. Check `aurora_list_assets` first.\n3. **Batch authorization, not per-call nagging.** When the user approves a multi-generation plan (\"make me 4 braams and a riser\"), that approval covers the enumerated batch — don't re-confirm each call. NEW spend beyond the approved batch needs a fresh ask.\n\n## Known costs (sunoapi.org credits, measured 2026-06-10)\n\n| Op | Cost |\n|---|---|\n| `aurora_sounds` | ~2.5 credits (~$0.0125) — the cheap verification + layer tool |\n| `aurora_cover` | ~12 credits + ~0.4 per WAV fetch |\n| `aurora_fetch_wav` | ~0.4 credits per conversion |\n| `aurora_generate` | not yet measured — check credits before/after and report the delta |\n| `aurora_add_vocals` / `aurora_add_instrumental` | not yet measured — same generation family; check the delta and report it |\n| `aurora_split` | MVSEP credits, priced by audio duration (separate balance); ALWAYS 3 MVSEP calls |\n| `aurora_extract` | MVSEP credits, VARIABLE by selection — the op's response includes the call plan; bundles count once however many of their stems you pick. Read the estimate before confirming a big catalog run |\n| `aurora_get_credits`, all local ffmpeg/stack/project ops | FREE |\n\n## Cheap-first ladder\n\n- Verifying a pipeline or experimenting? `aurora_sounds` first (2.5 credits), full `aurora_generate` only when the user wants a track.\n- Audition MP3s before paying for WAV upgrades; `aurora_fetch_wav` only the keepers.\n- Local ops (`aurora_pitch_shift`, `aurora_convert`, stack everything) cost nothing — prefer them over regenerating.\n",
     "aurora-music-production": "---\nname: aurora-music-production\ndescription: End-to-end Aurora workflow — create a project, generate or cover tracks, manufacture sounds, split into 7 stems, layer in the stack, export aligned WAVs for the DAW. Use when driving Aurora (the AI audio workbench) for any music production task.\n---\n\n# Aurora Music Production Workflow\n\nAurora is the desktop layer between AI music generation and a real DAW: generate AI music, split anything into stems, keep it all organized. Files on disk ARE the product — everything you create lands in a real project folder the user can open, play, and drag into their DAW.\n\n## Session start\n\n1. `aurora_get_workspace_state` — projects list, key status, folder locations. Once per session.\n2. `aurora_get_credits` — Suno credits + MVSEP minutes. ALWAYS before paid calls (see aurora-cost-discipline).\n\n## The verbs\n\n- **Generate** (`aurora_generate`) — full track from a prompt. 2 variations land as assets. 1-3 min.\n- **Cover** (`aurora_cover`) — style-transform an existing asset or file: same musical content, new style. `audioWeight` is the dial: 0 = new style dominates, 1 = stay close to the source.\n- **Sounds** (`aurora_sounds`) — samples, one-shots, loops with key/tempo lock. Fast (~20-30s), cheap (~2.5 credits). The layer-manufacturing tool: braams, booms, transitions, textures.\n- **Split** (`aurora_split`) — ANY asset → 7 stems (vocals, kick, snare, toms, hats, bass, everything-else). REAL MVSEP credits; never re-split (the op refuses if 7 stems exist).\n- **Stack** (`aurora_stack_*`) — layer assets/stems on lanes with offsets and gain, then `aurora_stack_export` for a sample-aligned multi-WAV bundle (drop at time zero in any DAW).\n\n## Long-op discipline\n\nGeneration and splits take minutes. Prefer `background: true` + `aurora_get_job_status` polling every 10-20s:\n\n- Status responses include `streamUrls` while a generation is still cooking — give the user the link, they can LISTEN ~30-45s in, minutes before files land.\n- Split stems land PROGRESSIVELY: vocals/kick/snare/toms/hats/bass appear as each MVSEP job finishes; everything-else (ee) lands last.\n- Jobs survive restarts — `aurora_list_jobs` recovers anything in flight.\n\n## Files + organization\n\n- Project folder: `generations/ covers/ imports/ references/ stems/<asset>/ masters/ stack-export/ stack.json`.\n- MP3 lands first; `aurora_fetch_wav` upgrades a generation/cover to provider WAV (~0.4 credits).\n- `aurora_pitch_shift` and `aurora_convert` are FREE local ffmpeg ops.\n- Mastering (analyze → mix → export) lives in the Aurora app window — point the user there once stems exist; it is not agent-drivable yet.\n\n## Suno prompting quick rules\n\n- Custom mode = set `style` AND `title` together; then `prompt` carries the LYRICS.\n- Non-custom mode: `prompt` is a track description.\n- `negativeTags` is ONE comma-separated string (\"Heavy Metal, Upbeat Drums\").\n- Sounds prompts: concrete and physical (\"huge cinematic braam, dark low brass, trailer hit\"), max 500 chars, lock `soundKey`/`tempo` when the track they'll sit in is known.\n",
     "aurora-split-and-stems": "---\nname: aurora-split-and-stems\ndescription: How Aurora's 7-stem split works (3 MVSEP jobs + phase cancellation), what the stems are, progressive landing, cost rules, and where stems live on disk. Use when calling aurora_split or working with split stems.\n---\n\n# Aurora Split & Stems\n\n## The 7 stems\n\n`vocals, kick, snare, toms, hats, bass, ee` (everything-else). Only 5 come from MVSEP; **hats** and **ee** are synthesized locally by phase cancellation (hats = drums − kick − snare − toms; ee = original − vocals − drums − bass). This is why ee always lands LAST.\n\n## How a split runs\n\n3 parallel MVSEP jobs (vocals model, drum separation, bass model) on one standardized 44.1kHz float32 WAV. Stems land **progressively** as each job finishes:\n\n- vocals job → `vocals`\n- drums job → `kick`, `snare`, `toms`, `hats`\n- bass job → `bass`\n- all three done → `ee`\n\nWith `background: true`, `aurora_get_job_status` shows the per-job landing state — the user can start auditioning early stems while the rest cook. Typical total: 3-5 minutes (longer if the MVSEP queue is busy — free-tier keys run 1 concurrent job, so the 3 jobs may serialize).\n\n## Cost rules\n\n- REAL MVSEP credits, priced by audio duration. Check `aurora_get_credits` (mvsepPremiumMinutes) first.\n- **Never re-split**: the op returns existing stems instead of spending again when a full set exists.\n- Any asset kind splits: generations, covers, imports, AND references (split-a-reference is a first-class loop for studying an arrangement).\n\n## On disk\n\nStems live at `<project>/stems/<asset-slug>-<id6>/*.wav` — 32-bit float, sample-aligned by construction. They are DAW-ready files: stack them (`aurora_stack_add_lane` with `stemType`), pitch them (`aurora_pitch_shift`), rip MIDI from them (`aurora_rip_midi`), or point the user at the folder.\n\nMastering against a reference (analyze → mix → export) happens in the Aurora app window from any split set — not agent-drivable yet.\n",
-    "aurora-suno-prompting": "---\nname: aurora-suno-prompting\ndescription: Prompting guide for Aurora's Suno-backed generation ops — generate (full tracks), cover (style transforms, the audioWeight dial), and sounds (samples/one-shots/loops with key+tempo lock). Use when writing prompts for aurora_generate, aurora_cover, or aurora_sounds.\n---\n\n# Suno Prompting for Aurora\n\n## aurora_generate — full tracks\n\nTwo modes, switched by whether you set `style`/`title`:\n\n- **Description mode** (no style/title): `prompt` describes the track — genre, mood, instrumentation, tempo feel, structure. One coherent paragraph beats keyword soup.\n- **Custom mode** (`style` AND `title` set): `prompt` carries the LYRICS; `style` carries the genre/production language. The provider requires BOTH style and title together.\n\nControls: `instrumental: true` for no vocals; `vocalGender` male/female; `negativeTags` as ONE comma-separated string of styles to avoid (\"Heavy Metal, Upbeat Drums\").\n\n## aurora_cover — style transforms\n\nThe source's musical content (melody, structure) is kept; the style is replaced.\n\n- `audioWeight` is the single most important dial: **0 = the new style dominates, 1 = stay close to the source.** 0.5-0.7 is the useful middle for \"same song, new genre\".\n- Custom mode rules are the same: `style` + `title` together, prompt describes the transformation target.\n- Source cap: 8 minutes. Project asset (`sourceAssetId`) or external file (`sourcePath`).\n\n## aurora_sounds — samples, one-shots, loops\n\nThe layer-manufacturing tool. Prompts are short (max 500 chars), physical, and concrete:\n\n- Name the sound type: braam, boom, riser, downer, whoosh, impact, drone, texture, loop.\n- Describe the material: \"dark low brass\", \"metallic scrape\", \"sub-heavy 808\", \"airy granular pad\".\n- Context helps: \"trailer hit\", \"transition\", \"intro swell\".\n- Lock `soundKey` (e.g. \"Cm\", \"F#\") and `tempo` (BPM) when the destination track is known — this is the point of the tool.\n- `loop: true` for loopable textures/grooves.\n\nEach call returns 2 variations — audition both before generating more.\n",
+    "aurora-suno-prompting": "---\nname: aurora-suno-prompting\ndescription: Prompting guide for Aurora's Suno-backed generation ops — generate (ultra-custom full tracks), cover (style transforms + single-layer covers), add_vocals/add_instrumental (layering over existing audio), and sounds (samples/loops with key+tempo lock). Use when writing prompts for aurora_generate, aurora_cover, aurora_add_vocals, aurora_add_instrumental, or aurora_sounds.\n---\n\n# Suno Prompting for Aurora\n\nFull wire-param reference: `docs/suno-param-surface.md` in this repo. Research receipts behind the layering recipes: second-brain `business/projects/aurora-docs/suno-layering-playbook-2026-06.md`.\n\n## The one principle that prevents the classic failure\n\n**Only show Suno the material you want performed.** Covers and audio-conditioned ops re-render EVERYTHING in the reference. Feed a full mix and ask for \"solo choir\" and you get a choir performing the drums. Feed one stem and you get that line re-performed.\n\n## aurora_generate — full tracks (ultra-custom is the default posture)\n\n- **Custom mode** (`customMode: true`, style + title required): `prompt` is the EXACT lyrics, sung as written (≤5000 chars on V4_5+). Use section metatags to steer arrangement: `[Verse]`, `[Chorus]`, `[Choir]`, `[Harmony]`, `[Guitar Solo]`, `[Instrumental]`. This is the default posture — the agent surface exists for full control.\n- **Description mode** (`customMode: false`): `prompt` ≤500 chars describing the track; Suno writes its own lyrics. Use only when the user genuinely wants a surprise.\n- Knobs: `styleWeight` (style adherence), `weirdnessConstraint` (low = predictable, high = surprises), `negativeTags` (ONE comma-separated string — more reliable than \"no X\" inside the style text), `vocalGender`, `personaId`/`personaModel` (consistent vocal character across generations; carries timbre, never melodies).\n- Models: V5/V5_5 have the best prompt + negative-tag adherence on record. V4 caps style at 200 chars and lyrics at 3000.\n\n### Isolated / solo material from scratch (a cappella choir, solo instrument)\n\nPure isolation is a coin flip on every model — stack the odds, expect 2-4 takes, and budget an aurora_split pass on keepers:\n\n1. Style field = ALL voice/instrument descriptors: `epic cinematic choir, a cappella, sacred choral, massed voices, no instruments` (under 200 chars, max 2-3 \"no X\" exclusions).\n2. `negativeTags: \"drums, percussion, orchestra, strings, piano, synthesizer, instruments\"`.\n3. Give the voices a job: Latin or invented syllables in the lyrics with `[Choir]`/`[Harmony]` tags — sung text occupies the slot that otherwise gets filled imitating instruments.\n4. Solo instrument: `instrumental: true` (hard mode, reliable) + single-instrument style + negativeTags for everything else.\n5. Key/BPM in the style text (\"120 BPM, D minor\") is approximate guidance, never a lock. For layering-grade sync, condition on audio instead (below) or conform the take in a DAW.\n\n## aurora_cover — style transforms AND single-layer covers\n\nThe source's musical content is kept; the style is replaced — for the WHOLE input.\n\n- **Whole-track transform** (same song, new genre): `audioWeight` 0.5-0.7.\n- **Single-layer cover** (the layering move — e.g. turn a string melody into a choir line): the reference must be ONLY the line to perform — one stem, a bare MIDI render, even a hummed take. Settings that lock structure while swapping timbre: `audioWeight` 0.7-0.85, `styleWeight` 0.55-0.75, `weirdnessConstraint` 0.2-0.4. Do not upload a dense master and expect surgical obedience. Change one knob at a time between takes.\n- Custom mode rules same as generate (style + title together). Source cap 8 minutes (V4_5ALL: 1 minute).\n\n## aurora_add_vocals — vocals/choir over an existing production\n\nThe designed-for-layering endpoint: upload an instrumental, get vocals performed against its tempo, key, and changes. THE recipe for \"add an epic choir to my finished arrangement\":\n\n1. Feed a SIMPLIFIED bounce — harmonic skeleton + the melody the choir should relate to. Strip drums and dense ornamentation first; dense masters degrade conditioning.\n2. `style: \"epic film choir, massed choral harmonies, latin chant\"`, `negativeTags: \"lead singer, pop vocal, rap, spoken word, autotune\"`, `audioWeight` 0.7-0.85, prompt = Latin/invented syllables with `[Choir]`/`[Harmony]` tags.\n3. The output is a full mix. **Discard Suno's backing**: aurora_split the result, keep ONLY the vocals stem, and lay it over the real production. This makes it irrelevant whether the endpoint preserved or re-rendered the upload.\n\nModels: V4_5PLUS (default) / V5 / V5_5 only.\n\n## aurora_add_instrumental — backing built around an upload\n\nInverse of add_vocals (input usually a vocal or melodic stem; output full mix with new instrumentation). Field name is `tags`, not `style`. Same split-and-keep-the-new-layer closer.\n\n## aurora_sounds — samples, loops, textures\n\nThe layer-manufacturing tool. Prompts are short (max 500 chars), physical, and concrete:\n\n- Name the sound type: braam, boom, riser, downer, whoosh, impact, drone, texture, loop.\n- Describe the material: \"dark low brass\", \"metallic scrape\", \"sub-heavy 808\", \"airy granular pad\".\n- Lock `soundKey` (e.g. \"Cm\", \"F#\") and `tempo` (BPM) when the destination track is known — this is the point of the tool. Sharps only at the wire (no flats).\n- `loop: true` for loopable textures/grooves; `grabLyrics: true` to capture lyric subtitles when the sound has voices.\n\n## When Suno is the wrong tool — say so\n\nFor \"a choir/vocalist singing the EXACT lines the user wrote, in tune with their track,\" no Suno path is note-precise. Recommend MIDI-native singing synths (Synthesizer V choir collections, ACE Studio choir mode) or sample libraries, and keep Suno for texture, surprise, and layer-covers where exact notes don't matter. The hybrid worth offering: write the line as MIDI, render it with anything, and aurora_cover THAT render with choir tags.\n\nEach generation-family call returns 2 variations — audition both before generating more.\n",
 };
 //# sourceMappingURL=content.js.map

package/dist/storage/assets.d.ts

@@ -5,6 +5,9 @@ export declare function getAsset(id: string): ProjectAsset | null;
 export declare function ensureKindDir(projectId: string, kind: AssetKind): Promise<string>;
 /** Where an asset's split stems land: <project>/stems/<asset-slug>-<shortid>/. */
 export declare function getAssetStemsDir(asset: ProjectAsset): string;
+/** Where an asset's Sample Extractor results land:
+ *  <project>/extracts/<asset-slug>-<shortid>/. Same naming discipline as stems. */
+export declare function getAssetExtractsDir(asset: ProjectAsset): string;
 /** Non-clobbering destination filename inside a kind dir. */
 export declare function uniqueDestPath(dir: string, fileName: string): string;
 export declare function insertAsset(params: {

package/dist/storage/assets.js

@@ -47,6 +47,11 @@ export async function ensureKindDir(projectId, kind) {
 export function getAssetStemsDir(asset) {
     return join(getProjectDirectory(asset.projectId), 'stems', `${slugify(asset.name, 40)}-${asset.id.slice(0, 6)}`);
 }
+/** Where an asset's Sample Extractor results land:
+ *  <project>/extracts/<asset-slug>-<shortid>/. Same naming discipline as stems. */
+export function getAssetExtractsDir(asset) {
+    return join(getProjectDirectory(asset.projectId), 'extracts', `${slugify(asset.name, 40)}-${asset.id.slice(0, 6)}`);
+}
 /** Non-clobbering destination filename inside a kind dir. */
 export function uniqueDestPath(dir, fileName) {
     const ext = extname(fileName);
@@ -93,9 +98,11 @@ export async function deleteAsset(id) {
         return;
     const db = getDb();
     db.prepare('DELETE FROM project_stems WHERE asset_id = ?').run(id);
+    db.prepare('DELETE FROM extraction_stems WHERE asset_id = ?').run(id);
     db.prepare('DELETE FROM project_assets WHERE id = ?').run(id);
     await rm(asset.path, { force: true }).catch(() => { });
     await rm(getAssetStemsDir(asset), { recursive: true, force: true }).catch(() => { });
+    await rm(getAssetExtractsDir(asset), { recursive: true, force: true }).catch(() => { });
     if (asset.refId)
         await deleteReference(asset.refId).catch(() => { });
     touchProject(asset.projectId);

package/dist/storage/extractions.d.ts

@@ -0,0 +1,11 @@
+import type { ExtractionStem } from '../types.js';
+export declare function getExtractionStems(assetId: string): ExtractionStem[];
+export declare function getProjectExtractionStems(projectId: string): ExtractionStem[];
+export declare function upsertExtractionStem(params: {
+    projectId: string;
+    assetId: string;
+    stemId: string;
+    path: string;
+    detectedKey: string | null;
+}): ExtractionStem;
+export declare function deleteExtractionStemsForAsset(assetId: string): void;

package/dist/storage/extractions.js

@@ -0,0 +1,42 @@
+import { randomUUID } from 'node:crypto';
+import { getDb } from '../db.js';
+function rowToStem(row) {
+    return {
+        id: row.id,
+        projectId: row.project_id,
+        assetId: row.asset_id,
+        stemId: row.stem_id,
+        path: row.path,
+        detectedKey: row.detected_key,
+        createdAt: row.created_at
+    };
+}
+export function getExtractionStems(assetId) {
+    const rows = getDb()
+        .prepare('SELECT * FROM extraction_stems WHERE asset_id = ? ORDER BY stem_id')
+        .all(assetId);
+    return rows.map(rowToStem);
+}
+export function getProjectExtractionStems(projectId) {
+    const rows = getDb()
+        .prepare('SELECT * FROM extraction_stems WHERE project_id = ? ORDER BY asset_id, stem_id')
+        .all(projectId);
+    return rows.map(rowToStem);
+}
+export function upsertExtractionStem(params) {
+    const db = getDb();
+    const id = randomUUID();
+    const now = Date.now();
+    db.prepare(`INSERT INTO extraction_stems (id, project_id, asset_id, stem_id, path, detected_key, created_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?)
+     ON CONFLICT(asset_id, stem_id)
+     DO UPDATE SET path = excluded.path, detected_key = excluded.detected_key, created_at = excluded.created_at`).run(id, params.projectId, params.assetId, params.stemId, params.path, params.detectedKey, now);
+    const row = db
+        .prepare('SELECT * FROM extraction_stems WHERE asset_id = ? AND stem_id = ?')
+        .get(params.assetId, params.stemId);
+    return rowToStem(row);
+}
+export function deleteExtractionStemsForAsset(assetId) {
+    getDb().prepare('DELETE FROM extraction_stems WHERE asset_id = ?').run(assetId);
+}
+//# sourceMappingURL=extractions.js.map

package/dist/types.d.ts

@@ -30,6 +30,18 @@ export interface ProjectStem {
     path: string;
     origin: 'mvsep' | 'synthesized';
 }
+/** A Sample Extractor result stem (schema v2 extraction_stems). stemId is a
+ *  catalog id from extract-catalog.ts (piano / vocal_lead / drum_kick / ee…). */
+export interface ExtractionStem {
+    id: string;
+    projectId: string;
+    assetId: string;
+    stemId: string;
+    path: string;
+    /** Krumhansl-Schmuckler result, e.g. "C major / A minor" (null = not detected). */
+    detectedKey: string | null;
+    createdAt: number;
+}
 export interface ReferenceTrack {
     id: string;
     name: string;

package/dist/types.js

@@ -1,5 +1,5 @@
 // Aurora domain types — mirrored from aurora/src/shared/types/index.ts (the
 // locked contract). The MCP works against the SAME DB + project folders as the
-// app, so these shapes must stay in lockstep with the app's schema v1.
+// app, so these shapes must stay in lockstep with the app's schema v2.
 export const STEM_TYPES = ['vocals', 'kick', 'snare', 'toms', 'hats', 'bass', 'ee'];
 //# sourceMappingURL=types.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ericdisero/aurora-shared",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Shared operations layer for the Aurora MCP server and CLI: storage, Suno/MVSEP provider clients, background jobs, and the single tool surface both consume. Most users want @ericdisero/aurora-mcp-server or @ericdisero/aurora-cli instead.",
   "license": "MIT",
   "type": "module",

package/skills/aurora-cost-discipline.md

@@ -1,6 +1,6 @@
 ---
 name: aurora-cost-discipline
-description: Credit and spend discipline for every paid Aurora operation (Suno generation/cover/sounds/WAV, MVSEP splits). Fires before any aurora_generate, aurora_cover, aurora_sounds, aurora_split, or aurora_fetch_wav call.
+description: Credit and spend discipline for every paid Aurora operation (Suno generation/cover/sounds/layering/WAV, MVSEP splits and extractions). Fires before any aurora_generate, aurora_cover, aurora_add_vocals, aurora_add_instrumental, aurora_sounds, aurora_split, aurora_extract, or aurora_fetch_wav call.
 ---
 
 # Aurora Cost Discipline
@@ -21,7 +21,9 @@ Two metered providers sit behind Aurora's cloud ops. Spend is real money. The ru
 | `aurora_cover` | ~12 credits + ~0.4 per WAV fetch |
 | `aurora_fetch_wav` | ~0.4 credits per conversion |
 | `aurora_generate` | not yet measured — check credits before/after and report the delta |
-| `aurora_split` | MVSEP credits, priced by audio duration (separate balance) |
+| `aurora_add_vocals` / `aurora_add_instrumental` | not yet measured — same generation family; check the delta and report it |
+| `aurora_split` | MVSEP credits, priced by audio duration (separate balance); ALWAYS 3 MVSEP calls |
+| `aurora_extract` | MVSEP credits, VARIABLE by selection — the op's response includes the call plan; bundles count once however many of their stems you pick. Read the estimate before confirming a big catalog run |
 | `aurora_get_credits`, all local ffmpeg/stack/project ops | FREE |
 
 ## Cheap-first ladder

package/skills/aurora-suno-prompting.md

@@ -1,35 +1,66 @@
 ---
 name: aurora-suno-prompting
-description: Prompting guide for Aurora's Suno-backed generation ops — generate (full tracks), cover (style transforms, the audioWeight dial), and sounds (samples/one-shots/loops with key+tempo lock). Use when writing prompts for aurora_generate, aurora_cover, or aurora_sounds.
+description: Prompting guide for Aurora's Suno-backed generation ops — generate (ultra-custom full tracks), cover (style transforms + single-layer covers), add_vocals/add_instrumental (layering over existing audio), and sounds (samples/loops with key+tempo lock). Use when writing prompts for aurora_generate, aurora_cover, aurora_add_vocals, aurora_add_instrumental, or aurora_sounds.
 ---
 
 # Suno Prompting for Aurora
 
-## aurora_generate — full tracks
+Full wire-param reference: `docs/suno-param-surface.md` in this repo. Research receipts behind the layering recipes: second-brain `business/projects/aurora-docs/suno-layering-playbook-2026-06.md`.
 
-Two modes, switched by whether you set `style`/`title`:
+## The one principle that prevents the classic failure
 
-- **Description mode** (no style/title): `prompt` describes the track — genre, mood, instrumentation, tempo feel, structure. One coherent paragraph beats keyword soup.
-- **Custom mode** (`style` AND `title` set): `prompt` carries the LYRICS; `style` carries the genre/production language. The provider requires BOTH style and title together.
+**Only show Suno the material you want performed.** Covers and audio-conditioned ops re-render EVERYTHING in the reference. Feed a full mix and ask for "solo choir" and you get a choir performing the drums. Feed one stem and you get that line re-performed.
 
-Controls: `instrumental: true` for no vocals; `vocalGender` male/female; `negativeTags` as ONE comma-separated string of styles to avoid ("Heavy Metal, Upbeat Drums").
+## aurora_generate — full tracks (ultra-custom is the default posture)
 
-## aurora_cover — style transforms
+- **Custom mode** (`customMode: true`, style + title required): `prompt` is the EXACT lyrics, sung as written (≤5000 chars on V4_5+). Use section metatags to steer arrangement: `[Verse]`, `[Chorus]`, `[Choir]`, `[Harmony]`, `[Guitar Solo]`, `[Instrumental]`. This is the default posture — the agent surface exists for full control.
+- **Description mode** (`customMode: false`): `prompt` ≤500 chars describing the track; Suno writes its own lyrics. Use only when the user genuinely wants a surprise.
+- Knobs: `styleWeight` (style adherence), `weirdnessConstraint` (low = predictable, high = surprises), `negativeTags` (ONE comma-separated string — more reliable than "no X" inside the style text), `vocalGender`, `personaId`/`personaModel` (consistent vocal character across generations; carries timbre, never melodies).
+- Models: V5/V5_5 have the best prompt + negative-tag adherence on record. V4 caps style at 200 chars and lyrics at 3000.
 
-The source's musical content (melody, structure) is kept; the style is replaced.
+### Isolated / solo material from scratch (a cappella choir, solo instrument)
 
-- `audioWeight` is the single most important dial: **0 = the new style dominates, 1 = stay close to the source.** 0.5-0.7 is the useful middle for "same song, new genre".
-- Custom mode rules are the same: `style` + `title` together, prompt describes the transformation target.
-- Source cap: 8 minutes. Project asset (`sourceAssetId`) or external file (`sourcePath`).
+Pure isolation is a coin flip on every model — stack the odds, expect 2-4 takes, and budget an aurora_split pass on keepers:
 
-## aurora_sounds — samples, one-shots, loops
+1. Style field = ALL voice/instrument descriptors: `epic cinematic choir, a cappella, sacred choral, massed voices, no instruments` (under 200 chars, max 2-3 "no X" exclusions).
+2. `negativeTags: "drums, percussion, orchestra, strings, piano, synthesizer, instruments"`.
+3. Give the voices a job: Latin or invented syllables in the lyrics with `[Choir]`/`[Harmony]` tags — sung text occupies the slot that otherwise gets filled imitating instruments.
+4. Solo instrument: `instrumental: true` (hard mode, reliable) + single-instrument style + negativeTags for everything else.
+5. Key/BPM in the style text ("120 BPM, D minor") is approximate guidance, never a lock. For layering-grade sync, condition on audio instead (below) or conform the take in a DAW.
+
+## aurora_cover — style transforms AND single-layer covers
+
+The source's musical content is kept; the style is replaced — for the WHOLE input.
+
+- **Whole-track transform** (same song, new genre): `audioWeight` 0.5-0.7.
+- **Single-layer cover** (the layering move — e.g. turn a string melody into a choir line): the reference must be ONLY the line to perform — one stem, a bare MIDI render, even a hummed take. Settings that lock structure while swapping timbre: `audioWeight` 0.7-0.85, `styleWeight` 0.55-0.75, `weirdnessConstraint` 0.2-0.4. Do not upload a dense master and expect surgical obedience. Change one knob at a time between takes.
+- Custom mode rules same as generate (style + title together). Source cap 8 minutes (V4_5ALL: 1 minute).
+
+## aurora_add_vocals — vocals/choir over an existing production
+
+The designed-for-layering endpoint: upload an instrumental, get vocals performed against its tempo, key, and changes. THE recipe for "add an epic choir to my finished arrangement":
+
+1. Feed a SIMPLIFIED bounce — harmonic skeleton + the melody the choir should relate to. Strip drums and dense ornamentation first; dense masters degrade conditioning.
+2. `style: "epic film choir, massed choral harmonies, latin chant"`, `negativeTags: "lead singer, pop vocal, rap, spoken word, autotune"`, `audioWeight` 0.7-0.85, prompt = Latin/invented syllables with `[Choir]`/`[Harmony]` tags.
+3. The output is a full mix. **Discard Suno's backing**: aurora_split the result, keep ONLY the vocals stem, and lay it over the real production. This makes it irrelevant whether the endpoint preserved or re-rendered the upload.
+
+Models: V4_5PLUS (default) / V5 / V5_5 only.
+
+## aurora_add_instrumental — backing built around an upload
+
+Inverse of add_vocals (input usually a vocal or melodic stem; output full mix with new instrumentation). Field name is `tags`, not `style`. Same split-and-keep-the-new-layer closer.
+
+## aurora_sounds — samples, loops, textures
 
 The layer-manufacturing tool. Prompts are short (max 500 chars), physical, and concrete:
 
 - Name the sound type: braam, boom, riser, downer, whoosh, impact, drone, texture, loop.
 - Describe the material: "dark low brass", "metallic scrape", "sub-heavy 808", "airy granular pad".
-- Context helps: "trailer hit", "transition", "intro swell".
-- Lock `soundKey` (e.g. "Cm", "F#") and `tempo` (BPM) when the destination track is known — this is the point of the tool.
-- `loop: true` for loopable textures/grooves.
+- Lock `soundKey` (e.g. "Cm", "F#") and `tempo` (BPM) when the destination track is known — this is the point of the tool. Sharps only at the wire (no flats).
+- `loop: true` for loopable textures/grooves; `grabLyrics: true` to capture lyric subtitles when the sound has voices.
+
+## When Suno is the wrong tool — say so
+
+For "a choir/vocalist singing the EXACT lines the user wrote, in tune with their track," no Suno path is note-precise. Recommend MIDI-native singing synths (Synthesizer V choir collections, ACE Studio choir mode) or sample libraries, and keep Suno for texture, surprise, and layer-covers where exact notes don't matter. The hybrid worth offering: write the line as MIDI, render it with anything, and aurora_cover THAT render with choir tags.
 
-Each call returns 2 variations — audition both before generating more.
+Each generation-family call returns 2 variations — audition both before generating more.