Skip to content

Write HTML. Render video. Built for agents.

15.7 KB
Raw Blame
import {
  memo,
  useCallback,
  useEffect,
  useMemo,
  useRef,
  type PointerEvent as ReactPointerEvent,
  type ReactNode,
  type Ref,
  type RefObject,
} from "react";
import {
  AUDIO_GAIN_FADER_MIN,
  AUDIO_GAIN_FADER_MAX,
  audioGainToFaderPosition,
  audioFaderPositionToGain,
  audioGainToText,
  formatAudioGain,
} from "@hyperframes/core/audio-gain";
import type { StereoLevel } from "@hyperframes/core/runtime/levelTap";
import { usePlayerStore } from "../../player";
import { clampNumber } from "../../utils/studioHelpers";
import { useAudioMetersVisible } from "../../utils/audioMeterVisibility";
import { EXPORT_PEAK_CEILING } from "../../utils/exportPeakCeiling";
import { useStudioShellContextOptional } from "../../contexts/StudioContext";
import { useTimelineEditContextOptional } from "../../contexts/TimelineEditContext";
import {
  METER_DB_MARKS,
  useProjectHasAudio,
  markFraction,
  stepPair,
  type MeterPair as Pair,
} from "../../utils/audioMeterMath";

interface Levels {
  master: StereoLevel;
  groups: Record<string, StereoLevel>;
}
interface AudioMeterHook {
  start(): void;
  stop(): void;
  read(): Levels;
}
interface Strip {
  id: string | null;
  label: string;
  volume: number;
}
type Bars = { mask: HTMLElement | null; peak: HTMLElement | null };
type StripBars = [Bars, Bars];

const MONITOR_LABEL = "Monitor";

/** The CLIP light latches at the export ceiling, stricter than RED_AT. */
export const CLIP_LATCH_PEAK = EXPORT_PEAK_CEILING;

export function stepClipLatch(latched: boolean, master: StereoLevel | undefined): boolean {
  if (latched || !master) return latched;
  return Math.max(master.l, master.r) >= CLIP_LATCH_PEAK;
}

function paintClipLight(el: HTMLElement | null, lit: boolean): void {
  if (!el) return;
  el.dataset.lit = String(lit);
  el.style.setProperty(
    "background-color",
    lit ? "var(--color-red-500)" : "var(--color-neutral-800)",
  );
  el.style.setProperty("color", lit ? "var(--color-white)" : "var(--color-neutral-500)");
}

/** Where the fill turns amber, then red, on the same piecewise dB scale the marks use. */
const AMBER_AT = markFraction(-6);
const RED_AT = markFraction(-3);

function useStrips(): Strip[] {
  const elements = usePlayerStore((s) => s.elements);
  const masterVolume = usePlayerStore((s) => s.audioVolume);
  return useMemo(() => {
    const labels = new Map<string, string>();
    const volumes = new Map<string, number>();
    for (const el of elements) {
      if (el.audioGroup && !labels.has(el.audioGroup)) {
        labels.set(el.audioGroup, el.audioGroupLabel ?? el.audioGroup);
        volumes.set(el.audioGroup, el.audioGroupVolume ?? 1);
      }
    }
    return [
      ...[...labels].map(([id, label]) => ({ id, label, volume: volumes.get(id) ?? 1 })),
      { id: null, label: MONITOR_LABEL, volume: masterVolume },
    ];
  }, [elements, masterVolume]);
}

/** Group volume through the existing `data-volume` write path (live while dragging, one
 *  undo entry on release); monitor volume through the player store's own volume action —
 *  the same one `VolumeControl` in `PlayerControls` already drives. */
function useVolumeHandlers(): {
  onLive: (id: string | null, volume: number) => void;
  onCommit: (id: string | null, volume: number) => void;
} {
  const { onSetAudioGroupAttributeLive, onSetAudioGroupAttributeQuiet } =
    useTimelineEditContextOptional();
  const setAudioVolume = usePlayerStore((s) => s.setAudioVolume);
  const onLive = useCallback(
    (id: string | null, volume: number) => {
      if (id === null) setAudioVolume(volume);
      else onSetAudioGroupAttributeLive?.(id, "data-volume", formatAudioGain(volume));
    },
    [onSetAudioGroupAttributeLive, setAudioVolume],
  );
  const onCommit = useCallback(
    (id: string | null, volume: number) => {
      if (id === null) setAudioVolume(volume);
      else
        void onSetAudioGroupAttributeQuiet?.(
          id,
          "data-volume",
          formatAudioGain(volume),
          "Set volume",
        );
    },
    [onSetAudioGroupAttributeQuiet, setAudioVolume],
  );
  return { onLive, onCommit };
}

