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.
TypeScript agentic-aiaiai-agentsai-videocompilerdslffmpeggenerative-aillmmarkup-languagemonorepoplugin-systemprogramming-languagetext-to-videotypescriptvideovideo-automationvideo-clonevideo-editingvideo-generation
fix(timeline): preflight exact-frame placements (#355)
Flanderne0f26d189a44
diff --git a/packages/timeline-author/src/program.ts b/packages/timeline-author/src/program.tsindex 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.tsindex 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.tsindex 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();+ }+ }+});