@anvpx/motion-audio 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 anvpx
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/align.d.ts

@@ -0,0 +1,40 @@
+/**
+ * wav2vec2 forced align-only on KNOWN script tokens (EN, diarization OFF).
+ *
+ * TS port of the spike's `align-stage2.py` contract: the caller supplies the
+ * exact script tokens, the venv python returns per-word `[start, end]`
+ * boundaries, and this module validates them. No STT, no VAD chunking, no
+ * pyannote — unknown audio content can never invent words here because the
+ * transcript is an input, not an output. Malformed model output fails closed
+ * as `unknown`; it is never interpolated into fake timings.
+ */
+import type { Runner } from "./index.ts";
+/** Pinned align-only model (spike Stage 2 receipt). */
+export declare const ALIGN_MODEL_ID = "facebook/wav2vec2-base-960h";
+export interface Word {
+    w: string;
+    start: number;
+    end: number;
+}
+export interface AlignRequest {
+    audioPath: string;
+    /** Exact known script tokens (surface forms, in order). */
+    tokens: string[];
+    /** Explicit python binary; skips the venv probe when set. */
+    python?: string;
+}
+export type AlignResult = {
+    ok: true;
+    words: Word[];
+} | {
+    ok: false;
+    status: "missing" | "unknown";
+    hint: string;
+};
+/**
+ * Inline align driver: CTC trellis over the KNOWN token sequence only.
+ * Prints `{"words": [{"w", "start", "end"}]}`. Diarization is always OFF.
+ */
+export declare const ALIGN_PY: string;
+/** Align known tokens to audio. Fails closed on any malformed output. */
+export declare function alignWords(run: Runner, req: AlignRequest): Promise<AlignResult>;

package/dist/align.js

@@ -0,0 +1,189 @@
+import { resolveVenvPython } from "./kokoro.js";
+/** Pinned align-only model (spike Stage 2 receipt). */
+export const ALIGN_MODEL_ID = "facebook/wav2vec2-base-960h";
+/** wav2vec2-base-960h is English-only; non-ASCII narration cannot align honestly. */
+const isAsciiToken = (token) => {
+    for (let i = 0; i < token.length; i += 1) {
+        if (token.charCodeAt(i) > 127)
+            return false;
+    }
+    return true;
+};
+/**
+ * Inline align driver: CTC trellis over the KNOWN token sequence only.
+ * Prints `{"words": [{"w", "start", "end"}]}`. Diarization is always OFF.
+ */
+export const ALIGN_PY = [
+    "import json, sys",
+    "import re",
+    "import numpy as np",
+    "import soundfile as sf",
+    "import torch",
+    "from transformers import Wav2Vec2ForCTC, Wav2Vec2Processor",
+    'MODEL_ID = "facebook/wav2vec2-base-960h"',
+    "SR = 24000",
+    "FRAME_STRIDE_S = 320 / 16000",
+    "def clean_word(w):",
+    '    return re.sub(r"[^A-Z\']", "", w.upper())',
+    "def aug_tokens(token_ids, blank):",
+    "    aug = [blank]",
+    "    for t in token_ids:",
+    "        aug += [t, blank]",
+    "    return aug",
+    "def trellis_forward(log_probs, aug, blank):",
+    "    T = log_probs.shape[0]",
+    "    S = len(aug)",
+    "    NEG = -1e9",
+    "    tr = np.full((T + 1, S + 1), NEG, dtype=np.float64)",
+    "    tr[0, 0] = 0.0",
+    "    emit = log_probs[:, np.asarray(aug, dtype=np.int64)]",
+    "    for t in range(1, T + 1):",
+    "        tr[t, 0] = tr[t - 1, 0] + log_probs[t - 1, blank]",
+    "        stay = tr[t - 1, 1:] + emit[t - 1]",
+    "        chg = tr[t - 1, :-1] + emit[t - 1]",
+    "        tr[t, 1:] = np.maximum(stay, chg)",
+    "    return tr",
+    "def backtrack_word_spans(tr, log_probs, aug, blank, word_ranges):",
+    "    T = log_probs.shape[0]",
+    "    S = len(aug)",
+    "    path = [0] * T",
+    "    t, s = T, S",
+    "    while t > 0:",
+    "        if s > 0:",
+    "            emit = log_probs[t - 1, aug[s - 1]]",
+    "            if tr[t - 1, s - 1] + emit > tr[t - 1, s] + emit:",
+    "                s -= 1",
+    "        path[t - 1] = s",
+    "        t -= 1",
+    "    spans = []",
+    "    prev_end = 0",
+    "    for (a0, a1) in word_ranges:",
+    "        frames = [f for f in range(T) if path[f] > 0 and a0 <= path[f] - 1 < a1 and aug[path[f] - 1] != blank]",
+    "        if frames:",
+    "            span = (frames[0], frames[-1] + 1)",
+    "        else:",
+    "            span = (prev_end, prev_end)",
+    "        spans.append(span)",
+    "        prev_end = span[1]",
+    "    return spans",
+    "def resample16(audio24, sr):",
+    "    n_out = int(round(len(audio24) * 16000 / sr))",
+    "    return np.interp(np.linspace(0, len(audio24), n_out, endpoint=False), np.arange(len(audio24)), audio24).astype(np.float32)",
+    "audio = sys.argv[sys.argv.index('--audio')+1]",
+    "tokens = json.loads(sys.argv[sys.argv.index('--tokens')+1])",
+    "audio24, sr = sf.read(audio, dtype='float32')",
+    "if audio24.ndim > 1:",
+    "    audio24 = audio24.mean(axis=1).astype(np.float32)",
+    "audio16 = resample16(audio24, sr)",
+    "surfaces = list(tokens)",
+    "cleaned = [clean_word(w) for w in surfaces]",
+    "for surf, c in zip(surfaces, cleaned):",
+    "    if not c:",
+    "        sys.stderr.write(f'token {surf!r} has no alignable chars (clean_word empty); refusing to fake timing\\n')",
+    "        sys.exit(1)",
+    "processor = Wav2Vec2Processor.from_pretrained(MODEL_ID)",
+    "model = Wav2Vec2ForCTC.from_pretrained(MODEL_ID).eval()",
+    "with torch.no_grad():",
+    "    inputs = processor(audio16, sampling_rate=16000, return_tensors='pt', padding=True)",
+    "    logits = model(inputs.input_values).logits[0].cpu().float().numpy()",
+    "log_probs = torch.from_numpy(logits).log_softmax(dim=-1).numpy()",
+    "vocab = processor.tokenizer.get_vocab()",
+    "blank = processor.tokenizer.pad_token_id",
+    "text = '|'.join(cleaned)",
+    "token_ids = [vocab[ch] for ch in text]",
+    "aug = aug_tokens(token_ids, blank)",
+    "tr = trellis_forward(log_probs, aug, blank)",
+    "if not np.isfinite(tr[-1, -1]):",
+    "    sys.stderr.write('trellis failed: transcript incompatible with audio\\n')",
+    "    sys.exit(1)",
+    "ranges = []",
+    "pos = 1",
+    "for i, w in enumerate(cleaned):",
+    "    a0 = pos",
+    "    ranges.append((a0, a0 + 2 * len(w) - 1))",
+    "    pos += 2 * len(w)",
+    "    if i < len(cleaned) - 1:",
+    "        pos += 2",
+    "spans = backtrack_word_spans(tr, log_probs, aug, blank, ranges)",
+    "dur = len(audio24) / float(sr)",
+    "words = []",
+    "for surf, (f0, f1) in zip(surfaces, spans):",
+    "    start = round(min(max(f0 * FRAME_STRIDE_S, 0.0), dur), 3)",
+    "    end = round(min(max(f1 * FRAME_STRIDE_S, 0.0), dur), 3)",
+    "    if end < start:",
+    "        end = start",
+    "    words.append({'w': surf, 'start': start, 'end': end})",
+    "print(json.dumps({'words': words}))",
+].join("\n");
+const isWord = (value) => {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const w = value.w;
+    const start = value.start;
+    const end = value.end;
+    return (typeof w === "string" &&
+        w.length > 0 &&
+        typeof start === "number" &&
+        Number.isFinite(start) &&
+        typeof end === "number" &&
+        Number.isFinite(end) &&
+        start >= 0 &&
+        end >= start);
+};
+/** Validate aligner stdout; count must match the known tokens exactly. */
+const parseAlignPayload = (stdout, tokenCount) => {
+    let payload;
+    try {
+        payload = JSON.parse(stdout);
+    }
+    catch {
+        return { ok: false, status: "unknown", hint: "aligner gave unparsable output" };
+    }
+    if (!Array.isArray(payload.words) || !payload.words.every(isWord)) {
+        return { ok: false, status: "unknown", hint: "aligner gave malformed word boundaries" };
+    }
+    if (payload.words.length !== tokenCount) {
+        return {
+            ok: false,
+            status: "unknown",
+            hint: `aligner returned ${payload.words.length} words for ${tokenCount} tokens`,
+        };
+    }
+    return { ok: true, words: payload.words };
+};
+/** Align known tokens to audio. Fails closed on any malformed output. */
+export async function alignWords(run, req) {
+    if (req.tokens.length === 0) {
+        return { ok: false, status: "unknown", hint: "align needs at least one known token" };
+    }
+    const bad = req.tokens.find((t) => !isAsciiToken(t));
+    if (bad !== undefined) {
+        return {
+            ok: false,
+            status: "unknown",
+            hint: `EN-only wav2vec2 aligner (${ALIGN_MODEL_ID}) cannot align non-ASCII token "${bad.slice(0, 24)}"; refusing Japanese/non-English narration. Run \`mk doctor\` for the voice setup steps.`,
+        };
+    }
+    let python = req.python;
+    if (python === undefined) {
+        const probe = await resolveVenvPython(run);
+        if (!probe.ok)
+            return probe;
+        python = probe.python;
+    }
+    const res = await run(python, [
+        "-c",
+        ALIGN_PY,
+        "--audio",
+        req.audioPath,
+        "--tokens",
+        JSON.stringify(req.tokens),
+    ]);
+    if (res.code === 127) {
+        return { ok: false, status: "missing", hint: `${python} is not runnable` };
+    }
+    if (res.code !== 0) {
+        return { ok: false, status: "unknown", hint: res.stderr.slice(-500) || "align failed" };
+    }
+    return parseAlignPayload(res.stdout, req.tokens.length);
+}

