@bitmagic/cli 0.1.66-dev.6 → 0.1.66-dev.7

package/assets/metahuman/tools/metahuman/merge-skeletons.mjs

@@ -0,0 +1,69 @@
+// Step 2: merge the export's duplicate skeleton hierarchies (face / outfit / body) into ONE.
+// The pipeline exports every skinned mesh with its own copy of the rig: the face hierarchy carries
+// torso / neck / head + the facial joints but stops at the upper arms; the body hierarchy carries the
+// full limbs. Limb subtrees are grafted from the body hierarchy onto the face hierarchy (same names,
+// same rest transforms — the script asserts they match), every other skin is re-pointed at the merged
+// joints (same joint order, so the inverse-bind accessors stay valid) and the duplicate roots dropped.
+// Skins are found by the export's naming: SKM_<name>_FaceMesh, SKM_<name>_BodyMesh, <name>_Outfits.
+//   node merge-skeletons.mjs in.glb out.glb
+import { NodeIO } from '@gltf-transform/core';
+import { ALL_EXTENSIONS } from '@gltf-transform/extensions';
+import { prune } from '@gltf-transform/functions';
+const [,, input, output] = process.argv;
+if (!input || !output) { console.error('usage: node merge-skeletons.mjs in.glb out.glb'); process.exit(2); }
+const io = new NodeIO().registerExtensions(ALL_EXTENSIONS);
+const doc = await io.read(input);
+const root = doc.getRoot();
+const skins = root.listSkins();
+const face = skins.find((s) => /^SKM_.*_FaceMesh$/i.test(s.getName()));
+const body = skins.find((s) => /^SKM_.*_BodyMesh$/i.test(s.getName()));
+if (!face || !body) throw new Error(`need a SKM_<name>_FaceMesh and a SKM_<name>_BodyMesh skin; found: ${skins.map((s) => s.getName()).join(', ')}`);
+const others = skins.filter((s) => s !== face);
+const key = (n) => n.getName().toLowerCase();
+const merged = new Map(face.listJoints().map((j) => [key(j), j]));
+const parentOf = (n) => n.listParents().find((p) => p.propertyType === 'Node') ?? null;
+const registerSubtree = (n) => { merged.set(key(n), n); for (const c of n.listChildren()) registerSubtree(c); };
+// Graft: walk the body hierarchy top-down; any joint missing from the merged map whose parent IS
+// mapped gets re-parented (with its whole subtree) under the mapped parent.
+let grafted = 0, maxRestDiff = 0;
+const bodyRoot = body.listJoints().find((j) => key(j) === 'root');
+if (!bodyRoot) throw new Error('the body skin has no joint named "root"');
+const walk = (n) => {
+  const k = key(n);
+  if (!merged.has(k)) {
+    const p = parentOf(n);
+    const mp = p ? merged.get(key(p)) : null;
+    if (!mp) throw new Error(`cannot graft ${n.getName()}: parent ${p?.getName()} unmapped`);
+    p.removeChild(n); mp.addChild(n); registerSubtree(n); grafted++;
+    return; // subtree moved wholesale
+  } else if (merged.get(k) !== n) {
+    const a = n.getTranslation(), b = merged.get(k).getTranslation();
+    for (let i = 0; i < 3; i++) maxRestDiff = Math.max(maxRestDiff, Math.abs(a[i] - b[i]));
+  }
+  for (const c of [...n.listChildren()]) walk(c);
+};
+walk(bodyRoot);
+console.log(`grafted ${grafted} limb subtrees from the body hierarchy; max rest-translation diff of duplicates = ${maxRestDiff.toExponential(2)}`);
+if (maxRestDiff > 1e-4) console.warn('WARNING: duplicate joints do not share a rest pose — the merge assumes they do; inspect before using this file');
+for (const skin of others) {
+  const joints = skin.listJoints();
+  const mapped = joints.map((j) => { const m = merged.get(key(j)); if (!m) throw new Error(`unmapped joint ${j.getName()} in ${skin.getName()}`); return m; });
+  for (const j of joints) skin.removeJoint(j);
+  for (const j of mapped) skin.addJoint(j);
+  skin.setSkeleton(merged.get('root'));
+}
+let detached = 0;
+for (const node of root.listNodes()) {
+  if (key(node) === 'root' && node !== merged.get('root')) {
+    for (const p of node.listParents().filter((p) => p.propertyType === 'Node')) { p.removeChild(node); detached++; }
+  }
+}
+await doc.transform(prune());
+const jointSets = root.listSkins().map((s) => s.getName() + ':' + s.listJoints().length);
+const uniqueJoints = new Set(root.listSkins().flatMap((s) => s.listJoints()));
+console.log(`detached ${detached} duplicate roots; nodes now ${root.listNodes().length}; skins ${jointSets.join(' ')}; unique joint nodes ${uniqueJoints.size}`);
+const reachable = new Set(); const dfs = (n) => { reachable.add(n); for (const c of n.listChildren()) dfs(c); }; dfs(merged.get('root'));
+const unreachable = [...uniqueJoints].filter((j) => !reachable.has(j)).map((j) => j.getName());
+if (unreachable.length) throw new Error(`${unreachable.length} joints unreachable from root: ${unreachable.slice(0, 10).join(', ')}`);
+await io.write(output, doc);
+console.log('written', output);