type PreviewWindow = (Window & { __hf?: { audioMeter?: AudioMeterHook } }) | null | undefined;

function readHook(iframe: HTMLIFrameElement | null | undefined): AudioMeterHook | null {
  try {
    return (iframe?.contentWindow as PreviewWindow)?.__hf?.audioMeter ?? null;
  } catch {
    return null;
  }
}

/** 0 dB is bottom 100% plus 1px down, so the tick stays inside overflow-hidden.
 *  A calc() bottom does not stick as an inline style on Windows happy-dom. */
function paintPeak(el: HTMLElement | null, peak: number): void {
  if (!el) return;
  el.style.setProperty("bottom", `${peak * 100}%`);
  el.style.setProperty("transform", peak >= 1 ? "translateY(1px)" : "none");
}

/** The fill is a fixed green/amber/red backdrop; painting only moves the dark mask that covers the unlit top
 *  portion, so a loud peak lights the real red band instead of tinting a flat colour brighter. */
function paint(bars: StripBars | undefined, channels: Pair): void {
  channels.forEach((ch, i) => {
    bars?.[i]?.mask?.style.setProperty("height", `${(1 - ch.level) * 100}%`);
    paintPeak(bars?.[i]?.peak ?? null, ch.peak);
  });
}

/** Attach to the live preview hook. Always returns `live`, even if start/stop throw. */
export function followMeterHook(
  active: AudioMeterHook | null,
  live: AudioMeterHook | null,
): AudioMeterHook | null {
  if (live === active) return active;
  try {
    active?.stop();
  } catch {
    // Preview iframe was torn down; the old hook is uncallable.
  }
  try {
    live?.start();
  } catch {
    // New preview is not ready to attach yet.
  }
  return live;
}

export function evictGoneMeterState(
  state: Map<string | null, Pair>,
  liveIds: ReadonlySet<string | null>,
): void {
  for (const id of [...state.keys()]) {
    if (!liveIds.has(id)) state.delete(id);
  }
}

export function stepAndPaintStrips(
  strips: readonly { id: string | null }[],
  state: Map<string | null, Pair>,
  bars: Map<string | null, StripBars>,
  levels: Levels | undefined,
  now: number,
  dt: number,
): void {
  for (const { id } of strips) {
    const prev = state.get(id);
    const next = stepPair(prev, id === null ? levels?.master : levels?.groups[id], now, dt);
    if (next === prev) continue;
    state.set(id, next);
    paint(bars.get(id), next);
  }
}

/** One rAF loop re-reads the hook off the live preview window, so a reloaded iframe is followed. */
interface ClipLatch {
  lit: boolean;
  light: HTMLElement | null;
}

function useMeterLoop(
  strips: Strip[],
  bars: RefObject<Map<string | null, StripBars>>,
  iframeRef: RefObject<HTMLIFrameElement | null> | undefined,
  clip: RefObject<ClipLatch>,
) {
  const shell = useStudioShellContextOptional();
  const previewIframeRef = iframeRef ?? shell?.previewIframeRef;
  const stripsRef = useRef(strips);
  stripsRef.current = strips;
  useEffect(() => {
    let raf = 0;
    let active: AudioMeterHook | null = null;
    let last = performance.now();
    const state = new Map<string | null, Pair>();
    const tick = (now: number) => {
      raf = requestAnimationFrame(tick);
      active = followMeterHook(active, readHook(previewIframeRef?.current));
      const levels = active?.read();
      const dt = now - last;
      last = now;
      evictGoneMeterState(state, new Set(stripsRef.current.map((s) => s.id)));
      stepAndPaintStrips(stripsRef.current, state, bars.current, levels, now, dt);
      const lit = stepClipLatch(clip.current.lit, levels?.master);
      if (lit !== clip.current.lit) {
        clip.current.lit = lit;
        paintClipLight(clip.current.light, lit);
      }
    };
    raf = requestAnimationFrame(tick);
    return () => {
      cancelAnimationFrame(raf);
      try {
        active?.stop();
      } catch {
        // Preview iframe already gone.
      }
    };
  }, [previewIframeRef, bars, clip]);
}