package/dist/fallback.d.ts

@@ -0,0 +1,22 @@
+/**
+ * No-venv fallback: proportional split labeled `source: "authored"`.
+ *
+ * Voice is opt-in — when the venv is missing the existing render path
+ * (autoDuration) must stay untouched. This fallback NEVER claims
+ * `source: "voice"`: it distributes a known total proportionally to word
+ * counts and labels the result `authored`, so downstream consumers can tell
+ * measured voice timing apart from an estimate. Fail-closed: non-positive
+ * totals throw instead of emitting fake timings.
+ */
+import type { TimingManifest } from "@anvpx/motion-schema";
+export interface FallbackSceneInput {
+    id: string;
+    text: string;
+}
+/** Split a total into per-weight shares; the last share absorbs rounding drift. */
+export declare function splitDurations(weights: readonly number[], total: number): number[];
+/**
+ * Proportional `authored` manifest for the no-venv path. Word counts are the
+ * split weights; exact float cumulative starts (mirrors buildVoiceManifest).
+ */
+export declare function fallbackManifest(scenes: readonly FallbackSceneInput[], totalDurationS: number): TimingManifest;

package/dist/fallback.js

@@ -0,0 +1,29 @@
+const round3 = (value) => Math.round(value * 1000) / 1000;
+const wordsOf = (text) => text.split(/\s+/).filter((w) => w.length > 0).length;
+/** Split a total into per-weight shares; the last share absorbs rounding drift. */
+export function splitDurations(weights, total) {
+    if (!(total > 0) || !Number.isFinite(total)) {
+        throw new Error("fallback split needs a positive finite total");
+    }
+    const sum = weights.reduce((acc, w) => acc + w, 0);
+    if (!(sum > 0))
+        throw new Error("fallback split needs positive weights");
+    const parts = weights.map((w) => round3((w / sum) * total));
+    const drift = round3(total - parts.reduce((acc, p) => acc + p, 0));
+    parts[parts.length - 1] = round3(parts[parts.length - 1] + drift);
+    return parts;
+}
+/**
+ * Proportional `authored` manifest for the no-venv path. Word counts are the
+ * split weights; exact float cumulative starts (mirrors buildVoiceManifest).
+ */
+export function fallbackManifest(scenes, totalDurationS) {
+    const durations = splitDurations(scenes.map((s) => Math.max(wordsOf(s.text), 1)), totalDurationS);
+    let cursor = 0;
+    const rows = scenes.map((scene, index) => {
+        const row = { id: scene.id, start: cursor, duration: durations[index] };
+        cursor = row.start + row.duration;
+        return row;
+    });
+    return { source: "authored", scenes: rows };
+}

package/dist/index.d.ts

