@aicopycoders/exodus 2026.9.1700-beta.1 → 2026.9.1800-beta.0

package/assets/skills/exodus-video/SKILL.md

@@ -89,6 +89,8 @@ exodus video start --show <id> --script script.txt --wait  start, wait for the s
 
 ```operator-guide
 exodus video storyboard <runId>                           read the scene cards
+exodus video voices <runId>                               who speaks and with whose voice
+exodus video voices <runId> --set <character>=<voiceId>   give a character a voice
 exodus video approve <runId>                              keep going
 exodus video flag <runId> --note "what's wrong"           send it back — SHOW RUNS ONLY
 exodus video retry-frame <runId> --node <nodeId> --scene <n>  redo one still at the pixel gate
@@ -162,6 +164,8 @@ Verified against the routes, not assumed. Everything here is admin-gated on top.
 | `workflow run` | starts the run | not the entry point |
 | `video status` | works | works |
 | `video storyboard` | works | works |
+| `video voices` (read) | works | works |
+| `video voices --set` | works | **refused** — the Show owns its voices |
 | `video approve` | works, both gates | works, both gates |
 | `video flag --note` | **refused** | works |
 | script-turn edits at the gate | **refused** | dashboard only |
@@ -196,13 +200,16 @@ Five consequences worth knowing before you promise a user anything:
 
 - **`flag` is Show-only and fails loudly.** `exodus video flag` on a workflow run
   answers "Flag-with-note is only available on Video-module ads."
-  (`convex/videoModule.ts:2208`, guarded on `!run.showId`). Script-turn edits
-  refuse the same way (`:2334`). There is **no** CLI path that sends a workflow
-  run's storyboard back with a note — the direct-edit mutation exists but is
-  wired only to the dashboard's gate screen, not to any API route. From the
-  terminal the storyboard is approve-or-cancel: `exodus workflow cancel <runId>`
-  and run again with a better script, or edit the workflow. Do not offer `flag`
-  to a user on the workflow route.
+  (`convex/videoModule.ts`, guarded on `!run.showId`). Script-turn edits refuse
+  the same way. There is **no** CLI path that sends a workflow run's storyboard
+  back with a note, and none that rewrites its scenes, script or prompts — the
+  whole-envelope edit mutation is wired only to the dashboard's gate screen, not
+  to any API route. The one exception is voices: `exodus video voices --set`
+  writes the cast's voice choices in place and nothing else (see "Giving the
+  characters voices"). For everything else the storyboard is approve-or-cancel
+  from the terminal: `exodus workflow cancel <runId>` and run again with a better
+  script, or edit the workflow. Do not offer `flag` to a user on the workflow
+  route.
 - **`--wait` lands on both video parks, but only those.** Since #1818 every
   `--wait` caller — `workflow run`, `triggers fire`, `checkpoint approve|retry`,
   `repair retry|skip` — ends at a storyboard gate or a final watch, exits 0, and
@@ -257,6 +264,94 @@ The note is read by the model that rewrites the storyboard, so make it concrete
 Either way, do not approve on the user's behalf unless they told you to run the
 whole loop unattended.
 
+## Giving the characters voices
+
+By default a workflow run's characters have no voice chosen, so every clip keeps
+the voice the video model invents. `exodus video voices` is where that gets
+fixed, and it only works **before** the storyboard is approved — once clips start
+it refuses.
+
+```
+exodus video voices <runId>
+exodus video voices <runId> --json
+exodus video voices <runId> --set C1=abc123voiceid --set "HOST 2=def456voiceid"
+exodus video voices <runId> --from voices.json
+exodus video voices <runId> --clear C2
+```
+
+Read it first. With no flags it prints one line per character: the character's
+ID, the name the script uses, the voice chosen, whether ElevenLabs actually has
+that voice on the user's account, and how many scenes that character speaks in.
+Under it: how the voices get applied, who pays, and anything worth knowing before
+approving.
+
+Name a character either way. `C1` is the ID the planner handed out; `HOST 1` is
+the name the script uses. Both work, and the name is the portable one — the same
+voices file works on every run of that brand because the planner may hand out the
+IDs differently each time.
+
+**What `--set` changes.** The voice choices, and nothing else. The script, the
+scene pictures and the run itself are left exactly as they were — no re-boarding,
+no picture is redrawn, nothing is charged. A character whose voice was already
+what you asked for reports "Nothing changed".
+
+**What it refuses, and why nothing is written when it does.** A character name
+nobody in the cast answers to, a voice ID with a space in it (people paste the
+voice's *name* by mistake), and a voice ID ElevenLabs is certain it does not have
+on that account. Each refusal says the plain reason and saves nothing. If
+ElevenLabs simply cannot be reached, the choice IS saved and the output says the
+check could not be made — a provider outage never blocks the run.
+
+**The voices file.** A plain JSON object, keyed by the names the script uses:
+
+```json
+{
+  "HOST 1": { "voiceId": "abc123voiceid", "label": "First host" },
+  "HOST 2": { "voiceId": "def456voiceid", "label": "Second host" }
+}
+```
+
+A bare string works instead of the object when you do not care about the label
+(`"HOST 1": "abc123voiceid"`), and `null` clears that character's voice. `--set`
+and `--clear` win over the same name in the file, so one entry can be overridden
+without editing it. Use the name the file uses: if the file says `HOST 2` and the
+flag says `C2`, that is one character named two ways, and the whole request is
+refused with a sentence saying so. Voice IDs belong to the user's own ElevenLabs account and to that brand's
+folder — never put a brand's voice IDs in a shared workflow or template.
+
+**The JSON receipt** (`--json`), the same shape for reading and for setting:
+
+```
+ok                    true
+runId
+changed[]             the characters whose voice actually moved (set only)
+canChange             false once the run has left the storyboard review
+whyNot                why, in one sentence, when canChange is false
+cast[]                one per character
+  characterId, name
+  voice               { voiceId, label } or null
+  availability        { state: "available" | "missing" | "not-checked", … }
+  spokenScenes        how many scenes this character speaks in
+  spokenSeconds       those scenes' planned seconds — what ElevenLabs bills on
+narrator              the one fallback voice, set on the workflow, not here
+treatment             how the voices reach the clips: summary, provider, model,
+                      speedChange, billedTo, estimatedCostUsd, costNote,
+                      usage { clips, seconds }, keyOnRun
+notices[]             plain sentences worth reading before approving
+```
+
+A failure is the same shape every `video` verb uses:
+`{ "ok": false, "status": 400, "error": "<one plain sentence>" }`, exit 1.
+
+**Before you approve, read `notices`.** The ones that cost the user something:
+a character who speaks but has no voice (those clips keep their generated
+voice), no ElevenLabs key saved on the run (no voice can be applied at all), and
+a voice ElevenLabs no longer has.
+
+`estimatedCostUsd` is always null. Exodus cannot price a voice conversion yet;
+ElevenLabs bills the user's own account by audio length, and `usage` gives the
+length. Do not invent a number.
+
 ## The handover: what `pull` gives you
 
 `pull` writes a flat folder and a `manifest.json` that indexes it. The manifest

package/dist/commands/video.d.ts

@@ -1,5 +1,6 @@
 import { type ApiResponse } from "../lib/client.js";
 export declare const helpText: string;
+export declare const VOICES_PATH = "/api/v2/video/voices";
 export interface ClipWord {
     w: string;
     s: number;
@@ -264,6 +265,55 @@ export declare function storyboardFlow(runId: string, json: boolean, deps: Video
 export declare function approveFlow(runId: string, json: boolean, deps: VideoDeps): Promise<FlowResult>;
 export declare function flagFlow(runId: string, note: string, json: boolean, deps: VideoDeps): Promise<FlowResult>;
 export declare function retryFrameFlow(runId: string, nodeId: string, sceneIndex: number, note: string | undefined, json: boolean, deps: VideoDeps): Promise<FlowResult>;
+export interface CastVoiceRow {
+    characterId: string;
+    name: string;
+    voice: {
+        voiceId: string;
+        label?: string;
+    } | null;
+    availability?: {
+        state: "available";
+        providerName: string;
+    } | {
+        state: "missing";
+    } | {
+        state: "not-checked";
+        why: string;
+    };
+    spokenScenes: number;
+    spokenSeconds: number;
+}
+export interface CastVoiceSheet {
+    runId: string;
+    canChange: boolean;
+    whyNot?: string;
+    cast: CastVoiceRow[];
+    narrator: {
+        voiceId: string;
+        label?: string;
+    } | null;
+    treatment: {
+        summary: string;
+        provider: string;
+        model: string;
+        speedChange: boolean;
+        costNote: string;
+        usage: {
+            clips: number;
+            seconds: number;
+        };
+    };
+    notices: string[];
+    changed?: string[];
+}
+export type VoiceMap = Record<string, string | {
+    voiceId: string;
+    label?: string;
+} | null>;
+export declare function parseVoiceFlags(argv: readonly string[], readFile: (path: string) => string): VoiceMap | null;
+export declare function voicesFlow(runId: string, voices: VoiceMap | null, json: boolean, deps: VideoDeps): Promise<FlowResult>;
+export declare function voiceSheetLines(sheet: CastVoiceSheet): string[];
 export declare function pullFlow(runId: string, dir: string, json: boolean, deps: VideoDeps): Promise<FlowResult>;
 export declare function parseMvhdDurationSec(bytes: Uint8Array): number | null;
 export declare const NO_DURATION_MESSAGE: string;

package/dist/commands/video.js

@@ -25,24 +25,28 @@ The whole loop, in order:
   3. exodus video storyboard <runId>
      The scene cards: what each scene says and the picture it will look like.
 
-  4. exodus video approve <runId>          (looks right — keep going)
+  4. exodus video voices <runId>
+     Who is in the ad, which voice each one has, how the voices get applied
+     and who pays. Add --set to give someone a voice, before any clip is made.
+
+  5. exodus video approve <runId>          (looks right — keep going)
      exodus video flag <runId> --note "…"  (something is wrong — send it back)
      exodus video retry-frame <runId> --node <nodeId> --scene <n>
        Redo ONE still at the pixel gate. Neighbours stay. The gate holds.
 
-  5. exodus video status <runId>
+  6. exodus video status <runId>
      Where the run is and how each scene's clip turned out.
 
-  6. exodus video pull <runId> --out ./ad
+  7. exodus video pull <runId> --out ./ad
      Writes every piece to that folder plus a manifest.json index.
 
-  7. Make your cut from those files.
+  8. Make your cut from those files.
 
-  8. exodus video upload <runId> --file cut.mp4
+  9. exodus video upload <runId> --file cut.mp4
      Attaches your cut to the run and prints the page to approve it on.
 
-  9. exodus video approve <runId>
-     Or click Approve on the page from step 8.
+  10. exodus video approve <runId>
+      Or click Approve on the page from step 9.
 
 Usage:
   exodus video shows [--json]
@@ -52,6 +56,7 @@ Usage:
   exodus video approve <runId> [--json]
   exodus video flag <runId> --note "<what is wrong>" [--json]
   exodus video retry-frame <runId> --node <nodeId> --scene <n> [--note "..."] [--json]
+  exodus video voices <runId> [--set <character>=<voiceId>] [--clear <character>] [--from <file.json>] [--json]
   exodus video pull <runId> --out <dir> [--json]
   exodus video upload <runId> --file <cut.mp4> [--duration <sec>] [--json]
 
@@ -70,6 +75,12 @@ Options:
                        steer one frame redo (retry-frame)
   --node <nodeId>      Which scene-frames node holds the still (retry-frame)
   --scene <n>          Which scene's frame to redo. One scene only (retry-frame)
+  --set <who>=<id>     Give a character an ElevenLabs voice (voices). Name the
+                       character by its ID or by the name your script uses.
+                       Repeat it once per character
+  --clear <who>        Take a character's voice off again (voices). Repeatable
+  --from <file.json>   A file of characters and voice IDs (voices). --set and
+                       --clear win over the same name in the file
   --json               Machine-readable output
   --help, -h           Show this help
 
@@ -82,6 +93,9 @@ Examples:
   exodus video storyboard run_123
   exodus video approve run_123
   exodus video retry-frame run_123 --node frames-1 --scene 2
+  exodus video voices run_123
+  exodus video voices run_123 --set C1=abc123voiceid --set "HOST 2=def456voiceid"
+  exodus video voices run_123 --from voices.json
   exodus video pull run_123 --out ./ad-run_123
   exodus video upload run_123 --file ./cut.mp4
 `.trim();
