Skip to content

Open source CapCut alternative.

TypeScript
4.8 KB
Raw Blame
"use client";

/**
 * Where the preview is, and where the mouse is hovering over the timeline.
 *
 * These two numbers change more often than anything else in Cut — sixty times a
 * second while playing, and once per pointer event while dragging. They used to
 * live in the editor store beside the clips, which meant every one of those
 * changes ran the document's write normalizer and woke every mounted selector
 * in the editor, a few hundred of them, to ask whether a title bar had moved.
 *
 * So they live here instead, in the smallest store that can hold them: a
 * number, a set of listeners, and nothing else. Surfaces that draw the playhead
 * subscribe; surfaces that only need to know where it is when the user does
 * something read it directly. The document store is left to describe the
 * document.
 *
 * The clamp to the project's length lives with the callers that know the
 * length. This module holds a time and tells people it changed.
 */

import { useSyncExternalStore } from "react";
import { markSeek } from "./perfTrace";

let at = 0;
let skim: number | null = null;
const listeners = new Set<() => void>();

function notify() {
  for (const fn of listeners) fn();
}

function subscribe(fn: () => void) {
  listeners.add(fn);
  return () => {
    listeners.delete(fn);
  };
}

/**
 * Run `fn` on every move, outside React.
 *
 * For surfaces whose whole response to the clock is one DOM write — the
 * playhead's transform, the grade on the picture. Re-rendering a component to
 * set one style property costs a reconcile per frame and buys nothing.
 */
export const subscribePlayhead = subscribe;

/** The playhead, in timeline seconds. */
export const playheadAt = () => at;

/** The frame rate the paused playhead steps at. */
const STEP_FPS = 30;

/** How far off a frame, in frames, still counts as on it. */
const ON_FRAME = 1e-6;

/**
 * The frame one step from `t`, forward for `dir` 1 and back for -1, as
 * exactly k / 30. Adding 1/30 drifts a hair under the frame (283 steps make
 * 9.4333…32), and a title cut in on that frame would not show yet while the
 * block under it had. A playhead between frames steps to the next one its way.
 */
export function stepFrame(t: number, dir: 1 | -1): number {
  const f = t * STEP_FPS;
  const k = dir > 0 ? Math.floor(f + ON_FRAME) + 1 : Math.ceil(f - ON_FRAME) - 1;
  return k / STEP_FPS;
}

/** The skimmer, or null when the pointer is off the timeline. */
export const skimAt = () => skim;

/**
 * The time the picture should show: the skimmer while one is live, the playhead
 * otherwise. One place decides this, so the preview and everything drawing
 * against the preview agree on which moment is on screen.
 */
export const previewAt = () => skim ?? at;

/** Move the playhead. Callers clamp to the project length first. */
export function setPlayhead(t: number): void {
  if (t === at) return;
  at = t;
  markSeek(t);
  notify();
}

export function setSkim(t: number | null): void {
  if (t === skim) return;
  skim = t;
  if (t !== null) markSeek(t);
  notify();
}

/**
 * Hold the playhead inside a timeline that just got shorter. Deleting the last
 * of a long row leaves the playhead standing past the new end, which puts the
 * readout ahead of the total and — since the playhead is placed with a
 * transform, and transforms count toward scrollable overflow — stretches the
 * scroll area into empty space.
 */
export function clampPlayhead(total: number): void {
  if (at > total) setPlayhead(total);
}

/** The playhead, as a subscription. Re-renders the caller on every change. */
export function usePlayhead(): number {
  return useSyncExternalStore(subscribe, playheadAt, () => 0);
}

export function useSkim(): number | null {
  return useSyncExternalStore(subscribe, skimAt, () => null);
}

export function usePreviewTime(): number {
  return useSyncExternalStore(subscribe, previewAt, () => 0);
}

/**
 * Something the preview time decides, without re-rendering when only the time
 * moved — whether a cue is the one being spoken, whether a clip is on screen.
 * `select` must return a primitive: React compares snapshots by identity, and a
 * fresh object every read would loop.
 */
export function usePreviewSelector<T extends string | number | boolean | null>(
  select: (t: number) => T
): T {
  return useSyncExternalStore(
    subscribe,
    () => select(previewAt()),
    () => select(0)
  );
}

/**
 * The preview time rounded to `steps` per second, for surfaces that want the
 * clock without wanting every frame of it — a picker's swatches, a panel's
 * live thumbnail. Rounding inside the snapshot means React compares the coarse
 * value and skips the render, so a 2 Hz caller re-renders twice a second while
 * the preview runs at sixty.
 */
export function usePreviewTimeEvery(steps: number): number {
  return useSyncExternalStore(
    subscribe,
    () => Math.round(previewAt() * steps),
    () => 0
  );
}