@@ -0,0 +1,42 @@
+/**
+ * @anvpx/motion-audio — voice port (opt-in).
+ *
+ * Standalone adapter driving a venv Python for Kokoro TTS plus wav2vec2
+ * align-only, consumed by build/CLI via structural {@link Runner}. Imports
+ * schema types only (constitution 2.1). Zero npm deps beyond
+ * `@anvpx/motion-schema`. No whisperx/pyannote; diarization is always OFF.
+ */
+export type CommandResult = {
+    code: number;
+    stdout: string;
+    stderr: string;
+};
+export type RunOptions = {
+    cwd?: string;
+    env?: Readonly<Record<string, string>>;
+    timeoutMs?: number;
+};
+/** Runs an external program. Never throws: missing programs yield 127. */
+export type Runner = (cmd: string, args: readonly string[], options?: RunOptions) => Promise<CommandResult>;
+/** Voice stack provenance (spike Stage 2 PASS receipts). */
+export declare const VOICE_PROVENANCE: {
+    readonly kokoro: "0.9.4";
+    readonly fasterWhisper: "1.2.1";
+    readonly alignModel: "facebook/wav2vec2-base-960h";
+    readonly alignModelRev: "22aad52d";
+    readonly diarization: "OFF";
+};
+export type { AlignRequest, AlignResult, Word } from "./align.ts";
+export { ALIGN_MODEL_ID, alignWords } from "./align.ts";
+export type { FallbackSceneInput } from "./fallback.ts";
+export { fallbackManifest, splitDurations } from "./fallback.ts";
+export type { SynthRequest, SynthResult, VenvProbe } from "./kokoro.ts";
+export { isJapaneseVoice, KOKORO_VERSION_PIN, resolveVenvPython, synthesize } from "./kokoro.ts";
+export type { MusicBedInput, MusicBedResult, ValidMusicBed } from "./music.ts";
+export { DEFAULT_MUSIC_VOLUME, MUSIC_LICENCE, validateMusicBed } from "./music.ts";
+export type { SilenceRequest, SilenceResult } from "./silence.ts";
+export { detectSilence, SILENCE_MIN_D, SILENCE_NOISE_N, wordsInSilence, } from "./silence.ts";
+export type { VoiceManifestResult, VoiceSceneInput } from "./timing.ts";
+export { buildVoiceManifest, sceneDurationFromAudio } from "./timing.ts";
+export type { Generate3dDeps, Generate3dRequest, Generate3dResult } from "./triposr.ts";
+export { generate3d, TRIPOSR_MISSING_HINT, TRIPOSR_MODEL_ID, TRIPOSR_MODEL_REV, TRIPOSR_PROVENANCE, TRIPOSR_VENDOR_REV, TRIPOSR_WEIGHT_BYTES, } from "./triposr.ts";

package/dist/index.js

@@ -0,0 +1,23 @@
+/**
+ * @anvpx/motion-audio — voice port (opt-in).
+ *
+ * Standalone adapter driving a venv Python for Kokoro TTS plus wav2vec2
+ * align-only, consumed by build/CLI via structural {@link Runner}. Imports
+ * schema types only (constitution 2.1). Zero npm deps beyond
+ * `@anvpx/motion-schema`. No whisperx/pyannote; diarization is always OFF.
+ */
+/** Voice stack provenance (spike Stage 2 PASS receipts). */
+export const VOICE_PROVENANCE = {
+    kokoro: "0.9.4",
+    fasterWhisper: "1.2.1",
+    alignModel: "facebook/wav2vec2-base-960h",
+    alignModelRev: "22aad52d",
+    diarization: "OFF",
+};
+export { ALIGN_MODEL_ID, alignWords } from "./align.js";
+export { fallbackManifest, splitDurations } from "./fallback.js";
+export { isJapaneseVoice, KOKORO_VERSION_PIN, resolveVenvPython, synthesize } from "./kokoro.js";
+export { DEFAULT_MUSIC_VOLUME, MUSIC_LICENCE, validateMusicBed } from "./music.js";
+export { detectSilence, SILENCE_MIN_D, SILENCE_NOISE_N, wordsInSilence, } from "./silence.js";
+export { buildVoiceManifest, sceneDurationFromAudio } from "./timing.js";
+export { generate3d, TRIPOSR_MISSING_HINT, TRIPOSR_MODEL_ID, TRIPOSR_MODEL_REV, TRIPOSR_PROVENANCE, TRIPOSR_VENDOR_REV, TRIPOSR_WEIGHT_BYTES, } from "./triposr.js";

package/dist/kokoro.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Kokoro TTS via the voice venv python (opt-in).
+ *
+ * Shells out with execFile semantics (no shell) through the injected
+ * {@link Runner}. Missing venv fails closed as `missing` — the caller keeps
+ * the existing render path untouched.
+ */
+import type { Runner } from "./index.ts";
+/** Pinned TTS version (spike Stage 1/2 receipt). */
+export declare const KOKORO_VERSION_PIN = "0.9.4";
+/** Venv python candidates, windows-first (mirrors `mk doctor` probes). */
+export declare const VENV_PYS: readonly [".venv-voice/Scripts/python", ".venv-voice/bin/python"];
+/** Max narration chars per synth call (bounds TTS cost/latency; fail closed above). */
+export declare const MAX_SYNTH_TEXT_CHARS = 6000;
+/** Voice ids are adapter slugs (no paths, no shell); mirrors storyboard SLUG. */
+export declare const VOICE_ID_RE: RegExp;
+/** `j*` voices select the Kokoro Japanese pipeline; they are unaligned-only. */
+export declare const isJapaneseVoice: (voice: string) => boolean;
+export type VenvProbe = {
+    ok: true;
+    python: string;
+} | {
+    ok: false;
+    status: "missing" | "unknown";
+    hint: string;
+};
+export interface SynthRequest {
+    text: string;
+    voice: string;
+    outPath: string;
+    /** Explicit python binary; skips the venv probe when set. */
+    python?: string;
+}
+export type SynthResult = {
+    ok: true;
+    outPath: string;
+    durationS: number;
+} | {
+    ok: false;
+    status: "missing" | "unknown";
+    hint: string;
+};
+/**
+ * Inline synth driver: Kokoro pipeline writes the wav, prints one JSON line.
+ * Voice prefix selects the pipeline language (`j*` voices are Japanese,
+ * matching the spike's `jf_alpha`/`jm_kumo` clips); diarization N/A (TTS).
+ */
+export declare const SYNTH_PY: string;
+/** Probe the voice venv pythons, windows-first. Never throws. */
+export declare function resolveVenvPython(run: Runner): Promise<VenvProbe>;
+/** Synthesize text with Kokoro. Fails closed when the venv is absent. */
+export declare function synthesize(run: Runner, req: SynthRequest): Promise<SynthResult>;

package/dist/kokoro.js