@@ -94,6 +108,7 @@ const FLAG_PATH = "/api/v2/video/storyboard/flag";
 const APPROVE_PATH = "/api/v2/workflow/approve";
 const SCENE_RETRY_PATH = "/api/v2/workflow/scene/retry";
 const FINAL_PATH = "/api/v2/video/final";
+export const VOICES_PATH = "/api/v2/video/voices";
 const ASSET_UPLOAD_URL_PATH = "/api/v2/workflows/asset-upload-url";
 const ASSETS_PATH = "/api/v2/workflows/assets";
 function withoutJudgeFields({ judgeDetail: _d, judgeSeverity: _s, ...rest }) {
@@ -1037,6 +1052,123 @@ export async function retryFrameFlow(runId, nodeId, sceneIndex, note, json, deps
         ],
     };
 }
+export function parseVoiceFlags(argv, readFile) {
+    const fromFile = {};
+    const typed = {};
+    let asked = false;
+    const valueFor = (i, flag) => {
+        const arg = argv[i];
+        if (arg.startsWith(`${flag}=`))
+            return [arg.slice(flag.length + 1), i];
+        const next = argv[i + 1];
+        if (next === undefined)
+            throw new Error(`${flag} needs a value.`);
+        return [next, i + 1];
+    };
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === "--set" || arg.startsWith("--set=")) {
+            const [raw, next] = valueFor(i, "--set");
+            i = next;
+            const eq = raw.lastIndexOf("=");
+            if (eq <= 0 || eq === raw.length - 1) {
+                throw new Error("--set must look like <character>=<voice id>, for example " +
+                    `--set C1=abc123voiceid (got "${raw}").`);
+            }
+            typed[raw.slice(0, eq).trim()] = raw.slice(eq + 1).trim();
+            asked = true;
+        }
+        else if (arg === "--clear" || arg.startsWith("--clear=")) {
+            const [raw, next] = valueFor(i, "--clear");
+            i = next;
+            if (!raw.trim())
+                throw new Error("--clear needs a character, for example --clear C1.");
+            typed[raw.trim()] = null;
+            asked = true;
+        }
+        else if (arg === "--from" || arg.startsWith("--from=")) {
+            const [file, next] = valueFor(i, "--from");
+            i = next;
+            let parsed;
+            try {
+                parsed = JSON.parse(readFile(file));
+            }
+            catch {
+                throw new Error(`Could not read ${file} as a list of characters and voice IDs.`);
+            }
+            if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+                throw new Error(`Could not read ${file} as a list of characters and voice IDs.`);
+            }
+            Object.assign(fromFile, parsed);
+            asked = true;
+        }
+    }
+    if (!asked)
+        return null;
+    const sameName = (a, b) => a.trim().toLowerCase() === b.trim().toLowerCase();
+    const merged = {};
+    for (const [who, choice] of Object.entries(fromFile)) {
+        if (!Object.keys(typed).some((t) => sameName(t, who)))
+            merged[who] = choice;
+    }
+    return { ...merged, ...typed };
+}
+export async function voicesFlow(runId, voices, json, deps) {
+    const res = voices
+        ? await deps.post(VOICES_PATH, { runId, voices })
+        : await deps.get(`${VOICES_PATH}?runId=${encodeURIComponent(runId)}`);
+    if (!res.ok)
+        return errorResult(res, json);
+    const sheet = res.data;
+    if (json)
+        return { code: 0, lines: [JSON.stringify({ ok: true, ...sheet })] };
+    return { code: 0, lines: voiceSheetLines(sheet) };
+}
+function availabilityWords(row) {
+    if (!row.voice)
+        return "no voice yet";
+    switch (row.availability?.state) {
+        case "available":
+            return "ElevenLabs has it";
+        case "missing":
+            return "ElevenLabs does not have it";
+        case "not-checked":
+            return "not checked just now";
+        default:
+            return "not checked";
+    }
+}
+export function voiceSheetLines(sheet) {
+    const lines = [`Voices for run ${sheet.runId}`];
+    if (sheet.cast.length === 0)
+        lines.push("  Nobody is in this ad yet.");
+    for (const row of sheet.cast) {
+        const voice = row.voice
+            ? `${row.voice.label ? `${row.voice.label} (${row.voice.voiceId})` : row.voice.voiceId}`
+            : "—";
+        lines.push(`  ${row.characterId}  ${row.name}  ${voice}  ${availabilityWords(row)}  ` +
+            `speaks in ${row.spokenScenes} scenes, about ${row.spokenSeconds}s`);
+    }
+    if (sheet.narrator) {
+        const label = sheet.narrator.label ? `${sheet.narrator.label} ` : "";
+        lines.push(`  Narrator  ${label}(${sheet.narrator.voiceId})  set on the workflow, not here`);
+    }
+    if (sheet.changed) {
+        lines.push(sheet.changed.length > 0
+            ? `Changed: ${sheet.changed.join(", ")}. Pictures and script were not touched.`
+            : "Nothing changed — those voices were already set. Pictures and script were not touched.");
+    }
+    lines.push(`How voices are applied: ${sheet.treatment.summary}${sheet.treatment.speedChange ? "" : " No speed change."}`);
+    lines.push(`Cost: billed to your own ElevenLabs key. ${sheet.treatment.costNote} ` +
+        `About ${sheet.treatment.usage.seconds} seconds of speech across ` +
+        `${sheet.treatment.usage.clips} clips will be converted.`);
+    for (const notice of sheet.notices)
+        lines.push(notice);
+    lines.push(sheet.canChange
+        ? "You can still change voices until you approve the storyboard."
+        : (sheet.whyNot ?? "Voices can no longer be changed on this run."));
+    return lines;
+}
 export async function pullFlow(runId, dir, json, deps) {
     const runRes = await deps.get(`${RUN_PATH}?runId=${encodeURIComponent(runId)}`);
     if (!runRes.ok)
@@ -1343,6 +1475,9 @@ const VALUE_FLAGS = new Set([
     "duration",
     "node",
     "scene",
+    "set",
+    "clear",
+    "from",
 ]);
 export function parsePositional(args = process.argv.slice(3)) {
     const out = [];
@@ -1402,7 +1537,16 @@ export async function run(flags) {
         }, defaultDeps));
     }
     const runId = rest[0];
