@odori/cli 0.0.6 → 0.0.8

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.
@@ -35,15 +35,36 @@ const CANVAS_SCRIPT = `(() => {
   });
 
   return canvases.map(function (canvas, index) {
-    var context = canvas.getContext("2d");
-    if (!context || canvas.width === 0 || canvas.height === 0) {
+    if (canvas.width === 0 || canvas.height === 0) {
       return {index: index, hash: "no-context", blank: true};
     }
     var data;
-    try {
-      data = context.getImageData(0, 0, canvas.width, canvas.height).data;
-    } catch (error) {
-      return {index: index, hash: "tainted", blank: false};
+    var isGl = false;
+    var context = canvas.getContext("2d");
+    if (context) {
+      try {
+        data = context.getImageData(0, 0, canvas.width, canvas.height).data;
+      } catch (error) {
+        return {index: index, hash: "tainted", blank: false};
+      }
+    } else {
+      /*
+       * A canvas that already holds a GL context returns null for "2d", and
+       * reading that as an empty canvas reported every shader video as having
+       * drawn nothing while it was drawing correctly. Pixels come back through
+       * readPixels instead, which is the only way to see a GL surface.
+       *
+       * Worth knowing when this comes back empty: a drawing buffer is cleared
+       * once it has been composited unless the context was asked for with
+       * preserveDrawingBuffer, so an author who has not set that gets a real
+       * frame on screen and nothing here.
+       */
+      var gl = canvas.getContext("webgl2") || canvas.getContext("webgl");
+      if (!gl) return {index: index, hash: "no-context", blank: true};
+      var pixels4 = new Uint8Array(canvas.width * canvas.height * 4);
+      gl.readPixels(0, 0, canvas.width, canvas.height, gl.RGBA, gl.UNSIGNED_BYTE, pixels4);
+      data = pixels4;
+      isGl = true;
     }
 
     // A prime stride over the whole buffer rather than a coarse grid: a grid
@@ -59,11 +80,11 @@ const CANVAS_SCRIPT = `(() => {
       hash =
         ((hash << 5) + hash + data[offset] + data[offset + 1] * 3 + data[offset + 2] * 7 + data[offset + 3] * 11) | 0;
     }
-    return {index: index, hash: String(hash), blank: opaque === 0};
+    return {index: index, hash: String(hash), blank: opaque === 0, gl: isGl};
   });
 })()`;
 
-type CanvasReport = Array<{index: number; hash: string; blank: boolean}>;
+type CanvasReport = Array<{index: number; hash: string; blank: boolean; gl?: boolean}>;
 
 /**
  * Evaluated as source in the page so no bundler helpers leak into the browser.
@@ -71,20 +92,41 @@ type CanvasReport = Array<{index: number; hash: string; blank: boolean}>;
  */
 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) {
     var node = nodes[index];
+    /* The subtree an effect surface is photographing is deliberately parked
+       outside the frame. It is the input to a canvas, not something a viewer
+       ever sees, so judging its position or its type size is judging the
+       wrong thing. */
+    if (node.closest("[data-odori-capture]")) continue;
     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;
@@ -109,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);
     }
 
@@ -138,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};
 })()`;
 
 /**
@@ -160,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,
@@ -180,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) {
@@ -204,14 +269,19 @@ 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) {
           const second = again.find((item) => item.index === canvas.index);
           if (canvas.blank) {
-            failures.push({video: id, message: `Frame ${frame}: canvas ${canvas.index} drew nothing.`});
+            failures.push({
+            video: id,
+            message: canvas.gl
+              ? `Frame ${frame}: canvas ${canvas.index} read back empty. A WebGL drawing buffer is cleared once it has been composited, so ask for the context with {preserveDrawingBuffer: true}.`
+              : `Frame ${frame}: canvas ${canvas.index} drew nothing.`,
+          });
             continue;
           }
           if (canvas.hash === "tainted") {

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,90 @@
+/**
+ * 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 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: MusicProvider): Promise<string | undefined> =>
+  process.env[provider.keyVariable] ?? (await storedKey(provider.keyVariable));