function ClipLight({ clip }: { clip: RefObject<ClipLatch> }) {
  return (
    <button
      type="button"
      data-testid="meter-clip-light"
      data-lit="false"
      title="Lights when the preview reaches −1 dBFS, the export ceiling. Click to reset."
      ref={(el) => {
        clip.current.light = el;
        paintClipLight(el, clip.current.lit);
      }}
      onClick={() => {
        clip.current.lit = false;
        paintClipLight(clip.current.light, false);
      }}
      className="rounded-[2px] px-1 font-mono text-[9px] leading-[14px] font-bold tracking-wide"
    >
      CLIP
    </button>
  );
}

function Bar({ maskRef, peakRef }: { maskRef: Ref<HTMLDivElement>; peakRef: Ref<HTMLDivElement> }) {
  return (
    <div className="scheme-dark relative h-full w-[18px] overflow-hidden rounded-[2px] bg-neutral-900">
      <div
        className="absolute inset-x-0 bottom-0 bg-green-500"
        style={{ height: `${AMBER_AT * 100}%` }}
      />
      <div
        className="absolute inset-x-0 bg-amber-500"
        style={{ bottom: `${AMBER_AT * 100}%`, height: `${(RED_AT - AMBER_AT) * 100}%` }}
      />
      <div
        className="absolute inset-x-0 top-0 bg-red-500"
        style={{ height: `${(1 - RED_AT) * 100}%` }}
      />
      <div
        ref={maskRef}
        data-testid="meter-mask"
        className="absolute inset-x-0 top-0 bg-neutral-900"
        style={{ height: "100%" }}
      />
      <div
        ref={peakRef}
        data-testid="meter-peak"
        className="absolute inset-x-0 bottom-0 h-px bg-text-0"
      />
    </div>
  );
}

/** Uses the authored clip-gain scale; meter readings have a separate scale. */
function Fader({
  label,
  title,
  volume,
  maxPosition,
  onLive,
  onCommit,
}: {
  label: string;
  title: string;
  volume: number;
  maxPosition: number;
  onLive: (v: number) => void;
  onCommit: (v: number) => void;
}) {
  const trackRef = useRef<HTMLDivElement>(null);
  const draggingRef = useRef<number | null>(null);
  const position = audioGainToFaderPosition(volume);
  const span = maxPosition - AUDIO_GAIN_FADER_MIN;
  const fraction = (position - AUDIO_GAIN_FADER_MIN) / span;
  const readout = audioGainToText(volume);

  const positionAt = useCallback(
    (clientY: number): number => {
      const rect = trackRef.current?.getBoundingClientRect();
      if (!rect || rect.height === 0) return position;
      return (
        AUDIO_GAIN_FADER_MIN + clampNumber(1 - (clientY - rect.top) / rect.height, 0, 1) * span
      );
    },
    [position, span],
  );

  const moveTo = (clientY: number) => {
    const gain = audioFaderPositionToGain(positionAt(clientY));
    draggingRef.current = gain;
    onLive(gain);
  };
  const finishDrag = () => {
    if (draggingRef.current === null) return;
    const gain = draggingRef.current;
    draggingRef.current = null;
    onCommit(gain);
  };
  const keyPositions = new Map([
    ["ArrowUp", position + span * 0.02],
    ["ArrowDown", position - span * 0.02],
    ["PageUp", position + span * 0.1],
    ["PageDown", position - span * 0.1],
    ["Home", AUDIO_GAIN_FADER_MIN],
    ["End", maxPosition],
  ]);

  return (
    <div
      ref={trackRef}
      role="slider"
      tabIndex={0}
      aria-label={label}
      title={`${title}: ${readout}`}
      aria-orientation="vertical"
      aria-valuemin={AUDIO_GAIN_FADER_MIN}
      aria-valuemax={maxPosition}
      aria-valuenow={Math.round(position)}
      aria-valuetext={readout}
      onPointerDown={(e: ReactPointerEvent<HTMLDivElement>) => {
        e.currentTarget.setPointerCapture(e.pointerId);
        moveTo(e.clientY);
      }}
      onPointerMove={(e: ReactPointerEvent<HTMLDivElement>) => {
        if (draggingRef.current === null) return;
        moveTo(e.clientY);
      }}
      onPointerUp={finishDrag}
      onPointerCancel={finishDrag}
      onLostPointerCapture={finishDrag}
      onKeyDown={(e) => {
        const next = keyPositions.get(e.key);
        if (next === undefined) return;
        onCommit(audioFaderPositionToGain(clampNumber(next, AUDIO_GAIN_FADER_MIN, maxPosition)));
        e.preventDefault();
      }}
      className="relative h-full w-2 shrink-0 cursor-ns-resize touch-none rounded-full bg-neutral-800 focus-visible:outline focus-visible:outline-2 focus-visible:outline-studio-accent"
    >
      <div
        className="absolute inset-x-[-3px] h-1.5 -translate-y-1/2 rounded-full bg-neutral-200"
        style={{ bottom: `${fraction * 100}%` }}
      />
    </div>
  );
}

