mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-19 00:18:27 +00:00
* fix(studio): serve files whose name has a bare percent sign A browser sends src="100%.png" with the % unescaped, and decoding the whole path threw, so Studio answered 500. Only well-formed escapes are decoded now. * fix(cli): serve files with a bare percent sign from the check and snapshot server One shared decode rule for request paths; the image thumbnail route's malformed-escape 400 could no longer fire, so a name that is not a file is a 404. * fix(cli): name a failed file with a bare percent sign in check * fix(studio): keep apostrophes and dollar signs in file names when editing attributes An attribute value is matched by its own quote kind, so src="it's.png" is replaced instead of duplicated, and every insert uses a function replacer, so $1 or $& in a file name is written as is. * fix(studio): rename references spelled with %20 or & and read quoted media sources WIP: not yet tested; see the resume note. * fix(studio): match whole attribute names when editing media sources * fix(studio): compare decoded names and escape replacement references * fix(studio): preserve file references across URL and string consumers * docs: clarify raw file references and URL fields * fix(studio): keep raw path identity distinct from URL spelling * fix: share attribute grammar and decode media URLs at their readers * fix: preserve local filename identity in HTML URL output * fix: decode entity references before rename candidate matching * style: format rename entity handling and regressions * fix: preserve platform file identity when renaming references * fix(core): decode CSS escapes before rebasing asset URLs * fix(core): consume CSS continuations before URL encoding * fix(core): preserve CSS URL identity and escape rebased suffixes * fix(core): express CSS suffix controls with Unicode categories * fix(core): preserve URL backslash identity while rebasing * test(core): respect platform backslash filename semantics * fix(studio): a dropped file with %, # or ? in its name loads, and an encoded reference renames * fix(studio): read an authored src as a URL so dropped files with spaces, %, # or ? load * fix(studio): media routes find files named with ? or #, and the probe reads a src as a URL * fix(studio-server): one rule for request file paths, so loudness finds files named with %, # or ? * chore: drop the design note from the change * fix(core): rename replaced clips whose src is URL-encoded
362 lines
12 KiB
TypeScript
362 lines
12 KiB
TypeScript
/**
|
|
* Timing Compiler
|
|
*
|
|
* Shared, pure HTML compilation that normalizes timing attributes.
|
|
* Works in both Node.js and browser without a DOM.
|
|
*
|
|
* Guarantees every timed element gets:
|
|
* - id on media elements when missing
|
|
* - data-end (computed from data-start + data-duration when possible)
|
|
* - data-has-audio on <video> elements (false for muted visual-only videos)
|
|
*
|
|
* For elements without data-duration (e.g. videos relying on source duration),
|
|
* this compiler identifies them as "unresolved" so the caller can provide
|
|
* durations via an environment-specific resolver (ffprobe, el.duration, etc.)
|
|
* and call injectDurations() to complete the compilation.
|
|
*
|
|
* Relative `data-start` (`intro`, `intro + 0.5`) is not numeric — leave
|
|
* `data-end` off so extract can resolve the id-ref later.
|
|
*/
|
|
|
|
import { scanHtmlOpeningTags, decodeAuthoredAttribute } from "@hyperframes/parsers";
|
|
import { parseNumeric } from "@hyperframes/parsers/composition-contract";
|
|
import {
|
|
parseStrictFiniteTimingNumber,
|
|
readElementRateSpec,
|
|
readMediaStart,
|
|
} from "../runtime/playbackRate.js";
|
|
import type { RateSpec } from "../speedRamp.js";
|
|
// ── Types ────────────────────────────────────────────────────────────────
|
|
|
|
export interface UnresolvedElement {
|
|
id: string;
|
|
tagName: string;
|
|
src?: string;
|
|
start: number;
|
|
end?: number;
|
|
duration?: number;
|
|
mediaStart: number;
|
|
playbackRate: RateSpec;
|
|
compositionSrc?: string;
|
|
}
|
|
|
|
export interface ResolvedDuration {
|
|
id: string;
|
|
duration: number;
|
|
}
|
|
|
|
export interface ResolvedMediaElement {
|
|
id: string;
|
|
tagName: string;
|
|
src?: string;
|
|
start: number;
|
|
duration: number;
|
|
mediaStart: number;
|
|
playbackRate: RateSpec;
|
|
loop: boolean;
|
|
}
|
|
|
|
export interface CompilationResult {
|
|
html: string;
|
|
unresolved: UnresolvedElement[];
|
|
}
|
|
|
|
// ffprobe precision can differ slightly across local and CI media stacks, so
|
|
// avoid shortening authored audio for insignificant probe drift.
|
|
export const MEDIA_DURATION_CLAMP_EPSILON_SECONDS = 0.05;
|
|
|
|
export function shouldClampMediaDuration(declaredDuration: number, maxDuration: number): boolean {
|
|
return declaredDuration > maxDuration + MEDIA_DURATION_CLAMP_EPSILON_SECONDS;
|
|
}
|
|
|
|
/**
|
|
* Whether compilation should shorten an authored media slot to its source.
|
|
*
|
|
* Non-looping video intentionally keeps an explicit longer slot: browsers and
|
|
* the render frame injector hold its final frame until that authored slot ends.
|
|
* Audio has no frame to hold, so its slot remains bounded by playable source.
|
|
*/
|
|
export function shouldClampResolvedMediaDuration(
|
|
tagName: ResolvedMediaElement["tagName"],
|
|
declaredDuration: number,
|
|
maxDuration: number,
|
|
): boolean {
|
|
return tagName === "audio" && shouldClampMediaDuration(declaredDuration, maxDuration);
|
|
}
|
|
|
|
// ── Helpers ──────────────────────────────────────────────────────────────
|
|
|
|
function sourceAttribute(tag: string, name: string) {
|
|
return scanHtmlOpeningTags(tag)[0]?.attributes.find((attr) => attr.name === name);
|
|
}
|
|
|
|
function getAttr(tag: string, name: string): string | null {
|
|
return tagAttrReader(tag).getAttribute(name);
|
|
}
|
|
|
|
function tagAttrReader(tag: string): Pick<Element, "getAttribute"> {
|
|
const attributes = scanHtmlOpeningTags(tag)[0]?.attributes ?? [];
|
|
return {
|
|
getAttribute: (name) => {
|
|
const attr = attributes.find((attr) => attr.name === name);
|
|
return attr?.kind === "value" ? decodeAuthoredAttribute(attr.value) : null;
|
|
},
|
|
};
|
|
}
|
|
|
|
function hasAttr(tag: string, name: string): boolean {
|
|
return sourceAttribute(tag, name) !== undefined;
|
|
}
|
|
|
|
function injectAttr(tag: string, attr: string, value: string): string {
|
|
return tag.replace(/>$/, ` ${attr}="${value}">`);
|
|
}
|
|
|
|
function setAttr(tag: string, name: string, value: string): string {
|
|
const attr = sourceAttribute(tag, name);
|
|
if (!attr) return injectAttr(tag, name, value);
|
|
return tag.slice(0, attr.start) + `${name}="${value}"` + tag.slice(attr.end);
|
|
}
|
|
|
|
function* iterateOpeningTags(html: string, names: readonly string[]) {
|
|
for (const span of scanHtmlOpeningTags(html)) {
|
|
if (span.closed && names.includes(span.name)) {
|
|
yield { tag: html.slice(span.start, span.end), index: span.start, end: span.end };
|
|
}
|
|
}
|
|
}
|
|
|
|
function replaceOpeningTags(
|
|
html: string,
|
|
names: readonly string[],
|
|
replace: (tag: string) => string,
|
|
): string {
|
|
const parts: string[] = [];
|
|
let cursor = 0;
|
|
for (const { tag, index, end } of iterateOpeningTags(html, names)) {
|
|
parts.push(html.slice(cursor, index), replace(tag));
|
|
cursor = end;
|
|
}
|
|
parts.push(html.slice(cursor));
|
|
return parts.join("");
|
|
}
|
|
|
|
function replaceIdTags(html: string, id: string, replace: (tag: string) => string): string {
|
|
const parts: string[] = [];
|
|
let cursor = 0;
|
|
for (const span of scanHtmlOpeningTags(html)) {
|
|
if (!span.closed) continue;
|
|
const tag = html.slice(span.start, span.end);
|
|
const attr = span.attributes.find((attr) => attr.name === "id");
|
|
if (attr?.kind !== "value" || decodeAuthoredAttribute(attr.value) !== id) continue;
|
|
parts.push(html.slice(cursor, span.start), replace(tag));
|
|
cursor = span.end;
|
|
}
|
|
parts.push(html.slice(cursor));
|
|
return parts.join("");
|
|
}
|
|
|
|
function withDefaultTimingAttrs(tag: string, tagName: string, generateId: () => number) {
|
|
let result = tag;
|
|
let id = getAttr(result, "id");
|
|
if (!id) {
|
|
id = `hf-${tagName}-${generateId()}`;
|
|
result = injectAttr(result, "id", id);
|
|
}
|
|
let startStr = getAttr(result, "data-start");
|
|
if (startStr === null) {
|
|
result = injectAttr(result, "data-start", "0");
|
|
result = injectAttr(result, "data-hf-auto-start", "");
|
|
startStr = "0";
|
|
}
|
|
return { tag: result, id, start: parseNumeric(startStr) };
|
|
}
|
|
|
|
function withVideoAudioFlag(tag: string, isVideo: boolean): string {
|
|
if (!isVideo || hasAttr(tag, "data-has-audio")) return tag;
|
|
return injectAttr(tag, "data-has-audio", hasAttr(tag, "muted") ? "false" : "true");
|
|
}
|
|
|
|
function compileTag(
|
|
tag: string,
|
|
isVideo: boolean,
|
|
generateId: () => number,
|
|
): { tag: string; unresolved: UnresolvedElement | null } {
|
|
const tagName = isVideo ? "video" : "audio";
|
|
const defaults = withDefaultTimingAttrs(tag, tagName, generateId);
|
|
let result = defaults.tag;
|
|
let unresolved: UnresolvedElement | null = null;
|
|
const { id, start } = defaults;
|
|
const attrReader = tagAttrReader(result);
|
|
const mediaStart = readMediaStart(attrReader);
|
|
const playbackRate = readElementRateSpec(attrReader);
|
|
|
|
// 1. Compute data-end from data-start + data-duration. Skip relative id-refs.
|
|
if (!hasAttr(result, "data-end")) {
|
|
const durationStr = getAttr(result, "data-duration");
|
|
const duration = parseStrictFiniteTimingNumber(durationStr);
|
|
if (duration != null) {
|
|
if (start != null) {
|
|
result = injectAttr(result, "data-end", String(start + duration));
|
|
}
|
|
} else {
|
|
// No data-duration: mark as unresolved so caller can provide it
|
|
unresolved = {
|
|
id,
|
|
tagName,
|
|
src: getAttr(result, "src") ?? undefined,
|
|
start: start ?? 0,
|
|
mediaStart,
|
|
playbackRate,
|
|
};
|
|
}
|
|
}
|
|
|
|
result = withVideoAudioFlag(result, isVideo);
|
|
|
|
return { tag: result, unresolved };
|
|
}
|
|
|
|
/**
|
|
* Compile timing attributes in HTML.
|
|
*
|
|
* Phase 1 (static): Adds data-end where data-duration exists,
|
|
* adds data-has-audio on videos.
|
|
*
|
|
* Returns the compiled HTML and a list of elements that could not be
|
|
* resolved statically (missing data-duration). The caller should resolve
|
|
* these via ffprobe / el.duration and call injectDurations().
|
|
*/
|
|
export function compileTimingAttrs(html: string): CompilationResult {
|
|
const unresolved: UnresolvedElement[] = [];
|
|
let nextVideoId = 0;
|
|
let nextAudioId = 0;
|
|
|
|
// Process <video ...> tags
|
|
html = replaceOpeningTags(html, ["video"], (match) => {
|
|
const { tag, unresolved: u } = compileTag(match, true, () => nextVideoId++);
|
|
if (u) unresolved.push(u);
|
|
return tag;
|
|
});
|
|
|
|
// Process <audio ...> tags
|
|
html = replaceOpeningTags(html, ["audio"], (match) => {
|
|
const { tag, unresolved: u } = compileTag(match, false, () => nextAudioId++);
|
|
if (u) unresolved.push(u);
|
|
return tag;
|
|
});
|
|
|
|
// Identify unresolved timed elements (divs with data-start but no data-end/data-duration)
|
|
// These are typically compositions whose duration depends on GSAP timelines
|
|
for (const { tag: match } of iterateOpeningTags(html, ["div", "section"])) {
|
|
if (!hasAttr(match, "data-start")) continue;
|
|
if (hasAttr(match, "data-end") || hasAttr(match, "data-duration")) continue;
|
|
|
|
const id = getAttr(match, "id");
|
|
const compositionSrc = getAttr(match, "data-composition-src");
|
|
if (id) {
|
|
const startStr = getAttr(match, "data-start");
|
|
unresolved.push({
|
|
id,
|
|
tagName: "div",
|
|
start: parseNumeric(startStr) ?? 0,
|
|
mediaStart: 0,
|
|
playbackRate: 1,
|
|
compositionSrc: compositionSrc ?? undefined,
|
|
});
|
|
}
|
|
}
|
|
|
|
return { html, unresolved };
|
|
}
|
|
|
|
/**
|
|
* Inject resolved durations into compiled HTML.
|
|
*
|
|
* For each resolved element, adds data-duration and data-end attributes.
|
|
* Call this after resolving durations via ffprobe, el.duration, or
|
|
* GSAP timeline queries.
|
|
*/
|
|
export function injectDurations(html: string, resolutions: ResolvedDuration[]): string {
|
|
for (const { id, duration } of resolutions) {
|
|
// Match the element's opening tag by id
|
|
html = replaceIdTags(html, id, (tag) => {
|
|
let result = tag;
|
|
|
|
// Add data-duration if missing
|
|
if (parseStrictFiniteTimingNumber(getAttr(result, "data-duration")) == null) {
|
|
result = setAttr(result, "data-duration", String(duration));
|
|
}
|
|
|
|
// Add data-end if missing. Skip relative id-refs.
|
|
if (!hasAttr(result, "data-end")) {
|
|
const start = parseNumeric(getAttr(result, "data-start"));
|
|
if (start != null) {
|
|
result = injectAttr(result, "data-end", String(start + duration));
|
|
}
|
|
}
|
|
|
|
return result;
|
|
});
|
|
}
|
|
|
|
return html;
|
|
}
|
|
|
|
/**
|
|
* Extract video/audio elements that already have data-duration set.
|
|
* Used by callers to validate declared durations against actual source durations.
|
|
*/
|
|
export function extractResolvedMedia(html: string): ResolvedMediaElement[] {
|
|
const resolved: ResolvedMediaElement[] = [];
|
|
|
|
for (const { tag } of iterateOpeningTags(html, ["video", "audio"])) {
|
|
const id = getAttr(tag, "id");
|
|
const durationStr = getAttr(tag, "data-duration");
|
|
if (!id || durationStr === null) continue;
|
|
|
|
const duration = parseStrictFiniteTimingNumber(durationStr);
|
|
if (duration == null || duration <= 0) continue;
|
|
|
|
const isVideo = /^<video/i.test(tag);
|
|
const startStr = getAttr(tag, "data-start");
|
|
const attrReader = tagAttrReader(tag);
|
|
|
|
resolved.push({
|
|
id,
|
|
tagName: isVideo ? "video" : "audio",
|
|
src: getAttr(tag, "src") ?? undefined,
|
|
start: parseNumeric(startStr) ?? 0,
|
|
duration,
|
|
mediaStart: readMediaStart(attrReader),
|
|
playbackRate: readElementRateSpec(attrReader),
|
|
loop: hasAttr(tag, "loop"),
|
|
});
|
|
}
|
|
|
|
return resolved;
|
|
}
|
|
|
|
/**
|
|
* Clamp existing data-duration and data-end on media elements.
|
|
* For each resolution, replaces the declared duration with the clamped value
|
|
* and recomputes data-end accordingly.
|
|
*/
|
|
export function clampDurations(html: string, clamps: ResolvedDuration[]): string {
|
|
for (const { id, duration } of clamps) {
|
|
html = replaceIdTags(html, id, (tag) => {
|
|
// Replace data-duration value
|
|
if (hasAttr(tag, "data-duration")) tag = setAttr(tag, "data-duration", String(duration));
|
|
|
|
const start = parseNumeric(getAttr(tag, "data-start"));
|
|
if (start != null && hasAttr(tag, "data-end")) {
|
|
tag = setAttr(tag, "data-end", String(start + duration));
|
|
}
|
|
|
|
return tag;
|
|
});
|
|
}
|
|
|
|
return html;
|
|
}
|