@odori/cli 0.0.6 → 0.0.8

package/src/cli.ts

@@ -7,9 +7,11 @@ import {doctorCommand} from "./commands/doctor";
 import {installCommand} from "./binaries";
 import {exportCommand, jobsCommand} from "./commands/exportVideo";
 import {initCommand} from "./commands/init";
+import {integrationsCommand} from "./commands/integrations";
 import {inspectCommand} from "./commands/inspect";
 import {listCommand} from "./commands/list";
 import {newCommand} from "./commands/new";
+import {bedCommand} from "./commands/bed";
 import {frameCommand} from "./commands/frame";
 import {testCommand} from "./commands/test";
 
@@ -23,7 +25,7 @@ type Flags = Record<string, string | boolean>;
  * vanishes from the list, which is two failures for the price of one and
  * neither of them says anything. A switch has no value to take.
  */
-const BOOLEAN_FLAGS = new Set(["force", "dry-run", "json", "no-audio", "no-frame-skip", "no-open", "open", "help", "version"]);
+const BOOLEAN_FLAGS = new Set(["force", "dry-run", "json", "no-audio", "fast", "no-frame-skip", "no-open", "open", "help", "version"]);
 
 /** Commands that used to exist under another name. */
 const RENAMED: Record<string, string> = {still: "frame"};
@@ -93,13 +95,15 @@ const COMMAND_FLAGS: Record<string, string[]> = {
   new: ["blank"],
   add: ["force", "dry-run"],
   registry: [],
+  integrations: [],
   diff: ["full"],
   update: ["force"],
   list: [],
   inspect: ["json", "input"],
   frame: ["at", "output", "input"],
+  bed: ["role", "output", "target", "generate", "provider", "seconds"],
   test: ["json"],
-  export: ["output", "input", "concurrency", "preset", "format", "quality", "scale", "no-audio", "no-frame-skip", "retry"],
+  export: ["output", "input", "concurrency", "preset", "format", "quality", "scale", "no-audio", "fast", "no-frame-skip", "retry"],
   jobs: [],
   help: [],
 };
