Skip to content

Write HTML. Render video. Built for agents.

7.9 KB
Raw Blame
import { timeAtSourceTime, type RateSpec } from "../speedRamp.js";
import { MEDIA_HARD_SYNC_SECONDS } from "./media.js";
import { playRangeHoldTime } from "./protocol.js";

export type TransportClockSnapshot = {
  time: number;
  playing: boolean;
  rate: number;
  duration: number;
  source: "monotonic" | "audio";
};

export type AudioClockSource =
  | {
      el: HTMLMediaElement;
      compositionStart: number;
      mediaStart: number;
      /** The clip's rate lane; a constant rate is read from `el.playbackRate`. */
      rate?: RateSpec;
    }
  | {
      currentTimeSeconds: number;
    };

/** GSAP's own `lagSmoothing` default — see the PR body for why this clock needs its own copy. */
const STALL_THRESHOLD_MS = 500;
const STALL_ADJUSTED_LAG_MS = 33;
const HAVE_FUTURE_DATA = 3;

export class TransportClock {
  private _baseTime = 0;
  private _playStartMs: number | null = null;
  private _rate = 1;
  private _duration = Infinity;
  private _playStart = 0;
  private _playEnd = Infinity;
  private _playHold = Infinity;
  private _nowMs: () => number;
  private _audioSource: AudioClockSource | null = null;
  /** Wall-clock time of the last `now()` read while playing; null while paused. */
  private _lastReadMs: number | null = null;
  private _lastNow = 0;

  constructor(opts?: {
    initialTime?: number;
    rate?: number;
    duration?: number;
    nowMs?: () => number;
  }) {
    this._baseTime = opts?.initialTime ?? 0;
    this._rate = opts?.rate ?? 1;
    this._duration = opts?.duration ?? Infinity;
    this._nowMs = opts?.nowMs ?? (() => performance.now());
  }

  now(): number {
    if (this._playStartMs === null) return this._baseTime;

    // Audio-master: drift is impossible because audio IS the clock. Clearing
    // `_lastReadMs` (not stamping it) means the next monotonic read starts
    // fresh from `_playStartMs` instead of a timestamp audio just made
    // meaningless — see the PR body.
    if (this._audioSource) {
      let audioTime: number | null = null;
      if ("currentTimeSeconds" in this._audioSource) {
        audioTime = this._audioSource.currentTimeSeconds;
      } else {
        audioTime = this._elementTimeNeverBehind(this._audioSource);
      }
      if (audioTime !== null) {
        const t = Math.min(audioTime, this.getEnd());
        this._baseTime = Math.max(0, t);
        this._playStartMs = this._nowMs();
        this._lastReadMs = null;
        this._lastNow = this._baseTime;
        return this._baseTime;
      }
    }

    // Monotonic fallback
    this._applyStallCorrection();
    const elapsed = (this._nowMs() - this._playStartMs) / 1000;
    const t = this._baseTime + elapsed * this._rate;
    this._lastNow = Math.max(0, Math.min(t, this.getEnd()));
    return this._lastNow;
  }

  private _elementTimeNeverBehind(
    source: Extract<AudioClockSource, { el: HTMLMediaElement }>,
  ): number | null {
    const { el, compositionStart, mediaStart, rate } = source;
    if (el.paused || !Number.isFinite(el.currentTime)) return null;
    if (el.seeking) return this._lastNow;
    const spec = rate ?? 1;
    const time = timeAtSourceTime(spec, el.currentTime - mediaStart) + compositionStart;
    return time >= this._lastNow ? time : this._heldTimeWhenBehind(el, this._lastNow - time, spec);
  }

  private _heldTimeWhenBehind(el: HTMLMediaElement, behind: number, spec: RateSpec): number | null {
    if (el.loop && behind > timeAtSourceTime(spec, el.duration) / 2) return null;
    const buffering = el.readyState < HAVE_FUTURE_DATA;
    return buffering || behind <= MEDIA_HARD_SYNC_SECONDS ? this._lastNow : null;
  }

  /** Folds a >500ms gap since the last read into `_playStartMs` so it's never reported as played time. */
  private _applyStallCorrection(): void {
    if (this._playStartMs === null) return;
    const nowMs = this._nowMs();
    if (this._lastReadMs !== null) {
      const gapMs = nowMs - this._lastReadMs;
      if (gapMs > STALL_THRESHOLD_MS) {
        this._playStartMs += gapMs - STALL_ADJUSTED_LAG_MS;
      }
    }
    this._lastReadMs = nowMs;
  }

