@odori/cli 0.0.2

package/studio/src/components/Thumbnail.tsx

@@ -0,0 +1,71 @@
+import {useState} from "react";
+import {OdoriRuntime, resolveEntryLayout, usePlayback, type VideoEntry} from "odori";
+import {PreviewBoundary} from "odori/preview";
+import {project} from "virtual:odori-project";
+import {useFitScale} from "./CanvasStage";
+
+/**
+ * A gallery thumbnail is the real composition at a chosen frame, letterboxed
+ * into a uniform card. Hovering plays it through the same runtime, so the
+ * catalog can never drift from the render.
+ */
+export const Thumbnail = ({
+  entry,
+  frame = 0,
+  durationInFrames,
+  playOnHover = true,
+}: {
+  entry: VideoEntry;
+  frame?: number;
+  durationInFrames?: number;
+  playOnHover?: boolean;
+}) => {
+  const layout = resolveEntryLayout(entry);
+  const {width, height, fps} = layout.format;
+  const [container, scale] = useFitScale(width, height);
+  const [hovering, setHovering] = useState(false);
+  const playback = usePlayback({
+    fps,
+    durationInFrames: Math.max(1, durationInFrames ?? fps * 8),
+    initialFrame: frame,
+    autoPlay: false,
+    loop: true,
+  });
+
+  const hover = (next: boolean) => {
+    if (!playOnHover) return;
+    setHovering(next);
+    if (next) playback.play();
+    else {
+      playback.pause();
+      playback.seek(frame);
+    }
+  };
+
+  return (
+    <div
+      className="card-canvas"
+      ref={container}
+      onPointerEnter={() => hover(true)}
+      onPointerLeave={() => hover(false)}
+    >
+      {/* Absolutely positioned so the composition never sizes the card. */}
+      <div
+        style={{
+          height,
+          left: "50%",
+          position: "absolute",
+          top: "50%",
+          transform: `translate(-50%, -50%) scale(${scale})`,
+          width,
+        }}
+      >
+        {/* A card in a grid of forty: one broken component must not blank
+            the library it is listed in. */}
+        <PreviewBoundary resetKey={entry.metadata.id} label="Threw">
+          <OdoriRuntime entry={entry} frame={hovering ? playback.frame : frame} assets={project.assets} />
+        </PreviewBoundary>
+      </div>
+    </div>
+  );
+};

package/studio/src/components/Transport.tsx