@@ -0,0 +1,156 @@
+/** Pinned TTS version (spike Stage 1/2 receipt). */
+export const KOKORO_VERSION_PIN = "0.9.4";
+/** Control chars (except tab/LF/CR) have no honest TTS rendering; fail closed. */
+const hasControlChars = (text) => {
+    for (let i = 0; i < text.length; i += 1) {
+        const code = text.charCodeAt(i);
+        if (code === 9 || code === 10 || code === 13)
+            continue;
+        if (code < 32 || code === 127)
+            return true;
+    }
+    return false;
+};
+/** Venv python candidates, windows-first (mirrors `mk doctor` probes). */
+export const VENV_PYS = [".venv-voice/Scripts/python", ".venv-voice/bin/python"];
+/** Max narration chars per synth call (bounds TTS cost/latency; fail closed above). */
+export const MAX_SYNTH_TEXT_CHARS = 6000;
+/** Voice ids are adapter slugs (no paths, no shell); mirrors storyboard SLUG. */
+export const VOICE_ID_RE = /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
+/** `j*` voices select the Kokoro Japanese pipeline; they are unaligned-only. */
+export const isJapaneseVoice = (voice) => voice.startsWith("j");
+/**
+ * Inline synth driver: Kokoro pipeline writes the wav, prints one JSON line.
+ * Voice prefix selects the pipeline language (`j*` voices are Japanese,
+ * matching the spike's `jf_alpha`/`jm_kumo` clips); diarization N/A (TTS).
+ */
+export const SYNTH_PY = [
+    "import json, sys",
+    "import numpy as np",
+    "import soundfile as sf",
+    "from kokoro import KPipeline",
+    "voice = sys.argv[sys.argv.index('--voice')+1]",
+    "out = sys.argv[sys.argv.index('--out')+1]",
+    "text = sys.argv[sys.argv.index('--text')+1]",
+    "pipe = KPipeline(lang_code=('j' if voice.startswith('j') else 'a'), repo_id='hexgrad/Kokoro-82M')",
+    "chunks = []",
+    "for _, _, audio in pipe(text, voice=voice): chunks.append(audio.numpy() if hasattr(audio, 'numpy') else np.asarray(audio))",
+    "wav = np.concatenate(chunks).astype(np.float32)",
+    "sf.write(out, wav, 24000)",
+    "print(json.dumps({'out': out, 'duration_s': round(float(len(wav))/24000, 3)}))",
+].join("\n");
+const isFiniteNumber = (value) => typeof value === "number" && Number.isFinite(value);
+/** Probe the voice venv pythons, windows-first. Never throws. */
+export async function resolveVenvPython(run) {
+    let sawVenv = false;
+    for (const cmd of VENV_PYS) {
+        const res = await run(cmd, ["--version"]);
+        if (res.code !== 0)
+            continue;
+        sawVenv = true;
+        if (/3\.12\.\d+/.test(`${res.stdout}${res.stderr}`)) {
+            return { ok: true, python: cmd };
+        }
+    }
+    if (sawVenv) {
+        return {
+            ok: false,
+            status: "unknown",
+            hint: "venv python is not 3.12; recreate with py -3.12 -m venv .venv-voice",
+        };
+    }
+    return {
+        ok: false,
+        status: "missing",
+        hint: "create the voice venv first: py -3.12 -m venv .venv-voice (voice phase only)",
+    };
+}
+const synthArgs = (req) => [
+    "-c",
+    SYNTH_PY,
+    "--voice",
+    req.voice,
+    "--out",
+    req.outPath,
+    "--text",
+    req.text,
+];
+/** Validate synth stdout JSON; tolerates leading stdout noise (e.g. Kokoro
+ * repo_id warning) by taking the last line that parses as the expected shape.
+ * Never invents a duration. */
+const parseSynthPayload = (stdout, expectedOut) => {
+    const lines = stdout
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0);
+    let sawMalformedJson = false;
+    for (let i = lines.length - 1; i >= 0; i -= 1) {
+        const raw = lines[i];
+        if (raw === undefined)
+            continue;
+        let payload;
+        try {
+            payload = JSON.parse(raw);
+        }
+        catch {
+            continue;
+        }
+        if (typeof payload.out !== "string" || !isFiniteNumber(payload.duration_s)) {
+            sawMalformedJson = true;
+            continue;
+        }
+        if (payload.out !== expectedOut) {
+            sawMalformedJson = true;
+            continue;
+        }
+        if (!(payload.duration_s > 0)) {
+            return { ok: false, status: "unknown", hint: "kokoro synth reported no audio" };
+        }
+        return { ok: true, outPath: payload.out, durationS: payload.duration_s };
+    }
+    if (sawMalformedJson) {
+        return { ok: false, status: "unknown", hint: "kokoro synth gave malformed JSON" };
+    }
+    return { ok: false, status: "unknown", hint: "kokoro synth gave unparsable output" };
+};
+/** Explicit binary wins; otherwise probe the voice venv (windows-first). */
+const pickPython = async (run, explicit) => {
+    if (explicit !== undefined)
+        return { python: explicit };
+    const probe = await resolveVenvPython(run);
+    return probe.ok ? { python: probe.python } : probe;
+};
+/** Synthesize text with Kokoro. Fails closed when the venv is absent. */
+export async function synthesize(run, req) {
+    if (req.text.trim().length === 0) {
+        return { ok: false, status: "unknown", hint: "refusing to synthesize empty text" };
+    }
+    if (!VOICE_ID_RE.test(req.voice)) {
+        return {
+            ok: false,
+            status: "unknown",
+            hint: `refusing voice id "${req.voice.slice(0, 32)}": must match ${VOICE_ID_RE.source}`,
+        };
+    }
+    if (req.text.length > MAX_SYNTH_TEXT_CHARS) {
+        return {
+            ok: false,
+            status: "unknown",
+            hint: `refusing to synthesize ${req.text.length} chars (cap ${MAX_SYNTH_TEXT_CHARS})`,
+        };
+    }
+    if (hasControlChars(req.text)) {
+        return { ok: false, status: "unknown", hint: "refusing text with control characters" };
+    }
+    const picked = await pickPython(run, req.python);
+    if (!("python" in picked))
+        return picked;
+    const res = await run(picked.python, synthArgs(req));
+    if (res.code === 127) {
+        return { ok: false, status: "missing", hint: `${picked.python} is not runnable` };
+    }
+    if (res.code !== 0) {
+        return { ok: false, status: "unknown", hint: res.stderr.slice(-500) || "kokoro synth failed" };
+    }
+    return parseSynthPayload(res.stdout, req.outPath);
+}

package/dist/music.d.ts

@@ -0,0 +1,34 @@
+/**
+ * User-supplied CC0 music bed (opt-in, explicit flag only).
+ *
+ * The engine never bundles copyrighted music: a bed is mixed only when the
+ * caller passes an explicit `{ wav }` bed pointing at a user CC0 file (or
+ * the repo's procedural `packages/assets/music/bed.wav`). Absent means
+ * silent/narration-only — never a synthetic fallback. Missing files fail
+ * closed via the mix layer's existence check.
+ *
+ * Guard rules live in `@anvpx/motion-schema` (`MusicBedSchema`), the single
+ * source shared with the build mix layer; this module maps schema failures
+ * to the CLI-facing hints below.
+ */
+/** Ducked bed level, re-exported from the schema single source. */
+export declare const DEFAULT_MUSIC_VOLUME: number;
+/** Only CC0 beds are supported until MK-013 (gated audio). */
+export declare const MUSIC_LICENCE = "CC0-1.0";
+export interface MusicBedInput {
+    readonly wav: string;
+    readonly volume?: number;
+}
+export interface ValidMusicBed {
+    readonly wav: string;
+    readonly volume: number;
+}
+export type MusicBedResult = {
+    ok: true;
+    bed: ValidMusicBed;
+} | {
+    ok: false;
+    hint: string;
+};
+/** Validate an explicit user bed; never invents a path or level. */
+export declare function validateMusicBed(value: unknown): MusicBedResult;

