@odori/cli 0.0.10 → 0.0.12

package/src/registry-source.ts

@@ -348,4 +348,143 @@ export const verifyIntegrity = (item: RegistryItemDocument, origin: RegistryOrig
   );
 };
 
+/**
+ * Blocks: whole videos, published the same way components are.
+ *
+ * A block is the larger unit — an entry and the files beside it, plus the
+ * components it installs — so it reuses every guarantee this module already
+ * makes rather than growing a second way in: the same index-then-document
+ * split, the same cache, the same integrity hash over the exact bytes a
+ * consumer writes, and the same refusal to write outside the project.
+ *
+ * There is no bundled floor for blocks. The snapshot exists so a locked-down
+ * machine can still install a component and so `odori test` never touches the
+ * network; taking a whole video is a deliberate act on a machine that has one.
+ * A block therefore resolves network → cache and says so when neither answers.
+ */
+export type BlockDocument = {
+  id: string;
+  title: string;
+  description: string;
+  tags: string[];
+  format: string;
+  /** The file to render, relative to the project root. */
+  entry: string;
+  /** Registry components this block imports, by namespaced name. */
+  components: string[];
+  files: Array<{path: string; content: string; target: string}>;
+  meta?: {integrity?: string};
+};
+
+/** The index: every block, without the file contents. */
+export type BlockSummary = Omit<BlockDocument, "files"> & {
+  files: Array<{path: string; target: string}>;
+};
+
+export type BlockIndex = {items: BlockSummary[]; origin: RegistryOrigin; detail: string};
+
+const blocksUnavailable = (url: string): Error =>
+  new Error(
+    `No blocks available: ${url}/blocks.json could not be fetched and nothing is cached on this machine. ` +
+      "Blocks are published rather than bundled, so this needs a network once. " +
+      "Components still install offline.",
+  );
+
+export const resolveBlocks = async (
+  config: ResolvedConfig,
+  options: {allowNetwork?: boolean} = {},
+): Promise<BlockIndex> => {
+  const url = registryUrl(config);
+  const cache = resolve(cacheDir(url), "blocks.json");
+
+  if (options.allowNetwork !== false) {
+    try {
+      const index = (await fetchJson(`${url}/blocks.json`)) as {items: BlockSummary[]};
+      if (!Array.isArray(index.items)) throw new Error("the index has no items array");
+      await mkdir(dirname(cache), {recursive: true});
+      await writeFile(cache, JSON.stringify(index), "utf8");
+      return {items: index.items, origin: "network", detail: url};
+    } catch {
+      // As with components: unreachable is not an error until the disk is
+      // empty too.
+    }
+  }
+
+  if (existsSync(cache)) {
+    try {
+      const index = JSON.parse(await readFile(cache, "utf8")) as {items: BlockSummary[]};
+      return {items: index.items, origin: "cache", detail: cache};
+    } catch {
+      // A corrupt cache is a cache miss.
+    }
+  }
+
+  throw blocksUnavailable(url);
+};
+
+/** One block, with the source of every file it ships. */
+export const resolveBlock = async (
+  config: ResolvedConfig,
+  id: string,
+  options: {allowNetwork?: boolean} = {},
+): Promise<{block: BlockDocument; origin: RegistryOrigin}> => {
+  assertSafeName(id);
+  const url = registryUrl(config);
+  const cache = resolve(cacheDir(url), `block-${id}.json`);
+
+  if (options.allowNetwork !== false) {
+    try {
+      const block = (await fetchJson(`${url}/blocks/${id}.json`)) as BlockDocument;
+      if (block?.id !== id) throw new Error(`the document at ${url}/blocks/${id}.json is for "${block?.id}"`);
+      await mkdir(dirname(cache), {recursive: true});
+      await writeFile(cache, JSON.stringify(block), "utf8");
+      return {block, origin: "network"};
+    } catch {
+      // Try the disk before giving up.
+    }
+  }
+
+  if (existsSync(cache)) {
+    try {
+      return {block: JSON.parse(await readFile(cache, "utf8")) as BlockDocument, origin: "cache"};
+    } catch {
+      // Corrupt: fall through to the error, which names the whole situation.
+    }
+  }
+
+  throw blocksUnavailable(url);
+};
+
+/**
+ * The same hash components use, over a block's files.
+ *
+ * Integrity proves the bytes and not the intent, which is why every target is
+ * still resolved against the project root before anything is written.
+ */
+export const verifyBlockIntegrity = (block: BlockDocument): void => {
+  const expected = block.meta?.integrity;
+  if (!expected) {
+    throw new Error(
+      `The document for block "${block.id}" carries no integrity hash. ` +
+        "A fetched block must be verifiable; refusing to write it. Nothing was written.",
+    );
+  }
+
+  const hash = createHash("sha256");
+  for (const file of [...block.files].sort((left, right) => left.path.localeCompare(right.path))) {
+    hash.update(file.path);
+    hash.update("\0");
+    hash.update(file.content);
+    hash.update("\0");
+  }
+  const actual = `sha256-${hash.digest("base64")}`;
+  if (actual === expected) return;
+
+  throw new Error(
+    `The files for block "${block.id}" do not match the hash the registry published.\n` +
+      `  expected ${expected}\n  received ${actual}\n` +
+      "Nothing was written. This is a truncated download, a stale proxy, or a tampered document.",
+  );
+};
+
 export type {RegistryItemDocument};

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/src/structure.ts

