@dailies-studio/shot-editor 0.1.0 → 0.2.0

package/src/panels/timeline/TransportVolume.tsx

@@ -0,0 +1,163 @@
+// THE TRANSPORT'S SPEAKER: preview mute and volume, beside play.
+//
+// Neither touches the document, so neither can change what an export sounds
+// like (see `ShotEditorState.previewMuted`). They are this tab's listening
+// level, which is why they sit with the verbs that play the film and not in the
+// mixer, where every level is saved. The mixer's master strip is a meter only.
+//
+// One button, two jobs. A press mutes. The volume lives in a popover that opens
+// while the pointer rests on the speaker (or on the popover itself), and when
+// the keyboard focuses it. The arrow keys on the focused speaker step the
+// volume without opening anything first, so the level is reachable without a
+// pointer at all.
+//
+// A leaf, because `previewVolume` changes once per slider pixel and a
+// subscription in `TimelineDock` would re-render every row on a drag.
+import { useEffect, useId, useRef, useState } from "react";
+import type { CSSProperties, KeyboardEvent as ReactKeyboardEvent } from "react";
+import { IconVolume, IconVolumeOff, Popover } from "@dailies-studio/ui";
+import { useShotEditor, useStore } from "../../state/context.js";
+
+/** Hover intent: long enough that a pointer crossing the transport on its way
+ *  to the loop does not flash the popover, short enough to feel immediate. */
+const OPEN_DELAY_MS = 120;
+/** Grace to cross the gap from the speaker into the popover. */
+const CLOSE_DELAY_MS = 240;
+/** One arrow press, and one with Shift. */
+const STEP = 0.05;
+const BIG_STEP = 0.2;
+
+/** True for keyboard focus only. `ownsActivation` in keymap.ts draws the same
+ *  line: a speaker the mouse pressed must not keep the arrow keys. Guarded
+ *  because an engine without the selector throws on `matches`. */
+function keyboardFocused(el: HTMLElement): boolean {
+  try {
+    return el.matches(":focus-visible");
+  } catch {
+    return false;
+  }
+}
+
+export function TransportVolume() {
+  const store = useStore();
+  const muted = useShotEditor((s) => s.previewMuted);
+  const volume = useShotEditor((s) => s.previewVolume);
+  const [open, setOpen] = useState(false);
+  const anchor = useRef<HTMLButtonElement | null>(null);
+  const timer = useRef<ReturnType<typeof setTimeout> | null>(null);
+  /** A thumb drag in progress: the pointer may leave the popover mid-drag,
+   *  and that must not close it under the drag. */
+  const dragging = useRef(false);
+  const sliderId = useId();
+
+  const cancel = (): void => {
+    if (timer.current === null) return;
+    clearTimeout(timer.current);
+    timer.current = null;
+  };
+  const later = (next: boolean, ms: number): void => {
+    cancel();
+    timer.current = setTimeout(() => {
+      timer.current = null;
+      setOpen(next);
+    }, ms);
+  };
+  const leave = (): void => {
+    if (dragging.current) return;
+    later(false, CLOSE_DELAY_MS);
+  };
+  useEffect(() => cancel, []);
+
+  const silent = muted || volume <= 0;
+  const percent = Math.round(volume * 100);
+
+  const onKeyDown = (e: ReactKeyboardEvent<HTMLButtonElement>): void => {
+    if (!keyboardFocused(e.currentTarget)) return;
+    const dir =
+      e.key === "ArrowUp" || e.key === "ArrowRight" ? 1 : e.key === "ArrowDown" || e.key === "ArrowLeft" ? -1 : 0;
+    if (dir === 0) return;
+    // Stopped, so the timeline's own arrows (edit points, nudges) do not fire.
+    e.preventDefault();
+    e.stopPropagation();
+    const next = Math.round(Math.min(1, Math.max(0, volume + dir * (e.shiftKey ? BIG_STEP : STEP))) * 100) / 100;
+    store.setPreviewVolume(next);
+    cancel();
+    setOpen(true);
+  };
+
+  return (
+    <>
+      <button
+        ref={anchor}
+        type="button"
+        className="btn is-icon is-ghost dock-mute"
+        data-testid="dock-mute"
+        // The name stays put and `aria-pressed` carries the state, which is how
+        // a toggle is announced. The level is the slider's, named below.
+        aria-label="Mute preview"
+        aria-pressed={muted}
+        aria-controls={open ? sliderId : undefined}
+        aria-keyshortcuts="ArrowUp ArrowDown"
+        title={muted ? "Preview muted, press to hear it" : `Preview ${percent}%: press to mute, arrows to set`}
+        onClick={() => {
+          // A speaker drawn silent because the level is at zero, not because
+          // it is muted, is brought back up rather than muted on top.
+          if (!muted && volume <= 0) store.setPreviewVolume(1);
+          else store.setPreviewMuted(!muted);
+        }}
+        onKeyDown={onKeyDown}
+        onPointerEnter={() => later(true, OPEN_DELAY_MS)}
+        onPointerLeave={leave}
+        onFocus={(e) => {
+          if (!keyboardFocused(e.currentTarget)) return;
+          cancel();
+          setOpen(true);
+        }}
+        onBlur={() => {
+          if (!dragging.current) later(false, 0);
+        }}
+      >
+        {silent ? <IconVolumeOff /> : <IconVolume />}
+      </button>
+      <Popover open={open} anchor={anchor} onClose={() => setOpen(false)} side="above" className="dock-volume-pop">
+        <div
+          className="dock-volume-body"
+          data-testid="dock-volume-pop"
+          onPointerEnter={cancel}
+          onPointerLeave={leave}
+        >
+          <input
+            id={sliderId}
+            className="dock-volume"
+            type="range"
+            min={0}
+            max={1}
+            step={0.01}
+            value={volume}
+            // The filled level (timeline-meters.css): WebKit has no progress part.
+            style={{ "--fill": volume } as CSSProperties}
+            aria-label="Preview volume"
+            aria-valuetext={muted ? `${percent}%, muted` : `${percent}%`}
+            onChange={(e) => store.setPreviewVolume(Number(e.currentTarget.value))}
+            onPointerDown={() => {
+              dragging.current = true;
+              window.addEventListener(
+                "pointerup",
+                () => {
+                  dragging.current = false;
+                },
+                { once: true },
+              );
+            }}
+            // `DockZoom`'s reason: a focused range swallows the keymap, and Space
+            // is the key an author presses right after setting a level.
+            onPointerUp={(e) => e.currentTarget.blur()}
+          />
+          <span className="dock-volume-value" aria-hidden="true">
+            {muted ? "Muted" : `${percent}%`}
+          </span>
+        </div>
+      </Popover>
+    </>
+  );
+}