@@ -0,0 +1,237 @@
+import {useEffect, useRef} from "react";
+import {formatTimecode, type AudioTrack, type CompiledTimeline, type Playback} from "odori";
+import {Button, Icon} from "./ui";
+
+/**
+ * Transport plus a scene-aware timeline. The track is the scene structure the
+ * runtime compiled, not a decorative bar.
+ */
+export const RATES = [0.25, 0.5, 1, 1.5, 2, 4];
+
+export const Transport = ({
+  playback,
+  timeline,
+  track,
+  durationInFrames,
+  fps,
+  loop,
+  muted,
+  soloCue,
+  audioBlocked,
+  onEnableAudio,
+  onToggleLoop,
+  onToggleMuted,
+  onSoloCue,
+  onScrubbing,
+  rate = 1,
+  onRate,
+}: {
+  playback: Playback;
+  timeline: CompiledTimeline | null;
+  track?: AudioTrack | null;
+  durationInFrames: number;
+  fps: number;
+  loop: boolean;
+  muted?: boolean;
+  /** Cue id auditioned alone, or null for the whole mix. */
+  soloCue?: string | null;
+  /** The browser is refusing to start cues until the page is interacted with. */
+  audioBlocked?: boolean;
+  onEnableAudio?: () => void;
+  onToggleLoop: () => void;
+  onToggleMuted?: () => void;
+  onSoloCue?: (id: string | null) => void;
+  onScrubbing?: (scrubbing: boolean) => void;
+  rate?: number;
+  onRate?: (rate: number) => void;
+}) => {
+  const trackRef = useRef<HTMLDivElement>(null);
+  const scrubbing = useRef(false);
+  // Scrubbing pauses the clock so the drag owns the playhead, then hands
+  // playback back in the state it was in. Picking a frame is not a request to
+  // stop.
+  const resumeAfterScrub = useRef(false);
+  // A click picks a frame; only a drag auditions. Audio waits for movement so
+  // choosing a frame while paused stays silent.
+  const dragOrigin = useRef(0);
+  const auditioning = useRef(false);
+  const {frame} = playback;
+
+  const scrubTo = (clientX: number) => {
+    const element = trackRef.current;
+    if (!element) return;
+    const bounds = element.getBoundingClientRect();
+    const ratio = Math.max(0, Math.min(1, (clientX - bounds.left) / bounds.width));
+    playback.seek(Math.round(ratio * (durationInFrames - 1)));
+  };
+
+  useEffect(() => {
+    const move = (event: PointerEvent) => {
+      if (!scrubbing.current) return;
+      if (!auditioning.current && Math.abs(event.clientX - dragOrigin.current) > 3) {
+        auditioning.current = true;
+        onScrubbing?.(true);
+      }
+      scrubTo(event.clientX);
+    };
+    const up = () => {
+      if (!scrubbing.current) return;
+      scrubbing.current = false;
+      if (auditioning.current) {
+        auditioning.current = false;
+        onScrubbing?.(false);
+      }
+      if (resumeAfterScrub.current) {
+        resumeAfterScrub.current = false;
+        playback.play();
+      }
+    };
+    window.addEventListener("pointermove", move);
+    window.addEventListener("pointerup", up);
+    return () => {
+      window.removeEventListener("pointermove", move);
+      window.removeEventListener("pointerup", up);
+    };
+  });
+
+  const scenes = timeline?.scenes ?? [];
+  const active = scenes.find((scene) => frame >= scene.start && frame < scene.start + scene.durationInFrames);
+  const seconds = Math.max(1, Math.round(durationInFrames / fps));
+  const ticks = Array.from({length: Math.min(seconds, 12) + 1}, (_, index) =>
+    Math.round((index * durationInFrames) / Math.min(seconds, 12)),
+  );
+
+  return (
+    <div className="transport">
+      <div className="timeline">
+        <div className="ruler">
+          {ticks.map((tick, index) => (
+            <span key={tick} style={{opacity: index === 0 || index === ticks.length - 1 ? 1 : 0.6}}>
+              {(tick / fps).toFixed(1)}s
+            </span>
+          ))}
+        </div>
+        <div
+          className="track"
+          ref={trackRef}
+          onPointerDown={(event) => {
+            scrubbing.current = true;
+            dragOrigin.current = event.clientX;
+            resumeAfterScrub.current = playback.playing;
+            playback.pause();
+            scrubTo(event.clientX);
+          }}
+        >
+          {scenes.length > 0 ? (
+            scenes.map((scene) => (
+              <div
+                key={scene.id}
+                className="segment"
+                data-active={active?.id === scene.id ? "true" : undefined}
+                style={{flexGrow: scene.durationInFrames, flexBasis: 0}}
+                title={`${scene.id}: frames ${scene.start} to ${scene.start + scene.durationInFrames - 1}`}
+              >
+                {scene.name ?? scene.id}
+              </div>
+            ))
+          ) : (
+            <div className="segment" style={{flexGrow: 1}}>
+              continuous timeline
+            </div>
+          )}
+          <div className="playhead" style={{left: `${(frame / Math.max(1, durationInFrames - 1)) * 100}%`}} />
+        </div>
+
+        {track && track.cues.length > 0 ? (
+          <div className="audio-track">
+            {track.cues.map((cue) => {
+              const share = cue.durationInFrames / durationInFrames;
+              // A short cue is narrower than its own name, so the label moves
+              // outside the bar rather than being cut mid-word.
+              const placement = share > 0.18 ? undefined : cue.fromFrame / durationInFrames > 0.6 ? "before" : "after";
+              return (
+              <div
+                key={cue.id}
+                className="cue"
+                data-label={placement}
+                data-active={
+                  frame >= cue.fromFrame && frame < cue.fromFrame + cue.durationInFrames ? "true" : undefined
+                }
+                style={{
+                  left: `${(cue.fromFrame / durationInFrames) * 100}%`,
+                  width: `${(cue.durationInFrames / durationInFrames) * 100}%`,
+                }}
+                data-solo={soloCue && soloCue !== cue.id ? "off" : undefined}
+                title={`${cue.src} · gain ${cue.gain}${cue.duckUnder ? " · ducked" : ""}`}
+                onPointerDown={(event) => event.stopPropagation()}
+                onClick={() => onSoloCue?.(soloCue === cue.id ? null : cue.id)}
+              >
+                <span>{cue.src.split("/").pop()}</span>
+              </div>
+              );
+            })}
+          </div>
+        ) : null}
+      </div>
+
+      <div className="transport-row">
+        <Button icon aria-label="Go to start" onClick={() => playback.seek(0)}>
+          <Icon name="start" />
+        </Button>
+        <Button icon aria-label="Previous frame" onClick={() => playback.step(-1)}>
+          <Icon name="prev" />
+        </Button>
+        <Button variant="outline" icon aria-label={playback.playing ? "Pause" : "Play"} onClick={playback.toggle}>
+          <Icon name={playback.playing ? "pause" : "play"} />
+        </Button>
+        <Button icon aria-label="Next frame" onClick={() => playback.step(1)}>
+          <Icon name="next" />
+        </Button>
+        <Button icon aria-label="Go to end" onClick={() => playback.seek(durationInFrames - 1)}>
+          <Icon name="end" />
+        </Button>
+        <Button icon aria-label="Toggle loop" active={loop} onClick={onToggleLoop}>
+          <Icon name="loop" />
+        </Button>
+        {onRate ? (
+          // Speed is a preview convenience, never a property of the video: the
+          // frame clock and the export are untouched.
+          <select
+            className="rate"
+            aria-label="Playback speed"
+            value={rate}
+            onChange={(event) => onRate(Number(event.currentTarget.value))}
+          >
+            {RATES.map((option) => (
+              <option key={option} value={option}>
+                {option}x
+              </option>
+            ))}
+          </select>
+        ) : null}
+        {onToggleMuted ? (
+          // Sound is on unless it is turned off, so the one state worth
+          // showing here is that the browser is holding it until the page has
+          // been interacted with. Clicking is that interaction.
+          <Button
+            icon
+            aria-label={audioBlocked ? "Enable sound" : muted ? "Unmute" : "Mute"}
+            title={audioBlocked ? "The browser blocks audio until you interact with the page" : undefined}
+            active={!muted && !audioBlocked}
+            onClick={() => (audioBlocked ? onEnableAudio?.() : onToggleMuted())}
+          >
+            <Icon name={muted || audioBlocked ? "muted" : "sound"} />
+          </Button>
+        ) : null}
+
+        <span className="timecode" style={{marginLeft: 8}}>
+          <b>{formatTimecode(frame, fps)}</b> / {formatTimecode(durationInFrames - 1, fps)}
+        </span>
+        <span className="timecode">
+          frame <b>{frame}</b> of {durationInFrames - 1}
+        </span>
+        {active ? <span className="timecode">scene <b>{active.name ?? active.id}</b></span> : null}
+      </div>
+    </div>
+  );
+};

