@melite/audio-music 0.2.2-alpha → 0.3.0-alpha

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/lib/card.d.ts CHANGED
@@ -25,12 +25,21 @@ export declare const schema: z<Schemastery.ObjectS<NoInfer<{
25
25
  tiled_decode: z<boolean, boolean, "plain">;
26
26
  }>>, "plain">;
27
27
  export declare const BOARDED: string[];
28
- /** THE ACTION BINDINGS (the atom vocabulary, stroke 3): the owning
29
- * family's declared compose action per boarded family — the card
30
- * owns only dispatch; the segment factories live in the family
31
- * packages (the legacy lanes stay the declared fallback +
32
- * byte-oracle). Keyed by OWNING FAMILY (`model.family ?? model.id`
33
- * at dispatch — a route id keys nothing, the derived-row law). */
28
+ /** THE SEAT-DRIVEN DISPATCH (the atom vocabulary, stroke 3): the
29
+ * owning family's declared compose action, resolved through the
30
+ * family's SEAT (family-seats.ts) at call time — the card owns
31
+ * only dispatch; the segment factories live in the family
32
+ * packages (the legacy lanes stay the declared fallback +
33
+ * byte-oracle). A family package absent from the install refuses
34
+ * loud HERE, by name; the card itself still loads and registers. */
35
+ export declare function composeFamilyAction(family: string, p: Record<string, unknown>, model: ModelFacts, g: GraphBuilder, runId: string): void;
36
+ /** THE ACTION BINDINGS: the dispatch table compose reads at call
37
+ * time, keyed by OWNING FAMILY (`model.family ?? model.id` — a
38
+ * route id keys nothing, the derived-row law). Each row closes
39
+ * over its literal family id and resolves the DECL through the
40
+ * seat, so a pruned family package costs its row's reach, never
41
+ * the table (the value-roundtrip corruption seats swap rows
42
+ * here). */
34
43
  export declare const ACTION_BINDINGS: Record<string, (p: Record<string, unknown>, model: ModelFacts, g: GraphBuilder, runId: string) => void>;
35
44
  /** The identity rung (label/description — the authored prose the
36
45
  * emitted tool row carries; the ring's spelling, stated once). */
package/lib/card.js CHANGED
@@ -1,19 +1,27 @@
1
1
  import z from '@deepseek-ai/schemastery';
2
2
  import { declaredAction, instantiateAction } from '@melite/comfyui-card-kit';
3
- import { DECL as music3Decl } from '@melite/models-music3';
4
- import { MUSIC3_FULL_STEPS } from '@melite/models-music3';
5
- import { DECL as yue2Decl } from '@melite/models-yue2';
6
3
  import { vocabulary } from '@melite/comfyui-card-kit/vocab';
7
4
  import { bag } from '@melite/contracts/extraKeys';
8
5
  import { seedExtra } from '@melite/comfyui-card-kit/fields';
9
6
  import { callableSchema, gatedResolve } from '@melite/comfyui-card-kit/admission';
