Skip to content

armgit / hypit

Public Imported from GitHub
0

Clone any viral video with AI agents. Not just a script, the whole workflow: swap the face, the words, the B-roll, ship 100 variants in one command, and get your 100M views.

fix(timeline): preflight exact-frame placements (#355)

Flanderne0f26d189a44
diff --git a/packages/timeline-author/src/program.ts b/packages/timeline-author/src/program.ts
index 811fd689..c9aa4057 100644
--- a/packages/timeline-author/src/program.ts
+++ b/packages/timeline-author/src/program.ts
@@ -1,5 +1,5 @@
import { assertProgramClockIdentity, type ProgramClock } from "@hypit/program-space";
-import { durationInFrames } from "@hypit/temporal";
+import { durationInFrames, type TemporalDuration } from "@hypit/temporal";
import { parseTemporalDuration } from "@hypit/temporal-markup";
import { assertSemanticTakeIdentity } from "@hypit/speech";
import type { SemanticTake } from "@hypit/speech";
@@ -93,15 +93,24 @@ export function placementExpression(expression: string, reference: string) {
duration: parseTemporalDuration(match[2]!, "Timeline offset") };
}
+function exactPlacementFrames(expression: string, duration: TemporalDuration, clock: ProgramClock): number {
+ const frames = durationInFrames(duration, clock);
+ if (frames.denominator !== 1n || frames.numerator > BigInt(Number.MAX_SAFE_INTEGER)) {
+ throw new Error(`Timeline duration ${expression} must land on an exact frame boundary.`);
+ }
+ return Number(frames.numerator);
+}
+
+export function assertPlacementFrameBoundary(expression: string, clock: ProgramClock, reference: string): void {
+ const parsed = placementExpression(expression, reference);
+ exactPlacementFrames(expression, parsed.duration, clock);
+}
+
/** Resolve local assembly expressions before a complete Timeline exists. */
export function placementFrame(expression: string, clock: ProgramClock, base: number | undefined, reference: string): number {
const parsed = placementExpression(expression, reference);
if (parsed.relative && base === undefined) throw new Error(`${reference} has no preceding Take.`);
- const frames = durationInFrames(parsed.duration, clock);
- if (frames.denominator !== 1n || frames.numerator > BigInt(Number.MAX_SAFE_INTEGER)) {
- throw new Error(`Timeline duration ${expression} must land on an exact frame boundary.`);
- }
- const frame = (parsed.relative ? base! : 0) + parsed.sign * Number(frames.numerator);
+ const frame = (parsed.relative ? base! : 0) + parsed.sign * exactPlacementFrames(expression, parsed.duration, clock);
if (!Number.isSafeInteger(frame) || frame < 0) throw new Error(`Timeline position ${expression} must resolve to a non-negative frame.`);
return frame;
}
diff --git a/packages/timeline-author/src/surface.ts b/packages/timeline-author/src/surface.ts
index b71ca696..dc713df7 100644
--- a/packages/timeline-author/src/surface.ts
+++ b/packages/timeline-author/src/surface.ts
@@ -1,5 +1,5 @@
-import { placementExpression } from "./program.js";
-import { programSpaceTypes } from "@hypit/program-space";
+import { assertPlacementFrameBoundary, placementExpression } from "./program.js";
+import { assertProgramClockIdentity, programSpaceTypes, type ProgramClock } from "@hypit/program-space";
import { assertAttributes, assertEmptyElement, localName, textAttribute, type StructuredSurfaceHandler } from "@hypit/markup";
import { sameType } from "@hypit/protocol";
import { speechTypes } from "@hypit/speech";
@@ -12,7 +12,24 @@ export const decodeTimelineAuthorSurface: StructuredSurfaceHandler = ({ element,
const rawClock = element.attributes.clock;
const clock = typeof rawClock === "object" && rawClock.kind === "reference" ? resolveReference(rawClock.path) : undefined;
if (clock === undefined || !sameType(clock.type, programSpaceTypes.clock)) throw new Error(`${element.name}.clock must reference a Clock.`);
- if (element.attributes.end !== undefined) placementExpression(textAttribute(element, "end"), "content.end");
+ const clockValue = clock.record?.value;
+ const staticClock = clockValue?.kind === "inline" ? clockValue.value as unknown as ProgramClock : undefined;
+ if (staticClock !== undefined) assertProgramClockIdentity(staticClock);
+ const checkBoundary = (expression: string, reference: string, subject: string): void => {
+ if (staticClock === undefined) return;
+ try {
+ assertPlacementFrameBoundary(expression, staticClock, reference);
+ } catch (error) {
+ if (!(error instanceof Error)) throw error;
+ const { numerator, denominator } = staticClock.frameRate;
+ throw new Error(`Timeline ${id} ${subject} at ${numerator}/${denominator} fps: ${error.message}`);
+ }
+ };
+ if (element.attributes.end !== undefined) {
+ const end = textAttribute(element, "end");
+ placementExpression(end, "content.end");
+ checkBoundary(end, "content.end", "end");
+ }
const at: string[] = [];
const takes = element.children.flatMap(child => {
if (child.kind === "text") {
@@ -24,6 +41,7 @@ export const decodeTimelineAuthorSurface: StructuredSurfaceHandler = ({ element,
at.push(child.attributes.at === undefined ? (at.length === 0 ? "0f" : "previous.end") : textAttribute(child, "at"));
const position = placementExpression(at.at(-1)!, "previous.end");
if (at.length === 1 && position.relative) throw new Error("The first Timeline Take has no previous.end.");
+ checkBoundary(at.at(-1)!, "previous.end", `Take ${at.length}.at`);
assertEmptyElement(child);
const source = child.attributes.source;
if (typeof source !== "object" || source.kind !== "reference") throw new Error("Timeline Take source must be a reference.");
diff --git a/packages/timeline-author/test/surface.test.ts b/packages/timeline-author/test/surface.test.ts
index b9703b5c..8d2e0744 100644
--- a/packages/timeline-author/test/surface.test.ts
+++ b/packages/timeline-author/test/surface.test.ts
@@ -36,7 +36,12 @@ const take: SemanticTake = {
};
function resolved(path: string): SurfaceResolvedReference | undefined {
- if (path === "clock") return { path, type: programSpaceTypes.clock, ref: { kind: "record", id: path } };
+ if (path === "clock") return {
+ path,
+ type: programSpaceTypes.clock,
+ ref: { kind: "record", id: path },
+ record: { id: path, type: programSpaceTypes.clock, value: { kind: "inline", value: { frameRate: { numerator: 30, denominator: 1 } } } },
+ };
if (path === "opening.take") return {
path,
ref: { kind: "record", id: path },
@@ -69,3 +74,115 @@ test("Timeline accepts only already-semantic Segment Takes", async () => {
assert.equal(output.records.length, 1);
assert.deepEqual(output.fragments?.[0]?.inputs.map(input => input.name), ["clock", "header", "take-1"]);
});
+
+test("Timeline rejects static placements that do not land on a Clock frame", () => {
+ const element: StructuredElement = {
+ kind: "element",
+ name: "time:Timeline",
+ attributes: { id: "speech", clock: { kind: "reference", path: "clock" }, end: "4.25s" },
+ children: [],
+ range: { start: 0, end: 70 },
+ };
+ assert.throws(() => decodeTimelineAuthorSurface({
+ sourceName: "main.svml",
+ element,
+ resolveReference: resolved,
+ resolveAsset() { throw new Error("Timeline does not resolve assets"); },
+ }), /Timeline speech end at 30\/1 fps: Timeline duration 4\.25s must land on an exact frame boundary\./);
+});
+
+test("Timeline leaves placements with a runtime-only Clock for Build validation", async () => {
+ const element: StructuredElement = {
+ kind: "element",
+ name: "time:Timeline",
+ attributes: { id: "speech", clock: { kind: "reference", path: "runtime-clock" }, end: "4.25s" },
+ children: [],
+ range: { start: 0, end: 70 },
+ };
+ const output = await decodeTimelineAuthorSurface({
+ sourceName: "main.svml",
+ element,
+ resolveReference(path) {
+ if (path === "runtime-clock") return { path, type: programSpaceTypes.clock, ref: { kind: "component-output", component: "clock", output: "clock" } };
+ return resolved(path);
+ },
+ resolveAsset() { throw new Error("Timeline does not resolve assets"); },
+ });
+ assert.equal(output.records.length, 1);
+});
+
+type BoundaryCase = {
+ readonly id: string;
+ readonly frameRate: { readonly numerator: number; readonly denominator: number };
+ readonly end?: string;
+ readonly at?: readonly string[];
+ readonly invalid: boolean;
+};
+
+const boundaryCases: readonly BoundaryCase[] = [
+ { id: "legal-30-end", frameRate: { numerator: 30, denominator: 1 }, end: "1s", invalid: false },
+ { id: "legal-24-end", frameRate: { numerator: 24, denominator: 1 }, end: "1s", invalid: false },
+ { id: "legal-25-end", frameRate: { numerator: 25, denominator: 1 }, end: "1s", invalid: false },
+ { id: "legal-ntsc-end", frameRate: { numerator: 30000, denominator: 1001 }, end: "1001ms", invalid: false },
+ { id: "legal-30-at", frameRate: { numerator: 30, denominator: 1 }, at: ["0.5s"], invalid: false },
+ { id: "legal-24-at", frameRate: { numerator: 24, denominator: 1 }, at: ["125ms"], invalid: false },
+ { id: "legal-25-at", frameRate: { numerator: 25, denominator: 1 }, at: ["0.2s"], invalid: false },
+ { id: "legal-relative", frameRate: { numerator: 30, denominator: 1 }, at: ["0f", "previous.end+2s"], invalid: false },
+ { id: "legal-relative-end", frameRate: { numerator: 30, denominator: 1 }, end: "content.end+2s", invalid: false },
+ { id: "invalid-30-end", frameRate: { numerator: 30, denominator: 1 }, end: "0.01s", invalid: true },
+ { id: "invalid-24-end", frameRate: { numerator: 24, denominator: 1 }, end: "0.1s", invalid: true },
+ { id: "invalid-25-end", frameRate: { numerator: 25, denominator: 1 }, end: "0.1s", invalid: true },
+ { id: "invalid-ntsc-end", frameRate: { numerator: 30000, denominator: 1001 }, end: "1s", invalid: true },
+ { id: "invalid-30-at", frameRate: { numerator: 30, denominator: 1 }, at: ["0.01s"], invalid: true },
+ { id: "invalid-24-at", frameRate: { numerator: 24, denominator: 1 }, at: ["0.1s"], invalid: true },
+ { id: "invalid-25-at", frameRate: { numerator: 25, denominator: 1 }, at: ["0.02s"], invalid: true },
+ { id: "invalid-relative", frameRate: { numerator: 30, denominator: 1 }, at: ["0f", "previous.end+0.01s"], invalid: true },
+ { id: "invalid-relative-end", frameRate: { numerator: 30, denominator: 1 }, end: "content.end+0.01s", invalid: true },
+];
+
+function boundaryElement(sample: BoundaryCase): StructuredElement {
+ const takes = (sample.at ?? []).map((at, index) => ({
+ kind: "element" as const,
+ name: "time:Take",
+ attributes: { source: { kind: "reference" as const, path: `take-${index}` }, at },
+ children: [],
+ range: { start: index * 10, end: index * 10 + 9 },
+ }));
+ return {
+ kind: "element",
+ name: "time:Timeline",
+ attributes: {
+ id: sample.id,
+ clock: { kind: "reference", path: "clock" },
+ ...(sample.end === undefined ? {} : { end: sample.end }),
+ },
+ children: takes,
+ range: { start: 0, end: 100 },
+ };
+}
+
+test("static Clock preflight covers legal and fractional-frame placements", async () => {
+ for (const sample of boundaryCases) {
+ const clockValue = { frameRate: sample.frameRate };
+ const decode = () => decodeTimelineAuthorSurface({
+ sourceName: `${sample.id}.svml`,
+ element: boundaryElement(sample),
+ resolveReference(path) {
+ if (path === "clock") return {
+ path, type: programSpaceTypes.clock, ref: { kind: "record", id: path },
+ record: { id: path, type: programSpaceTypes.clock, value: { kind: "inline", value: clockValue } },
+ };
+ return {
+ path, type: speechTypes.semanticTake, ref: { kind: "record", id: path },
+ record: { id: path, type: speechTypes.semanticTake, value: { kind: "inline", value: take } },
+ };
+ },
+ resolveAsset() { throw new Error("Timeline does not resolve assets"); },
+ });
+ if (sample.invalid) {
+ assert.throws(decode, /exact frame boundary/);
+ } else {
+ await decode();
+ }
+ }
+});