@@ -0,0 +1,177 @@
+import {readFile} from "node:fs/promises";
+import {existsSync} from "node:fs";
+import {relative, resolve, sep} from "node:path";
+import {resolveEntryLayout} from "odori";
+import type {ResolvedConfig} from "./config";
+import {walkSource, type ProjectGraph} from "./discovery";
+import type {LoadedVideo} from "./project";
+
+/**
+ * A fact about the project's shape that discovery itself cannot say.
+ *
+ * Discovery answers "what exists": it walks the tree and takes what matches.
+ * That is the right behaviour for a build — an unrecognized file must never
+ * take the project down — and exactly the wrong behaviour for an author,
+ * because everything discovery quietly steps over is a file someone wrote on
+ * purpose. The filesystem is Odori's contract: `video.tsx` is a video,
+ * `*.preview.tsx` is a fixture, a directory under components/ names a
+ * component. This module checks the places where that contract can be almost
+ * met, which is the one distance discovery cannot see.
+ *
+ * An `error` is a promise the project makes and breaks at render or play
+ * time: a sound that will be silence, an override that will never be heard.
+ * A `warn` is a file that works today and will surprise someone later.
+ */
+export type StructureFinding = {
+  level: "error" | "warn";
+  /** The file an author would open to fix it, relative to the project root. */
+  file: string;
+  message: string;
+};
+
+/** Entry basenames one keystroke away from meaning something. */
+const NEAR_MISSES: Array<{test: (base: string) => boolean; message: string}> = [
+  {
+    test: (base) => base === "video.ts" || base === "video.jsx",
+    message: "Only video.tsx is a video entry. This file is invisible to discovery: rename it to video.tsx.",
+  },
+  {
+    test: (base) => base.toLowerCase() === "video.tsx" && base !== "video.tsx",
+    message: "Entry names are exact and lower case. This file is invisible to discovery: rename it to video.tsx.",
+  },
+  {
+    test: (base) => /\.preview\.(ts|jsx)$/.test(base),
+    message:
+      "Only *.preview.tsx is a component fixture. This file is invisible to discovery: rename it to end in .preview.tsx.",
+  },
+  {
+    test: (base) => base.toLowerCase().endsWith(".preview.tsx") && !base.endsWith(".preview.tsx"),
+    message:
+      "Fixture names are exact and lower case. This file is invisible to discovery: rename it to end in .preview.tsx.",
+  },
+];
+
+/** String literals that name a file under the served audio library. */
+const AUDIO_REFERENCE = /["'`](\/audio\/[^"'`\s]+\.[a-z0-9]{2,4})["'`]/gi;
+
+/**
+ * Check the filesystem contract and report every place it is almost met.
+ *
+ * Everything here is answerable in Node from the tree and the loaded
+ * metadata: no browser, no network, no render. That is what makes it cheap
+ * enough to run inside `odori doctor` and first inside `odori test`, before
+ * a browser ever starts.
+ */
+export const checkStructure = async (
+  config: ResolvedConfig,
+  graph: ProjectGraph,
+  videos: LoadedVideo[],
+): Promise<StructureFinding[]> => {
+  const findings: StructureFinding[] = [];
+  const videosRoot = resolve(config.root, config.videosDir);
+  const componentsRoot = resolve(config.root, config.componentsDir);
+  const files = existsSync(videosRoot) ? await walkSource(videosRoot) : [];
+
+  // Files one keystroke away from being entries. Discovery is filename
+  // driven, so `video.ts` is not a video with a small problem — it is not a
+  // video at all, and nothing else in the pipeline will ever say so.
+  for (const file of files) {
+    const base = file.split(sep).pop() ?? "";
+    const miss = NEAR_MISSES.find((candidate) => candidate.test(base));
+    if (miss) findings.push({level: "warn", file: relative(config.root, file), message: miss.message});
+  }
+
+  // A fixture named after something other than its directory. The catalog
+  // attributes usage by matching the fixture's name to the directory videos
+  // import from, so a mismatched name previews fine and is credited to
+  // nothing: its "used by" list stays empty forever.
+  for (const preview of graph.previews) {
+    if (!preview.file.startsWith(componentsRoot + sep)) continue;
+    const directory = resolve(preview.file, "..").split(sep).pop() ?? "";
+    if (directory && preview.name !== directory) {
+      findings.push({
+        level: "warn",
+        file: preview.relativeFile,
+        message:
+          `Fixture "${preview.name}" sits in components/${directory}/, so usage is never attributed to it. ` +
+          `Name the fixture after its directory: ${directory}.preview.tsx.`,
+      });
+    }
+  }
+
+  // A literal audio path with no file behind it. The dev server answers 404
+  // and plays on; the export hasher shrugs and warns late. The author finds
+  // out when the cut is silent where the sound was supposed to be.
+  const audioUrls = new Set(graph.audio.map((entry) => entry.url));
+  for (const file of files) {
+    if (!/\.(tsx|ts)$/.test(file)) continue;
+    const contents = await readFile(file, "utf8");
+    const reported = new Set<string>();
+    for (const match of contents.matchAll(AUDIO_REFERENCE)) {
+      const url = match[1];
+      // A template literal with an interpolation is a path decided at
+      // runtime. Only what is written in full can be answered for here.
+      if (url.includes("${") || audioUrls.has(url) || reported.has(url)) continue;
+      reported.add(url);
+      findings.push({
+        level: "error",
+        file: relative(config.root, file),
+        message: `References ${url}, and no file answers it under ${config.audioDir}/. It will play as silence.`,
+      });
+    }
+  }
+
+  // Variant overrides that answer to nothing. A variant replaces brand cues
+  // by name, so a name the brand never defines is an override nothing asks
+  // for, and a file path with no file is a sound that cannot load. Both are
+  // authored intent that the player will quietly ignore.
+  for (const video of videos) {
+    const layout = resolveEntryLayout(video.entry);
+    const brandCues = new Set(Object.keys(layout.brand.audio.cues));
+    for (const [variant, overrides] of Object.entries(video.entry.metadata.audio?.variants ?? {})) {
+      for (const [cue, value] of Object.entries(overrides)) {
+        if (!brandCues.has(cue)) {
+          findings.push({
+            level: "warn",
+            file: video.relativeFile,
+            message:
+              `Variant "${variant}" overrides a cue named "${cue}" that the brand "${layout.brand.name}" does not define. ` +
+              `Nothing plays that name, so the override is never heard.`,
+          });
+        }
+        if (typeof value === "string" && value.startsWith("/") && !audioUrls.has(value)) {
+          findings.push({
+            level: "error",
+            file: video.relativeFile,
+            message: `Variant "${variant}" points cue "${cue}" at ${value}, and no file answers it under ${config.audioDir}/.`,
+          });
+        }
+      }
+    }
+  }
+
+  // A compiled catalog that no longer describes the tree. Anything that
+  // reads the artifact instead of running discovery — an agent, a CI step,
+  // another tool — would be reading yesterday's project as if it were today's.
+  const catalogFile = resolve(config.root, config.outDir, "catalog.json");
+  if (existsSync(catalogFile)) {
+    try {
+      const catalog = JSON.parse(await readFile(catalogFile, "utf8")) as {sourceHash?: string};
+      if (catalog.sourceHash && catalog.sourceHash !== graph.sourceHash) {
+        findings.push({
+          level: "warn",
+          file: relative(config.root, catalogFile),
+          message: "The compiled catalog is older than the source tree. Run odori graph (or odori dev) to refresh it.",
+        });
+      }
+    } catch {
+      findings.push({
+        level: "warn",
+        file: relative(config.root, catalogFile),
+        message: "The compiled catalog is not valid JSON. Run odori graph (or odori dev) to rewrite it.",
+      });
+    }
+  }
+
+  return findings;
+};

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}