7
+ import { primeFamilySeats, seatOf } from "./family-seats.js";
10
8
  export const schema = z.object({
11
9
  prompt: z.string().description("Tags / Description").extra('extra', bag({ order: 0, group: "prompt", columns: 1, tooltip: "Structured caption, three sections: Global Metadata (genre, mood, BPM) + Vocal Details (gender, timbre, range) + Arrangement (instruments, structure). Weak one-word captions end the song early — the tail turns to noise. E.g. 'A funk-pop soul track at 105 BPM; male baritone, warm rasp; clean guitar riff, brass stabs, tight pocket drums'.", required: true, wtype: 'textarea', })),
12
10
  lyrics: z.string().description("Lyrics").extra('extra', bag({ order: 1, group: "prompt", tooltip: "The song's PLAN — length lives here, not in Duration. Sung words with structure tags ([verse], [chorus]) for a song. Instrumental: sequential section tags only, each on its own line — [intro] / [instrumental] / [solo] / [instrumental] / [outro] — the model grants ~20-40s per block; repeat blocks to reach target length. An EMPTY box (or a lone [instrumental]) plans one ~35s phrase and ends. Keep 'no vocals, no choir, no humming' in the caption so extended blocks stay instrumental.", wtype: 'textarea' })),
13
11
  duration: z.number().description("Duration (s)").min(5).max(360).step(1).default(30).extra('extra', bag({ order: 0, group: "generation", width: 1, tooltip: "Audio length CEILING in seconds (5-360) — never a floor: the model ends the song when its plan ends, not when this number arrives. The plan lives in the LYRICS field — sung words for a song, sequential section tags ([intro] / [instrumental] / [solo] blocks, one per line, ~20-40s each) for an instrumental. An empty or single-tag lyrics box plans ONE phrase and wraps ~35s no matter how high this sits. Long track (>2min) + CUDA OOM: state tiled_decode.", wtype: 'slider' })),
14
12
  mode: vocabulary(["full", "melody", "off"]).description("ABC Planning").default("full").extra('extra', bag({ order: 1, group: "generation", width: 1, tooltip: "YuE2 only: plan a symbolic score before generating. full = melody + chords; melody = melody only (cover-recommended); off = direct generation.", wtype: 'select', visible_when: 'model=yue2' })),
15
13
  guidance_scale: z.number().description("CFG").min(0.1).max(10).step(0.1).default(1.7).extra('extra', bag({ order: 2, group: "generation", width: 1, tooltip: "Classifier-free guidance (KSampler cfg). 1.7 = the default.", visible_when: 'model=music3' })),
16
- n_diffusion_steps: z.number().description("Diffusion Steps").min(1).max(200).step(1).default(MUSIC3_FULL_STEPS.default).extra('extra', bag({ order: 3, group: "generation", width: 1, tooltip: "Denoising steps. 30 = the default (the full-schedule checkpoint tier's own default — the step↔checkpoint pairing). A distilled checkpoint states its own tier's window. Never 0.", wtype: 'number' })),
14
+ // THE SERVED DEFAULT (the full-schedule checkpoint tier's own
15
+ // default — the step↔checkpoint pairing; the tooltip carries the
16
+
17
+ // constant lives in the family package (music3's tier.ts,
18
+ // MUSIC3_FULL_STEPS.default) and this card loads WITHOUT it, so
19
+ // the number is a literal here — one home of the DERIVATION stays
20
+ // tier.ts (the DECL's resolver_defaults spread from it, and the
21
+ // step-tier wall judges the marriage on the dev tree); the
22
+ // compose action refuses a stated steps outside the resolved
23
+ // checkpoint's tier window at run time, never a silent drift.
24
+ n_diffusion_steps: z.number().description("Diffusion Steps").min(1).max(200).step(1).default(30).extra('extra', bag({ order: 3, group: "generation", width: 1, tooltip: "Denoising steps. 30 = the default (the full-schedule checkpoint tier's own default — the step↔checkpoint pairing). A distilled checkpoint states its own tier's window. Never 0.", wtype: 'number' })),
17
25
  lm_cfg_scale: z.number().description("LM CFG").min(0.1).max(10).step(0.1).default(1.7).extra('extra', bag({ order: 4, group: "generation", width: 1, tooltip: "Lyric-encoder guidance (MiniMaxMusic3TextEncode cfg_scale). 1.7 = the default.", visible_when: 'model=music3' })),
18
26
  seed: z.number().description("Seed").step(1).default(-1).extra('extra', bag(seedExtra({ order: 0, group: 'seed', width: 1 }))),
19
27
  // THE DECODE TIER KNOB (audit 014 C3): NO .default() — absence is
@@ -23,22 +31,43 @@ export const schema = z.object({
23
31
  tiled_decode: z.boolean().description("Tiled VAE Decode").extra('extra', bag({ order: 5, group: "generation", width: 1, tooltip: "Decode the audio latent in segments (lower VRAM, no quality loss at the template's 1536/64 seats). Absent = derived from the checkpoint's own numbers — a low-VRAM checkpoint or a track past 90s tiles; a roomy checkpoint at a short track decodes plain.", visible_when: 'model=music3' })),
24
32
  });
25
33
  const schemaFn = callableSchema(schema);
26
- // THE FAMILY IDS COME FROM THEIR DECLS (the closure gate's RULE 5):
27
- // a retyped id breaks the card at RUNTIME — not-boarded — with every
28
- // wall green. image-gen has done it this way all along.
29
- export const BOARDED = [music3Decl.id, yue2Decl.id];
30
- /** THE ACTION BINDINGS (the atom vocabulary, stroke 3): the owning
31
- * family's declared compose action per boarded family — the card
32
- * owns only dispatch; the segment factories live in the family
33
- * packages (the legacy lanes stay the declared fallback +
34
- * byte-oracle). Keyed by OWNING FAMILY (`model.family ?? model.id`
35
- * at dispatch — a route id keys nothing, the derived-row law). */
34
+
35
+ // "The Card can exist without a Family"): the family packages
36
+ // resolve through ./family-seats.ts (guarded dynamic seats, primed
37
+ // at registration) — a missing family package costs its OWN seat,
38
+ // never this card's load. A retyped id breaks the binding on the
39
+ // dev tree (the family-coverage wall judges every boarded entry
40
+ // against the live registry; the seat table skips a module whose
41
+ // DECL id names nothing), never silently at the not-boarded
42
+ // refusal.
43
+ export const BOARDED = ['music3', 'yue2'];
44
+ /** THE SEAT-DRIVEN DISPATCH (the atom vocabulary, stroke 3): the
45
+ * owning family's declared compose action, resolved through the
46
+ * family's SEAT (family-seats.ts) at call time — the card owns
47
+ * only dispatch; the segment factories live in the family
48
+ * packages (the legacy lanes stay the declared fallback +
49
+ * byte-oracle). A family package absent from the install refuses
50
+ * loud HERE, by name; the card itself still loads and registers. */
51
+ export function composeFamilyAction(family, p, model, g, runId) {
52
+ const seat = seatOf(family);
53
+ if (seat === undefined) {
54
+ throw new Error(`no declared action for family '${family}' on the music card — every boarded family (music3, yue2) composes its own declared segment; this address owns none (a family package absent from the install refuses here, by name)`);
55
+ }
56
+ instantiateAction(declaredAction(seat.decl, 'compose'), p, model, g, runId);
57
+ }
58
+ /** THE ACTION BINDINGS: the dispatch table compose reads at call
59
+ * time, keyed by OWNING FAMILY (`model.family ?? model.id` — a
60
+ * route id keys nothing, the derived-row law). Each row closes
61
+ * over its literal family id and resolves the DECL through the
62
+ * seat, so a pruned family package costs its row's reach, never
63
+ * the table (the value-roundtrip corruption seats swap rows
64
+ * here). */
36
65
  export const ACTION_BINDINGS = {
37
- [music3Decl.id]: (p, model, g, runId) => {
38
- instantiateAction(declaredAction(music3Decl, 'compose'), p, model, g, runId);
66
+ ['music3']: (p, model, g, runId) => {
67
+ composeFamilyAction('music3', p, model, g, runId);
39
68
  },
40
- [yue2Decl.id]: (p, model, g, runId) => {
41
- instantiateAction(declaredAction(yue2Decl, 'compose'), p, model, g, runId);
69
+ ['yue2']: (p, model, g, runId) => {
70
+ composeFamilyAction('yue2', p, model, g, runId);
42
71
  },
43
72
  };
44
73
  /** The identity rung (label/description — the authored prose the
@@ -50,13 +79,19 @@ export const identity = {
50
79
  icon: 'music',
51
80
  };
52
81
  export function registerCard(ctx, comfy) {
82
+ // THE PLUGIN LAW'S PRIMING (fire-and-forget, image-gen shape): the
83
+ // guarded dynamic imports of the boarded family packages start
84
+ // here; registration NEVER waits on a family package — a pruned
85
+ // family costs its own seat, never the estate boot.
86
+ void primeFamilySeats();
53
87
  ctx.effect(() => comfy.registerCard({
54
88
  id: 'music',
55
89
  // stage-row id the compose emits (retired skeleton= verbatim; TS owns the truth post-flip).
56
90
  skeleton: 'music',
57
-
58
- // rename silently diverged from this hand list. The spread is
59
- // the derivation; closure-gate RULE 5 pins it.)
91
+ // THE BOARDING LITERALS (the plugin law): ids stated once, judged
92
+ // on the dev tree by the family-coverage wall (a board naming
93
+ // nothing reds there), never derived at load from a package this
94
+ // card must load without.
60
95
  boarded: [...BOARDED],
61
96
  tags: ['audio', 'music', 'generate'],
62
97
  identity,
@@ -71,6 +106,16 @@ export function registerCard(ctx, comfy) {
71
106
  },
72
107
  // stock-only card: the MiniMax + YuE2 nodes ride upstream core
73
108
  // (comfy_extras.nodes_minimax_music / nodes_yue2); no requires.
109
+
110
+ // doc through gatedResolve('music', schemaFn, ['model'], p) —
111
+ // the model row id is admitted BEYOND the schema knobs (the
112
+ // card's own lane branch reads it; flowKinds.requiresModel:
113
+ // false only lifts the flow-stage demand). Declared here so
114
+ // the registry's admission surface (cardsFacts: def.admits)
115
+ // matches what the compose door actually serves — the
116
+ // dropped-knob sweep (runs-graph-receipt ARM j) reds on the
117
+
118
+ admits: ['model'],
74
119
  schema: schemaFn,
75
120
  compose(p, model, g, runId) {
76
121
  // THE SCHEMA GATE (the h3 admission precedent — the card's
@@ -0,0 +1,22 @@
1
+ import type { ModelDecl } from '@melite/comfyui-card-kit/model-contract';
2
+ /** One family's runtime seat: its DECL. The seat is the pattern any
3
+ * future craft face the families export rides (image-gen's seat
4
+ * carries anima's promptTags restorer the same way). */
5
+ export type FamilySeat = {
6
+ decl: ModelDecl;
7
+ };
8
+ /** Prime every family seat (idempotent; absent packages degrade to
9
+ * their own absence — the card never dies for a family). Fired
10
+ * fire-and-forget at registration; the post-boot seats read the
11
+ * filled table synchronously. */
12
+ export declare const primeFamilySeats: () => Promise<void>;
13
+ /** A family's seat — undefined when the package is absent (the
14
+ * compose door's own loud refusal names the family there). */
15
+ export declare const seatOf: (id: string) => FamilySeat | undefined;
16
+ /** The boarded knob's live ids — the PRESENT families in the
17
+ * FAMILY_MODULES order (a missing family costs its enum row, never
18
+ * the knob; an all-absent install serves an empty list and the
19
+ * tool face falls back to the BOARDED literal, where the run
20
+ * refuses loud at the model seat). */
21
+ export declare const boardedModels: () => string[];
22
+ //# sourceMappingURL=family-seats.d.ts.map
@@ -0,0 +1,46 @@
1
+ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
2
+ if (typeof path === "string" && /^\.\.?\//.test(path)) {
3
+ return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
4
+ return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
5
+ });
6
+ }
7
+ return path;
8
+ };
9
+ /** The boarded family modules, by package — ids live in card.ts's
10
+ * BOARDED literal (the family-coverage wall judges the binding on
11
+ * the dev tree; a typo'd id reds it there). */
12
+ const FAMILY_MODULES = [
13
+ '@melite/models-music3',
14
+ '@melite/models-yue2',
15
+ ];
16
+ const seats = new Map();
17
+ let priming = null;
18
+ /** Prime every family seat (idempotent; absent packages degrade to
19
+ * their own absence — the card never dies for a family). Fired
20
+ * fire-and-forget at registration; the post-boot seats read the
21
+ * filled table synchronously. */
22
+ export const primeFamilySeats = () => {
23
+ priming ??= Promise.allSettled(FAMILY_MODULES.map((spec) => import(__rewriteRelativeImportExtension(spec))))
24
+ .then((results) => {
25
+ for (const result of results) {
26
+ if (result.status !== 'fulfilled')
27
+ continue;
28
+ const mod = result.value;
29
+ const decl = mod?.DECL;
30
+ if (decl?.id === undefined || typeof decl.id !== 'string')
31
+ continue;
32
+ seats.set(decl.id, { decl });
33
+ }
34
+ });
35
+ return priming;
36
+ };
37
+ /** A family's seat — undefined when the package is absent (the
38
+ * compose door's own loud refusal names the family there). */
39
+ export const seatOf = (id) => seats.get(id);
40
+ /** The boarded knob's live ids — the PRESENT families in the
41
+ * FAMILY_MODULES order (a missing family costs its enum row, never
42
+ * the knob; an all-absent install serves an empty list and the
43
+ * tool face falls back to the BOARDED literal, where the run
44
+ * refuses loud at the model seat). */
45
+ export const boardedModels = () => [...seats.values()].map((seat) => seat.decl.id);
46
+ //# sourceMappingURL=family-seats.js.map
package/lib/tool.d.ts CHANGED
@@ -1,5 +1,10 @@
1
1
  import type { ToolDefinition } from '@deepseek-ai/dsh-tools';
2
2
  import type { EstateCall } from '@melite/estate-call';
3
3
  export declare const TOOL_NAME = "music";
4
- export declare const buildMusicTool: (call: EstateCall) => ToolDefinition;
4
+ /** Async since the L3 cure: the knob derives from the PRESENT
5
+ * family seats (primeFamilySeats awaits the guarded dynamic
6
+ * imports; a missing family package costs its own enum row, never
7
+ * the tool face). The harness seat that builds this tool is
8
+ * already async (melite-tools' lane seat awaits the builder). */
9
+ export declare const buildMusicTool: (call: EstateCall) => Promise<ToolDefinition>;
5
10
  //# sourceMappingURL=tool.d.ts.map
package/lib/tool.js CHANGED
@@ -1,18 +1,32 @@
1
1
  import { defineCardTool } from '@melite/estate-call/cardTool';
2
2
  import { emitParamsSpec } from '@melite/comfyui-card-kit/params-emit';
3
3
  import { schema, identity, BOARDED } from "./card.js";
4
+ import { boardedModels, primeFamilySeats } from "./family-seats.js";
4
5
  export const TOOL_NAME = 'music';
5
- export const buildMusicTool = (call) => defineCardTool(call, {
6
- name: TOOL_NAME,
7
- flow: 'music',
8
- label: identity.label,
9
- description: identity.description,
10
- // THE MODEL INPUT: the params walk synthesizes the model knob
11
- // from the boarded array (a CLOSED enum — the wrapper rejects
12
- // ''/unknown models at the seam); execute resolves the unstated
13
- // default itself (the DSL plane carries no defaults).
14
- parameters: emitParamsSpec(schema, BOARDED),
15
- defaultModel: BOARDED[0],
16
- previewField: 'prompt',
17
- });
6
+ /** Async since the L3 cure: the knob derives from the PRESENT
7
+ * family seats (primeFamilySeats awaits the guarded dynamic
8
+ * imports; a missing family package costs its own enum row, never
9
+ * the tool face). The harness seat that builds this tool is
10
+ * already async (melite-tools' lane seat awaits the builder). */
11
+ export const buildMusicTool = async (call) => {
12
+ await primeFamilySeats();
13
+ // The knob: the PRESENT families' ids, falling back to the
14
+ // BOARDED literal when no family package is installed (the enum
15
+ // serves the ids; the run refuses loud at the model seat — the
16
+ // image-gen fallback law).
17
+ const knob = boardedModels().length > 0 ? boardedModels() : [...BOARDED];
18
+ return defineCardTool(call, {
19
+ name: TOOL_NAME,
20
+ flow: 'music',
21
+ label: identity.label,
22
+ description: identity.description,
23
+ // THE MODEL INPUT: the params walk synthesizes the model knob
24
+ // from the boarded list (a CLOSED enum — the wrapper rejects
25
+ // ''/unknown models at the seam); execute resolves the unstated
26
+ // default itself (the DSL plane carries no defaults).
27
+ parameters: emitParamsSpec(schema, knob),
28
+ defaultModel: knob[0],
29
+ previewField: 'prompt',
30
+ });
31
+ };
18
32
  //# sourceMappingURL=tool.js.map
package/package.json CHANGED
@@ -1,5 +1,5 @@
1
1
  {
2
- "version": "0.2.2-alpha",
2
+ "version": "0.3.0-alpha",
3
3
  "license": "AGPL-3.0-or-later",
4
4
  "type": "module",
5
5
  "exports": {
@@ -18,23 +18,25 @@
18
18
  }
19
19
  },
20
20
  "dependencies": {
21
- "@deepseek-ai/dsh-tools": "0.2.1-rc.2",
22
- "@deepseek-ai/schemastery": "^3.18.5",
23
- "@melite/contracts": "0.2.2-alpha",
24
- "@melite/comfyui-card-kit": "0.2.2-alpha",
25
- "@melite/models-music3": "0.2.2-alpha",
26
- "@melite/estate-call": "0.2.2-alpha",
27
- "@melite/models-yue2": "0.2.2-alpha"
21
+ "@deepseek-ai/dsh-tools": "0.2.2-rc.5",
22
+ "@deepseek-ai/schemastery": "^3.19.0",
23
+ "@melite/comfyui-card-kit": "0.3.0-alpha",
24
+ "@melite/estate-call": "0.3.0-alpha",
25
+ "@melite/models-yue2": "0.3.0-alpha",
26
+ "@melite/models-music3": "0.3.0-alpha",
27
+ "@melite/contracts": "0.3.0-alpha"
28
28
  },
29
29
  "name": "@melite/audio-music",
30
30
  "description": "Text-to-music card and agent tool over the MiniMax Music 3 and YuE2-3B stock ComfyUI nodes.",
31
31
  "files": [
32
32
  "lib/index.js",
33
33
  "lib/**/*.js",
34
- "lib/**/*.d.ts"
34
+ "lib/**/*.d.ts",
35
+ "src/card.ts",
36
+ "src/agents"
35
37
  ],
36
38
  "peerDependencies": {
37
- "@deepseek-ai/cordis": "^4.0.5"
39
+ "@deepseek-ai/cordis": "^4.1.0"
38
40
  },
39
41
  "repository": {
40
42
  "type": "git",
@@ -0,0 +1,64 @@
1
+ ---
2
+ name: Music Card Agent
3
+ description: Drives the music card — MiniMax Music 3 (structured caption in params.prompt) and YuE2 (style + lyrics) through the queue
4
+ genre: audio
5
+ ---
6
+
7
+ # Music Card Agent
8
+
9
+ You compose MUSIC action cards. You never execute — the queue does.
10
+
11
+ ## Laws
12
+
13
+ 1. ONE card per session. Compose, verify, done.
14
+ 2. Structured caption rides **`params.prompt`** — there is NO
15
+ `caption` param. Genre + Vocal
16
+ Details + Arrangement — in that order, comma-separated.
17
+ 3. Genre sets the foundation; vocals and arrangement add detail. A WEAK
18
+ caption ("Disco music") makes the model end the song early and the
19
+ tail run as noise — all three sections, always (engine-observed).
20
+ 4. **DURATION IS A LEVER — for a SUNG song.** The lyrical plan carries
21
+ the clock and `duration` (5–360) caps it: set it near the target
22
+ and the song fills toward it. Draft ~30, final 90–120.
23
+ 5. **THE INSTRUMENTAL IS THE EXCEPTION — the tags are the clock.**
24
+ With no words to carry the plan, the model emits its end-of-audio
25
+ stop token when the tag roadmap runs out: a blank box or a lone
26
+ `[instrumental]` wraps ~20–35s no matter how high `duration` sits.
27
+ The long-form instrumental formula (all three legs, always):
28
+ - **Tag roadmap in `params.lyrics`** — stack 8–12 structural tags,
29
+ ONE PER LINE, nothing else on the line and no text under the
30
+ tags (any words there get vocalized): `[intro]` / `[instrumental]`
31
+ / `[interlude]` / `[solo]` / `[break]` / `[build up]` / `[outro]`.
32
+ Each tag is a distinct movement (~20–40s); repeat blocks to
33
+ reach the target length.
34
+ - **Disarm the vocal module in the caption's Vocal Details** —
35
+ explicit override: "Instrumental track — no vocals. Strictly
36
+ non-vocal composition without background humming, chops, or
37
+ synthesized vocal pads." The model is biased toward vocal
38
+ production; an omitted vocal line invites ad-libs, choir swells,
39
+ and humming into the extended blocks.
40
+ - **Coordinate the movement in Arrangement** — name lead and
41
+ rhythm instruments PER SECTION (intro: pads establish the key;
42
+ solo: lead takes the front; outro: fade to sustained pads).
43
+ With no singer to carry phrasing, per-section instrumentation
44
+ is what keeps the take from looping or cutting short.
45
+ - Set `duration` to the maximum you will allow — it is only the
46
+ cap; the roadmap decides the actual length.
47
+ 6. THE FAMILY EDGE: MiniMax Music 3
48
+ carries INSTRUMENTALS well; YuE2 has the edge in RAP. Both
49
+ families are boarded — pick by the ask's genre before composing,
50
+ not after a weak first pass.
51
+
52
+ ## Doors
53
+
54
+ - Compose: `melite_construct` — `add_stage` this card onto the shared
55
+ bench (`patch` / `rewire` to refine). The flow is live in the user's
56
+ cards tab; keep editing it as the user asks.
57
+ - Run: THE USER'S Run press on the card — never yours by default.
58
+ THE LANE LAW: when both lanes feel true,
59
+ THE LANE TEST decides — is the brief addressed to you as a DELIVERABLE?
60
+ Then compose it fully and say it is ready to run.
61
+ A question or joint exploration is not a deliverable — answer
62
+ it and shape the bench; either way your contract ends
63
+ at melite_construct and "ready to run".
64
+ - Progress: on the card itself (the user watches it run).
@@ -0,0 +1,42 @@
1
+ ---
2
+ name: gamekit-music
3
+ description: Survival theme music via music3 - three-section structured caption; the Recipe rows are short-sting (5s) / full-length (360s).
4
+ ---
5
+
6
+ ## Caption contract (90% of quality)
7
+ Plain `Label: text` lines, exactly three sections:
8
+ Genre (2-4 tags + era) / Vocal Details (or "instrumental, no vocals") /
9
+ Arrangement (instrumentation timeline, bpm, key).
10
+
11
+ ## Run (queue door — the only inference door)
12
+ Gateway: in-process estate lanes (DSH host; no port).
13
+ Compose via `melite_construct` `add_stage` onto the shared bench — the
14
+ run starts at the user's Run press, never the agent's.
15
+ Iterate ONLY at **`duration: 30`**; render the final at `duration: 90–120`
16
+ once the caption is locked (no `preset` knob exists — duration is the
17
+ draft/final lever; the caption itself rides `params.prompt`).
18
+ **LENGTH LIVES IN `params.lyrics`, not duration**: duration is a LEVER for
19
+ sung songs (the plan fills toward the cap) — but an INSTRUMENTAL has no
20
+ words to carry the clock, so the section tags ARE the roadmap and the
21
+ model stops when they run out (blank or lone `[instrumental]` wraps
22
+ ~20-35s no matter the duration). Long-form formula:
23
+ - 8-12 structural tags, one per line, NOTHING on the line or under the
24
+ tags (`[intro]` / `[instrumental]` / `[interlude]` / `[solo]` /
25
+ `[break]` / `[build up]` / `[outro]`) — ~20-40s per movement, repeat
26
+ to target length.
27
+ - Vocal Details carries the disarm directive: "Instrumental track — no
28
+ vocals. Strictly non-vocal composition without background humming,
29
+ chops, or synthesized vocal pads."
30
+ - Arrangement names lead/rhythm instruments PER SECTION so the take
31
+ doesn't loop or cut short.
32
+ - `duration` rides at the max you'll allow — cap only, the roadmap
33
+ decides.
34
+ Variations = same caption, new seeds.
35
+
36
+ ## Gotcha
37
+ The status endpoint may list NO artifacts while the FLAC lands in the run dir -
38
+ trust disk (`ls data/runs/<run_id>/`).
39
+
40
+ ## Deliver
41
+ FLAC in the run output dir — hand the artifact path to the asker
42
+ (the destination is the caller's product, not this skill's).
package/src/card.ts ADDED
@@ -0,0 +1,171 @@
1
+ // Tier 3 — the music card (the music_t1 renderer port).
2
+ // Decl + admission + one kit recipe call — the lane body rides @melite/comfyui-card-kit (musicT1/yue2T1).
3
+ // Instrumental = lyrics "" (MiniMax's own convention — baked, never
4
+ // an absent ref). Stock-only: the MiniMax + YuE2 nodes ride upstream
5
+ // core; no extension to declare (the retired card carried no requires).
6
+ import type { Context } from '@melite/comfyui-card-kit/card-definition'
7
+ import z from '@deepseek-ai/schemastery'
8
+ import { declaredAction, instantiateAction } from '@melite/comfyui-card-kit'
9
+ import type { ModelFacts } from '@melite/comfyui-card-kit/facts'
10
+ import type { GraphBuilder } from '@melite/comfyui-card-kit/graph'
11
+ import { vocabulary } from '@melite/comfyui-card-kit/vocab'
12
+ import { ComfyUIServiceFace } from '@melite/comfyui-card-kit/service-faces'
13
+ import { bag } from '@melite/contracts/extraKeys'
14
+ import { seedExtra } from '@melite/comfyui-card-kit/fields'
15
+ import { callableSchema, gatedResolve } from '@melite/comfyui-card-kit/admission'
16
+ import { primeFamilySeats, seatOf } from './family-seats.ts'
17
+
18
+ export const schema = z.object({
19
+ prompt: z.string().description("Tags / Description").extra('extra', bag({ order: 0, group: "prompt", columns: 1, tooltip: "Structured caption, three sections: Global Metadata (genre, mood, BPM) + Vocal Details (gender, timbre, range) + Arrangement (instruments, structure). Weak one-word captions end the song early — the tail turns to noise. E.g. 'A funk-pop soul track at 105 BPM; male baritone, warm rasp; clean guitar riff, brass stabs, tight pocket drums'.", required: true, wtype: 'textarea', })),
20
+ lyrics: z.string().description("Lyrics").extra('extra', bag({ order: 1, group: "prompt", tooltip: "The song's PLAN — length lives here, not in Duration. Sung words with structure tags ([verse], [chorus]) for a song. Instrumental: sequential section tags only, each on its own line — [intro] / [instrumental] / [solo] / [instrumental] / [outro] — the model grants ~20-40s per block; repeat blocks to reach target length. An EMPTY box (or a lone [instrumental]) plans one ~35s phrase and ends. Keep 'no vocals, no choir, no humming' in the caption so extended blocks stay instrumental.", wtype: 'textarea' })),
21
+ duration: z.number().description("Duration (s)").min(5).max(360).step(1).default(30).extra('extra', bag({ order: 0, group: "generation", width: 1, tooltip: "Audio length CEILING in seconds (5-360) — never a floor: the model ends the song when its plan ends, not when this number arrives. The plan lives in the LYRICS field — sung words for a song, sequential section tags ([intro] / [instrumental] / [solo] blocks, one per line, ~20-40s each) for an instrumental. An empty or single-tag lyrics box plans ONE phrase and wraps ~35s no matter how high this sits. Long track (>2min) + CUDA OOM: state tiled_decode.", wtype: 'slider' })),
22
+ mode: vocabulary(["full", "melody", "off"]).description("ABC Planning").default("full").extra('extra', bag({ order: 1, group: "generation", width: 1, tooltip: "YuE2 only: plan a symbolic score before generating. full = melody + chords; melody = melody only (cover-recommended); off = direct generation.", wtype: 'select', visible_when: 'model=yue2' })),
23
+ guidance_scale: z.number().description("CFG").min(0.1).max(10).step(0.1).default(1.7).extra('extra', bag({ order: 2, group: "generation", width: 1, tooltip: "Classifier-free guidance (KSampler cfg). 1.7 = the default.", visible_when: 'model=music3' })),
24
+ // THE SERVED DEFAULT (the full-schedule checkpoint tier's own
25
+ // default — the step↔checkpoint pairing; the tooltip carries the
26
+ // number). THE PLUGIN LAW (L3 cure, 2026-11-16): the tier
27
+ // constant lives in the family package (music3's tier.ts,
28
+ // MUSIC3_FULL_STEPS.default) and this card loads WITHOUT it, so
29
+ // the number is a literal here — one home of the DERIVATION stays
30
+ // tier.ts (the DECL's resolver_defaults spread from it, and the
31
+ // step-tier wall judges the marriage on the dev tree); the
32
+ // compose action refuses a stated steps outside the resolved
33
+ // checkpoint's tier window at run time, never a silent drift.
34
+ n_diffusion_steps: z.number().description("Diffusion Steps").min(1).max(200).step(1).default(30).extra('extra', bag({ order: 3, group: "generation", width: 1, tooltip: "Denoising steps. 30 = the default (the full-schedule checkpoint tier's own default — the step↔checkpoint pairing). A distilled checkpoint states its own tier's window. Never 0.", wtype: 'number' })),
35
+ lm_cfg_scale: z.number().description("LM CFG").min(0.1).max(10).step(0.1).default(1.7).extra('extra', bag({ order: 4, group: "generation", width: 1, tooltip: "Lyric-encoder guidance (MiniMaxMusic3TextEncode cfg_scale). 1.7 = the default.", visible_when: 'model=music3' })),
36
+ seed: z.number().description("Seed").step(1).default(-1).extra('extra', bag(seedExtra({ order: 0, group: 'seed', width: 1 }))),
37
+ // THE DECODE TIER KNOB (audit 014 C3): NO .default() — absence is
38
+ // the derivation's seat (the action derives plain/tiled from the
39
+ // lane's own VRAM/size signal; a stamped literal here would be the
40
+ // second default home the cure forbids). Stated, it overrides.
41
+ tiled_decode: z.boolean().description("Tiled VAE Decode").extra('extra', bag({ order: 5, group: "generation", width: 1, tooltip: "Decode the audio latent in segments (lower VRAM, no quality loss at the template's 1536/64 seats). Absent = derived from the checkpoint's own numbers — a low-VRAM checkpoint or a track past 90s tiles; a roomy checkpoint at a short track decodes plain.", visible_when: 'model=music3' })),
42
+ })
43
+
44
+ const schemaFn = callableSchema(schema)
45
+
46
+ // THE FAMILY IDS ARE LITERALS (the plugin law, L3 cure, 2026-11-16:
47
+ // "The Card can exist without a Family"): the family packages
48
+ // resolve through ./family-seats.ts (guarded dynamic seats, primed
49
+ // at registration) — a missing family package costs its OWN seat,
50
+ // never this card's load. A retyped id breaks the binding on the
51
+ // dev tree (the family-coverage wall judges every boarded entry
52
+ // against the live registry; the seat table skips a module whose
53
+ // DECL id names nothing), never silently at the not-boarded
54
+ // refusal.
55
+ export const BOARDED: string[] = ['music3', 'yue2']
56
+
57
+ /** THE SEAT-DRIVEN DISPATCH (the atom vocabulary, stroke 3): the
58
+ * owning family's declared compose action, resolved through the
59
+ * family's SEAT (family-seats.ts) at call time — the card owns
60
+ * only dispatch; the segment factories live in the family
61
+ * packages (the legacy lanes stay the declared fallback +
62
+ * byte-oracle). A family package absent from the install refuses
63
+ * loud HERE, by name; the card itself still loads and registers. */
64
+ export function composeFamilyAction(
65
+ family: string,
66
+ p: Record<string, unknown>,
67
+ model: ModelFacts,
68
+ g: GraphBuilder,
69
+ runId: string,
70
+ ): void {
71
+ const seat = seatOf(family)
72
+ if (seat === undefined) {
73
+ throw new Error(
74
+ `no declared action for family '${family}' on the music card — every boarded family (music3, yue2) composes its own declared segment; this address owns none (a family package absent from the install refuses here, by name)`)
75
+ }
76
+ instantiateAction(declaredAction(seat.decl, 'compose'), p, model, g, runId)
77
+ }
78
+
79
+ /** THE ACTION BINDINGS: the dispatch table compose reads at call
80
+ * time, keyed by OWNING FAMILY (`model.family ?? model.id` — a
81
+ * route id keys nothing, the derived-row law). Each row closes
82
+ * over its literal family id and resolves the DECL through the
83
+ * seat, so a pruned family package costs its row's reach, never
84
+ * the table (the value-roundtrip corruption seats swap rows
85
+ * here). */
86
+ export const ACTION_BINDINGS: Record<string, (p: Record<string, unknown>, model: ModelFacts, g: GraphBuilder, runId: string) => void> = {
87
+ ['music3']: (p, model, g, runId) => {
88
+ composeFamilyAction('music3', p, model, g, runId)
89
+ },
90
+ ['yue2']: (p, model, g, runId) => {
91
+ composeFamilyAction('yue2', p, model, g, runId)
92
+ },
93
+ }
94
+
95
+ /** The identity rung (label/description — the authored prose the
96
+ * emitted tool row carries; the ring's spelling, stated once). */
97
+ export const identity = {
98
+ label: 'Music',
99
+ description: 'Generate music — MiniMax Music 3 (structured captions with tagged lyrics) or YuE2-3B (style + lyrics with ABC planning)',
100
+ genre: 'audio',
101
+ icon: 'music',
102
+ }
103
+
104
+ export function registerCard(ctx: Context, comfy: ComfyUIServiceFace): void {
105
+ // THE PLUGIN LAW'S PRIMING (fire-and-forget, image-gen shape): the
106
+ // guarded dynamic imports of the boarded family packages start
107
+ // here; registration NEVER waits on a family package — a pruned
108
+ // family costs its own seat, never the estate boot.
109
+ void primeFamilySeats()
110
+ ctx.effect(() => comfy.registerCard({
111
+ id: 'music',
112
+ // stage-row id the compose emits (retired skeleton= verbatim; TS owns the truth post-flip).
113
+ skeleton: 'music',
114
+ // THE BOARDING LITERALS (the plugin law): ids stated once, judged
115
+ // on the dev tree by the family-coverage wall (a board naming
116
+ // nothing reds there), never derived at load from a package this
117
+ // card must load without.
118
+ boarded: [...BOARDED],
119
+ tags: ['audio', 'music', 'generate'],
120
+ identity,
121
+ // THE DISCOVERY ROWS (migrated 2026-09-10 from the frozen
122
+ // discovery export — the card owns its sidebar, surface, and
123
+ // flow-stage declarations; the discovery arms derive from here).
124
+ sidebar: { key: 'audio', order: 5 },
125
+ flowKinds: {
126
+ inputs: { prompt: 'text', lyrics: 'text' },
127
+ outputs: { default: 'audio' },
128
+ requiresModel: false,
129
+ },
130
+ // stock-only card: the MiniMax + YuE2 nodes ride upstream core
131
+ // (comfy_extras.nodes_minimax_music / nodes_yue2); no requires.
132
+ // THE MODEL ADMISSION (F3-04, 2026-11-15): compose resolves the
133
+ // doc through gatedResolve('music', schemaFn, ['model'], p) —
134
+ // the model row id is admitted BEYOND the schema knobs (the
135
+ // card's own lane branch reads it; flowKinds.requiresModel:
136
+ // false only lifts the flow-stage demand). Declared here so
137
+ // the registry's admission surface (cardsFacts: def.admits)
138
+ // matches what the compose door actually serves — the
139
+ // dropped-knob sweep (runs-graph-receipt ARM j) reds on the
140
+ // gap this row used to be.
141
+ admits: ['model'],
142
+ schema: schemaFn,
143
+ compose(p, model, g, runId) {
144
+ // THE SCHEMA GATE (the h3 admission precedent — the card's
145
+ // own declaration validates the last hop into the engine):
146
+ // schemastery walk enforces declared types + bounds (a
147
+ // duration=900 draft refuses LOUD here, never composes),
148
+ // fills defaults, admits legacy keys inert. The composer's
149
+ // reads below are reads of the GATED doc.
150
+ const doc = gatedResolve('music', schemaFn, ['model'], p)
151
+ if (!doc.prompt) {
152
+ throw new Error("required param 'prompt' missing or empty on the music card (the music caption — what the song IS)")
153
+ }
154
+ // THE LANE BRANCH (data never a family-id switch — the
155
+ // latent_node precedent): yue2's rail resolves a checkpoint
156
+ // row (one file carries model+clip+vae); music3's resolves
157
+ // the unet/clip/vae trio. THE DECLARED ACTIONS (the atom
158
+ // vocabulary, stroke 3): each boarded family's own compose
159
+ // action composes first — the data branch below is the
160
+ // declared legacy-lane fallback for family-less rows, never a
161
+ // silent second copy.
162
+ const bound = ACTION_BINDINGS[model.family ?? model.id]
163
+ if (bound) {
164
+ bound(doc, model, g, runId)
165
+ } else {
166
+ throw new Error(
167
+ `no declared action for family '${String(model.family ?? model.id)}' on the music card — every boarded family (music3, yue2) composes its own declared segment; this address owns none. State params.model (one of the boarded families) on the stage to compose it`)
168
+ }
169
+ },
170
+ }))
171
+ }