@odori/cli 0.0.7 → 0.0.9

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/commands/test.ts

@@ -9,7 +9,7 @@ import type {ResolvedConfig} from "../config";
 
 type Failure = {video: string; message: string};
 
-type FrameReport = {overflow: string[]; small: string[]; empty: boolean; painted: number};
+type FrameReport = {overflow: string[]; small: string[]; empty: boolean; painted: number; faded: number};
 
 /**
  * A fingerprint of every canvas on the frame.
@@ -92,12 +92,13 @@ type CanvasReport = Array<{index: number; hash: string; blank: boolean; gl?: boo
  */
 const FRAME_SCRIPT = `(() => {
   var root = document.querySelector("[data-odori-video]");
-  if (!root) return {overflow: [], small: [], empty: true, painted: 0};
+  if (!root) return {overflow: [], small: [], empty: true, painted: 0, faded: 0};
 
   var bounds = root.getBoundingClientRect();
   var overflow = [];
   var small = [];
   var painted = 0;
+  var faded = 0;
   var nodes = Array.prototype.slice.call(root.querySelectorAll("*"));
 
   for (var index = 0; index < nodes.length; index += 1) {
@@ -110,7 +111,22 @@ const FRAME_SCRIPT = `(() => {
     var box = node.getBoundingClientRect();
     if (box.width === 0 || box.height === 0) continue;
     var style = getComputedStyle(node);
-    if (style.visibility === "hidden" || Number(style.opacity) < 0.02) continue;
+    if (style.visibility === "hidden") continue;
+    /* Opacity inherits down the tree in effect even though it does not
+       inherit as a property: a parent faded to nothing takes its children
+       with it, while each child still computes its own opacity as 1. Reading
+       one node's value therefore judges text nobody can see. A scene that has
+       faded out is the common case, and it was reporting its hidden dialogue
+       as unreadable. */
+    var effective = 1;
+    for (var up = node; up && up !== root.parentElement; up = up.parentElement) {
+      effective *= Number(getComputedStyle(up).opacity);
+      if (effective < 0.02) break;
+    }
+    if (effective < 0.02) {
+      faded += 1;
+      continue;
+    }
     painted += 1;
 
     var media = ["IMG", "SVG", "CANVAS", "VIDEO"].indexOf(node.tagName) >= 0;
@@ -135,12 +151,27 @@ const FRAME_SCRIPT = `(() => {
      * content the video is actually about, which is what stays checked.
      */
     var chrome = node.closest("[data-odori-chrome]") !== null;
-    if (
-      box.right > bounds.right + 1 ||
-      box.left < bounds.left - 1 ||
-      box.bottom > bounds.bottom + 1 ||
-      box.top < bounds.top - 1
-    ) {
+
+    /*
+     * Crossing the frame edge is not a fault. Film bleeds: a surface runs past
+     * the corner, a push-in takes a headline wider than the shot, a full-frame
+     * image is cropped rather than letterboxed. The old rule flagged any box
+     * that crossed by a pixel, which is a rule about a document, not about a
+     * cut, and the only reason the recreations passed it is that five sampled
+     * frames happened to miss their own bleeds.
+     *
+     * What is worth reporting is content with no intersection at all: nothing
+     * of it is on screen at the frame that was sampled, which is what a layout
+     * mistake looks like. Deliberate overscan does that too, and says so with
+     * data-odori-bleed.
+     */
+    var bleed = node.closest("[data-odori-bleed]") !== null;
+    var offCanvas =
+      box.right <= bounds.left ||
+      box.left >= bounds.right ||
+      box.bottom <= bounds.top ||
+      box.top >= bounds.bottom;
+    if (offCanvas && !bleed) {
       if (overflow.indexOf(label) < 0) overflow.push(label);
     }
 
@@ -164,7 +195,7 @@ const FRAME_SCRIPT = `(() => {
     }
   }
 
-  return {overflow: overflow.slice(0, 5), small: small.slice(0, 5), empty: false, painted: painted};
+  return {overflow: overflow.slice(0, 5), small: small.slice(0, 5), empty: false, painted: painted, faded: faded};
 })()`;
 
 /**
@@ -186,7 +217,7 @@ const testVideo = async (
     if (!result.success) failures.push({video: id, message: `defaultProps fail the schema: ${result.issues.join("; ")}`});
   }
 
-  const {browser, page} = await openRenderPage(origin, targetFor(video), config);
+  const {browser, page, errors} = await openRenderPage(origin, targetFor(video), config);
   try {
     const timeline = await readTimeline(page);
     // The track is compiled by the same pass the player and the encoder read,
@@ -206,16 +237,24 @@ const testVideo = async (
 
     const samples = [0, Math.floor(total / 4), Math.floor(total / 2), Math.floor((total * 3) / 4), total - 1];
     for (const frame of [...new Set(samples)]) {
-      await seekTo(page, frame);
+      await seekTo(page, frame, errors);
       const result = (await page.evaluate(FRAME_SCRIPT)) as FrameReport;
       if (result.empty) failures.push({video: id, message: `Frame ${frame} rendered no video root.`});
-      if (!result.empty && result.painted < 2) {
+      /*
+       * A scene's fade envelope drives its first and last frame to zero
+       * opacity, so those two frames are blank on purpose in every video that
+       * does not opt out with transition="cut". What separates that from the
+       * failure worth reporting is whether anything was there to fade: a frame
+       * holding a faded-out tree drew its picture and dimmed it, while a frame
+       * holding nothing at all never built one.
+       */
+      if (!result.empty && result.painted < 2 && result.faded < 2) {
         failures.push({video: id, message: `Frame ${frame} is blank.`});
       }
       for (const item of result.overflow) {
         failures.push({
           video: id,
-          message: `Frame ${frame}: ${item} escapes the ${layout.format.width}x${layout.format.height} canvas.`,
+          message: `Frame ${frame}: ${item} is entirely outside the ${layout.format.width}x${layout.format.height} canvas.`,
         });
       }
       for (const item of result.small) {
@@ -230,8 +269,8 @@ const testVideo = async (
       if (canvases.length > 0) {
         // Seek away and back, so the second read is a real re-render rather
         // than a second look at the same paint.
-        await seekTo(page, frame === 0 ? Math.min(total - 1, frame + 1) : frame - 1);
-        await seekTo(page, frame);
+        await seekTo(page, frame === 0 ? Math.min(total - 1, frame + 1) : frame - 1, errors);
+        await seekTo(page, frame, errors);
         const again = (await page.evaluate(CANVAS_SCRIPT)) as CanvasReport;
 
         for (const canvas of canvases) {

package/src/config.ts

@@ -44,6 +44,11 @@ export type OdoriConfig = {
   skipUnchangedFrames?: boolean;
   /** Reuse encoded chunks whose frames still look identical. Defaults to true. */
   cacheChunks?: boolean;
+  /**
+   * Default providers for `--generate`, by kind. The choice is committed like
+   * every other decision; the keys never are.
+   */
+  generation?: {music?: string};
 };
 
 export const defaultConfig: OdoriConfig = {

package/src/jobs.ts

@@ -5,7 +5,7 @@ import type {ExportJob, RenderManifest} from "odori";
 import type {ResolvedConfig} from "./config";
 
 /** How a job should be encoded, frozen with it so a retry cannot drift. */
-export type JobRender = {format?: string; quality?: string; scale?: number; preset?: string; audio?: boolean};
+export type JobRender = {format?: string; quality?: string; scale?: number; preset?: string; audio?: boolean; graphics?: string};
 
 export type JobRecord = {job: ExportJob; manifest: RenderManifest; output: string; render?: JobRender};
 

package/src/keystore.ts

@@ -0,0 +1,76 @@
+import {existsSync} from "node:fs";
+import {chmod, mkdir, readFile, rm, writeFile} from "node:fs/promises";
+import {homedir} from "node:os";
+import {dirname, join} from "node:path";
+
+/**
+ * Provider keys, stored per machine.
+ *
+ * A key is personal, not project property: it belongs next to the login in
+ * `~/.config`, never inside a repository where one .gitignore mistake ships
+ * it. The environment always wins over this file, so nothing changes for a
+ * shell or a CI runner that already sets the variable — the store is the
+ * fallback for the key typed once into Studio.
+ *
+ * The file is written 0600 and read whole. There is no listing of values
+ * anywhere: callers ask for one variable and get one answer, and the Studio
+ * endpoint that fronts this reports only whether a key exists, never what it
+ * is.
+ */
+const storePath = (): string =>
+  join(process.env.XDG_CONFIG_HOME || join(homedir(), ".config"), "odori", "keys.json");
+
+const readStore = async (): Promise<Record<string, string>> => {
+  const path = storePath();
+  if (!existsSync(path)) return {};
+  try {
+    const parsed: unknown = JSON.parse(await readFile(path, "utf8"));
+    if (typeof parsed !== "object" || parsed === null) return {};
+    return Object.fromEntries(Object.entries(parsed).filter(([, value]) => typeof value === "string")) as Record<
+      string,
+      string
+    >;
+  } catch {
+    // A corrupt store reads as empty rather than throwing: the recovery in
+    // either case is typing the key again, and a parse error should not take
+    // Studio down with it.
+    return {};
+  }
+};
+
+const writeStore = async (store: Record<string, string>): Promise<void> => {
+  const path = storePath();
+  if (Object.keys(store).length === 0) {
+    await rm(path, {force: true});
+    return;
+  }
+  await mkdir(dirname(path), {recursive: true, mode: 0o700});
+  await writeFile(path, JSON.stringify(store, null, 2) + "\n", {mode: 0o600});
+  // writeFile's mode only applies on creation; an existing file keeps its
+  // permissions, so they are asserted rather than assumed.
+  await chmod(path, 0o600);
+};
+
+/** The stored value for one variable, or nothing. Environment is the caller's job. */
+export const storedKey = async (variable: string): Promise<string | undefined> => (await readStore())[variable];
+
+export const setStoredKey = async (variable: string, value: string): Promise<void> => {
+  const store = await readStore();
+  store[variable] = value;
+  await writeStore(store);
+};
+
+export const clearStoredKey = async (variable: string): Promise<void> => {
+  const store = await readStore();
+  delete store[variable];
+  await writeStore(store);
+};
+
+/**
+ * Where a key would come from, for status displays. Never the key itself.
+ */
+export const keySource = async (variable: string): Promise<"environment" | "stored" | null> => {
+  if (process.env[variable]) return "environment";
+  if ((await readStore())[variable]) return "stored";
+  return null;
+};

package/src/providers.ts

@@ -0,0 +1,173 @@
+/**
+ * Generation providers.
+ *
+ * Generation is an authoring step, not a render step: a provider is called
+ * once, at the keyboard, and what it returns goes through the same prepare
+ * pass as a file from disk. The render never talks to any of this, which is
+ * how it stays deterministic while the way tracks are made keeps changing.
+ *
+ * Keys come from the environment and are never written to config: the user's
+ * key, the user's account, the user's output. Odori redistributes nothing.
+ */
+
+import {storedKey} from "./keystore";
+
+export type GeneratedAudio = {
+  bytes: Uint8Array;
+  /** File extension for the bytes, without the dot. */
+  extension: string;
+};
+
+export type MusicProvider = {
+  name: string;
+  /** Shown in Studio and `odori integrations`. */
+  title: string;
+  docsUrl: string;
+  /** The environment variable the key is read from. */
+  keyVariable: string;
+  generate(options: {prompt: string; seconds: number; apiKey: string}): Promise<GeneratedAudio>;
+  /**
+   * Whether a key is currently accepted, asked cheaply. Distinguishes a wrong
+   * key (false) from an unreachable provider (thrown), because Studio should
+   * refuse to store the first and shrug at the second.
+   */
+  verifyKey(apiKey: string): Promise<boolean>;
+};
+
+const elevenlabs: MusicProvider = {
+  name: "elevenlabs",
+  title: "ElevenLabs Music",
+  docsUrl: "https://elevenlabs.io/docs/api-reference/music",
+  keyVariable: "ELEVENLABS_API_KEY",
+  async verifyKey(apiKey) {
+    const response = await fetch("https://api.elevenlabs.io/v1/user", {
+      headers: {"xi-api-key": apiKey},
+      signal: AbortSignal.timeout(10_000),
+    });
+    if (response.ok) return true;
+    if (response.status === 401 || response.status === 403) return false;
+    throw new Error(`ElevenLabs answered ${response.status} to a key check.`);
+  },
+  async generate({prompt, seconds, apiKey}) {
+    const response = await fetch("https://api.elevenlabs.io/v1/music", {
+      method: "POST",
+      headers: {"xi-api-key": apiKey, "content-type": "application/json"},
+      body: JSON.stringify({prompt, music_length_ms: Math.round(seconds * 1000)}),
+      signal: AbortSignal.timeout(300_000),
+    });
+    if (!response.ok) {
+      const detail = await response.text().catch(() => "");
+      throw new Error(
+        `ElevenLabs returned ${response.status} ${response.statusText}.` +
+          (detail ? `\n${detail.slice(0, 400)}` : "") +
+          (response.status === 401 ? `\nIs ${elevenlabs.keyVariable} a current key?` : ""),
+      );
+    }
+    const type = response.headers.get("content-type") ?? "";
+    const extension = type.includes("wav") ? "wav" : type.includes("mp4") ? "m4a" : "mp3";
+    return {bytes: new Uint8Array(await response.arrayBuffer()), extension};
+  },
+};
+
+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 => {
+  const provider = musicProviders[name];
+  if (!provider) {
+    throw new Error(
+      `No music provider named "${name}". Available: ${Object.keys(musicProviders).join(", ")}.`,
+    );
+  }
+  return provider;
+};
+
+/**
+ * The key for a provider: the environment first, then the machine store the
+ * 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: {keyVariable: string}): Promise<string | undefined> =>
+  process.env[provider.keyVariable] ?? (await storedKey(provider.keyVariable));