Skip to content

Write HTML. Render video. Built for agents.

4.0 KB
Raw Blame
import {
  clampPlaybackRate,
  readAuthoredDurationSeconds,
  readDataDurationSeconds,
  readMediaOffsetSeconds,
  readPlaybackRate,
  resolveMediaDuration,
  resolveNaturalDurationSeconds,
} from "@hyperframes/parsers/media-duration";
import { resolveRateSpec, timeAtSourceTime, type RateSpec } from "../speedRamp";
import { isImageElement, isMediaElement } from "./domRealm";
import { parseNumeric } from "./startExpression";

export const normalizePlaybackRate = clampPlaybackRate;

/** Parse a literal numeric timing attribute without accepting trailing units or garbage. */
export function parseStrictFiniteTimingNumber(raw: string | null | undefined): number | null {
  return parseNumeric(raw);
}

export function readElementPlaybackRate(el: Pick<Element, "getAttribute">): number {
  return readPlaybackRate(
    (name) => el.getAttribute(name),
    isMediaElement(el) ? el.defaultPlaybackRate : 1,
  );
}

/** A constant rate clamped to the shared range; a lane is already normalised by its parser. */
export function normalizeRateSpec(spec: RateSpec | undefined): RateSpec {
  return typeof spec === "object" ? spec : normalizePlaybackRate(spec ?? 1);
}

/** The clip's rate: its `rate` lane when present, otherwise the constant rate. */
export function readElementRateSpec(el: Pick<Element, "getAttribute">): RateSpec {
  return resolveRateSpec(el.getAttribute("data-automation"), readElementPlaybackRate(el));
}

export function readMediaStart(el: Pick<Element, "getAttribute">): number {
  return readMediaOffsetSeconds((name) => el.getAttribute(name));
}

export function resolveNaturalMediaTimelineDuration(
  el: Pick<Element, "getAttribute">,
  sourceDuration: number,
): number | null {
  return resolveNaturalMediaTimelineDurationFromValues(
    sourceDuration,
    readMediaStart(el),
    readElementRateSpec(el),
  );
}

/**
 * How long a media element occupies the timeline: an authored `data-duration` trim, otherwise
 * the source's natural length adjusted for playback start and rate (lane-aware). `null` while
 * the source has not reported a duration yet. The authored/pending decision is the shared
 * parsers resolver's; only a `rate` lane's arithmetic stays here, because lanes live in core.
 */
export function resolveMediaElementDurationSeconds(
  el: Pick<Element, "getAttribute"> & { duration: number },
): number | null {
  const resolved = resolveMediaDuration({
    tag: "video", // video and audio resolve identically
    authoredDurationSeconds: readDataDurationSeconds((name) => el.getAttribute(name)),
    sourceDurationSeconds: Number.isFinite(el.duration) ? el.duration : null,
    mediaStartSeconds: readMediaStart(el),
    playbackRate: readElementPlaybackRate(el),
  });
  return resolved.source === "media"
    ? resolveNaturalMediaTimelineDuration(el, el.duration)
    : resolved.seconds;
}

/** A timed `<img>` (`data-start` or `data-track-index`) gets the dropped-image default unless
 *  trimmed by `data-duration` or `data-end`; a bare `<img>` is a static layer. `null` otherwise. */
export function resolveTimedImageDurationSeconds(el: Element, startSeconds = 0): number | null {
  if (!isImageElement(el)) return null;
  if (!el.hasAttribute("data-start") && !el.hasAttribute("data-track-index")) return null;
  return resolveMediaDuration({
    tag: "img",
    authoredDurationSeconds: readAuthoredDurationSeconds(
      (name) => el.getAttribute(name),
      startSeconds,
    ),
    sourceDurationSeconds: null,
    mediaStartSeconds: 0,
    playbackRate: 1,
  }).seconds;
}

/** A constant rate goes through the shared arithmetic; a `rate` lane integrates over its points. */
export function resolveNaturalMediaTimelineDurationFromValues(
  sourceDuration: number,
  mediaStart: number,
  playbackRate: RateSpec,
): number | null {
  if (typeof playbackRate === "number") {
    return resolveNaturalDurationSeconds(sourceDuration, mediaStart, playbackRate);
  }
  if (!Number.isFinite(sourceDuration)) return null;
  return timeAtSourceTime(playbackRate, Math.max(0, sourceDuration - mediaStart));
}