package/dist/music.js

@@ -0,0 +1,44 @@
+import { parseMusicBed as parseSchemaMusicBed, DEFAULT_MUSIC_VOLUME as SCHEMA_DEFAULT_MUSIC_VOLUME, } from "@anvpx/motion-schema";
+/**
+ * User-supplied CC0 music bed (opt-in, explicit flag only).
+ *
+ * The engine never bundles copyrighted music: a bed is mixed only when the
+ * caller passes an explicit `{ wav }` bed pointing at a user CC0 file (or
+ * the repo's procedural `packages/assets/music/bed.wav`). Absent means
+ * silent/narration-only — never a synthetic fallback. Missing files fail
+ * closed via the mix layer's existence check.
+ *
+ * Guard rules live in `@anvpx/motion-schema` (`MusicBedSchema`), the single
+ * source shared with the build mix layer; this module maps schema failures
+ * to the CLI-facing hints below.
+ */
+/** Ducked bed level, re-exported from the schema single source. */
+export const DEFAULT_MUSIC_VOLUME = SCHEMA_DEFAULT_MUSIC_VOLUME;
+/** Only CC0 beds are supported until MK-013 (gated audio). */
+export const MUSIC_LICENCE = "CC0-1.0";
+const isFiniteVolume = (value) => typeof value === "number" && Number.isFinite(value) && value > 0 && value <= 1;
+/** Validate an explicit user bed; never invents a path or level. */
+export function validateMusicBed(value) {
+    const parsed = parseSchemaMusicBed(value);
+    if (parsed.ok)
+        return { ok: true, bed: parsed.bed };
+    if (typeof value !== "object" || value === null) {
+        return { ok: false, hint: "music bed needs an explicit { wav } (user CC0 .wav)" };
+    }
+    const record = value;
+    const wav = record.wav;
+    if (typeof wav !== "string" || wav.length === 0) {
+        return { ok: false, hint: "music bed needs an explicit { wav } (user CC0 .wav)" };
+    }
+    if (!wav.endsWith(".wav") || wav.includes("..")) {
+        return {
+            ok: false,
+            hint: `refusing music bed "${wav.slice(0, 48)}": must be a local .wav without traversal`,
+        };
+    }
+    const raw = record.volume;
+    if (raw !== undefined && !isFiniteVolume(raw)) {
+        return { ok: false, hint: "music bed volume must be within (0, 1]" };
+    }
+    return { ok: false, hint: parsed.hint };
+}

package/dist/silence.d.ts

@@ -0,0 +1,31 @@
+/**
+ * ffprobe silencedetect gate over voice audio (non-speech guard).
+ *
+ * Mirrors the spike's `silence_intervals`: ffprobe takes LINEAR amplitude
+ * (not dB), so `0.003` is the Kokoro noise floor (~-50 dBFS). A word fully
+ * inside a detected silence interval is flagged — surfacing it keeps the
+ * gate honest instead of silently passing a vacuous check.
+ */
+import type { Word } from "./align.ts";
+import type { Runner } from "./index.ts";
+/** Linear amplitude threshold (NOT dB) — spike receipt. */
+export declare const SILENCE_NOISE_N = 0.003;
+/** Minimum silence duration, seconds — spike receipt. */
+export declare const SILENCE_MIN_D = 0.2;
+export interface SilenceRequest {
+    audioPath: string;
+}
+export type SilenceResult = {
+    ok: true;
+    intervals: Array<readonly [number, number]>;
+} | {
+    ok: false;
+    status: "missing" | "unknown";
+    hint: string;
+};
+/** Escape a path for the lavfi `amovie='…'` single-quoted string (no breakout). */
+export declare const escapeAmoviePath: (path: string) => string;
+/** Detect non-speech intervals. Fails closed when ffprobe is absent. */
+export declare function detectSilence(run: Runner, req: SilenceRequest): Promise<SilenceResult>;
+/** Surface words fully enclosed in a silence interval (non-speech gate), with their timing. */
+export declare function wordsInSilence(words: readonly Pick<Word, "w" | "start" | "end">[], intervals: readonly (readonly [number, number])[]): Array<Pick<Word, "w" | "start" | "end">>;

package/dist/silence.js