package/studio/src/components/Waveform.tsx

@@ -0,0 +1,114 @@
+import {useEffect, useState} from "react";
+
+const PEAKS = 240;
+/** Half-height of the drawn wave, out of a 100 unit viewBox. Deliberately short
+ * of the lane so the cue's label stays the loudest thing in the row. */
+const AMPLITUDE = 30;
+type Decoded = {peaks: number[]; duration: number};
+
+const cache = new Map<string, Promise<Decoded>>();
+
+/**
+ * Peaks for one source, decoded once per Studio session.
+ *
+ * A flat bar tells you a cue exists; peaks tell you where its hits are, which
+ * is what aligning a cut to a sound actually needs.
+ */
+const loadPeaks = (url: string): Promise<Decoded> => {
+  const hit = cache.get(url);
+  if (hit) return hit;
+
+  const pending = (async () => {
+    const response = await fetch(url);
+    if (!response.ok) throw new Error(`${response.status}`);
+    const context = new AudioContext();
+    try {
+      const buffer = await context.decodeAudioData(await response.arrayBuffer());
+      const samples = buffer.getChannelData(0);
+      const window = Math.max(1, Math.floor(samples.length / PEAKS));
+      const peaks: number[] = [];
+      // RMS rather than peak: a mastered music bed is peak-limited, so peaks
+      // draw one solid block where RMS still shows the shape of the track.
+      for (let index = 0; index < PEAKS; index += 1) {
+        const start = index * window;
+        let sum = 0;
+        let counted = 0;
+        for (let offset = 0; offset < window && start + offset < samples.length; offset += 1) {
+          const sample = samples[start + offset];
+          sum += sample * sample;
+          counted += 1;
+        }
+        peaks.push(counted === 0 ? 0 : Math.sqrt(sum / counted));
+      }
+      return {peaks, duration: buffer.duration};
+    } finally {
+      void context.close();
+    }
+  })();
+
+  cache.set(url, pending);
+  // A source that cannot be decoded falls back to a flat lane rather than
+  // taking the transport down with it.
+  return pending.catch(() => {
+    cache.delete(url);
+    return {peaks: [], duration: 0};
+  });
+};
+
+/** Decoded peaks and duration for a source, shared with the transport lanes. */
+export const useAudioPeaks = (url: string): Decoded => {
+  const [decoded, setDecoded] = useState<Decoded>({peaks: [], duration: 0});
+  useEffect(() => {
+    let live = true;
+    void loadPeaks(url).then((value) => {
+      if (live) setDecoded(value);
+    });
+    return () => {
+      live = false;
+    };
+  }, [url]);
+  return decoded;
+};
+
+export const Waveform = ({
+  url,
+  trimStartSeconds = 0,
+  windowSeconds,
+  loop = false,
+}: {
+  url: string;
+  trimStartSeconds?: number;
+  /** Seconds of the source the cue actually uses. */
+  windowSeconds?: number;
+  loop?: boolean;
+}) => {
+  const {peaks, duration} = useAudioPeaks(url);
+  if (peaks.length === 0 || duration === 0) return null;
+
+  // The lane shows the slice the cue plays, not the whole file.
+  const perSecond = peaks.length / duration;
+  const start = Math.min(peaks.length - 1, Math.max(0, Math.round(trimStartSeconds * perSecond)));
+  const count = windowSeconds ? Math.max(1, Math.round(windowSeconds * perSecond)) : peaks.length - start;
+  const window = loop
+    ? Array.from({length: count}, (_, index) => peaks[(start + index) % peaks.length])
+    : peaks.slice(start, start + count);
+
+  // Normalized to the loudest moment of the slice this cue plays, so a lane
+  // 20 pixels tall shows shape. Level lives in the Audio panel as numbers.
+  const ceiling = Math.max(...window);
+  const visible = ceiling > 0.001 ? window.map((peak) => peak / ceiling) : window;
+  const step = 100 / Math.max(1, visible.length - 1);
+  const top = visible.map((peak, index) => `${index * step},${50 - peak * AMPLITUDE}`).join(" ");
+  const bottom = visible
+    .map((_, index) => {
+      const mirrored = visible.length - 1 - index;
+      return `${mirrored * step},${50 + visible[mirrored] * AMPLITUDE}`;
+    })
+    .join(" ");
+
+  return (
+    <svg className="waveform" viewBox="0 0 100 100" preserveAspectRatio="none" aria-hidden="true">
+      <polygon points={`${top} ${bottom}`} fill="currentColor" />
+    </svg>
+  );
+};