package/assets/metahuman/tools/metahuman/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "metahuman-tools",
+  "private": true,
+  "description": "GLB preparation and verification rig for Epic MetaHuman exports — see the importing-metahumans skill",
+  "type": "module",
+  "dependencies": {
+    "@gltf-transform/core": "^4.5.0",
+    "@gltf-transform/extensions": "^4.5.0",
+    "@gltf-transform/functions": "^4.5.0",
+    "draco3dgltf": "^1.5.7",
+    "playwright-core": "^1.59.1"
+  }
+}

package/assets/metahuman/tools/metahuman/prepare.sh

@@ -0,0 +1,25 @@
+#!/bin/zsh
+# Prepare a MetaHuman glTF export (smorchj/metahuman-to-glb) for the Bitmagic engine, in five steps:
+#   1 strip Draco (the engine's loader has no decoder)      2 merge the three skeleton copies into one
+#   3 body mesh first (the engine reads the bind pose from the first skin)
+#   4 Laplacian-smooth the garment weights (shorts 6 × λ0.5, shirt 12 × λ0.6)
+#   5 give the garment the skin's weights wherever skin lies under it (no more poke-through)
+# Usage: tools/metahuman/prepare.sh <export.glb> <out.glb>   (env SHORT_RE / SHIRT_RE override the garment
+# material regexes; KEEP_STEPS=1 keeps the intermediate files next to <out.glb>)
+set -e
+HERE="${0:A:h}"
+IN="${1:A}"; OUT="${2:A}"
+[[ -f "$IN" && -n "$2" ]] || { echo "usage: tools/metahuman/prepare.sh <export.glb> <out.glb>"; exit 2; }
+mkdir -p "${OUT:h}"
+cd "$HERE"
+[[ -d node_modules ]] || npm install --no-audit --no-fund
+T=$(mktemp -d)
+node strip-draco.mjs "$IN" "$T/1-nodraco.glb"
+node merge-skeletons.mjs "$T/1-nodraco.glb" "$T/2-merged.glb"
+node reorder-body-first.mjs "$T/2-merged.glb" "$T/3-bodyfirst.glb"
+node smooth-outfit-weights.mjs "$T/3-bodyfirst.glb" "$T/4-smooth-a.glb" 6 0.5 "${SHORT_RE:-Short}"
+node smooth-outfit-weights.mjs "$T/4-smooth-a.glb" "$T/5-smooth-b.glb" 12 0.6 "${SHIRT_RE:-Shirt}"
+node transfer-skin-weights.mjs "$T/5-smooth-b.glb" "$OUT" 0.02 0.045
+if [[ -n "$KEEP_STEPS" ]]; then cp "$T"/*.glb "${OUT:h}/"; fi
+rm -rf "$T"
+ls -la "$OUT" | awk '{printf "prepared %s (%.1f MB)\n", $9, $5/1e6}'

package/assets/metahuman/tools/metahuman/reorder-body-first.mjs

@@ -0,0 +1,20 @@
+// Step 3: put the full-body skinned mesh FIRST in the glTF scene. The engine's CharacterLoader captures a
+// rig's bind pose from the first skinned mesh it traverses; the face skin stops at the upper arms, so with
+// the face first the forearms, hands and legs get raw clip rotations (split legs, twisted arms).
+// Order: SKM_<name>_BodyMesh, <name>_Outfits, everything else, SKM_<name>_FaceMesh.
+//   node reorder-body-first.mjs in.glb out.glb
+import { NodeIO } from '@gltf-transform/core';
+import { ALL_EXTENSIONS } from '@gltf-transform/extensions';
+const [,, input, output] = process.argv;
+if (!input || !output) { console.error('usage: node reorder-body-first.mjs in.glb out.glb'); process.exit(2); }
+const io = new NodeIO().registerExtensions(ALL_EXTENSIONS);
+const doc = await io.read(input);
+const scene = doc.getRoot().listScenes()[0];
+const kids = scene.listChildren();
+const rank = (n) => (/^SKM_.*_BodyMesh$/i.test(n.getName()) ? 0 : /_Outfits$/i.test(n.getName()) ? 1 : /^SKM_.*_FaceMesh$/i.test(n.getName()) ? 3 : 2);
+const sorted = [...kids].sort((a, b) => rank(a) - rank(b));
+if (!sorted.some((n) => rank(n) === 0)) throw new Error(`no SKM_<name>_BodyMesh node at the scene root; roots: ${kids.map((n) => n.getName()).join(', ')}`);
+for (const k of kids) scene.removeChild(k);
+for (const k of sorted) scene.addChild(k);
+console.log('scene order now:', scene.listChildren().map((n) => n.getName()).join(' → '));
+await io.write(output, doc);

package/assets/metahuman/tools/metahuman/smooth-outfit-weights.mjs

@@ -0,0 +1,48 @@
+// Step 4: Laplacian-smooth the skin weights of the outfit mesh so hard weight seams (a torso helper joint
+// next to arm twist correctives at the armpit) become gradients. Keeps the 4 strongest influences.
+// Run once per garment with its own strength: a short garment needs less than a shirt.
+//   node smooth-outfit-weights.mjs in.glb out.glb [iterations=6] [lambda=0.5] [materialRegex=.] [meshRegex=_Outfits$]
+import { NodeIO } from '@gltf-transform/core';
+import { ALL_EXTENSIONS } from '@gltf-transform/extensions';
+const [,, input, output, iterationsArg = '6', lambdaArg = '0.5', onlyArg = '.', meshArg = '_Outfits$'] = process.argv;
+if (!input || !output) { console.error('usage: node smooth-outfit-weights.mjs in.glb out.glb [iterations] [lambda] [materialRegex] [meshRegex]'); process.exit(2); }
+const only = new RegExp(onlyArg, 'i'); const meshRe = new RegExp(meshArg, 'i');
+const iterations = +iterationsArg, lambda = +lambdaArg;
+const io = new NodeIO().registerExtensions(ALL_EXTENSIONS);
+const doc = await io.read(input);
+let done = 0;
+for (const mesh of doc.getRoot().listMeshes()) {
+  if (!meshRe.test(mesh.getName())) continue;
+  for (const prim of mesh.listPrimitives()) {
+    if (!only.test(prim.getMaterial()?.getName() ?? '')) continue;
+    const J = prim.getAttribute('JOINTS_0'), W = prim.getAttribute('WEIGHTS_0'), I = prim.getIndices();
+    if (!J || !W || !I) continue;
+    const n = J.getCount(); const j = new Uint32Array(4), w = new Float32Array(4);
+    const maps = [];
+    for (let v = 0; v < n; v++) { J.getElement(v, j); W.getElement(v, w); const m = new Map(); for (let k = 0; k < 4; k++) if (w[k] > 0) m.set(j[k], (m.get(j[k]) || 0) + w[k]); maps.push(m); }
+    const adj = Array.from({ length: n }, () => new Set());
+    const ia = I.getArray();
+    for (let t = 0; t < ia.length; t += 3) { const a = ia[t], b = ia[t + 1], c = ia[t + 2]; adj[a].add(b); adj[a].add(c); adj[b].add(a); adj[b].add(c); adj[c].add(a); adj[c].add(b); }
+    let cur = maps;
+    for (let it = 0; it < iterations; it++) {
+      const next = [];
+      for (let v = 0; v < n; v++) {
+        const nb = adj[v]; const acc = new Map();
+        for (const [k, x] of cur[v]) acc.set(k, (1 - lambda) * x);
+        if (nb.size) { const s = lambda / nb.size; for (const u of nb) for (const [k, x] of cur[u]) acc.set(k, (acc.get(k) || 0) + s * x); }
+        next.push(acc);
+      }
+      cur = next;
+    }
+    const jOut = new Uint16Array(n * 4), wOut = new Float32Array(n * 4);
+    for (let v = 0; v < n; v++) {
+      const top = [...cur[v].entries()].sort((a, b) => b[1] - a[1]).slice(0, 4);
+      const sum = top.reduce((s, [, x]) => s + x, 0) || 1;
+      top.forEach(([k, x], i) => { jOut[v * 4 + i] = k; wOut[v * 4 + i] = x / sum; });
+    }
+    J.setArray(jOut); W.setArray(wOut); done++;
+    console.log(`smoothed ${mesh.getName()} / ${prim.getMaterial()?.getName()}: ${n} vertices, ${iterations} iterations, lambda ${lambda}`);
+  }
+}
+if (!done) console.warn(`nothing matched mesh /${meshArg}/ material /${onlyArg}/`);
+await io.write(output, doc);

package/assets/metahuman/tools/metahuman/strip-draco.mjs

@@ -0,0 +1,32 @@
+// Step 1: rewrite a MetaHuman export without Draco compression — the engine's `engine.loader` is a plain
+// GLTFLoader (no Draco / KTX2 decoders), so a compressed export loads as nothing at all. Prints an
+// inventory (morph targets, skins, the joints the later steps rely on) so you can see what the export is.
+//   node strip-draco.mjs in.glb out.glb
+import { NodeIO } from '@gltf-transform/core';
+import { ALL_EXTENSIONS } from '@gltf-transform/extensions';
+import draco3d from 'draco3dgltf';
+const [,, input, output] = process.argv;
+if (!input || !output) { console.error('usage: node strip-draco.mjs in.glb out.glb'); process.exit(2); }
+const io = new NodeIO().registerExtensions(ALL_EXTENSIONS).registerDependencies({
+  'draco3d.decoder': await draco3d.createDecoderModule(),
+  'draco3d.encoder': await draco3d.createEncoderModule(),
+});
+const doc = await io.read(input);
+let stripped = 0;
+for (const ext of doc.getRoot().listExtensionsUsed()) {
+  if (ext.extensionName === 'KHR_draco_mesh_compression') { ext.dispose(); stripped++; }
+}
+console.log(stripped ? 'Draco stripped' : 'no Draco extension present');
+for (const mesh of doc.getRoot().listMeshes()) {
+  for (const prim of mesh.listPrimitives()) {
+    const t = prim.listTargets();
+    if (t.length) console.log(`mesh ${mesh.getName()} prim mat=${prim.getMaterial()?.getName()} targets=${t.length} targetAttrs=${t[0].listSemantics().join(',')}`);
+  }
+}
+for (const skin of doc.getRoot().listSkins()) {
+  const names = skin.listJoints().map((j) => j.getName());
+  console.log(`skin ${skin.getName()} joints=${names.length} first=${names.slice(0, 8).join(',')}`);
+  console.log(`  body/head joints present: ${names.filter((n) => /^(head|neck_0[12]|spine_0[1-5]|pelvis|root|clavicle_[lr]|upperarm_[lr]|hand_[lr]|thigh_[lr]|foot_[lr])$/.test(n)).join(',')}`);
+}
+await io.write(output, doc);
+console.log('written', output);

package/assets/metahuman/tools/metahuman/transfer-skin-weights.mjs

@@ -0,0 +1,90 @@
+// Step 5: give the outfit meshes the SKIN's weights wherever skin exists under them (shoulders, collar, arm
+// tops from the body + the face mesh's neck skirt), so cloth and skin deform identically and the
+// skin can no longer poke through. Blends back to the outfit's own weights away from any skin.
+//   node transfer-skin-weights.mjs in.glb out.glb [rFull=0.02] [rMax=0.045]
+import { NodeIO } from '@gltf-transform/core';
+import { ALL_EXTENSIONS } from '@gltf-transform/extensions';
+const [,, input, output, rFullArg = '0.02', rMaxArg = '0.045'] = process.argv;
+const R_FULL = +rFullArg, R_MAX = +rMaxArg;
+const io = new NodeIO().registerExtensions(ALL_EXTENSIONS);
+const doc = await io.read(input);
+const root = doc.getRoot();
+const nodeFor = (re) => root.listNodes().find((n) => re.test(n.getMesh()?.getName() ?? ''));
+const outfitNode = nodeFor(/_Outfits$/i), bodyNode = nodeFor(/^SKM_.*_BodyMesh$/i), faceNode = nodeFor(/^SKM_.*_FaceMesh$/i);
+if (!outfitNode || !bodyNode || !faceNode) throw new Error(`nodes: outfit ${!!outfitNode} body ${!!bodyNode} face ${!!faceNode}`);
+const outSkin = outfitNode.getSkin();
+const jointNames = (skin) => skin.listJoints().map((j) => j.getName());
+const outNames = jointNames(outSkin); const outIndex = new Map(outNames.map((n, i) => [n, i]));
+
+// Gather skin sources: [position, Map<jointName, weight>] per vertex, from every skin-material primitive.
+const sources = [];
+for (const [node, re] of [[bodyNode, /Body/], [faceNode, /Face_Skin/]]) {
+  const skin = node.getSkin(); const names = jointNames(skin);
+  for (const prim of node.getMesh().listPrimitives()) {
+    if (!re.test(prim.getMaterial()?.getName() ?? '')) continue;
+    const P = prim.getAttribute('POSITION'), J = prim.getAttribute('JOINTS_0'), W = prim.getAttribute('WEIGHTS_0');
+    const p = new Float32Array(3), j = new Uint32Array(4), w = new Float32Array(4);
+    for (let v = 0; v < P.getCount(); v++) {
+      P.getElement(v, p); J.getElement(v, j); W.getElement(v, w);
+      const m = new Map(); for (let k = 0; k < 4; k++) if (w[k] > 0.001) m.set(names[j[k]], (m.get(names[j[k]]) || 0) + w[k]);
+      sources.push({ x: p[0], y: p[1], z: p[2], m });
+    }
+  }
+}
+// Spatial hash.
+const CELL = R_MAX; const grid = new Map(); const key = (x, y, z) => `${Math.floor(x / CELL)},${Math.floor(y / CELL)},${Math.floor(z / CELL)}`;
+sources.forEach((s, i) => { const k = key(s.x, s.y, s.z); (grid.get(k) || grid.set(k, []).get(k)).push(i); });
+const near = (x, y, z) => {
+  const out = []; const cx = Math.floor(x / CELL), cy = Math.floor(y / CELL), cz = Math.floor(z / CELL);
+  for (let dx = -1; dx <= 1; dx++) for (let dy = -1; dy <= 1; dy++) for (let dz = -1; dz <= 1; dz++) {
+    const cell = grid.get(`${cx + dx},${cy + dy},${cz + dz}`); if (!cell) continue;
+    for (const i of cell) { const s = sources[i]; const d = Math.hypot(s.x - x, s.y - y, s.z - z); if (d <= R_MAX) out.push([d, i]); }
+  }
+  out.sort((a, b) => a[0] - b[0]); return out.slice(0, 3);
+};
+const smoothstep = (e0, e1, x) => { const t = Math.min(1, Math.max(0, (x - e0) / (e1 - e0))); return t * t * (3 - 2 * t); };
+// Joints the outfit skin lacks (the face's neck correctives): add them, with the source skin's IBMs.
+const needed = new Set();
+for (const s of sources) for (const n of s.m.keys()) if (!outIndex.has(n)) needed.add(n);
+if (needed.size) {
+  const faceSkin = faceNode.getSkin(); const faceNames = jointNames(faceSkin);
+  const ibmAcc = outSkin.getInverseBindMatrices(); const faceIbm = faceSkin.getInverseBindMatrices();
+  const old = ibmAcc.getArray(); const added = [...needed];
+  const arr = new Float32Array(old.length + added.length * 16); arr.set(old);
+  const m = new Float32Array(16);
+  added.forEach((name, k) => {
+    const fi = faceNames.indexOf(name); if (fi < 0) throw new Error(`joint ${name} not in face skin`);
+    faceIbm.getElement(fi, m); arr.set(m, old.length + k * 16);
+    outSkin.addJoint(faceSkin.listJoints()[fi]); outIndex.set(name, outNames.length + k);
+  });
+  ibmAcc.setArray(arr);
+  console.log(`added ${added.length} joints to the outfit skin (${added.slice(0, 4).join(', ')}…)`);
+}
+let full = 0, blended = 0, untouched = 0;
+for (const prim of outfitNode.getMesh().listPrimitives()) {
+  const P = prim.getAttribute('POSITION'), J = prim.getAttribute('JOINTS_0'), W = prim.getAttribute('WEIGHTS_0');
+  const n = P.getCount(); const p = new Float32Array(3), j = new Uint32Array(4), w = new Float32Array(4);
+  const jOut = new Uint16Array(n * 4), wOut = new Float32Array(n * 4);
+  const curNames = jointNames(outSkin);
+  for (let v = 0; v < n; v++) {
+    P.getElement(v, p); J.getElement(v, j); W.getElement(v, w);
+    const own = new Map(); for (let k = 0; k < 4; k++) if (w[k] > 0.001) own.set(curNames[j[k]], (own.get(curNames[j[k]]) || 0) + w[k]);
+    const nb = near(p[0], p[1], p[2]);
+    let mix = own;
+    if (nb.length) {
+      const skinMap = new Map(); let tot = 0;
+      for (const [d, i] of nb) { const wgt = 1 / (d * d + 1e-6); tot += wgt; for (const [name, x] of sources[i].m) skinMap.set(name, (skinMap.get(name) || 0) + wgt * x); }
+      for (const [name, x] of skinMap) skinMap.set(name, x / tot);
+      const t = 1 - smoothstep(R_FULL, R_MAX, nb[0][0]);
+      if (t >= 0.999) full++; else blended++;
+      mix = new Map(); for (const [name, x] of skinMap) mix.set(name, t * x); for (const [name, x] of own) mix.set(name, (mix.get(name) || 0) + (1 - t) * x);
+    } else untouched++;
+    const top = [...mix.entries()].sort((a, b) => b[1] - a[1]).slice(0, 4);
+    const sum = top.reduce((s, [, x]) => s + x, 0) || 1;
+    top.forEach(([name, x], i) => { const idx = outIndex.get(name); if (idx === undefined) throw new Error(`no joint ${name}`); jOut[v * 4 + i] = idx; wOut[v * 4 + i] = x / sum; });
+  }
+  J.setArray(jOut); W.setArray(wOut);
+  console.log(`${prim.getMaterial()?.getName()}: ${n} vertices`);
+}
+console.log(`transfer: ${full} full, ${blended} blended, ${untouched} untouched (R_FULL ${R_FULL} m, R_MAX ${R_MAX} m); skin sources ${sources.length}`);
+await io.write(output, doc);

package/dist/commands/generate.d.ts

@@ -49,6 +49,25 @@ export interface MusicArgs {
  * request is made — the plan's verification line 7.
  */
 export declare function buildMusicBody(args: MusicArgs): Record<string, unknown>;