@@ -151,6 +155,16 @@ const USAGE: Record<string, string> = {
   Discover project resources and start Studio.`,
   init: `odori init
   Add videos/ and odori.config.ts to a project.`,
+  bed: `odori bed <file> [--role <name>] [--target <lufs>] [--output <path>]
+  Prepare an audio file to sit under a video: measure it, level it to the stem
+  target every other bed is prepared to, and write it where audio is served.
+  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.`,
+  integrations: `odori integrations
+  List generation providers and whether each is connected. Configuration
+  lives in the environment or Studio's integrations page; generation happens
+  in task commands like "odori bed --generate".`,
   doctor: `odori doctor
   Check Node, React, the source root, Chrome, FFmpeg, and the generated cache.`,
   install: `odori install
@@ -181,11 +195,15 @@ const USAGE: Record<string, string> = {
   check, for CI.`,
   export: `odori export <id> [--output <path>] [--input <json>] [--concurrency <n>]
              [--preset <name>] [--format <name>] [--quality <tier>] [--scale <n>]
-             [--no-audio] [--no-frame-skip] [--retry <job>]
+             [--no-audio] [--fast] [--no-frame-skip] [--retry <job>]
   Render and encode a distributable file. --format is mp4, webm, prores, gif,
   or png; without it the output's extension decides, and mp4 is the default.
   --quality is studio, social, or web. --scale multiplies the output size,
-  0.25 to 2. --no-audio writes the picture with no sound. A retry keeps the
+  0.25 to 2. --no-audio writes the picture with no sound.
+  --fast draws on this machine's GPU rather than the reproducible software
+  backend. Measured here: about five percent on ordinary post-processing, and
+  fourteen times on a shader that is genuinely per-pixel expensive. The pixels
+  it makes belong to this machine, so keep it for iterating. A retry keeps the
   settings its job was created with.`,
   jobs: `odori jobs
   List export jobs and their status.`,
@@ -270,6 +288,9 @@ export const run = async (argv: string[]): Promise<number> => {
       case "init":
         await initCommand();
         return 0;
+      case "integrations":
+        await integrationsCommand();
+        return 0;
       case "doctor":
         return await doctorCommand();
       case "install":
@@ -295,6 +316,17 @@ export const run = async (argv: string[]): Promise<number> => {
       case "inspect":
         await inspectCommand(positionals[0] ?? "", {json: flags.json === true, input: parseInput(flags)});
         return 0;
+      case "bed":
+        if (!positionals[0]) throw new Error('Which file? "odori bed ./track.mp3".');
+        await bedCommand(positionals[0], {
+          role: typeof flags.role === "string" ? flags.role : undefined,
+          output: typeof flags.output === "string" ? flags.output : undefined,
+          target: numberFlag(flags, "target"),
+          generate: flags.generate === true,
+          provider: typeof flags.provider === "string" ? flags.provider : undefined,
+          seconds: numberFlag(flags, "seconds"),
+        });
+        return 0;
       case "frame":
         await frameCommand(positionals[0] ?? "", {
           // A duration, so "4s" and "120f" both work; a bare number is
@@ -317,6 +349,7 @@ export const run = async (argv: string[]): Promise<number> => {
           scale: numberFlag(flags, "scale"),
           format: typeof flags.format === "string" ? flags.format : undefined,
           audio: flags["no-audio"] === true ? false : undefined,
+          fast: flags.fast === true,
           skipUnchangedFrames: flags["no-frame-skip"] === true ? false : undefined,
           retry: typeof flags.retry === "string" ? flags.retry : undefined,
         });

package/src/commands/bed.ts

@@ -0,0 +1,224 @@
+import {spawn} from "node:child_process";
+import {mkdir, stat, writeFile} from "node:fs/promises";
+import {basename, dirname, extname, join, relative, resolve} from "node:path";
+import {log} from "../log";
+import {loadConfig, type ResolvedConfig} from "../config";
+import {ffmpegExecutable} from "../render";
+import {registerCueInBrand} from "../brand-file";
+import {resolveKey, resolveMusicProvider} from "../providers";
+
+/**
+ * The level a bed is prepared to.
+ *
+ * Not the level it is delivered at: a mix is normalised to the brand's target
+ * on the way out, around -14 LUFS. A bed sits under that, and the six decibels
+ * between the two are where the cues and any narration live. Preparing every
+ * bed to the same number is what makes them interchangeable — swap one for
+ * another and the video does not re-mix itself.
+ */
+const STEM_LUFS = -20;
+
+/** Below full scale, so nothing clips after the encoder resamples it. */
+const STEM_PEAK = -1.5;
+
+type Measured = {input_i: string; input_tp: string; input_lra: string; input_thresh: string};
+
+export type BedOptions = {
+  role?: string;
+  output?: string;
+  target?: number;
+  generate?: boolean;
+  provider?: string;
+  seconds?: number;
+};
+
+/** What preparing a bed did, for the CLI to print and Studio to render. */
+export type BedReport = {
+  source: string;
+  destination: string;
+  role: string;
+  /** Servable path when the file landed under public/, or nothing. */
+  url: string | null;
+  registered: {file: string; already: boolean} | null;
+  before: {lufs: number; peak: number; range: number};
+  after: {lufs: number; peak: number};
+  bytes: number;
+  warnings: string[];
+};
+
+const run = (command: string, args: string[]) =>
+  new Promise<string>((resolveRun, rejectRun) => {
+    const child = spawn(command, args, {stdio: ["ignore", "ignore", "pipe"]});
+    let stderr = "";
+    child.stderr?.on("data", (chunk: Buffer) => {
+      stderr += chunk.toString();
+    });
+    child.on("error", rejectRun);
+    child.on("exit", (code) => {
+      if (code === 0) resolveRun(stderr);
+      else rejectRun(new Error(`ffmpeg exited with ${code}: ${stderr.slice(-800)}`));
+    });
+  });
+
+/**
+ * What the file measures now.
+ *
+ * loudnorm reports its analysis as JSON on stderr, and the second pass needs
+ * those exact numbers: given them it corrects linearly, applying one gain to
+ * the whole file. Without them it works a window at a time and moves quiet
+ * passages relative to loud ones, which is a mastering decision nobody asked
+ * it to make.
+ */
+const measure = async (ffmpeg: string, file: string): Promise<Measured> => {
+  const stderr = await run(ffmpeg, [
+    "-i", file,
+    "-af", `loudnorm=I=${STEM_LUFS}:TP=${STEM_PEAK}:print_format=json`,
+    "-f", "null", "-",
+  ]);
+  const start = stderr.lastIndexOf("{");
+  const end = stderr.lastIndexOf("}");
+  if (start === -1 || end === -1) throw new Error(`Could not read loudness from ${basename(file)}.`);
+  return JSON.parse(stderr.slice(start, end + 1)) as Measured;
+};
+
+const round = (value: string | number) => Number(value).toFixed(1);
+
+/**
+ * Ask a provider for a track and land it next to the file it becomes.
+ *
+ * The raw answer is kept beside the prepared output, extension and all,
+ * because it is the one copy of the generation that exists: the provider will
+ * not produce it again, and re-preparing to a different target later needs
+ * the original, not the levelled encode.
+ */
+const generateSource = async (config: ResolvedConfig, prompt: string, options: BedOptions): Promise<string> => {
+  const provider = resolveMusicProvider(options.provider ?? config.generation?.music ?? "elevenlabs");
+  const apiKey = await resolveKey(provider);
+  if (!apiKey) {
+    throw new Error(
+      `Generating with ${provider.name} needs a key: set ${provider.keyVariable} in the environment,\n` +
+        'or paste one once into Studio\u2019s integrations page ("odori dev", then Integrations).\n' +
+        "Either way it is sent only to the provider and never stored in the project.",
+    );
+  }
+
+  const seconds = options.seconds ?? 60;
+  log.detail(`Generating ${seconds}s with ${provider.name}`);
+  const {bytes, extension} = await provider.generate({prompt, seconds, apiKey});
+
+  const stem = options.output
+    ? basename(options.output, extname(options.output))
+    : prompt.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 40) || "generated";
+  const directory = options.output ? dirname(resolve(config.root, options.output)) : join(config.root, "public", "audio");
+  await mkdir(directory, {recursive: true});
+  const source = join(directory, `${stem}-source.${extension}`);
+  await writeFile(source, bytes);
+  log.detail(`  kept the original at ${basename(source)} (${(bytes.length / 1024).toFixed(0)} KB)`);
+  return source;
+};
+
+/**
+ * Prepare an audio file to sit under a video, and wire it to its role.
+ *
+ * The one job is levelling, because that is what was wrong: a library whose
+ * beds ranged over eight decibels meant choosing a bed and choosing a mix were
+ * the same act. Everything here is measurement and one correction, so the file
+ * that comes out is the file that went in at a known level. When the result
+ * lands under public/ the role is registered in the brand too, the same way
+ * `odori add` registers an installed asset, so the name works immediately.
+ */
+export const prepareBed = async (config: ResolvedConfig, input: string, options: BedOptions = {}): Promise<BedReport> => {
+  // With --generate the positional is a prompt, not a path: a provider is
+  // called once, here at author time, and its answer becomes the source file
+  // the rest of this command has always started from. The render never knows.
+  const source = options.generate ? await generateSource(config, input, options) : resolve(config.root, input);
+  if (!options.generate) {
+    await stat(source).catch(() => {
+      throw new Error(`No file at ${input}.`);
+    });
+  }
+
+  const ffmpeg = await ffmpegExecutable(config);
+  const target = options.target ?? STEM_LUFS;
+
+  // A generated original keeps a -source suffix; the prepared file drops it.
+  const name = basename(source, extname(source)).replace(/-source$/, "");
+  const destination = options.output
+    ? resolve(config.root, options.output)
+    : join(config.root, "public", "audio", `${name}.m4a`);
+  await mkdir(dirname(destination), {recursive: true});
+
+  log.detail(`Measuring ${basename(source)}`);
+  const measured = await measure(ffmpeg, source);
+
+  await run(ffmpeg, [
+    "-y", "-i", source,
+    "-af",
+    `loudnorm=I=${target}:TP=${STEM_PEAK}` +
+      `:measured_I=${measured.input_i}:measured_TP=${measured.input_tp}` +
+      `:measured_LRA=${measured.input_lra}:measured_thresh=${measured.input_thresh}` +
+      `:linear=true`,
+    "-c:a", "aac", "-b:a", "192k",
+    destination,
+  ]);
+
+  const after = await measure(ffmpeg, destination);
+  const bytes = (await stat(destination)).size;
+
+  const before = {lufs: Number(measured.input_i), peak: Number(measured.input_tp), range: Number(measured.input_lra)};
+  const warnings: string[] = [];
+  /* The range is the one number this cannot fix. It is a property of the
+     recording, and a bed with none of it has nowhere to go under a cut. */
+  if (before.range < 4) {
+    warnings.push(
+      `A range of ${round(before.range)} LU is very compressed. Mastered music sits around 5 to 8, ` +
+        "and film score higher. Levelling cannot restore range a recording does not have; " +
+        "this bed will sit flat under the cut.",
+    );
+  }
+  if (before.peak > 0) {
+    warnings.push(`The source peaked at ${round(before.peak)} dBTP, which is above full scale.`);
+  }
+
+  const role = options.role ?? `bed.${name.replace(/^bed[-.]?/, "") || "main"}`;
+
+  // Registration needs a URL, and a URL needs the file to be servable: only a
+  // destination under public/ has one. Anywhere else the caller chose a path
+  // on purpose and gets the report instead.
+  const publicDir = join(config.root, "public");
+  const relativeToPublic = relative(publicDir, destination);
+  const url = relativeToPublic.startsWith("..") ? null : "/" + relativeToPublic.split("\\").join("/");
+  const registered = url ? await registerCueInBrand(config, {name: role, url}, name) : null;
+
+  return {source, destination, role, url, registered, before, after: {lufs: Number(after.input_i), peak: Number(after.input_tp)}, bytes, warnings};
+};
+
+export const bedCommand = async (input: string, options: BedOptions = {}) => {
+  const config = await loadConfig(process.cwd());
+  const report = await prepareBed(config, input, options);
+
+  log.info(`Prepared ${basename(report.destination)}`);
+  log.detail(`  loudness  ${round(report.before.lufs)} → ${round(report.after.lufs)} LUFS`);
+  log.detail(`  peak      ${round(report.before.peak)} → ${round(report.after.peak)} dBTP`);
+  log.detail(`  range     ${round(report.before.range)} LU`);
+  log.detail(`  size      ${(report.bytes / 1024).toFixed(0)} KB`);
+
+  for (const warning of report.warnings) {
+    log.detail("");
+    log.detail(`  ${warning}`);
+  }
+
+  log.detail("");
+  if (report.registered?.already) {
+    log.detail(`  "${report.role}" is already registered in ${report.registered.file}`);
+  } else if (report.registered) {
+    log.detail(`  registered "${report.role}" in ${report.registered.file}`);
+  } else if (report.url) {
+    log.detail("  No brand with an audio cues block was found. Register it by hand:");
+    log.detail(`    audio: {cues: {"${report.role}": "${report.url}"}}`);
+  } else {
+    log.detail("  The output is outside public/, so it cannot be registered or served.");
+  }
+  log.detail("  Place it in a video:");
+  log.detail(`    <Audio src="${report.role}" fadeIn="1s" fadeOut="1.5s" duckUnder />`);
+};

package/src/commands/dev.ts

@@ -4,6 +4,9 @@ import {existsSync} from "node:fs";
 import {readFile} from "node:fs/promises";
 import type {IncomingMessage, ServerResponse} from "node:http";
 import {loadConfig} from "../config";
+import {clearStoredKey, keySource, setStoredKey} from "../keystore";
+import {musicProviders} from "../providers";
+import {prepareBed} from "./bed";
 import {log} from "../log";
 import {createJob, listJobs, readJob} from "../jobs";
 import {discoverProject} from "../discovery";
@@ -238,6 +241,83 @@ export const devCommand = async (options: {port?: number; root?: string; open?:
               return;
             }
 
+            if (request.method === "POST" && url.startsWith("/generate")) {
+              const body = await readBody(request);
+              const prompt = typeof body.prompt === "string" ? body.prompt.trim() : "";
+              if (!prompt) {
+                json(response, 400, {error: "A prompt is required."});
+                return;
+              }
+              // The same path the CLI walks: provider, prepare, register. The
+              // report comes back whole so Studio can show the numbers the
+              // terminal would have printed.
+              const report = await prepareBed(config, prompt, {
+                generate: true,
+                seconds: typeof body.seconds === "number" ? Math.min(300, Math.max(5, body.seconds)) : undefined,
+                role: typeof body.role === "string" && body.role.trim() ? body.role.trim() : undefined,
+                provider: typeof body.provider === "string" ? body.provider : undefined,
+              });
+              json(response, 200, {
+                ...report,
+                source: relative(config.root, report.source),
+                destination: relative(config.root, report.destination),
+              });
+              return;
+            }
+
+            if (url === "/integrations" || url === "/integrations/") {
+              // Status only, and only booleans: which providers exist, whether
+              // each has a key, and where it came from. The value itself has
+              // no read path over HTTP, in either direction.
+              if (request.method === "GET") {
+                const providers = await Promise.all(
+                  Object.values(musicProviders).map(async (provider) => ({
+                    name: provider.name,
+                    title: provider.title,
+                    kind: "music",
+                    keyVariable: provider.keyVariable,
+                    docsUrl: provider.docsUrl,
+                    source: await keySource(provider.keyVariable),
+                  })),
+                );
+                json(response, 200, {providers});
+                return;
+              }
+              if (request.method === "POST") {
+                const body = await readBody(request);
+                const provider = musicProviders[String(body.provider ?? "")];
+                if (!provider) {
+                  json(response, 400, {error: `No provider named ${JSON.stringify(body.provider)}.`});
+                  return;
+                }
+                const key = typeof body.key === "string" ? body.key.trim() : "";
+                if (!key) {
+                  // An empty key is the clear action, so removing a key is the
+                  // same gesture as setting one.
+                  await clearStoredKey(provider.keyVariable);
+                  json(response, 200, {source: await keySource(provider.keyVariable), verified: null});
+                  return;
+                }
+                // A key that the provider rejects outright is not stored: a
+                // stored bad key fails later, at generation, where the person
+                // who typed it may be long gone. An unreachable provider is
+                // not the same thing, so that key is kept and said so.
+                let verified: boolean | null = null;
+                try {
+                  verified = await provider.verifyKey(key);
+                } catch {
+                  verified = null;
+                }
+                if (verified === false) {
+                  json(response, 400, {error: `${provider.title} rejected that key.`});
+                  return;
+                }
+                await setStoredKey(provider.keyVariable, key);
+                json(response, 200, {source: await keySource(provider.keyVariable), verified});
+                return;
+              }
+            }
+
             if (request.method === "GET" && url.startsWith("/jobs")) {
               json(response, 200, await listJobs(config));
               return;

package/src/commands/doctor.ts

@@ -4,6 +4,8 @@ import {existsSync} from "node:fs";
 import {createRequire} from "node:module";
 import {relative, resolve} from "node:path";
 import {loadConfig} from "../config";
+import {keySource} from "../keystore";
+import {musicProviders} from "../providers";
 import {CHROME_BUILD, cacheRoot, resolveBrowser, resolveFfmpeg} from "../binaries";
 import {log} from "../log";
 
@@ -165,6 +167,24 @@ export const runChecks = async (root: string): Promise<Check[]> => {
     fix: `Add a sibling <name>.preview.tsx with defineComponentPreview so Studio can play it on its own. A component with no fixture only ever renders inside a video.`,
   });
 
+  // A missing provider key is not a broken project — generation is optional —
+  // but doctor is exactly where "why does --generate fail" gets answered.
+  for (const provider of Object.values(musicProviders)) {
+    const source = await keySource(provider.keyVariable);
+    checks.push({
+      name: `Provider: ${provider.name}`,
+      detail:
+        source === "environment"
+          ? `connected (${provider.keyVariable})`
+          : source === "stored"
+            ? "connected (key stored on this machine)"
+            : "not configured",
+      ok: true,
+      warn: source === null,
+      fix: `Optional. To generate with ${provider.title}: set ${provider.keyVariable}, or paste a key in Studio's integrations page.`,
+    });
+  }
+
   checks.push({
     name: "Generated cache",
     detail: writable ? ".odori/ is writable" : ".odori/ cannot be written",

package/src/commands/exportVideo.ts

@@ -2,6 +2,7 @@ import {resolve} from "node:path";
 import {resolveEntryLayout, type ExportJob} from "odori";
 import type {ResolvedConfig} from "../config";
 import {log} from "../log";
+import type {Graphics} from "../render";
 import {JobQueue, appendJobLog, createJob, listJobs, readJob, updateJob, type JobRecord} from "../jobs";
 import {findVideo, freezeManifest, outputName, type LoadedVideo} from "../project";
 import {resolveFormat, QUALITIES, type Quality, type VideoFormat} from "../formats";
@@ -37,6 +38,7 @@ export const runJob = async (
     scale?: number;
     format?: VideoFormat;
     audio?: boolean;
+    graphics?: Graphics;
     skipUnchangedFrames?: boolean;
     signal?: AbortSignal;
     onProgress?: (job: ExportJob) => void;
@@ -96,6 +98,7 @@ export const runJob = async (
           scale: options.scale ?? record.render?.scale,
           format: options.format ?? (record.render?.format ? resolveFormat(record.render.format, record.output) : undefined),
           audio: options.audio ?? record.render?.audio,
+          graphics: options.graphics ?? (record.render?.graphics as Graphics | undefined),
           skipUnchangedFrames: options.skipUnchangedFrames,
           signal: controller.signal,
           onTimings: (timings) => {
@@ -155,6 +158,8 @@ export const exportCommand = async (
     format?: string;
     /** False writes the picture with no audio track. */
     audio?: boolean;
+    /** True draws on the machine's GPU instead of the reproducible backend. */
+    fast?: boolean;
     skipUnchangedFrames?: boolean;
     retry?: string;
   } = {},
@@ -188,12 +193,21 @@ export const exportCommand = async (
             quality,
             scale,
             audio: options.audio !== false,
+            graphics: options.fast ? "gpu" : "software",
             ...(options.preset ? {preset: options.preset} : {}),
           });
         })();
 
     const video = findVideo(videos, record.manifest.videoId);
     log.detail(`job ${record.job.id} manifest ${record.manifest.manifestHash}`);
+    /* Said every time, not only when it is unusual. A file that came out
+       different should never leave you guessing which of the two drew it. */
+    const backend = options.fast ? "gpu" : (record.render?.graphics ?? "software");
+    log.detail(
+      backend === "gpu"
+        ? "graphics: this machine's GPU. Faster, and the pixels are specific to it."
+        : "graphics: software, reproducible on any machine",
+    );
     if (options.retry) log.detail(`retrying attempt ${record.job.attempts + 1} from the frozen manifest`);
     if (record.manifest.audio.length > 0) {
       log.detail(`${record.manifest.audio.length} audio cue(s) at ${record.manifest.format.durationInFrames} frames`);
@@ -207,6 +221,7 @@ export const exportCommand = async (
       scale: options.retry && options.scale === undefined ? undefined : scale,
       format: options.retry ? undefined : format,
       audio: options.audio,
+      graphics: options.fast ? "gpu" : undefined,
       skipUnchangedFrames: options.skipUnchangedFrames,
       onProgress: (next) => {
         if (next.status === "rendering" || next.status === "encoding") {

package/src/commands/integrations.ts

@@ -0,0 +1,26 @@
+import {log} from "../log";
+import {keySource} from "../keystore";
+import {musicProviders} from "../providers";
+
+/**
+ * The directory of generation providers: what exists, what is connected, and
+ * where each key would come from. Read-only on purpose — the work happens in
+ * task commands like `odori bed --generate`, and configuration happens where
+ * keys live: the environment, or Studio's integrations page.
+ */
+export const integrationsCommand = async () => {
+  log.title("Integrations");
+  for (const provider of Object.values(musicProviders)) {
+    const source = await keySource(provider.keyVariable);
+    const status =
+      source === "environment"
+        ? `connected (${provider.keyVariable})`
+        : source === "stored"
+          ? "connected (stored on this machine)"
+          : `not configured — set ${provider.keyVariable}, or paste a key in Studio`;
+    log.info(`  ${provider.name.padEnd(14)} music  ${status}`);
+  }
+  log.detail("");
+  log.detail('  Generate through a task command: odori bed "warm ambient, no drums" --generate');
+  log.detail("  Keys are read from the environment first, then ~/.config/odori. Never the project.");
+};