@odori/cli 0.0.8 → 0.0.10

package/dist/{chunk-UPYHTDXP.js → chunk-AJBK4XRB.js}

@@ -317,7 +317,7 @@ var toComponent = (item) => ({
 });
 var snapshotItems = async () => {
   try {
-    const loaded = await import("./registry-snapshot-GV6FFZXV.js");
+    const loaded = await import("./registry-snapshot-TKH2KAC3.js");
     return loaded.default.items;
   } catch {
     throw new Error(
@@ -870,7 +870,11 @@ var elevenlabs = {
       signal: AbortSignal.timeout(1e4)
     });
     if (response.ok) return true;
-    if (response.status === 401 || response.status === 403) return false;
+    if (response.status === 401 || response.status === 403) {
+      const detail = await response.text().catch(() => "");
+      if (/missing_permissions|permission/i.test(detail)) return true;
+      return false;
+    }
     throw new Error(`ElevenLabs answered ${response.status} to a key check.`);
   },
   async generate({ prompt, seconds, apiKey }) {
@@ -893,6 +897,54 @@ Is ${elevenlabs.keyVariable} a current key?` : "")
     return { bytes: new Uint8Array(await response.arrayBuffer()), extension };
   }
 };
+var elevenlabsVoice = {
+  name: "elevenlabs",
+  title: "ElevenLabs Speech",
+  docsUrl: "https://elevenlabs.io/docs/api-reference/text-to-speech",
+  keyVariable: "ELEVENLABS_API_KEY",
+  // Rachel, the provider's most neutral narrator. --voice overrides.
+  defaultVoice: "21m00Tcm4TlvDq8ikWAM",
+  verifyKey: (apiKey) => elevenlabs.verifyKey(apiKey),
+  async speak({ script, voice, apiKey }) {
+    const response = await fetch(
+      `https://api.elevenlabs.io/v1/text-to-speech/${encodeURIComponent(voice)}/with-timestamps?output_format=mp3_44100_128`,
+      {
+        method: "POST",
+        headers: { "xi-api-key": apiKey, "content-type": "application/json" },
+        body: JSON.stringify({ text: script, model_id: "eleven_multilingual_v2" }),
+        signal: AbortSignal.timeout(3e5)
+      }
+    );
+    if (!response.ok) {
+      const detail = await response.text().catch(() => "");
+      throw new Error(
+        `ElevenLabs returned ${response.status} ${response.statusText}.` + (detail ? `
+${detail.slice(0, 400)}` : "") + (response.status === 401 ? `
+Is ${elevenlabsVoice.keyVariable} a current key?` : "")
+      );
+    }
+    const payload = await response.json();
+    return {
+      bytes: Uint8Array.from(Buffer.from(payload.audio_base64, "base64")),
+      extension: "mp3",
+      alignment: {
+        characters: payload.alignment.characters,
+        startSeconds: payload.alignment.character_start_times_seconds,
+        endSeconds: payload.alignment.character_end_times_seconds
+      }
+    };
+  }
+};
+var voiceProviders = { elevenlabs: elevenlabsVoice };
+var resolveVoiceProvider = (name) => {
+  const provider = voiceProviders[name];
+  if (!provider) {
+    throw new Error(
+      `No voice provider named "${name}". Available: ${Object.keys(voiceProviders).join(", ")}.`
+    );
+  }
+  return provider;
+};
 var musicProviders = { elevenlabs };
 var resolveMusicProvider = (name) => {
   const provider = musicProviders[name];
@@ -2445,6 +2497,13 @@ var studioEntry = resolve18(studioRoot, "index.html");
 var installRoot = resolve18(cliRoot, "..", "..");
 var VIRTUAL_ID = "virtual:odori-project";
 var RESOLVED_ID = `\0${VIRTUAL_ID}`;
+var cliVersion = () => {
+  try {
+    return createRequire2(import.meta.url)("../package.json").version;
+  } catch {
+    return "dev";
+  }
+};
 var runtimeSource = (root) => {
   for (const from of [resolve18(root, "package.json"), import.meta.url]) {
     try {
@@ -2495,6 +2554,7 @@ var odoriProjectPlugin = (config, getGraph) => ({
         audioDir: config.audioDir,
         docsUrl: config.docsUrl,
         audio: graph.audio,
+        version: cliVersion(),
         sourceHash: graph.sourceHash,
         assets: config.assets ?? [],
         files: {
@@ -3561,8 +3621,50 @@ var listCommand = async () => {
   }
 };
 
+// src/commands/narrate.ts
+import { mkdir as mkdir18, writeFile as writeFile19 } from "fs/promises";
+import { basename as basename3, dirname as dirname9, extname as extname2, join as join9, resolve as resolve24 } from "path";
+import { wordsFromCharacters } from "odori";
+var narrateCommand = async (script, options = {}) => {
+  if (!script.trim()) throw new Error('Give the script to read, for example: odori narrate "One definition. Every render."');
+  const config = await loadConfig(process.cwd());
+  const provider = resolveVoiceProvider(options.provider ?? "elevenlabs");
+  const apiKey = await resolveKey(provider);
+  if (!apiKey) {
+    throw new Error(
+      `Narrating with ${provider.name} needs a key: set ${provider.keyVariable} in the environment,
+or paste one once into Studio\u2019s integrations page ("odori dev", then Integrations).
+Either way it is sent only to the provider and never stored in the project.`
+    );
+  }
+  const voice = options.voice ?? provider.defaultVoice;
+  log.detail(`Recording ${script.split(/\s+/).length} words with ${provider.title}`);
+  const { bytes, extension, alignment } = await provider.speak({ script, voice, apiKey });
+  const words = wordsFromCharacters(alignment);
+  if (words.length === 0) throw new Error("The provider returned no word timings, so captions cannot be derived. Nothing was written.");
+  const stem = options.output ? basename3(options.output, extname2(options.output)) : script.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 40) || "narration";
+  const directory2 = options.output ? dirname9(resolve24(config.root, options.output)) : join9(config.root, "public", "audio");
+  await mkdir18(directory2, { recursive: true });
+  const audioFile = join9(directory2, `${stem}.${extension}`);
+  await writeFile19(audioFile, bytes);
+  const role = options.role ?? "voice.narration";
+  const url = `/audio/${basename3(audioFile)}`;
+  const narration = { script, provider: provider.name, voice, audio: role, words };
+  const timingFile = join9(directory2, `${stem}.narration.json`);
+  await writeFile19(timingFile, `${JSON.stringify(narration, null, 2)}
+`, "utf8");
+  const registered = await registerCueInBrand(config, { name: role, url }, stem);
+  const seconds = words[words.length - 1].endSeconds;
+  log.success(`Recorded ${seconds.toFixed(1)}s to ${basename3(audioFile)} (${(bytes.length / 1024).toFixed(0)} KB)`);
+  log.success(`Word timings in ${basename3(timingFile)}`);
+  if (registered) log.detail(`Registered "${role}" in the brand`);
+  log.detail("In a video:");
+  log.detail(`  <Audio src="${role}" />`);
+  log.detail(`  <Captions cues={captionCues(narration, fps)} />  // import narration from the json`);
+};
+
 // src/commands/frame.ts
-import { resolve as resolve24 } from "path";
+import { resolve as resolve25 } from "path";
 import { framesFromOffset, resolveEntryLayout as resolveEntryLayout7 } from "odori";
 var frameCommand = async (id, options = {}) => {
   const at = options.at ?? 0;
@@ -3584,7 +3686,7 @@ var frameCommand = async (id, options = {}) => {
       throw new Error(`Frame ${frame} is past the last frame (${manifest.format.durationInFrames - 1}).`);
     }
     const target = targetFor({ ...video, durationInFrames: manifest.format.durationInFrames }, input, prepared);
-    const file = resolve24(config.root, options.output ?? `${config.exportDir}/${outputName(id)}-${frame}.png`);
+    const file = resolve25(config.root, options.output ?? `${config.exportDir}/${outputName(id)}-${frame}.png`);
     return renderStill(server.url, target, frame, file, config);
   });
   log.success(`Frame ${frame} written to ${output}`);
@@ -3597,7 +3699,7 @@ import { isOdoriSchema as isOdoriSchema2, resolveEntryLayout as resolveEntryLayo
 // src/contracts.ts
 import { existsSync as existsSync21 } from "fs";
 import { readdir as readdir7 } from "fs/promises";
-import { resolve as resolve25 } from "path";
+import { resolve as resolve26 } from "path";
 import { cueUrl as cueUrl2, isCueDefinition as isCueDefinition2, resolveEntryLayout as resolveEntryLayout8 } from "odori";
 var primaryFamily = (stack) => (stack.split(",")[0] ?? "").trim().replace(/^["']|["']$/g, "");
 var SYSTEM_FAMILIES = /* @__PURE__ */ new Set([
@@ -3664,7 +3766,7 @@ var checkAudioWindows = (cues, brand, videoId) => {
   return failures;
 };
 var checkInstalledContracts = async (config, videos) => {
-  const componentsDir = resolve25(config.root, config.componentsDir);
+  const componentsDir = resolve26(config.root, config.componentsDir);
   const onDisk = existsSync21(componentsDir) ? (await readdir7(componentsDir, { withFileTypes: true })).filter((entry) => entry.isDirectory()).map((entry) => entry.name) : [];
   const names = /* @__PURE__ */ new Set([...Object.keys(await readProvenance(config)), ...onDisk]);
   if (names.size === 0) return [];
@@ -3688,7 +3790,7 @@ var checkInstalledContracts = async (config, videos) => {
 // src/determinism.ts
 import { readdir as readdir8, readFile as readFile17 } from "fs/promises";
 import { existsSync as existsSync22 } from "fs";
-import { join as join9, relative as relative12, resolve as resolve26 } from "path";
+import { join as join10, relative as relative12, resolve as resolve27 } from "path";
 var FORBIDDEN = [
   {
     pattern: /\bMath\.random\s*\(/,
@@ -3722,14 +3824,14 @@ var scanSource = (source, file) => {
 var walk2 = async (directory2, files = []) => {
   for (const entry of await readdir8(directory2, { withFileTypes: true })) {
     if (entry.name.startsWith(".") || entry.name === "node_modules") continue;
-    const full = join9(directory2, entry.name);
+    const full = join10(directory2, entry.name);
     if (entry.isDirectory()) await walk2(full, files);
     else if (/\.(tsx|ts|jsx|js)$/.test(entry.name) && !/\.preview\.(tsx|jsx)$/.test(entry.name)) files.push(full);
   }
   return files;
 };
 var checkDeterminism = async (config) => {
-  const root = resolve26(config.root, config.videosDir);
+  const root = resolve27(config.root, config.videosDir);
   if (!existsSync22(root)) return [];
   const files = await walk2(root);
   const findings = await Promise.all(
@@ -4084,6 +4186,7 @@ var COMMAND_FLAGS = {
   inspect: ["json", "input"],
   frame: ["at", "output", "input"],
   bed: ["role", "output", "target", "generate", "provider", "seconds"],
+  narrate: ["output", "voice", "role", "provider"],
   test: ["json"],
   export: ["output", "input", "concurrency", "preset", "format", "quality", "scale", "no-audio", "fast", "no-frame-skip", "retry"],
   jobs: [],
@@ -4130,6 +4233,11 @@ var USAGE = {
   With --generate the positional is a prompt instead of a path: the track is
   generated with a provider (--provider, default elevenlabs, key from
   ELEVENLABS_API_KEY), then prepared identically. --seconds sets its length.`,
+  narrate: `odori narrate <script> [--output <path>] [--voice <id>] [--role <cue>]
+  Record the script as narration. Writes the audio and a .narration.json with
+  the time every word starts and ends, and registers the cue role (default
+  voice.narration) in the brand. Captions derive from the timings at compose
+  time, so they cannot drift from the voice.`,
   integrations: `odori integrations
   List generation providers and whether each is connected. Configuration
   lives in the environment or Studio's integrations page; generation happens
@@ -4194,6 +4302,7 @@ Usage
   odori frame <id> --at 4s          Render one deterministic frame to a PNG
   odori test [id] [--json]         Validate contracts and representative frames
   odori export <id> [--output f]   Render and encode a distributable file
+  odori narrate <script>          Record narration with word timings
   odori jobs                       List export jobs and their status
 
 Options
@@ -4212,7 +4321,7 @@ Options
 
 Run "odori <command> --help" for one command, or "odori doctor" to check setup.
 `;
-var cliVersion = () => {
+var cliVersion2 = () => {
   try {
     const require2 = createRequire4(import.meta.url);
     return require2("../package.json").version;
@@ -4224,7 +4333,7 @@ var run3 = async (argv) => {
   const { command: command2, positionals, flags } = parseArgs(argv);
   try {
     if (command2 === "--version" || command2 === "-v" || command2 === "version") {
-      log.info(`odori ${cliVersion()} (node ${process.version})`);
+      log.info(`odori ${cliVersion2()} (node ${process.version})`);
       return 0;
     }
     if (flags.help === true && USAGE[command2]) {
@@ -4289,6 +4398,14 @@ var run3 = async (argv) => {
           seconds: numberFlag(flags, "seconds")
         });
         return 0;
+      case "narrate":
+        await narrateCommand(positionals.join(" "), {
+          output: typeof flags.output === "string" ? flags.output : void 0,
+          voice: typeof flags.voice === "string" ? flags.voice : void 0,
+          role: typeof flags.role === "string" ? flags.role : void 0,
+          provider: typeof flags.provider === "string" ? flags.provider : void 0
+        });
+        return 0;
       case "frame":
         await frameCommand(positionals[0] ?? "", {
           // A duration, so "4s" and "120f" both work; a bare number is

package/dist/cli.js

@@ -2,7 +2,7 @@ import {
   checkFlags,
   parseArgs,
   run
-} from "./chunk-UPYHTDXP.js";
+} from "./chunk-AJBK4XRB.js";
 export {
   checkFlags,
   parseArgs,

package/dist/index.js

@@ -75,7 +75,7 @@ import {
   withServer,
   writeGenerated,
   writePrepareCache
-} from "./chunk-UPYHTDXP.js";
+} from "./chunk-AJBK4XRB.js";
 export {
   CHROME_BUILD,
   FORMATS,

package/dist/{registry-snapshot-GV6FFZXV.js → registry-snapshot-TKH2KAC3.js}

@@ -4267,7 +4267,7 @@ export default defineComponentPreview({
       files: [
         {
           path: "components/statement/statement.tsx",
-          content: 'import {Fill, Easing, interpolate, useBrand, useFrame, useDesignScale} from "odori";\n\nexport type StatementChip = {\n  /** The chip\'s text. */\n  label: string;\n  /** A glyph drawn before the label: a logo, a symbol, a single letter. */\n  icon?: string;\n  /** Which surface the chip is drawn on. */\n  tone?: "neutral" | "dark" | "accent";\n};\n\nexport type StatementProps = {\n  /** The sentence, in order. A string is a word; an object is a chip. */\n  parts: Array<string | StatementChip>;\n  /**\n   * What arrives at a time. Characters read as someone typing, words as\n   * someone talking, and `none` puts the whole line up at once.\n   */\n  reveal?: "characters" | "words" | "none";\n  /**\n   * How a part arrives. `rise` lifts and fades it in; `cut` switches it on.\n   * A cut is not a lesser rise: a video built entirely of hard cuts has a\n   * rhythm that any easing softens away.\n   */\n  motion?: "rise" | "cut";\n  /** Frames between one unit and the next. */\n  stagger?: number;\n  /** Where the sentence sits. */\n  align?: "left" | "center";\n  /** Light page or dark page. Chips and text follow it. */\n  theme?: "light" | "dark";\n  /** A chip that replaces the last chip in place. */\n  swap?: StatementChip;\n  /** The frame the swap happens on. */\n  swapAt?: number;\n};\n\nconst isChip = (part: string | StatementChip): part is StatementChip => typeof part !== "string";\n\n/**\n * A sentence, arriving under its own discipline, with product controls set\n * inline where the prose needs one.\n *\n * Real product videos disagree about how type should arrive, and they are all\n * right. One types character by character because it is imitating a person at\n * a keyboard. One cuts word by word with no easing anywhere, because every\n * other transition in it is a cut and a single eased rise would sound a wrong\n * note. One lifts whole phrases because it is narrating. So the discipline is\n * a choice here rather than a house opinion baked into three near-identical\n * components.\n *\n * Characters reveal inside a layout that is already the whole sentence: each\n * glyph switches on where it will finally sit, so nothing reflows and no caret\n * is needed to explain a ragged edge, because there is no ragged edge.\n *\n * A chip is drawn the way the interface draws it, so a sentence can name a\n * control and the next scene can cut to that control at scale without the two\n * disagreeing about what the product looks like. `swap` exchanges the last\n * chip in place, so one vendor becoming another is a substitution rather than\n * a reflow of the line.\n */\nexport const Statement = ({\n  parts,\n  reveal = "words",\n  motion = "rise",\n  stagger,\n  align = "left",\n  theme = "light",\n  swap,\n  swapAt,\n}: StatementProps) => {\n  const frame = useFrame();\n  const brand = useBrand();\n  const scale = useDesignScale();\n  const dark = theme === "dark";\n  const ink = dark ? brand.colors.background : brand.colors.foreground;\n  const paper = dark ? brand.colors.foreground : brand.colors.background;\n\n  // One frame per character reads as typing; a couple of stagger units per\n  // word reads as speech.\n  const step = stagger ?? (reveal === "characters" ? 1 : brand.motion.staggerFrames * 2);\n  const start = 6;\n  const lastChip = parts.map(isChip).lastIndexOf(true);\n  const swapFrame = swapAt ?? 0;\n\n  // Where each part begins, counted in whatever unit is being revealed.\n  const offsets: number[] = [];\n  let units = 0;\n  for (const part of parts) {\n    offsets.push(units);\n    units += reveal === "characters" && !isChip(part) ? part.length + 1 : 1;\n  }\n\n  const shown = (unit: number) => {\n    if (reveal === "none") return frame >= start ? 1 : 0;\n    const at = start + unit * step;\n    if (motion === "cut") return frame >= at ? 1 : 0;\n    return interpolate(frame, [at, at + 20], [0, 1], {easing: Easing.standard});\n  };\n\n  const enter = (progress: number) =>\n    motion === "cut"\n      ? {display: "inline-block", opacity: progress}\n      : {\n          display: "inline-block",\n          opacity: progress,\n          transform: `translateY(${(1 - progress) * 26 * scale}px)`,\n        };\n\n  const chipSurface = (tone: StatementChip["tone"]) => {\n    if (tone === "accent") return {background: brand.colors.accent, color: paper, border: "transparent"};\n    if (tone === "dark") return {background: ink, color: paper, border: "transparent"};\n    // Mixed from the ink rather than named, so a neutral chip is legible on a\n    // light brand, a dark brand, and the inverted scenes without being told\n    // which it is standing on.\n    return {\n      background: `color-mix(in srgb, ${ink} 8%, transparent)`,\n      color: ink,\n      border: `color-mix(in srgb, ${ink} 20%, transparent)`,\n    };\n  };\n\n  const chipBody = (chip: StatementChip) => {\n    const surface = chipSurface(chip.tone);\n    return (\n      <span\n        style={{\n          alignItems: "center",\n          background: surface.background,\n          border: `${Math.max(1, scale)}px solid ${surface.border}`,\n          borderRadius: 14 * scale,\n          color: surface.color,\n          display: "inline-flex",\n          gap: 10 * scale,\n          padding: `${6 * scale}px ${16 * scale}px`,\n          whiteSpace: "nowrap",\n        }}\n      >\n        {chip.icon ? <span style={{fontSize: 46 * scale, lineHeight: 1}}>{chip.icon}</span> : null}\n        {chip.label}\n      </span>\n    );\n  };\n\n  return (\n    <Fill\n      style={{\n        alignItems: align === "center" ? "center" : "flex-start",\n        background: dark ? ink : "transparent",\n        justifyContent: "center",\n        padding: `${120 * scale}px ${150 * scale}px`,\n      }}\n    >\n      <div\n        style={{\n          alignItems: "center",\n          color: ink,\n          columnGap: 16 * scale,\n          display: "flex",\n          flexWrap: "wrap",\n          fontSize: 64 * scale,\n          fontWeight: 500,\n          justifyContent: align === "center" ? "center" : "flex-start",\n          letterSpacing: "-0.03em",\n          lineHeight: 1.35,\n          rowGap: 8 * scale,\n          textAlign: align,\n        }}\n      >\n        {parts.map((part, index) => {\n          const swapping = swap !== undefined && index === lastChip;\n          const swapped = swapping\n            ? interpolate(frame, [swapFrame, swapFrame + (motion === "cut" ? 1 : 16)], [0, 1], {\n                easing: Easing.standard,\n              })\n            : 0;\n\n          if (!isChip(part)) {\n            // In a pre-measured layout every glyph already occupies its final\n            // place, so revealing one cannot move the ones after it.\n            if (reveal === "characters") {\n              return (\n                <span key={`${part}-${index}`} style={{display: "inline-block", whiteSpace: "pre"}}>\n                  {[...part].map((character, position) => (\n                    <span key={position} style={{display: "inline-block", opacity: shown(offsets[index] + position)}}>\n                      {character}\n                    </span>\n                  ))}\n                </span>\n              );\n            }\n            return (\n              <span key={`${part}-${index}`} style={enter(shown(offsets[index]))}>\n                {part}\n              </span>\n            );\n          }\n\n          const entrance = shown(offsets[index]);\n          return (\n            <span\n              key={`chip-${index}`}\n              style={{\n                ...enter(entrance),\n                // A chip settles from slightly small, the way a control that\n                // just appeared under the cursor does. A cut skips the settle.\n                ...(motion === "cut"\n                  ? {}\n                  : {transform: `translateY(${(1 - entrance) * 26 * scale}px) scale(${0.92 + entrance * 0.08})`}),\n              }}\n            >\n              {swapping ? (\n                <span style={{display: "inline-grid"}}>\n                  <span\n                    style={{\n                      gridArea: "1 / 1",\n                      opacity: 1 - swapped,\n                      transform: motion === "cut" ? undefined : `translateY(${swapped * -18 * scale}px)`,\n                    }}\n                  >\n                    {chipBody(part)}\n                  </span>\n                  <span\n                    style={{\n                      gridArea: "1 / 1",\n                      opacity: swapped,\n                      transform: motion === "cut" ? undefined : `translateY(${(1 - swapped) * 18 * scale}px)`,\n                    }}\n                  >\n                    {chipBody(swap)}\n                  </span>\n                </span>\n              ) : (\n                chipBody(part)\n              )}\n            </span>\n          );\n        })}\n      </div>\n    </Fill>\n  );\n};\n',
+          content: 'import {Fill, Easing, interpolate, useBrand, useFrame, useDesignScale} from "odori";\n\nexport type StatementChip = {\n  /** The chip\'s text. */\n  label: string;\n  /** A glyph drawn before the label: a logo, a symbol, a single letter. */\n  icon?: string;\n  /** Which surface the chip is drawn on. */\n  tone?: "neutral" | "dark" | "accent";\n};\n\nexport type StatementProps = {\n  /** The sentence, in order. A string is a word; an object is a chip. */\n  parts: Array<string | StatementChip>;\n  /**\n   * What arrives at a time. Characters read as someone typing, words as\n   * someone talking, and `none` puts the whole line up at once.\n   */\n  reveal?: "characters" | "words" | "none";\n  /**\n   * How a part arrives. `rise` lifts and fades it in; `cut` switches it on.\n   * A cut is not a lesser rise: a video built entirely of hard cuts has a\n   * rhythm that any easing softens away.\n   */\n  motion?: "rise" | "cut";\n  /** Frames between one unit and the next. */\n  stagger?: number;\n  /** Where the sentence sits. */\n  align?: "left" | "center";\n  /** Light page or dark page. Chips and text follow it. */\n  theme?: "light" | "dark";\n  /** A chip that replaces the last chip in place. */\n  swap?: StatementChip;\n  /** The frame the swap happens on. */\n  swapAt?: number;\n};\n\nconst isChip = (part: string | StatementChip): part is StatementChip => typeof part !== "string";\n\n/**\n * A sentence, arriving under its own discipline, with product controls set\n * inline where the prose needs one.\n *\n * Real product videos disagree about how type should arrive, and they are all\n * right. One types character by character because it is imitating a person at\n * a keyboard. One cuts word by word with no easing anywhere, because every\n * other transition in it is a cut and a single eased rise would sound a wrong\n * note. One lifts whole phrases because it is narrating. So the discipline is\n * a choice here rather than a house opinion baked into three near-identical\n * components.\n *\n * Characters reveal inside a layout that is already the whole sentence: each\n * glyph switches on where it will finally sit, so nothing reflows and no caret\n * is needed to explain a ragged edge, because there is no ragged edge.\n *\n * A chip is drawn the way the interface draws it, so a sentence can name a\n * control and the next scene can cut to that control at scale without the two\n * disagreeing about what the product looks like. `swap` exchanges the last\n * chip in place, so one vendor becoming another is a substitution rather than\n * a reflow of the line.\n */\nexport const Statement = ({\n  parts,\n  reveal = "words",\n  motion = "rise",\n  stagger,\n  align = "left",\n  theme = "light",\n  swap,\n  swapAt,\n}: StatementProps) => {\n  const frame = useFrame();\n  const brand = useBrand();\n  const scale = useDesignScale();\n  const dark = theme === "dark";\n  const ink = dark ? brand.colors.background : brand.colors.foreground;\n  const paper = dark ? brand.colors.foreground : brand.colors.background;\n\n  // One frame per character reads as typing; a couple of stagger units per\n  // word reads as speech.\n  const step = stagger ?? (reveal === "characters" ? 1 : brand.motion.staggerFrames * 2);\n  const start = 6;\n  const lastChip = parts.map(isChip).lastIndexOf(true);\n  const swapFrame = swapAt ?? 0;\n\n  // Where each part begins, counted in whatever unit is being revealed.\n  const offsets: number[] = [];\n  let units = 0;\n  for (const part of parts) {\n    offsets.push(units);\n    units += reveal === "characters" && !isChip(part) ? part.length + 1 : 1;\n  }\n\n  const shown = (unit: number) => {\n    if (reveal === "none") return frame >= start ? 1 : 0;\n    const at = start + unit * step;\n    if (motion === "cut") return frame >= at ? 1 : 0;\n    return interpolate(frame, [at, at + 20], [0, 1], {easing: Easing.standard});\n  };\n\n  const enter = (progress: number) =>\n    motion === "cut"\n      ? {display: "inline-block", opacity: progress}\n      : {\n          display: "inline-block",\n          opacity: progress,\n          transform: `translateY(${(1 - progress) * 26 * scale}px)`,\n        };\n\n  const chipSurface = (tone: StatementChip["tone"]) => {\n    if (tone === "accent") return {background: brand.colors.accent, color: paper, border: "transparent"};\n    if (tone === "dark") return {background: ink, color: paper, border: "transparent"};\n    // Mixed from the ink rather than named, so a neutral chip is legible on a\n    // light brand, a dark brand, and the inverted scenes without being told\n    // which it is standing on.\n    return {\n      background: `color-mix(in srgb, ${ink} 8%, transparent)`,\n      color: ink,\n      border: `color-mix(in srgb, ${ink} 20%, transparent)`,\n    };\n  };\n\n  const chipBody = (chip: StatementChip) => {\n    const surface = chipSurface(chip.tone);\n    return (\n      <span\n        style={{\n          alignItems: "center",\n          background: surface.background,\n          border: `${Math.max(1, scale)}px solid ${surface.border}`,\n          borderRadius: 14 * scale,\n          color: surface.color,\n          display: "inline-flex",\n          gap: 10 * scale,\n          padding: `${6 * scale}px ${16 * scale}px`,\n          whiteSpace: "nowrap",\n        }}\n      >\n        {chip.icon ? <span style={{fontSize: 46 * scale, lineHeight: 1}}>{chip.icon}</span> : null}\n        {chip.label}\n      </span>\n    );\n  };\n\n  return (\n    <Fill\n      style={{\n        alignItems: align === "center" ? "center" : "flex-start",\n        // paper, not ink. ink is the type colour, and painting the ground\n        // with it put light text on a light ground: the dark theme rendered\n        // the sentence invisible, including in this component\'s own fixture.\n        background: dark ? paper : "transparent",\n        justifyContent: "center",\n        padding: `${120 * scale}px ${150 * scale}px`,\n      }}\n    >\n      <div\n        style={{\n          alignItems: "center",\n          color: ink,\n          columnGap: 16 * scale,\n          display: "flex",\n          flexWrap: "wrap",\n          fontSize: 64 * scale,\n          fontWeight: 500,\n          justifyContent: align === "center" ? "center" : "flex-start",\n          letterSpacing: "-0.03em",\n          lineHeight: 1.35,\n          rowGap: 8 * scale,\n          textAlign: align,\n        }}\n      >\n        {parts.map((part, index) => {\n          const swapping = swap !== undefined && index === lastChip;\n          const swapped = swapping\n            ? interpolate(frame, [swapFrame, swapFrame + (motion === "cut" ? 1 : 16)], [0, 1], {\n                easing: Easing.standard,\n              })\n            : 0;\n\n          if (!isChip(part)) {\n            // In a pre-measured layout every glyph already occupies its final\n            // place, so revealing one cannot move the ones after it.\n            if (reveal === "characters") {\n              return (\n                <span key={`${part}-${index}`} style={{display: "inline-block", whiteSpace: "pre"}}>\n                  {[...part].map((character, position) => (\n                    <span key={position} style={{display: "inline-block", opacity: shown(offsets[index] + position)}}>\n                      {character}\n                    </span>\n                  ))}\n                </span>\n              );\n            }\n            return (\n              <span key={`${part}-${index}`} style={enter(shown(offsets[index]))}>\n                {part}\n              </span>\n            );\n          }\n\n          const entrance = shown(offsets[index]);\n          return (\n            <span\n              key={`chip-${index}`}\n              style={{\n                ...enter(entrance),\n                // A chip settles from slightly small, the way a control that\n                // just appeared under the cursor does. A cut skips the settle.\n                ...(motion === "cut"\n                  ? {}\n                  : {transform: `translateY(${(1 - entrance) * 26 * scale}px) scale(${0.92 + entrance * 0.08})`}),\n              }}\n            >\n              {swapping ? (\n                <span style={{display: "inline-grid"}}>\n                  <span\n                    style={{\n                      gridArea: "1 / 1",\n                      opacity: 1 - swapped,\n                      transform: motion === "cut" ? undefined : `translateY(${swapped * -18 * scale}px)`,\n                    }}\n                  >\n                    {chipBody(part)}\n                  </span>\n                  <span\n                    style={{\n                      gridArea: "1 / 1",\n                      opacity: swapped,\n                      transform: motion === "cut" ? undefined : `translateY(${(1 - swapped) * 18 * scale}px)`,\n                    }}\n                  >\n                    {chipBody(swap)}\n                  </span>\n                </span>\n              ) : (\n                chipBody(part)\n              )}\n            </span>\n          );\n        })}\n      </div>\n    </Fill>\n  );\n};\n',
           target: "videos/components/statement/statement.tsx"
         },
         {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@odori/cli",
-  "version": "0.0.8",
+  "version": "0.0.10",
   "type": "module",
   "description": "The odori command line: discovery, Studio, component installation, stills, tests, and export jobs.",
   "license": "Apache-2.0",
@@ -28,7 +28,7 @@
     "playwright-core": "1.55.0",
     "tsx": "4.20.5",
     "vite": "7.3.0",
-    "odori": "0.0.8"
+    "odori": "0.0.10"
   },
   "devDependencies": {
     "@types/node": "22.19.0",
@@ -36,7 +36,7 @@
     "@types/react-dom": "19.2.3",
     "tsup": "^8.5.1",
     "typescript": "5.9.3",
-    "@odori/registry": "0.0.8"
+    "@odori/registry": "0.0.9"
   },
   "publishConfig": {
     "access": "public"

package/src/cli.ts

@@ -12,6 +12,7 @@ import {inspectCommand} from "./commands/inspect";
 import {listCommand} from "./commands/list";
 import {newCommand} from "./commands/new";
 import {bedCommand} from "./commands/bed";
+import {narrateCommand} from "./commands/narrate";
 import {frameCommand} from "./commands/frame";
 import {testCommand} from "./commands/test";
 
@@ -102,6 +103,7 @@ const COMMAND_FLAGS: Record<string, string[]> = {
   inspect: ["json", "input"],
   frame: ["at", "output", "input"],
   bed: ["role", "output", "target", "generate", "provider", "seconds"],
+  narrate: ["output", "voice", "role", "provider"],
   test: ["json"],
   export: ["output", "input", "concurrency", "preset", "format", "quality", "scale", "no-audio", "fast", "no-frame-skip", "retry"],
   jobs: [],
@@ -161,6 +163,11 @@ const USAGE: Record<string, string> = {
   With --generate the positional is a prompt instead of a path: the track is
   generated with a provider (--provider, default elevenlabs, key from
   ELEVENLABS_API_KEY), then prepared identically. --seconds sets its length.`,
+  narrate: `odori narrate <script> [--output <path>] [--voice <id>] [--role <cue>]
+  Record the script as narration. Writes the audio and a .narration.json with
+  the time every word starts and ends, and registers the cue role (default
+  voice.narration) in the brand. Captions derive from the timings at compose
+  time, so they cannot drift from the voice.`,
   integrations: `odori integrations
   List generation providers and whether each is connected. Configuration
   lives in the environment or Studio's integrations page; generation happens
@@ -226,6 +233,7 @@ Usage
   odori frame <id> --at 4s          Render one deterministic frame to a PNG
   odori test [id] [--json]         Validate contracts and representative frames
   odori export <id> [--output f]   Render and encode a distributable file
+  odori narrate <script>          Record narration with word timings
   odori jobs                       List export jobs and their status
 
 Options
@@ -327,6 +335,14 @@ export const run = async (argv: string[]): Promise<number> => {
           seconds: numberFlag(flags, "seconds"),
         });
         return 0;
+      case "narrate":
+        await narrateCommand(positionals.join(" "), {
+          output: typeof flags.output === "string" ? flags.output : undefined,
+          voice: typeof flags.voice === "string" ? flags.voice : undefined,
+          role: typeof flags.role === "string" ? flags.role : undefined,
+          provider: typeof flags.provider === "string" ? flags.provider : undefined,
+        });
+        return 0;
       case "frame":
         await frameCommand(positionals[0] ?? "", {
           // A duration, so "4s" and "120f" both work; a bare number is

package/src/commands/dev.ts

@@ -309,6 +309,8 @@ export const devCommand = async (options: {port?: number; root?: string; open?:
                   verified = null;
                 }
                 if (verified === false) {
+                  // The provider's check accepts a valid key regardless of its
+                  // scoping, so a rejection here means the key itself.
                   json(response, 400, {error: `${provider.title} rejected that key.`});
                   return;
                 }

package/src/commands/narrate.ts

@@ -0,0 +1,74 @@
+import {mkdir, writeFile} from "node:fs/promises";
+import {basename, dirname, extname, join, resolve} from "node:path";
+import {wordsFromCharacters, type Narration} from "odori";
+import {registerCueInBrand} from "../brand-file";
+import {loadConfig} from "../config";
+import {log} from "../log";
+import {resolveKey, resolveVoiceProvider} from "../providers";
+
+export type NarrateOptions = {
+  output?: string;
+  voice?: string;
+  provider?: string;
+  /** The brand cue role the audio registers under. */
+  role?: string;
+};
+
+/**
+ * Record a narration and keep it as source.
+ *
+ * One call produces the audio and the time every word starts and ends, and
+ * both land in the project: the file under public/audio, the timings beside
+ * it as `<name>.narration.json`. Captions derive from the timings at compose
+ * time, so they cannot drift from the voice, and a scene can be sized to a
+ * sentence because the sentence's end is data.
+ *
+ * Like every generation in Odori this is an authoring step. The provider is
+ * called once, here, and the render never knows a network was involved.
+ */
+export const narrateCommand = async (script: string, options: NarrateOptions = {}) => {
+  if (!script.trim()) throw new Error('Give the script to read, for example: odori narrate "One definition. Every render."');
+  const config = await loadConfig(process.cwd());
+  const provider = resolveVoiceProvider(options.provider ?? "elevenlabs");
+  const apiKey = await resolveKey(provider);
+  if (!apiKey) {
+    throw new Error(
+      `Narrating with ${provider.name} needs a key: set ${provider.keyVariable} in the environment,\n` +
+        'or paste one once into Studio’s integrations page ("odori dev", then Integrations).\n' +
+        "Either way it is sent only to the provider and never stored in the project.",
+    );
+  }
+
+  const voice = options.voice ?? provider.defaultVoice;
+  log.detail(`Recording ${script.split(/\s+/).length} words with ${provider.title}`);
+  const {bytes, extension, alignment} = await provider.speak({script, voice, apiKey});
+  const words = wordsFromCharacters(alignment);
+  if (words.length === 0) throw new Error("The provider returned no word timings, so captions cannot be derived. Nothing was written.");
+
+  const stem = options.output
+    ? basename(options.output, extname(options.output))
+    : script.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 40) || "narration";
+  const directory = options.output
+    ? dirname(resolve(config.root, options.output))
+    : join(config.root, "public", "audio");
+  await mkdir(directory, {recursive: true});
+
+  const audioFile = join(directory, `${stem}.${extension}`);
+  await writeFile(audioFile, bytes);
+
+  const role = options.role ?? "voice.narration";
+  const url = `/audio/${basename(audioFile)}`;
+  const narration: Narration = {script, provider: provider.name, voice, audio: role, words};
+  const timingFile = join(directory, `${stem}.narration.json`);
+  await writeFile(timingFile, `${JSON.stringify(narration, null, 2)}\n`, "utf8");
+
+  const registered = await registerCueInBrand(config, {name: role, url}, stem);
+  const seconds = words[words.length - 1].endSeconds;
+
+  log.success(`Recorded ${seconds.toFixed(1)}s to ${basename(audioFile)} (${(bytes.length / 1024).toFixed(0)} KB)`);
+  log.success(`Word timings in ${basename(timingFile)}`);
+  if (registered) log.detail(`Registered "${role}" in the brand`);
+  log.detail("In a video:");
+  log.detail(`  <Audio src="${role}" />`);
+  log.detail(`  <Captions cues={captionCues(narration, fps)} />  // import narration from the json`);
+};

package/src/providers.ts

@@ -45,7 +45,20 @@ const elevenlabs: MusicProvider = {
       signal: AbortSignal.timeout(10_000),
     });
     if (response.ok) return true;
-    if (response.status === 401 || response.status === 403) return false;
+    if (response.status === 401 || response.status === 403) {
+      /*
+       * A restricted key opts in to endpoints one by one, and this probe's
+       * endpoint is one of them: a real key scoped to something else answers
+       * 401 here exactly like a wrong key does. The error body tells them
+       * apart, an invalid key names itself invalid, a valid one names the
+       * permission it lacks, and a key that is real but scoped elsewhere is
+       * a pass. Whether it can reach the integration's own endpoint is the
+       * generate call's problem, which reports it properly.
+       */
+      const detail = await response.text().catch(() => "");
+      if (/missing_permissions|permission/i.test(detail)) return true;
+      return false;
+    }
     throw new Error(`ElevenLabs answered ${response.status} to a key check.`);
   },
   async generate({prompt, seconds, apiKey}) {
@@ -69,6 +82,89 @@ const elevenlabs: MusicProvider = {
   },
 };
 
+export type GeneratedSpeech = {
+  bytes: Uint8Array;
+  extension: string;
+  /** Character-level timing, parallel arrays over the spoken text. */
+  alignment: {characters: string[]; startSeconds: number[]; endSeconds: number[]};
+};
+
+export type VoiceProvider = {
+  name: string;
+  title: string;
+  docsUrl: string;
+  keyVariable: string;
+  defaultVoice: string;
+  speak(options: {script: string; voice: string; apiKey: string}): Promise<GeneratedSpeech>;
+  verifyKey(apiKey: string): Promise<boolean>;
+};
+
+/*
+ * Speech comes back with its own word timing, in the same call as the audio.
+ * That is the whole design: the recording and its alignment are one artifact,
+ * so captions derived from it cannot drift from the voice, and nothing ever
+ * has to transcribe audio after the fact to find out when a word happened.
+ */
+const elevenlabsVoice: VoiceProvider = {
+  name: "elevenlabs",
+  title: "ElevenLabs Speech",
+  docsUrl: "https://elevenlabs.io/docs/api-reference/text-to-speech",
+  keyVariable: "ELEVENLABS_API_KEY",
+  // Rachel, the provider's most neutral narrator. --voice overrides.
+  defaultVoice: "21m00Tcm4TlvDq8ikWAM",
+  verifyKey: (apiKey) => elevenlabs.verifyKey(apiKey),
+  async speak({script, voice, apiKey}) {
+    const response = await fetch(
+      `https://api.elevenlabs.io/v1/text-to-speech/${encodeURIComponent(voice)}/with-timestamps?output_format=mp3_44100_128`,
+      {
+        method: "POST",
+        headers: {"xi-api-key": apiKey, "content-type": "application/json"},
+        body: JSON.stringify({text: script, model_id: "eleven_multilingual_v2"}),
+        signal: AbortSignal.timeout(300_000),
+      },
+    );
+    if (!response.ok) {
+      const detail = await response.text().catch(() => "");
+      throw new Error(
+        `ElevenLabs returned ${response.status} ${response.statusText}.` +
+          (detail ? `
+${detail.slice(0, 400)}` : "") +
+          (response.status === 401 ? `
+Is ${elevenlabsVoice.keyVariable} a current key?` : ""),
+      );
+    }
+    const payload = (await response.json()) as {
+      audio_base64: string;
+      alignment: {
+        characters: string[];
+        character_start_times_seconds: number[];
+        character_end_times_seconds: number[];
+      };
+    };
+    return {
+      bytes: Uint8Array.from(Buffer.from(payload.audio_base64, "base64")),
+      extension: "mp3",
+      alignment: {
+        characters: payload.alignment.characters,
+        startSeconds: payload.alignment.character_start_times_seconds,
+        endSeconds: payload.alignment.character_end_times_seconds,
+      },
+    };
+  },
+};
+
+export const voiceProviders: Record<string, VoiceProvider> = {elevenlabs: elevenlabsVoice};
+
+export const resolveVoiceProvider = (name: string): VoiceProvider => {
+  const provider = voiceProviders[name];
+  if (!provider) {
+    throw new Error(
+      `No voice provider named "${name}". Available: ${Object.keys(voiceProviders).join(", ")}.`,
+    );
+  }
+  return provider;
+};
+
 export const musicProviders: Record<string, MusicProvider> = {elevenlabs};
 
 export const resolveMusicProvider = (name: string): MusicProvider => {
@@ -86,5 +182,5 @@ export const resolveMusicProvider = (name: string): MusicProvider => {
  * Studio integrations page writes. Both are read here and nowhere else, so
  * "where do keys come from" has one answer.
  */
-export const resolveKey = async (provider: MusicProvider): Promise<string | undefined> =>
+export const resolveKey = async (provider: {keyVariable: string}): Promise<string | undefined> =>
   process.env[provider.keyVariable] ?? (await storedKey(provider.keyVariable));