@odori/cli 0.0.9 → 0.0.11

package/dist/{chunk-TDM65HRW.js → chunk-77R3UC27.js}

@@ -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 }) {
@@ -1019,6 +1023,13 @@ var registerCues = (brands, fps) => {
   }
   return known.size;
 };
+var registerVariantCues = (variants, fps) => {
+  for (const overrides of Object.values(variants ?? {})) {
+    for (const value of Object.values(overrides)) {
+      if (isCueDefinition(value)) known.set(cueUrl(value), { cue: value, fps });
+    }
+  }
+};
 var renderedCue = (url) => {
   const cached = rendered.get(url);
   if (cached) return cached;
@@ -1049,6 +1060,7 @@ var registerProjectCues = async (graph, load = importFresh) => {
       const entry = { component: module.default, metadata: module.metadata };
       const layout = resolveEntryLayout(entry);
       registerCues([layout.brand], layout.format.fps);
+      registerVariantCues(entry.metadata.audio?.variants, layout.format.fps);
     } catch (error) {
       log.warn(`[odori] generated cues in ${video.relativeFile} may use the default frame rate: ${message(error)}`);
     }
@@ -1361,6 +1373,7 @@ var renderUrl = (origin, target, frame) => {
   const params = new URLSearchParams({ render: "1", video: target.videoId, frame: String(frame) });
   if (target.input) params.set("input", encodeParam(target.input));
   if (target.prepared !== void 0) params.set("prepared", encodeParam(target.prepared));
+  if (target.audioVariant) params.set("audio", target.audioVariant);
   return `${origin}/?${params.toString()}`;
 };
 var DEFAULT_GRAPHICS = "software";
@@ -2753,10 +2766,11 @@ var createContext = async (root = process.cwd()) => {
     const layout = resolveEntryLayout3(video.entry);
     brands.set(layout.brand.name, layout.brand);
     registerCues([layout.brand], layout.format.fps);
+    registerVariantCues(video.entry.metadata.audio?.variants, layout.format.fps);
   }
   return { config, graph, videos };
 };