+export interface SpeechArgs {
+    text: string;
+    voice?: string;
+    model?: string;
+    stability?: string;
+    similarityBoost?: string;
+    style?: string;
+    speed?: string;
+    assetId?: string;
+}
+/**
+ * The same omission contract as {@link buildSoundBody}: a voice setting left alone is left out
+ * entirely, so Eleven Labs' own default stands rather than the CLI pinning a copy of it.
+ *
+ * The character cap is restated from the generator schema so an over-long line is refused here,
+ * before a request is made — this lane is billed by the length of the audio, and a 20,000
+ * character paste is an expensive way to learn about a 400.
+ */
+export declare function buildSpeechBody(args: SpeechArgs): Record<string, unknown>;
 export interface ImageArgs {
     name: string;
     prompt: string;
@@ -220,6 +239,36 @@ export declare function runMusicGeneration(options: {
     json: boolean;
     deps?: GenerateRunDeps;
 }): Promise<MusicRunResult>;
+export interface SpeechRunResult {
+    speechUrl: string;
+    originalUrl: string;
+    speechId: string;
+    durationSeconds: number;
+    patchesApplied: number;
+    /** Where the MP3 was saved, when `--out` asked for it. */
+    file?: string;
+    bytes?: number;
+}
+/**
+ * `generate speech` has the same two-outputs shape as `generate music`, and for a sharper reason:
+ * the world.json asset is a line an NPC speaks (`engine.playSound`), while the MP3 is the input
+ * `tools/lipsync/make_line.py --audio` needs to cut mouth cues from. A creator rigging a talking
+ * character wants the file and NOT the asset, so `--no-world` is a first-class path here rather
+ * than an escape hatch.
+ *
+ * Cannot go through {@link runAssetGeneration} because that always applies the patches and never
+ * downloads; it shares {@link requestAssetWithJobRecord} so the request, the job record and the
+ * "world.json is unchanged" failure contract are the same as every other lane's.
+ */
+export declare function runSpeechGeneration(options: {
+    body: Record<string, unknown>;
+    /** Save the MP3 here (relative to the current directory). */
+    out?: string;
+    /** Apply the asset to world.json. The default; `--no-world` turns it off. */
+    world: boolean;
+    json: boolean;
+    deps?: GenerateRunDeps;
+}): Promise<SpeechRunResult>;
 /**
  * Refuses `--voxel-grid` alongside `--mesh`, rather than ignoring it.
  *

package/dist/commands/generate.js

@@ -24,7 +24,8 @@ import { DEFAULT_MASTER_GRID, generateAndInstallProp } from '../generate/prop.js
 import { generateAndInstallVehicle } from '../generate/vehicle.js';
 import { generateAndInstallModel } from '../generate/model.js';
 import { downloadMusicFile } from '../generate/music.js';
-import { MUSIC_MAX_SECONDS, MUSIC_MIN_SECONDS, VIDEO_MAX_SECONDS, VIDEO_MIN_SECONDS } from '@bitmagic/asset-core';
+import { downloadAudioFile } from '../generate/audio-file.js';
+import { MUSIC_MAX_SECONDS, MUSIC_MIN_SECONDS, SPEECH_MAX_CHARS, SPEECH_VOICES, VIDEO_MAX_SECONDS, VIDEO_MIN_SECONDS, } from '@bitmagic/asset-core';
 import { generateAndInstallAnimationFromVideo, isLocomotionState, isVideoToMotionModel, } from '../generate/animation-from-video.js';
 import { generateAndInstallVideo, IMAGE_EXTENSIONS, } from '../generate/video.js';
 import { reviewGeneratedClip } from '../generate/video-review.js';
@@ -98,6 +99,30 @@ export function buildMusicBody(args) {
         assetId: args.assetId,
     });
 }
+/**
+ * The same omission contract as {@link buildSoundBody}: a voice setting left alone is left out
+ * entirely, so Eleven Labs' own default stands rather than the CLI pinning a copy of it.
+ *
+ * The character cap is restated from the generator schema so an over-long line is refused here,
+ * before a request is made — this lane is billed by the length of the audio, and a 20,000
+ * character paste is an expensive way to learn about a 400.
+ */
+export function buildSpeechBody(args) {
+    if (args.text.length > SPEECH_MAX_CHARS) {
+        throw new CliError(`--text is ${args.text.length} characters; the limit is ${SPEECH_MAX_CHARS}. `
+            + 'Split the line and generate it in parts. world.json is unchanged.');
+    }
+    return withoutAbsentFlags({
+        text: args.text,
+        voice: args.voice,
+        model: args.model,
+        stability: parseNumberFlag('stability', args.stability, { min: 0, max: 1 }),
+        similarityBoost: parseNumberFlag('similarity-boost', args.similarityBoost, { min: 0, max: 1 }),
+        style: parseNumberFlag('style', args.style, { min: 0, max: 1 }),
+        speed: parseNumberFlag('speed', args.speed, { min: 0.7, max: 1.2 }),
+        assetId: args.assetId,
+    });
+}
 export function buildImageBody(args) {
     return withoutAbsentFlags({
         name: args.name,
@@ -605,6 +630,77 @@ export async function runMusicGeneration(options) {
     }
     return result;
 }
+/**
+ * `generate speech` has the same two-outputs shape as `generate music`, and for a sharper reason:
+ * the world.json asset is a line an NPC speaks (`engine.playSound`), while the MP3 is the input
+ * `tools/lipsync/make_line.py --audio` needs to cut mouth cues from. A creator rigging a talking
+ * character wants the file and NOT the asset, so `--no-world` is a first-class path here rather
+ * than an escape hatch.
+ *
+ * Cannot go through {@link runAssetGeneration} because that always applies the patches and never
+ * downloads; it shares {@link requestAssetWithJobRecord} so the request, the job record and the
+ * "world.json is unchanged" failure contract are the same as every other lane's.
+ */
+export async function runSpeechGeneration(options) {
+    const output = createOutput(options.json);
+    const runDeps = options.deps ?? defaultDeps(options.json);
+    const outPath = options.out === undefined ? undefined : path.resolve(options.out);
+    const result = await requestAssetWithJobRecord('speech', 'speech', options.body, runDeps, async (outcome, worldPath, log) => {
+        if (!outcome.speech) {
+            throw new CliError('The server reported the speech as generated but sent no audio URLs. world.json is unchanged.');
+        }
+        const { speech } = outcome;
+        let patchesApplied = 0;
+        if (options.world) {
+            let applyResult;
+            try {
+                applyResult = applyPatchesToWorld(worldPath, outcome.patches);
+            }
+            catch (error) {
+                throw decoratedError(error, (message) => `Generated speech successfully, but could not write it into world.json: ${message} `
+                    + 'world.json is unchanged — the line was generated (and may have been billed) but is not '
+                    + `yet in your project. It is at ${speech.originalUrl}.`);
+            }
+            patchesApplied = applyResult.applied;
+            log(`Generated speech (${speech.durationSeconds.toFixed(1)}s): ${outcome.message}`);
+            for (const line of applyResult.summary)
+                runDeps.log(`  - ${line}`);
+            runDeps.log(worldUpdatedLine(patchesApplied));
+        }
+        else {
+            log(`Generated speech (${speech.durationSeconds.toFixed(1)}s): ${outcome.message}`);
+            runDeps.log('world.json is unchanged (--no-world).');
+        }
+        let bytes;
+        if (outPath !== undefined) {
+            try {
+                bytes = await downloadAudioFile(speech.originalUrl, outPath, runDeps.fetch, 'line');
+            }
+            catch (error) {
+                // The line is generated, billed, and (unless --no-world) already in world.json; only the
+                // local copy is missing, and the message has to say so or the creator regenerates.
+                throw decoratedError(error, (message) => `${message} The line was generated${options.world ? ' and is in world.json' : ''}; only saving `
+                    + 'the local copy failed.');
+            }
+            runDeps.log(`Saved ${outPath} (${Math.round(bytes / 1024)} KB).`);
+        }
+        return {
+            speechUrl: speech.speechUrl,
+            originalUrl: speech.originalUrl,
+            speechId: speech.speechId,
+            durationSeconds: speech.durationSeconds,
+            patchesApplied,
+            ...(outPath !== undefined ? { file: outPath } : {}),
+            ...(bytes !== undefined ? { bytes } : {}),
+        };
+    });
+    output.result({ ok: true, kind: 'speech', ...result });
+    if (options.world) {
+        runDeps.log(`Play it from game code with engine.playSound('${result.speechId}').`);
+        runDeps.log(DEV_VIEW_RELOADS);
+    }
+    return result;
+}
 /**
  * Refuses `--voxel-grid` alongside `--mesh`, rather than ignoring it.
  *
@@ -1168,6 +1264,76 @@ const musicCommand = defineCommand({
         });
     },
 });
+const speechCommand = defineCommand({
+    meta: {
+        name: 'speech',
+        description: 'Speak a line of text and add it to world.json assets (or save it as a file).',
+    },
+    args: {
+        text: {
+            type: 'string',
+            required: true,
+            description: 'The line to speak. Billed by the length of the audio it produces.',
+        },
+        voice: {
+            type: 'string',
+            description: `Voice: ${SPEECH_VOICES.join(', ')}, or a raw Eleven Labs voice_id. Default ${SPEECH_VOICES[0]}.`,
+        },
+        model: {
+            type: 'string',
+            description: 'Eleven Labs model id. Defaults to eleven_multilingual_v2.',
+        },
+        stability: {
+            type: 'string',
+            description: 'Voice stability, 0-1. Lower is more expressive, higher is more consistent.',
+        },
+        'similarity-boost': {
+            type: 'string',
+            description: 'How closely to match the original voice, 0-1.',
+        },
+        style: {
+            type: 'string',
+            description: 'Style exaggeration, 0-1.',
+        },
+        speed: {
+            type: 'string',
+            description: 'Speaking rate, 0.7-1.2.',
+        },
+        'asset-id': {
+            type: 'string',
+            description: 'Pre-minted asset_… id to store the line under, so code already referencing it resolves.',
+        },
+        out: {
+            type: 'string',
+            description: 'Also save the MP3 to this path — what tools/lipsync/make_line.py --audio takes.',
+        },
+        world: {
+            type: 'boolean',
+            default: true,
+            description: 'Add the line to world.json assets (the default). Pass --no-world with --out for a file only.',
+        },
+        'original-prompt': ORIGINAL_PROMPT_FLAG,
+        json: JSON_FLAG,
+    },
+    async run({ args }) {
+        const body = buildSpeechBody({
+            text: args.text,
+            voice: args.voice,
+            model: args.model,
+            stability: args.stability,
+            similarityBoost: args['similarity-boost'],
+            style: args.style,
+            speed: args.speed,
+            assetId: args['asset-id'],
+        });
+        await runSpeechGeneration({
+            body: withParent(body),
+            ...(args.out !== undefined ? { out: args.out } : {}),
+            world: args.world !== false,
+            json: args.json === true,
+        });
+    },
+});
 const imageCommand = defineCommand({
     meta: { name: 'image', description: 'Generate an image asset and add it to world.json assets.' },
     args: {
@@ -1935,6 +2101,7 @@ export const generateCommand = defineCommand({
         'block-type': blockTypeCommand,
         sound: soundCommand,
         music: musicCommand,
+        speech: speechCommand,
         image: imageCommand,
         character: characterCommand,
         animation: animationCommand,