-    const needsRunId = ["status", "storyboard", "approve", "flag", "retry-frame", "pull", "upload"];
+    const needsRunId = [
+        "status",
+        "storyboard",
+        "approve",
+        "flag",
+        "retry-frame",
+        "voices",
+        "pull",
+        "upload",
+    ];
     if (needsRunId.includes(sub) && !runId) {
         usage(`video ${sub} needs a run id: exodus video ${sub} <runId>`);
     }
@@ -1432,6 +1576,16 @@ export async function run(flags) {
         }
         return printResult(await retryFrameFlow(runId, nodeId, sceneIndex, flagString(flags, "note"), json, defaultDeps));
     }
+    if (sub === "voices") {
+        let voices;
+        try {
+            voices = parseVoiceFlags(process.argv.slice(3), defaultDeps.readFile);
+        }
+        catch (err) {
+            usage(err.message);
+        }
+        return printResult(await voicesFlow(runId, voices, json, defaultDeps));
+    }
     if (sub === "pull") {
         const dir = flagString(flags, "out");
         if (!dir)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aicopycoders/exodus",
-  "version": "2026.9.1700-beta.1",
+  "version": "2026.9.1800-beta.0",
   "description": "CLI + Claude Code skills for the Copycoders Exodus ad pipeline",
   "repository": {
     "type": "git",