@@ -0,0 +1,84 @@
+/**
+ * ffprobe silencedetect gate over voice audio (non-speech guard).
+ *
+ * Mirrors the spike's `silence_intervals`: ffprobe takes LINEAR amplitude
+ * (not dB), so `0.003` is the Kokoro noise floor (~-50 dBFS). A word fully
+ * inside a detected silence interval is flagged — surfacing it keeps the
+ * gate honest instead of silently passing a vacuous check.
+ */
+/** Linear amplitude threshold (NOT dB) — spike receipt. */
+export const SILENCE_NOISE_N = 0.003;
+/** Minimum silence duration, seconds — spike receipt. */
+export const SILENCE_MIN_D = 0.2;
+const START_RE = /silence_start:\s*([\d.]+)/;
+const END_RE = /silence_end:\s*([\d.]+)/;
+/** Fold one parsed line; returns a hint when the line is incoherent. */
+const foldLine = (line, starts, intervals) => {
+    const s = START_RE.exec(line);
+    if (s) {
+        starts.push(Number(s[1]));
+        return undefined;
+    }
+    const e = END_RE.exec(line);
+    if (e !== null && starts.length > 0) {
+        const s0 = starts.pop();
+        const s1 = Number(e[1]);
+        if (!(s1 > s0))
+            return "silencedetect gave inverted interval";
+        intervals.push([s0, s1]);
+    }
+    return undefined;
+};
+/** Parse silencedetect stderr; unterminated starts fail closed (no vacuous pass). */
+const parseSilenceStderr = (stderr) => {
+    const intervals = [];
+    const starts = [];
+    for (const line of stderr.split("\n")) {
+        const hint = foldLine(line, starts, intervals);
+        if (hint !== undefined)
+            return { ok: false, status: "unknown", hint };
+    }
+    if (starts.length > 0) {
+        return { ok: false, status: "unknown", hint: "silencedetect left an interval unterminated" };
+    }
+    return { ok: true, intervals };
+};
+/** Escape a path for the lavfi `amovie='…'` single-quoted string (no breakout). */
+export const escapeAmoviePath = (path) => path.replace(/\\/g, "\\\\").replace(/'/g, "\\'").replace(/:/g, "\\:").replace(/,/g, "\\,");
+/** Detect non-speech intervals. Fails closed when ffprobe is absent. */
+export async function detectSilence(run, req) {
+    const filter = `amovie='${escapeAmoviePath(req.audioPath)}',silencedetect=n=${SILENCE_NOISE_N}:d=${SILENCE_MIN_D}`;
+    const res = await run("ffprobe", [
+        "-hide_banner",
+        "-v",
+        "info",
+        "-f",
+        "lavfi",
+        "-i",
+        filter,
+        "-show_entries",
+        "frame=pkt_pts_time",
+        "-of",
+        "csv",
+    ]);
+    if (res.code === 127) {
+        return { ok: false, status: "missing", hint: "install ffmpeg >= 6 and put ffprobe on PATH" };
+    }
+    if (res.code !== 0) {
+        return { ok: false, status: "unknown", hint: res.stderr.slice(-500) || "silencedetect failed" };
+    }
+    return parseSilenceStderr(res.stderr);
+}
+/** Surface words fully enclosed in a silence interval (non-speech gate), with their timing. */
+export function wordsInSilence(words, intervals) {
+    const bad = [];
+    for (const w of words) {
+        for (const [s0, s1] of intervals) {
+            if (w.start >= s0 && w.end <= s1) {
+                bad.push(w);
+                break;
+            }
+        }
+    }
+    return bad;
+}

package/dist/timing.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Voice TimingManifest builder: measured audio durations override autoDuration.
+ *
+ * Each row's duration is the MEASURED wav length for that scene — never
+ * inferred from word spans, so gaps and pauses cannot shrink a scene.
+ * Starts are exact float cumulative sums (no rounding): the schema's strict
+ * `start < prev.start + prev.duration` comparison false-positives on rounded
+ * starts (spike NOTE 2026-10-29). The manifest validates against
+ * `TimingManifestSchema` before it is returned.
+ */
+import { type TimingManifest } from "@anvpx/motion-schema";
+export interface VoiceSceneInput {
+    id: string;
+    /** Measured wav duration for the scene, seconds. Must be positive. */
+    durationS: number;
+}
+export type VoiceManifestResult = {
+    ok: true;
+    manifest: TimingManifest;
+} | {
+    ok: false;
+    problems: string[];
+};
+/** Voice timing for one scene is its measured audio length. */
+export declare const sceneDurationFromAudio: (audioDurationS: number) => number;
+/** Build a `source: "voice"` manifest from measured scene durations. */
+export declare function buildVoiceManifest(rows: readonly VoiceSceneInput[]): VoiceManifestResult;

package/dist/timing.js

@@ -0,0 +1,43 @@
+/**
+ * Voice TimingManifest builder: measured audio durations override autoDuration.
+ *
+ * Each row's duration is the MEASURED wav length for that scene — never
+ * inferred from word spans, so gaps and pauses cannot shrink a scene.
+ * Starts are exact float cumulative sums (no rounding): the schema's strict
+ * `start < prev.start + prev.duration` comparison false-positives on rounded
+ * starts (spike NOTE 2026-10-29). The manifest validates against
+ * `TimingManifestSchema` before it is returned.
+ */
+import { TimingManifestSchema } from "@anvpx/motion-schema";
+/** Voice timing for one scene is its measured audio length. */
+export const sceneDurationFromAudio = (audioDurationS) => audioDurationS;
+/** Build a `source: "voice"` manifest from measured scene durations. */
+export function buildVoiceManifest(rows) {
+    const problems = [];
+    const seen = new Set();
+    rows.forEach((row) => {
+        if (seen.has(row.id))
+            problems.push(`duplicate scene id "${row.id}"`);
+        seen.add(row.id);
+        if (!(row.durationS > 0) || !Number.isFinite(row.durationS)) {
+            problems.push(`scene "${row.id}": duration must be a positive finite number`);
+        }
+    });
+    if (problems.length > 0)
+        return { ok: false, problems };
+    // Exact float cumulative starts — never rounded (see module doc).
+    let cursor = 0;
+    const scenes = rows.map((row) => {
+        const scene = { id: row.id, start: cursor, duration: row.durationS };
+        cursor = scene.start + scene.duration;
+        return scene;
+    });
+    const parsed = TimingManifestSchema.safeParse({ source: "voice", scenes });
+    if (!parsed.success) {
+        return {
+            ok: false,
+            problems: parsed.error.issues.map((issue) => `${issue.path.join("/")}: ${issue.message}`),
+        };
+    }
+    return { ok: true, manifest: parsed.data };
+}

package/dist/triposr.d.ts

@@ -0,0 +1,59 @@
+import type { Runner } from "./index.ts";
+/** Local GLB validator (byte-correct port of cli validateGlb; no cross-layer import). */
+export declare const validateGlbBytes: (bytes: Uint8Array) => {
+    ok: true;
+    bytes: number;
+} | {
+    ok: false;
+    message: string;
+};
+/** Pinned model id (spike `run_spike.py` + REPORT). */
+export declare const TRIPOSR_MODEL_ID = "stabilityai/TripoSR";
+/** Pinned weights snapshot (REPORT: HF cache snapshot hash). */
+export declare const TRIPOSR_MODEL_REV = "5b521936b01fbe1890f6f9baed0254ab6351c04a";
+/** Pinned TripoSR source revision vendored for the spike. */
+export declare const TRIPOSR_VENDOR_REV = "107cefdc244c39106fa830359024f6a2f1c78871";
+/** Weights size on disk: 1,677,247,729 bytes (~1.68GB, one-time fetch). */
+export declare const TRIPOSR_WEIGHT_BYTES = 1677247729;
+/** Model + weights provenance (spike REPORT receipts). */
+export declare const TRIPOSR_PROVENANCE: {
+    readonly model: "stabilityai/TripoSR";
+    readonly revision: "5b521936b01fbe1890f6f9baed0254ab6351c04a";
+    readonly vendorRev: "107cefdc244c39106fa830359024f6a2f1c78871";
+    readonly weightBytes: 1677247729;
+    readonly weightNote: "one-time ~1.68GB fetch, cached offline after first fetch";
+    readonly license: "MIT";
+    readonly device: "cpu";
+    readonly resolution: 256;
+};
+/** Doctor-style hint: audio owns no doctor, so the hint carries the setup. */
+export declare const TRIPOSR_MISSING_HINT = "triposr opt-in unavailable: install triposr in the voice venv (.venv-voice) and fetch weights stabilityai/TripoSR@5b52193 (~1.68GB one-time, cached offline after first fetch)";
+export interface Generate3dRequest {
+    image: string;
+    outGlb: string;
+    /** Explicit python binary; skips the venv probe when set. */
+    python?: string;
+    /** Marching-cubes resolution (spike: 256). */
+    resolution?: number;
+}
+export type Generate3dResult = {
+    ok: true;
+    outGlb: string;
+    glbBytes: number;
+} | {
+    ok: false;
+    status: "missing" | "unknown";
+    hint: string;
+};
+export interface Generate3dDeps {
+    /** Overrideable file reader (tests inject fakes; default reads disk bytes). */
+    readFile?: (path: string) => Promise<Uint8Array>;
+}
+/**
+ * Inline TripoSR driver: rembg + TSR inference + mesh extract + GLB export,
+ * then a byte-level GLB check via local `validateGlbBytes`. Prints one JSON line:
+ * `{"out": ..., "glb_bytes": ...}`.
+ */
+export declare const TRIPOSR_PY: string;
+/** Image -> GLB via the venv python. Fails closed when opt-in deps are absent. */
+export declare function generate3d(run: Runner, req: Generate3dRequest, deps?: Generate3dDeps): Promise<Generate3dResult>;

package/dist/triposr.js

@@ -0,0 +1,241 @@
+/**
+ * Opt-in TripoSR image-to-3D adapter (no repo GLB changes here).
+ *
+ * Shells out with execFile semantics (no shell) through the injected
+ * {@link Runner}, reusing the voice venv probe from `kokoro.ts`. Missing
+ * venv or missing TripoSR weights fail closed as `missing` with a
+ * doctor-style hint — the caller keeps the existing path untouched and no
+ * fake GLB is ever produced. The fetch is pinned to `TRIPOSR_MODEL_REV` and
+ * the downloaded checkpoint is verified pre-inference (byte size always,
+ * sha256 when `TRIPOSR_WEIGHT_SHA256` is set); a mismatch fails closed as
+ * `unknown`. Output bytes are validated with the local
+ * `validateGlbBytes` port (magic `glTF`, version 2, declared length matches).
+ */
+import { readFile as fsReadFile } from "node:fs/promises";
+import { resolveVenvPython } from "./kokoro.js";
+/** Local GLB validator (byte-correct port of cli validateGlb; no cross-layer import). */
+export const validateGlbBytes = (bytes) => {
+    if (bytes.length < 12 ||
+        bytes[0] !== 0x67 ||
+        bytes[1] !== 0x6c ||
+        bytes[2] !== 0x54 ||
+        bytes[3] !== 0x46) {
+        return { ok: false, message: "not a GLB model (missing glTF magic)" };
+    }
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    const version = view.getUint32(4, true);
+    if (version !== 2)
+        return { ok: false, message: `unsupported glTF version ${version}; need 2` };
+    const total = view.getUint32(8, true);
+    if (total !== bytes.length) {
+        return {
+            ok: false,
+            message: `GLB length mismatch: header says ${total} bytes, file has ${bytes.length}`,
+        };
+    }
+    return { ok: true, bytes: bytes.length };
+};
+/** Pinned model id (spike `run_spike.py` + REPORT). */
+export const TRIPOSR_MODEL_ID = "stabilityai/TripoSR";
+/** Pinned weights snapshot (REPORT: HF cache snapshot hash). */
+export const TRIPOSR_MODEL_REV = "5b521936b01fbe1890f6f9baed0254ab6351c04a";
+/** Pinned TripoSR source revision vendored for the spike. */
+export const TRIPOSR_VENDOR_REV = "107cefdc244c39106fa830359024f6a2f1c78871";
+/** Weights size on disk: 1,677,247,729 bytes (~1.68GB, one-time fetch). */
+export const TRIPOSR_WEIGHT_BYTES = 1677247729;
+/** Model + weights provenance (spike REPORT receipts). */
+export const TRIPOSR_PROVENANCE = {
+    model: TRIPOSR_MODEL_ID,
+    revision: TRIPOSR_MODEL_REV,
+    vendorRev: TRIPOSR_VENDOR_REV,
+    weightBytes: TRIPOSR_WEIGHT_BYTES,
+    weightNote: "one-time ~1.68GB fetch, cached offline after first fetch",
+    license: "MIT",
+    device: "cpu",
+    resolution: 256,
+};
+/** Doctor-style hint: audio owns no doctor, so the hint carries the setup. */
+export const TRIPOSR_MISSING_HINT = "triposr opt-in unavailable: install triposr in the voice venv (.venv-voice) and fetch weights stabilityai/TripoSR@5b52193 (~1.68GB one-time, cached offline after first fetch)";
+/**
+ * Inline TripoSR driver: rembg + TSR inference + mesh extract + GLB export,
+ * then a byte-level GLB check via local `validateGlbBytes`. Prints one JSON line:
+ * `{"out": ..., "glb_bytes": ...}`.
+ */
+export const TRIPOSR_PY = [
+    "import json, os, struct, sys",
+    "image_path = sys.argv[sys.argv.index('--image')+1]",
+    "out_path = sys.argv[sys.argv.index('--out')+1]",
+    "resolution = int(sys.argv[sys.argv.index('--resolution')+1]) if '--resolution' in sys.argv else 256",
+    "import numpy as np",
+    "import rembg",
+    "import torch",
+    "from PIL import Image",
+    "from tsr.system import TSR",
+    "from tsr.utils import remove_background, resize_foreground",
+    "from huggingface_hub import hf_hub_download",
+    `ckpt_path = hf_hub_download(repo_id="${TRIPOSR_MODEL_ID}", filename="model.ckpt", revision="${TRIPOSR_MODEL_REV}")`,
+    "actual_bytes = os.path.getsize(ckpt_path)",
+    `if actual_bytes != ${TRIPOSR_WEIGHT_BYTES}:`,
+    `    sys.stderr.write(f"weight verification failed: model.ckpt expected ${TRIPOSR_WEIGHT_BYTES} bytes, got {actual_bytes}\\n"); sys.exit(3)`,
+    `expected_sha256 = os.environ.get("TRIPOSR_WEIGHT_SHA256", "")`,
+    "if expected_sha256:",
+    "    import hashlib",
+    "    digest = hashlib.sha256()",
+    "    with open(ckpt_path, 'rb') as weights_file:",
+    "        for chunk in iter(lambda: weights_file.read(8388608), b''):",
+    "            digest.update(chunk)",
+    "    if digest.hexdigest() != expected_sha256:",
+    "        sys.stderr.write('weight verification failed: sha256 mismatch\\n'); sys.exit(3)",
+    `model = TSR.from_pretrained("${TRIPOSR_MODEL_ID}", revision="${TRIPOSR_MODEL_REV}", config_name="config.yaml", weight_name="model.ckpt")`,
+    "model.renderer.set_chunk_size(8192)",
+    "model.to('cpu')",
+    "session = rembg.new_session()",
+    "image = remove_background(Image.open(image_path), session)",
+    "image = resize_foreground(image, 0.85)",
+    "arr = np.array(image).astype(np.float32) / 255.0",
+    "arr = arr[:, :, :3] * arr[:, :, 3:4] + (1 - arr[:, :, 3:4]) * 0.5",
+    "image = Image.fromarray((arr * 255.0).astype(np.uint8))",
+    "with torch.no_grad():",
+    "    scene_codes = model([image], device='cpu')",
+    "meshes = model.extract_mesh(scene_codes, True, resolution=resolution)",
+    "meshes[0].export(out_path)",
+    "with open(out_path, 'rb') as f:",
+    "    data = f.read()",
+    "if len(data) < 12 or data[0:4] != b'glTF':",
+    "    sys.stderr.write('not a GLB model (missing glTF magic)\\n'); sys.exit(2)",
+    "(version, total) = struct.unpack('<II', data[4:12])",
+    "if version != 2:",
+    "    sys.stderr.write(f'unsupported glTF version {version}; need 2\\n'); sys.exit(2)",
+    "if total != len(data):",
+    "    sys.stderr.write(f'GLB length mismatch: header says {total} bytes, file has {len(data)}\\n'); sys.exit(2)",
+    "print(json.dumps({'out': out_path, 'glb_bytes': len(data)}))",
+].join("\n");
+const isFiniteNumber = (value) => typeof value === "number" && Number.isFinite(value);
+const parseModelPayload = (stdout) => {
+    let payload;
+    try {
+        payload = JSON.parse(stdout);
+    }
+    catch {
+        return { ok: false, status: "unknown", hint: "triposr gave unparsable output" };
+    }
+    if (typeof payload.out !== "string" || !isFiniteNumber(payload.glb_bytes)) {
+        return { ok: false, status: "unknown", hint: "triposr gave malformed JSON" };
+    }
+    if (!(payload.glb_bytes > 0)) {
+        return { ok: false, status: "unknown", hint: "triposr reported no GLB bytes" };
+    }
+    return { ok: true, outGlb: payload.out, glbBytes: payload.glb_bytes };
+};
+const MODEL_MISSING_RE = /tsr|triposr|model\.ckpt|from_pretrained|huggingface|no module named/i;
+/** Weight tampering/drift marker from the driver — a trust failure, never "missing deps". */
+const WEIGHT_MISMATCH_RE = /weight verification failed/i;
+const defaultReadFile = async (path) => {
+    const buf = await fsReadFile(path);
+    return new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
+};
+const validateRequest = (req) => {
+    if (req.image.trim().length === 0 || req.outGlb.trim().length === 0) {
+        return { ok: false, status: "unknown", hint: "refusing empty image/outGlb path" };
+    }
+    const resolution = req.resolution ?? TRIPOSR_PROVENANCE.resolution;
+    if (!Number.isInteger(resolution) || resolution < 64 || resolution > 1024) {
+        return {
+            ok: false,
+            status: "unknown",
+            hint: `refusing resolution ${String(req.resolution)} (want integer 64..1024)`,
+        };
+    }
+    return { resolution };
+};
+const pickPython = async (run, explicit) => {
+    if (explicit !== undefined)
+        return { python: explicit };
+    const probe = await resolveVenvPython(run);
+    if (!probe.ok) {
+        return {
+            ok: false,
+            status: probe.status,
+            hint: `${probe.hint}; ${TRIPOSR_MISSING_HINT}`,
+        };
+    }
+    return { python: probe.python };
+};
+const runModel = async (run, python, req, resolution) => {
+    const res = await run(python, [
+        "-c",
+        TRIPOSR_PY,
+        "--image",
+        req.image,
+        "--out",
+        req.outGlb,
+        "--resolution",
+        String(resolution),
+    ]);
+    if (res.code === 127) {
+        return {
+            ok: false,
+            status: "missing",
+            hint: `${python} is not runnable; ${TRIPOSR_MISSING_HINT}`,
+        };
+    }
+    if (res.code !== 0) {
+        const tail = res.stderr.slice(-500) || "triposr failed";
+        // Weight mismatch mentions model.ckpt but means corruption/drift, not absent deps.
+        if (WEIGHT_MISMATCH_RE.test(tail)) {
+            return { ok: false, status: "unknown", hint: tail };
+        }
+        if (MODEL_MISSING_RE.test(tail)) {
+            return { ok: false, status: "missing", hint: `${tail}; ${TRIPOSR_MISSING_HINT}` };
+        }
+        return { ok: false, status: "unknown", hint: tail };
+    }
+    return { stdout: res.stdout };
+};
+const verifyOutput = async (readFile, outGlb, claimedBytes) => {
+    let bytes;
+    try {
+        bytes = await readFile(outGlb);
+    }
+    catch {
+        return { ok: false, status: "unknown", hint: `cannot read generated GLB "${outGlb}"` };
+    }
+    // Never trust the subprocess byte count: the file on disk is the truth.
+    if (claimedBytes !== bytes.length) {
+        return {
+            ok: false,
+            status: "unknown",
+            hint: `GLB byte-count mismatch: model said ${claimedBytes} bytes, file has ${bytes.length}`,
+        };
+    }
+    const checked = validateGlbBytes(bytes);
+    if (!checked.ok)
+        return { ok: false, status: "unknown", hint: checked.message };
+    return { glbBytes: checked.bytes };
+};
+/** Image -> GLB via the venv python. Fails closed when opt-in deps are absent. */
+export async function generate3d(run, req, deps) {
+    const valid = validateRequest(req);
+    if (!("resolution" in valid))
+        return valid;
+    const picked = await pickPython(run, req.python);
+    if (!("python" in picked))
+        return picked;
+    const ran = await runModel(run, picked.python, req, valid.resolution);
+    if (!("stdout" in ran))
+        return ran;
+    const parsed = parseModelPayload(ran.stdout);
+    if (!parsed.ok)
+        return parsed;
+    if (parsed.outGlb !== req.outGlb) {
+        return {
+            ok: false,
+            status: "unknown",
+            hint: `triposr reported unexpected out path "${parsed.outGlb.slice(0, 64)}"`,
+        };
+    }
+    const verified = await verifyOutput(deps?.readFile ?? defaultReadFile, req.outGlb, parsed.glbBytes);
+    if (!("glbBytes" in verified))
+        return verified;
+    return { ok: true, outGlb: req.outGlb, glbBytes: verified.glbBytes };
+}

package/package.json

@@ -1,6 +1,33 @@
 {
   "name": "@anvpx/motion-audio",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Audio helpers for @anvpx/motion: voice, alignment, mixing and TripoSR pins.",
+  "license": "MIT",
+  "author": "anvpx",
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "keywords": [
+    "motion-kit",
+    "audio",
+    "voice",
+    "tts",
+    "mixing"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": "./dist/index.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts"
+  ],
+  "dependencies": {
+    "@anvpx/motion-schema": "0.1.0"
+  },
+  "scripts": {}
 }

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.