package/src/panels/timeline/beatRuler.ts

@@ -0,0 +1,74 @@
+// THE BEAT GRID: sound mode's ruler ticks and the "bar.beat" readout.
+//
+// Pure, and apart from SoundMode.tsx, because the timeline's ruler draws them
+// with the shell while sound mode's lanes and mixer load when its view opens.
+import type { Rational } from "@dailies-studio/engine";
+import { beatFrames } from "@dailies-studio/shot/doc";
+import type { Tempo3D } from "@dailies-studio/shot/doc";
+
+/** Frames per beat. */
+function beatStep(tempo: Tempo3D, fps: Rational): number {
+  return (60 * fps.num) / (fps.den * tempo.bpm);
+}
+
+/**
+ * "bar.beat" at a MASTER frame, both 1-based: "3.2". The beat holding a frame
+ * is the last one whose rounded frame is at or before it, the same rounding
+ * `beatFrames` draws with, so the readout and the grid line agree.
+ */
+export function barBeatAt(tempo: Tempo3D, fps: Rational, frame: number): string {
+  const step = beatStep(tempo, fps);
+  if (!(step > 0)) return "1.1";
+  const perBar = Math.max(1, Math.trunc(tempo.beatsPerBar ?? 4));
+  // Math.round(x) <= f  <=>  x < f + 0.5, so the last beat n with
+  // start + n * step < f + 0.5.
+  const n = Math.ceil((frame - (tempo.startFrame ?? 0) + 0.5) / step) - 1;
+  const bar = Math.floor(n / perBar) + 1;
+  const beat = (((n % perBar) + perBar) % perBar) + 1;
+  return `${bar}.${beat}`;
+}
+
+export interface BeatTick {
+  /** LANE frame: master less the shot context's origin. */
+  frame: number;
+  /** 0 a labelled bar, 1 an unlabelled bar, 2 a beat. */
+  tier: 0 | 1 | 2;
+  label?: string;
+}
+
+/**
+ * The ruler's and the lanes' beat grid for `[origin, origin + extentF)`.
+ *
+ * Bars are labelled at a power-of-two stride so labels stay 32px apart, and
+ * beats are drawn only once they are 6px apart: a grid denser than that is a
+ * grey wash, not a grid.
+ */
+export function beatRulerTicks(
+  tempo: Tempo3D,
+  fps: Rational,
+  origin: number,
+  extentF: number,
+  ppf: number,
+): BeatTick[] {
+  const step = beatStep(tempo, fps);
+  if (!(step > 0) || !(extentF > 0) || !(ppf > 0)) return [];
+  const perBar = Math.max(1, Math.trunc(tempo.beatsPerBar ?? 4));
+  const barPx = step * perBar * ppf;
+  let stride = 1;
+  while (stride * barPx < 32 && stride < 1 << 20) stride *= 2;
+  const showBeats = step * ppf >= 6;
+  // A bar line is drawn at all only when bars are 4px apart.
+  const showBars = barPx >= 4 || stride > 1;
+  const out: BeatTick[] = [];
+  for (const b of beatFrames(tempo, fps, origin, origin + extentF)) {
+    const lane = b.frame - origin;
+    if (b.bar) {
+      const bar = Math.floor(b.beat / perBar) + 1;
+      if ((bar - 1) % stride === 0) out.push({ frame: lane, tier: 0, label: String(bar) });
+      else if (showBars && barPx >= 8) out.push({ frame: lane, tier: 1 });
+    } else if (showBeats) {
+      out.push({ frame: lane, tier: 2 });
+    }
+  }
+  return out;
+}