mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-18 07:50:13 +00:00
* fix(core): audio no longer plays fast for a moment after Play * refactor(core): split the audio start wait out of the clock read
276 lines
9.1 KiB
TypeScript
276 lines
9.1 KiB
TypeScript
import { timeAtSourceTime, type RateSpec } from "../speedRamp.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;
|
|
webAudio?: boolean;
|
|
};
|
|
|
|
/** 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;
|
|
const AUDIO_START_WAIT_MS = 1500;
|
|
const MEDIA_SYNC_STEER_TOLERANCE_SECONDS = 0.04;
|
|
|
|
type PendingAudioStart = { sinceMs: number; at: number; from: number | null };
|
|
|
|
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;
|
|
private _audioStart: PendingAudioStart | null = null;
|
|
|
|
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;
|
|
}
|
|
}
|
|
|
|
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;
|
|
const spec = rate ?? 1;
|
|
const time = timeAtSourceTime(spec, el.currentTime - mediaStart) + compositionStart;
|
|
const held = this._heldUntilAudioOutputStarts(el.seeking, time);
|
|
if (held !== undefined) return held;
|
|
if (time >= this._lastNow) return time;
|
|
const wrapped = el.loop && this._lastNow - time > timeAtSourceTime(spec, el.duration) / 2;
|
|
return !wrapped && el.readyState < HAVE_FUTURE_DATA ? this._lastNow : null;
|
|
}
|
|
|
|
private _heldUntilAudioOutputStarts(seeking: boolean, time: number): number | null | undefined {
|
|
const pending = this._pendingAudioStart();
|
|
if (seeking) return pending ? this._lastNow : null;
|
|
if (!pending) return undefined;
|
|
pending.from ??= time;
|
|
const startsHere = Math.abs(pending.from - pending.at) <= MEDIA_SYNC_STEER_TOLERANCE_SECONDS;
|
|
if (startsHere && time === pending.from) return time;
|
|
this._audioStart = null;
|
|
return undefined;
|
|
}
|
|
|
|
private _pendingAudioStart(): PendingAudioStart | null {
|
|
const pending = this._audioStart;
|
|
if (pending && this._nowMs() - pending.sinceMs > AUDIO_START_WAIT_MS) this._audioStart = null;
|
|
return this._audioStart;
|
|
}
|
|
|
|
/** 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._audioStart = { sinceMs: this._playStartMs, at: this._baseTime, from: null };
|
|
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();
|
|
this._audioStart = { sinceMs: this._playStartMs, at: clamped, from: null };
|
|
// 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. */
|
|
// fallow-ignore-next-line unused-class-member
|
|
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";
|
|
}
|
|
|
|
followedClock(): "audio" | "webaudio" | "monotonic" {
|
|
if (this.getSource() === "monotonic") return "monotonic";
|
|
return this._audioSource && "webAudio" in this._audioSource && this._audioSource.webAudio
|
|
? "webaudio"
|
|
: "audio";
|
|
}
|
|
|
|
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());
|
|
}
|
|
}
|