-var targetFor = (video, input, prepared, audio, scenes) => {
+var targetFor = (video, input, prepared, audio, scenes, audioVariant) => {
   const layout = resolveEntryLayout3(video.entry);
   return {
     videoId: video.entry.metadata.id,
@@ -2768,6 +2782,7 @@ var targetFor = (video, input, prepared, audio, scenes) => {
     prepared,
     audio,
     scenes,
+    audioVariant,
     targetLufs: layout.audio.targetLufs
   };
 };
@@ -2902,7 +2917,19 @@ var exportCommand = async (id, options = {}) => {
   return withServer(config, async (server) => {
     const record = options.retry ? await readJob(config, options.retry) : await (async () => {
       const video2 = findVideo(videos, id);
-      const compiled = await compileInBrowser(server.url, targetFor(video2, options.input), config);
+      if (options.audioVariant) {
+        const declared = Object.keys(video2.entry.metadata.audio?.variants ?? {});
+        if (!declared.includes(options.audioVariant)) {
+          throw new Error(
+            declared.length ? `No audio variant named "${options.audioVariant}". Declared: ${declared.join(", ")}.` : `"${id}" declares no audio variants; drop --audio-variant or add metadata.audio.variants.`
+          );
+        }
+      }
+      const compiled = await compileInBrowser(
+        server.url,
+        targetFor(video2, options.input, void 0, void 0, void 0, options.audioVariant),
+        config
+      );
       const { manifest } = await freezeManifest(
         { ...video2, durationInFrames: compiled.durationInFrames },
         graph,
@@ -2910,9 +2937,10 @@ var exportCommand = async (id, options = {}) => {
         options.input ?? {},
         { scenes: compiled.scenes, audio: compiled.audio }
       );
+      const suffix = options.audioVariant ? `-${options.audioVariant}` : "";
       const output = resolve19(
         config.root,
-        options.output ?? `${config.exportDir}/${outputName(id)}${format.extension}`
+        options.output ?? `${config.exportDir}/${outputName(id)}${suffix}${format.extension}`
       );
       return createJob(config, manifest, output, {
         format: format.name,
@@ -3074,7 +3102,12 @@ var devCommand = async (options = {}) => {
               const { graph, videos } = await context();
               const video = findVideo(videos, String(body.videoId));
               const input = body.input ?? {};
-              const compiled = await compileInBrowser(origin, targetFor(video, input), config);
+              const audioVariant = typeof body.audioVariant === "string" ? body.audioVariant : void 0;
+              const compiled = await compileInBrowser(
+                origin,
+                targetFor(video, input, void 0, void 0, void 0, audioVariant),
+                config
+              );
               const { manifest } = await freezeManifest(
                 { ...video, durationInFrames: compiled.durationInFrames },
                 graph,
@@ -4184,7 +4217,7 @@ var COMMAND_FLAGS = {
   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"],
+  export: ["output", "input", "concurrency", "preset", "format", "quality", "scale", "no-audio", "audio-variant", "fast", "no-frame-skip", "retry"],
   jobs: [],
   help: []
 };
@@ -4268,7 +4301,7 @@ var USAGE = {
   check, for CI.`,
   export: `odori export <id> [--output <path>] [--input <json>] [--concurrency <n>]
              [--preset <name>] [--format <name>] [--quality <tier>] [--scale <n>]
-             [--no-audio] [--fast] [--no-frame-skip] [--retry <job>]
+             [--no-audio] [--audio-variant <name>] [--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,
@@ -4424,6 +4457,7 @@ var run3 = async (argv) => {
           scale: numberFlag(flags, "scale"),
           format: typeof flags.format === "string" ? flags.format : void 0,
           audio: flags["no-audio"] === true ? false : void 0,
+          audioVariant: typeof flags["audio-variant"] === "string" ? flags["audio-variant"] : void 0,
           fast: flags.fast === true,
           skipUnchangedFrames: flags["no-frame-skip"] === true ? false : void 0,
           retry: typeof flags.retry === "string" ? flags.retry : void 0

package/dist/cli.js

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

package/dist/index.d.ts

@@ -251,6 +251,8 @@ type RenderTarget = {
     input?: Record<string, unknown>;
     prepared?: unknown;
     audio?: ManifestAudioCue[];
+    /** A declared audio variant's name, applied when the page compiles cues. */
+    audioVariant?: string;
     targetLufs?: number;
     scenes?: Array<{
         id: string;
@@ -360,7 +362,7 @@ declare const targetFor: (video: LoadedVideo, input?: Record<string, unknown>, p
     id: string;
     start: number;
     durationInFrames: number;
-}>) => RenderTarget;
+}>, audioVariant?: string) => RenderTarget;
 /**
  * `metadata.duration` is authoritative. When it is absent, the compiled
  * timeline reported by the runtime is used instead.
@@ -607,6 +609,8 @@ declare const exportCommand: (id: string, options?: {
     format?: string;
     /** False writes the picture with no audio track. */
     audio?: boolean;
+    /** A declared audio variant to voice this export with. */
+    audioVariant?: string;
     /** True draws on the machine's GPU instead of the reproducible backend. */
     fast?: boolean;
     skipUnchangedFrames?: boolean;

package/dist/index.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@odori/cli",
-  "version": "0.0.9",
+  "version": "0.0.11",
   "type": "module",
   "description": "The odori command line: discovery, Studio, component installation, stills, tests, and export jobs.",
   "license": "Apache-2.0",
@@ -8,10 +8,7 @@
     "odori": "./bin/odori.mjs"
   },
   "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
-    }
+    ".": "./src/index.ts"
   },
   "files": [
     "bin",
@@ -19,16 +16,23 @@
     "src",
     "studio"
   ],
+  "scripts": {
+    "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.studio.json",
+    "build": "tsup",
+    "snapshot": "tsx scripts/snapshot.ts",
+    "verify:package": "tsx scripts/verify-package.ts",
+    "prepack": "pnpm snapshot && pnpm build && pnpm verify:package"
+  },
   "dependencies": {
     "@puppeteer/browsers": "3.2.0",
     "@vitejs/plugin-react": "5.1.2",
     "ffmpeg-static": "5.3.0",
+    "odori": "workspace:*",
     "react": "19.2.3",
     "react-dom": "19.2.3",
     "playwright-core": "1.55.0",
     "tsx": "4.20.5",
-    "vite": "7.3.0",
-    "odori": "0.0.9"
+    "vite": "7.3.0"
   },
   "devDependencies": {
     "@types/node": "22.19.0",
@@ -36,15 +40,15 @@
     "@types/react-dom": "19.2.3",
     "tsup": "^8.5.1",
     "typescript": "5.9.3",
-    "@odori/registry": "0.0.8"
+    "@odori/registry": "workspace:*"
   },
   "publishConfig": {
-    "access": "public"
-  },
-  "scripts": {
-    "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.studio.json",
-    "build": "tsup",
-    "snapshot": "tsx scripts/snapshot.ts",
-    "verify:package": "tsx scripts/verify-package.ts"
+    "access": "public",
+    "exports": {
+      ".": {
+        "types": "./dist/index.d.ts",
+        "import": "./dist/index.js"
+      }
+    }
   }
-}
+}

package/src/cli.ts

@@ -105,7 +105,7 @@ const COMMAND_FLAGS: Record<string, string[]> = {
   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"],
+  export: ["output", "input", "concurrency", "preset", "format", "quality", "scale", "no-audio", "audio-variant", "fast", "no-frame-skip", "retry"],
   jobs: [],
   help: [],
 };
@@ -202,7 +202,7 @@ 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] [--fast] [--no-frame-skip] [--retry <job>]
+             [--no-audio] [--audio-variant <name>] [--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,
@@ -365,6 +365,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,
+          audioVariant: typeof flags["audio-variant"] === "string" ? flags["audio-variant"] : undefined,
           fast: flags.fast === true,
           skipUnchangedFrames: flags["no-frame-skip"] === true ? false : undefined,
           retry: typeof flags.retry === "string" ? flags.retry : undefined,

package/src/commands/dev.ts

@@ -165,7 +165,12 @@ export const devCommand = async (options: {port?: number; root?: string; open?:
               const {graph, videos} = await context();
               const video = findVideo(videos, String(body.videoId));
               const input = (body.input ?? {}) as Record<string, unknown>;
-              const compiled = await compileInBrowser(origin, targetFor(video, input), config);
+              const audioVariant = typeof body.audioVariant === "string" ? body.audioVariant : undefined;
+              const compiled = await compileInBrowser(
+                origin,
+                targetFor(video, input, undefined, undefined, undefined, audioVariant),
+                config,
+              );
               const {manifest} = await freezeManifest(
                 {...video, durationInFrames: compiled.durationInFrames},
                 graph,
@@ -309,6 +314,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/exportVideo.ts

@@ -158,6 +158,8 @@ export const exportCommand = async (
     format?: string;
     /** False writes the picture with no audio track. */
     audio?: boolean;
+    /** A declared audio variant to voice this export with. */
+    audioVariant?: string;
     /** True draws on the machine's GPU instead of the reproducible backend. */
     fast?: boolean;
     skipUnchangedFrames?: boolean;
@@ -176,7 +178,21 @@ export const exportCommand = async (
       ? await readJob(config, options.retry)
       : await (async () => {
           const video = findVideo(videos, id);
-          const compiled = await compileInBrowser(server.url, targetFor(video, options.input), config);
+          if (options.audioVariant) {
+            const declared = Object.keys(video.entry.metadata.audio?.variants ?? {});
+            if (!declared.includes(options.audioVariant)) {
+              throw new Error(
+                declared.length
+                  ? `No audio variant named "${options.audioVariant}". Declared: ${declared.join(", ")}.`
+                  : `"${id}" declares no audio variants; drop --audio-variant or add metadata.audio.variants.`,
+              );
+            }
+          }
+          const compiled = await compileInBrowser(
+            server.url,
+            targetFor(video, options.input, undefined, undefined, undefined, options.audioVariant),
+            config,
+          );
           const {manifest} = await freezeManifest(
             {...video, durationInFrames: compiled.durationInFrames},
             graph,
@@ -184,9 +200,12 @@ export const exportCommand = async (
             options.input ?? {},
             {scenes: compiled.scenes, audio: compiled.audio},
           );
+          // The variant names the file, so two voices cannot overwrite each
+          // other's exports.
+          const suffix = options.audioVariant ? `-${options.audioVariant}` : "";
           const output = resolve(
             config.root,
-            options.output ?? `${config.exportDir}/${outputName(id)}${format.extension}`,
+            options.output ?? `${config.exportDir}/${outputName(id)}${suffix}${format.extension}`,
           );
           return createJob(config, manifest, output, {
             format: format.name,

package/src/commands/shared.ts

@@ -1,6 +1,6 @@
 import {resolveEntryLayout, type AudioCue, type ManifestAudioCue, type Brand} from "odori";
 import {loadConfig, type ResolvedConfig} from "../config";
-import {registerCues} from "../cues";
+import {registerCues, registerVariantCues} from "../cues";
 import {discoverProject, type ProjectGraph} from "../discovery";
 import {loadVideos, type LoadedVideo} from "../project";
 import {openRenderPage, readAudio, readTimeline, type RenderTarget} from "../render";
@@ -19,6 +19,7 @@ export const createContext = async (root = process.cwd()): Promise<Context> => {
     const layout = resolveEntryLayout(video.entry);
     brands.set(layout.brand.name, layout.brand);
     registerCues([layout.brand], layout.format.fps);
+    registerVariantCues(video.entry.metadata.audio?.variants, layout.format.fps);
   }
   return {config, graph, videos};
 };
@@ -29,6 +30,7 @@ export const targetFor = (
   prepared?: unknown,
   audio?: ManifestAudioCue[],
   scenes?: Array<{id: string; start: number; durationInFrames: number}>,
+  audioVariant?: string,
 ): RenderTarget => {
   const layout = resolveEntryLayout(video.entry);
   return {
@@ -41,6 +43,7 @@ export const targetFor = (
     prepared,
     audio,
     scenes,
+    audioVariant,
     targetLufs: layout.audio.targetLufs,
   };
 };

package/src/cues.ts

@@ -80,6 +80,22 @@ export const registerCues = (brands: Brand[], fps: number): number => {
   return known.size;
 };
 
+/**
+ * Variant cues live on a video's metadata rather than on a brand, and a
+ * synthesized one still has to be answerable by URL: an audition that plays
+ * the default voice but 404s the alternatives is not an audition.
+ */
+export const registerVariantCues = (
+  variants: Record<string, Record<string, string | CueDefinition>> | undefined,
+  fps: number,
+): void => {
+  for (const overrides of Object.values(variants ?? {})) {
+    for (const value of Object.values(overrides)) {
+      if (isCueDefinition(value)) known.set(cueUrl(value), {cue: value, fps});
+    }
+  }
+};
+
 export const renderedCue = (url: string): Uint8Array | null => {
   const cached = rendered.get(url);
   if (cached) return cached;
@@ -143,6 +159,7 @@ export const registerProjectCues = async (graph: ProjectGraph, load: ModuleLoade
       const entry = {component: module.default, metadata: module.metadata} as VideoEntry;
       const layout = resolveEntryLayout(entry);
       registerCues([layout.brand], layout.format.fps);
+      registerVariantCues(entry.metadata.audio?.variants, layout.format.fps);
     } catch (error) {
       log.warn(`[odori] generated cues in ${video.relativeFile} may use the default frame rate: ${message(error)}`);
     }

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}) {

package/src/render.ts

@@ -22,6 +22,8 @@ export type RenderTarget = {
   input?: Record<string, unknown>;
   prepared?: unknown;
   audio?: ManifestAudioCue[];
+  /** A declared audio variant's name, applied when the page compiles cues. */
+  audioVariant?: string;
   targetLufs?: number;
   scenes?: Array<{id: string; start: number; durationInFrames: number}>;
 };
@@ -32,6 +34,7 @@ const renderUrl = (origin: string, target: RenderTarget, frame: number) => {
   const params = new URLSearchParams({render: "1", video: target.videoId, frame: String(frame)});
   if (target.input) params.set("input", encodeParam(target.input));
   if (target.prepared !== undefined) params.set("prepared", encodeParam(target.prepared));
+  if (target.audioVariant) params.set("audio", target.audioVariant);
   return `${origin}/?${params.toString()}`;
 };
 

package/studio/src/components/ExportPanel.tsx

@@ -51,12 +51,18 @@ const outputName = (videoId: string) => videoId.split("/").join("-");
  * started here can be retried from either surface.
  */
 export const ExportPanel = ({
+  audioVariant = null,
+  sound = true,
   videoId,
   input,
   frame,
   width,
   height,
 }: {
+  /** The audio choices, made where the audio is described: the inspector's
+      Audio section owns the controls, the export ships what is playing. */
+  audioVariant?: string | null;
+  sound?: boolean;
   videoId: string;
   input: Record<string, unknown>;
   frame: number;
@@ -70,7 +76,6 @@ export const ExportPanel = ({
   /* Sound is part of the video, so it ships unless it is turned off. GIF has
      no audio track at all and a still is one frame, so the choice only exists
      where it means something. */
-  const [sound, setSound] = useState(true);
   const [format, setFormat] = useState<Format>("mp4");
   const [quality, setQuality] = useState<Quality>("studio");
   const [scale, setScale] = useState(1);
@@ -193,7 +198,7 @@ export const ExportPanel = ({
   const run = async () => {
     setNotice(null);
     if (format === "frame") return post("/__odori/still", {videoId, input, frame});
-    return post("/__odori/exports", {videoId, input, format, quality, scale, audio: hasSound ? sound : false});
+    return post("/__odori/exports", {videoId, input, format, quality, scale, audio: hasSound ? sound : false, ...(audioVariant ? {audioVariant} : {})});
   };
 
   const file = outputName(videoId);
@@ -250,7 +255,10 @@ export const ExportPanel = ({
                 disabled={busy}
                 onClick={() => setScale(option)}
               >
-                {option}x
+                {/* A resolution, not a multiplier: 1080p means something at a
+                    glance and 1.5x means arithmetic. The height names the
+                    chip because that is how people say resolutions. */}
+                {scaled(height, option)}p
               </Button>
             ))}
           </div>
@@ -280,21 +288,6 @@ export const ExportPanel = ({
         </div>
       ) : null}
 
-      {hasSound ? (
-        <div className="export-row">
-          <span className="export-label">Sound</span>
-          <div className="export-options">
-            <Button variant="outline" active={sound} disabled={busy} onClick={() => setSound(true)}
-              title="Mix the brand's cues into the file">
-              On
-            </Button>
-            <Button variant="outline" active={!sound} disabled={busy} onClick={() => setSound(false)}
-              title="Write the picture with no audio track">
-              Off
-            </Button>
-          </div>
-        </div>
-      ) : null}
 
       <div className="export-actions">
         <Button

package/studio/src/main.tsx

@@ -20,6 +20,7 @@ if (renderMode) {
     <RenderSurface
       entry={entry}
       initialFrame={Number(query.get("frame") ?? 0)}
+      audioVariant={query.get("audio") ?? undefined}
       input={input}
       prepared={prepared}
       assets={project.assets}

package/studio/src/studio.css

@@ -1181,6 +1181,18 @@ html[data-inspector="collapsed"] .main:not([data-single="true"]) {
   flex-wrap: wrap;
   gap: 6px;
 }
+/* The Voice and Sound rows above the cue facts: each row breathes, and the
+   pair stands clear of the list it governs. */
+.audio-controls {
+  display: grid;
+  gap: 12px;
+  margin: 2px 0 14px;
+}
+/* Cue labels are file names, which outgrow the fact grid's 84px column:
+   bed-launch.m4a wrapped onto two lines in the default width. */
+.facts-audio .fact {
+  grid-template-columns: 122px minmax(0, 1fr);
+}
 .export-dimensions {
   color: var(--subtle);
   font-family: var(--font-mono);
@@ -1216,6 +1228,12 @@ html[data-inspector="collapsed"] .main:not([data-single="true"]) {
   gap: 6px;
   padding: 16px 20px 0;
 }
+.catalog-filter-rule {
+  align-self: stretch;
+  background: var(--border);
+  margin: 2px 6px;
+  width: 1px;
+}
 .catalog-filter button {
   background: transparent;
   border: 1px solid var(--border);

package/studio/src/views/ComponentsView.tsx

@@ -159,7 +159,11 @@ export const ComponentsView = ({
 }) => {
   // Finding one by name is ⌘K; the gallery is for browsing them all. A route
   // with no selection is the gallery; a selection is that component's player.
-  const [usedIn, setUsedIn] = useState<string | null>(null);
+  //
+  // One active filter, of either kind: a video from the derived usage, or a
+  // tag an author declared. Stacking them multiplies chips into a query
+  // builder, and the question is always singular: what belongs to this?
+  const [filter, setFilter] = useState<{kind: "video" | "tag"; value: string} | null>(null);
 
   /**
    * Which video a component appears in, derived from the imports rather than
@@ -174,11 +178,17 @@ export const ComponentsView = ({
     () => [...new Set(Object.values(usage).flat())].sort(),
     [usage],
   );
+  const tags = useMemo(
+    () => [...new Set(componentPreviews.flatMap((item) => item.preview.tags ?? []))].sort(),
+    [],
+  );
 
   const filtered = useMemo(() => {
     const all = [...componentPreviews].sort(byFamily);
-    return usedIn ? all.filter((item) => (usage[item.id] ?? []).includes(usedIn)) : all;
-  }, [usedIn, usage]);
+    if (!filter) return all;
+    if (filter.kind === "video") return all.filter((item) => (usage[item.id] ?? []).includes(filter.value));
+    return all.filter((item) => (item.preview.tags ?? []).includes(filter.value));
+  }, [filter, usage]);
   const selected = selection ? (filtered.find((entry) => entry.id === selection) ?? null) : null;
   const brands = projectBrands();
   const [brandName, setBrandName] = useState(brands[0]?.name ?? defaultBrand.name);
@@ -246,21 +256,32 @@ export const ComponentsView = ({
     }
     return (
       <div style={{overflowY: "auto", width: "100%"}}>
-        {videosUsing.length > 0 ? (
+        {videosUsing.length > 0 || tags.length > 0 ? (
           <div className="catalog-filter">
-            <button type="button" data-active={usedIn === null ? "true" : undefined} onClick={() => setUsedIn(null)}>
+            <button type="button" data-active={filter === null ? "true" : undefined} onClick={() => setFilter(null)}>
               All
             </button>
             {videosUsing.map((video) => (
               <button
                 key={video}
                 type="button"
-                data-active={usedIn === video ? "true" : undefined}
-                onClick={() => setUsedIn(video)}
+                data-active={filter?.kind === "video" && filter.value === video ? "true" : undefined}
+                onClick={() => setFilter({kind: "video", value: video})}
               >
                 {video}
               </button>
             ))}
+            {tags.length > 0 && videosUsing.length > 0 ? <span className="catalog-filter-rule" /> : null}
+            {tags.map((tag) => (
+              <button
+                key={tag}
+                type="button"
+                data-active={filter?.kind === "tag" && filter.value === tag ? "true" : undefined}
+                onClick={() => setFilter({kind: "tag", value: tag})}
+              >
+                {tag}
+              </button>
+            ))}
           </div>
         ) : null}
         {families.map((family) => (

package/studio/src/views/VideosView.tsx

@@ -1,5 +1,6 @@
 import {useCallback, useEffect, useMemo, useRef, useState} from "react";
 import {
+  AudioVariantContext,
   DUCK_GAIN,
   OdoriRuntime,
   entryDurationInFrames,
@@ -21,7 +22,7 @@ import {ExportPanel} from "../components/ExportPanel";
 import {Diagnostics} from "../components/Diagnostics";
 import {Inspector} from "../components/Inspector";
 import {Navigator} from "../components/Navigator";
-import {Badge, Empty, Fact, SectionTitle, Separator} from "../components/ui";
+import {Badge, Button, Empty, Fact, SectionTitle, Separator} from "../components/ui";
 import {measureTrack} from "../lib/mix-loudness";
 import {readStartSound} from "../settings";
 import {useShortcuts} from "../shortcuts";
@@ -46,7 +47,16 @@ export const VideosView = ({
 }) => {
   // Finding one by name is ⌘K; the gallery is for browsing them all. A route
   // with no selection is the gallery; a selection is that video's player.
-  const filtered = videos;
+  // The same chips the catalog offers: one active tag, or all of them.
+  const [tag, setTag] = useState<string | null>(null);
+  // Which declared audio variant plays. Lives here rather than in the export
+  // panel because the player has to hear the same voice the export will ship.
+  const [audioVariant, setAudioVariant] = useState<string | null>(null);
+  // Whether the export ships its track. Lives beside the voice choice: both
+  // are audio decisions, and the export panel only inherits them.
+  const [sound, setSound] = useState(true);
+  const tags = useMemo(() => [...new Set(videos.flatMap((video) => video.metadata.tags ?? []))].sort(), []);
+  const filtered = tag ? videos.filter((video) => (video.metadata.tags ?? []).includes(tag)) : videos;
   const selected = selection ? (filtered.find((video) => video.metadata.id === selection) ?? null) : null;
   const [input, setInput] = useState<Record<string, unknown>>({});
   const [timeline, setTimeline] = useState<CompiledTimeline | null>(null);
@@ -180,6 +190,24 @@ export const VideosView = ({
 
   if (!selected || !layout) {
     return (
+      <div style={{overflowY: "auto", width: "100%"}}>
+        {tags.length > 0 ? (
+          <div className="catalog-filter">
+            <button type="button" data-active={tag === null ? "true" : undefined} onClick={() => setTag(null)}>
+              All
+            </button>
+            {tags.map((name) => (
+              <button
+                key={name}
+                type="button"
+                data-active={tag === name ? "true" : undefined}
+                onClick={() => setTag(name)}
+              >
+                {name}
+              </button>
+            ))}
+          </div>
+        ) : null}
       <div className="gallery">
         {filtered.map((video) => {
           const videoLayout = resolveEntryLayout(video);
@@ -204,6 +232,7 @@ export const VideosView = ({
           );
         })}
       </div>
+      </div>
     );
   }
 
@@ -243,14 +272,18 @@ export const VideosView = ({
               transport, the inspector, and the file list stay usable while
               the error is read and fixed. */}
           <PreviewBoundary resetKey={selected.metadata.id}>
-            <OdoriRuntime
-              entry={selected}
-              frame={preview ?? playback.frame}
-              input={input}
-              assets={project.assets}
-              onTimeline={handleTimeline}
-              onAudio={handleAudio}
-            />
+            <AudioVariantContext.Provider
+              value={(audioVariant && selected.metadata.audio?.variants?.[audioVariant]) || null}
+            >
+              <OdoriRuntime
+                entry={selected}
+                frame={preview ?? playback.frame}
+                input={input}
+                assets={project.assets}
+                onTimeline={handleTimeline}
+                onAudio={handleAudio}
+              />
+            </AudioVariantContext.Provider>
           </PreviewBoundary>
         </CanvasStage>
         <Transport
@@ -277,6 +310,8 @@ export const VideosView = ({
         {/* Export sits first: it is the pane's one action, and the header
             names what is being worked on right above it. */}
         <ExportPanel
+          audioVariant={audioVariant}
+          sound={sound}
           videoId={selected.metadata.id}
           input={input}
           frame={playback.frame}
@@ -322,7 +357,44 @@ export const VideosView = ({
           <>
             <Separator />
             <SectionTitle>Audio</SectionTitle>
-            <dl className="facts">
+            <div className="audio-controls">
+            {Object.keys(selected.metadata.audio?.variants ?? {}).length > 0 ? (
+              <div className="export-row">
+                {/* "Variant", not "Voice": the field is audio.variants and a variant
+                    can re-point any cue, a bed or a language track as readily as a
+                    narrator. The label matches the metadata and the export flag, so
+                    the same word names the thing everywhere it appears. */}
+                <span className="export-label">Variant</span>
+                <div className="export-options">
+                  <Button variant="outline" active={audioVariant === null} onClick={() => setAudioVariant(null)}>
+                    Default
+                  </Button>
+                  {Object.keys(selected.metadata.audio?.variants ?? {}).map((name) => (
+                    <Button
+                      key={name}
+                      variant="outline"
+                      active={audioVariant === name}
+                      onClick={() => setAudioVariant(name)}
+                    >
+                      {name}
+                    </Button>
+                  ))}
+                </div>
+              </div>
+            ) : null}
+            <div className="export-row">
+              <span className="export-label">Sound</span>
+              <div className="export-options">
+                <Button variant="outline" active={sound} onClick={() => setSound(true)}>
+                  On
+                </Button>
+                <Button variant="outline" active={!sound} onClick={() => setSound(false)}>
+                  Off
+                </Button>
+              </div>
+            </div>
+            </div>
+            <dl className="facts facts-audio">
               {track.cues.map((cue) => (
                 <Fact key={cue.id} label={cueLabel(cue.src)} title={cue.src.split("/").pop()}>
                   {cue.fromFrame}-{cue.fromFrame + cue.durationInFrames - 1} · gain {cue.gain}

package/LICENSE

@@ -1,22 +0,0 @@
-MIT License
-
-Copyright (c) 2026 Allen Zhou
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
-