  play(): boolean {
    if (this._playStartMs !== null) return false;
    if (this._baseTime >= this.getEnd()) return false;
    this._playStartMs = this._nowMs();
    this._lastNow = this._baseTime;
    // Not a stall: the gap since the clock was last read (possibly a long
    // paused idle) says nothing about lost playback time, since none was
    // playing. `_applyStallCorrection` treats null as "nothing to compare
    // against yet" and starts the window fresh from the next read.
    this._lastReadMs = null;
    return true;
  }

  pause(): boolean {
    if (this._playStartMs === null) return false;
    this._baseTime = this.now();
    this._playStartMs = null;
    return true;
  }

  seek(timeSeconds: number): void {
    const clamped = Number.isFinite(this._duration)
      ? Math.max(0, Math.min(timeSeconds, this._duration))
      : Math.max(0, timeSeconds);
    this._baseTime = clamped;
    this._lastNow = clamped;
    if (this._playStartMs !== null) {
      this._playStartMs = this._nowMs();
      // Same reasoning as `play()`: the seek itself, not any elapsed gap
      // since the last read, is why the reported time is moving now.
      this._lastReadMs = null;
    }
  }

  isPlaying(): boolean {
    return this._playStartMs !== null;
  }

  setRate(rate: number): void {
    const safe = Number.isFinite(rate) && rate > 0 ? Math.max(0.1, Math.min(5, rate)) : 1;
    if (this._playStartMs !== null) {
      this._baseTime = this.now();
      this._playStartMs = this._nowMs();
      this._lastReadMs = null;
    }
    this._rate = safe;
  }

  getRate(): number {
    return this._rate;
  }

  setDuration(duration: number): void {
    this._duration = Number.isFinite(duration) && duration > 0 ? duration : Infinity;
    if (this._baseTime > this._duration) {
      this._baseTime = this._duration;
    }
  }

  getDuration(): number {
    return this._duration;
  }

  setPlayRange(start: number, end: number | null, fps: number): void {
    this._playStart = Number.isFinite(start) && start > 0 ? start : 0;
    this._playEnd = end !== null && Number.isFinite(end) && end > this._playStart ? end : Infinity;
    this._playHold = playRangeHoldTime(this._playStart, this._playEnd, fps);
  }

  getPlayStart(): number {
    return this._playStart;
  }

  getEnd(): number {
    return Math.min(this._duration, this._playEnd);
  }

  /** Where a stop parks: the film's end, or a range's last frame, since the moment is [start, end). */
  getStopTime(): number {
    return this._playEnd < this._duration ? this._playHold : this.getEnd();
  }

  attachAudioSource(source: AudioClockSource): void {
    this._audioSource = source;
  }

  detachAudioSource(): void {
    if (this._audioSource && this._playStartMs !== null) {
      this._baseTime = this.now();
      this._playStartMs = this._nowMs();
      // Falling back to monotonic timing fresh, same reasoning as `play()`:
      // any gap while audio was the time source is not a monotonic stall.
      this._lastReadMs = null;
    }
    this._audioSource = null;
  }

  /** The element the playhead currently follows, if the source is one. */
  audioElement(): HTMLMediaElement | null {
    return this._audioSource && "el" in this._audioSource ? this._audioSource.el : null;
  }

  hasAudioSource(): boolean {
    return this._audioSource !== null;
  }

  getSource(): "monotonic" | "audio" {
    if (this._audioSource && this._playStartMs !== null) {
      if ("currentTimeSeconds" in this._audioSource) return "audio";
      const { el } = this._audioSource;
      if (!el.paused && Number.isFinite(el.currentTime)) return "audio";
    }
    return "monotonic";
  }

  snapshot(): TransportClockSnapshot {
    return {
      time: this.now(),
      playing: this.isPlaying(),
      rate: this._rate,
      duration: this._duration,
      source: this.getSource(),
    };
  }

  reachedEnd(): boolean {
    const time = this.now();
    return time >= this.getEnd() || (this._playStartMs === null && time >= this.getStopTime());
  }
}