function MeterStrip({
  strip,
  register,
  onLive,
  onCommit,
  clipLight,
}: {
  strip: Strip;
  register: (id: string | null, bars: StripBars | null) => void;
  onLive: (id: string | null, volume: number) => void;
  onCommit: (id: string | null, volume: number) => void;
  clipLight?: ReactNode;
}) {
  const refs = [
    useRef<HTMLDivElement>(null),
    useRef<HTMLDivElement>(null),
    useRef<HTMLDivElement>(null),
    useRef<HTMLDivElement>(null),
  ] as const;
  useEffect(() => {
    register(strip.id, [
      { mask: refs[0].current, peak: refs[1].current },
      { mask: refs[2].current, peak: refs[3].current },
    ]);
    return () => register(strip.id, null);
    // refs are stable objects
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, [strip.id, register]);
  return (
    <div className="flex w-[104px] shrink-0 flex-col items-center gap-1 px-1.5 pt-2 pb-1">
      {clipLight}
      <div
        className="flex min-h-0 flex-1 items-stretch gap-1.5"
        aria-label={`${strip.label} level`}
      >
        <Fader
          label={`${strip.label} volume`}
          title={strip.id === null ? "Preview monitor volume" : `${strip.label} volume`}
          volume={strip.volume}
          maxPosition={strip.id === null ? audioGainToFaderPosition(1) : AUDIO_GAIN_FADER_MAX}
          onLive={(v) => onLive(strip.id, v)}
          onCommit={(v) => onCommit(strip.id, v)}
        />
        <div className="relative w-5 font-mono text-[9px] leading-none text-neutral-500">
          {METER_DB_MARKS.map((db) => (
            <span
              key={db}
              className="absolute right-0 translate-y-1/2"
              style={{ bottom: `${markFraction(db) * 100}%` }}
            >
              {db}
            </span>
          ))}
        </div>
        <div className="flex items-stretch gap-0.5">
          <Bar maskRef={refs[0]} peakRef={refs[1]} />
          <Bar maskRef={refs[2]} peakRef={refs[3]} />
        </div>
      </div>
      <span className="max-w-full truncate text-[10px] text-neutral-400" title={strip.label}>
        {strip.label}
      </span>
    </div>
  );
}

export interface AudioMeterStripProps {
  /** Pass a stable ref (useRef): a new object each render restarts the meter loop. */
  previewIframeRef?: RefObject<HTMLIFrameElement | null>;
}

export const AudioMeterStrip = memo(function AudioMeterStrip({
  previewIframeRef,
}: AudioMeterStripProps) {
  const visible = useAudioMetersVisible((s) => s.visible);
  const projectHasAudio = useProjectHasAudio();
  if (!visible || !projectHasAudio) return null;
  return <MeterStripBody previewIframeRef={previewIframeRef} />;
});

function MeterStripBody({ previewIframeRef }: AudioMeterStripProps) {
  const strips = useStrips();
  const bars = useRef(new Map<string | null, StripBars>());
  const register = useRef((id: string | null, b: StripBars | null) => {
    if (b) bars.current.set(id, b);
    else bars.current.delete(id);
  }).current;
  const { onLive, onCommit } = useVolumeHandlers();
  const clip = useRef<ClipLatch>({ lit: false, light: null });
  useMeterLoop(strips, bars, previewIframeRef, clip);
  return (
    <div
      data-testid="audio-meter-strip"
      className="flex shrink-0 overflow-x-auto border-l border-neutral-800/50 bg-neutral-950"
    >
      {strips.map((strip) => (
        <MeterStrip
          key={strip.id ?? "master"}
          strip={strip}
          register={register}
          onLive={onLive}
          onCommit={onCommit}
          clipLight={strip.id === null ? <ClipLight clip={clip} /> : undefined}
        />
      ))}
    </div>
  );
}