feat(studio): sync origin, out-of-sync repair, linked selection toggle and grouped clip menu (7/8)

packages/cli/src/timeline/describeProject.test.ts

@@ -116,6 +116,20 @@ describe("describeProject", () => {
     ]);
   });
 
+  it("reports each half's out-of-sync offset from its source pair, at the project fps", async () => {
+    const { rows, text } = await rowsOf(`<html><body>
+<div data-composition-id="main" data-duration="10" data-fps="24">
+  <video id="v" src="t.mp4" muted data-sync-origin="lk-1" data-start="1" data-duration="4" data-track-index="0"></video>
+  <audio id="a" src="t.mp4" data-sync-origin="lk-1" data-start="1.5" data-duration="4" data-track-index="1"></audio>
+  <audio id="m" src="m.mp3" data-start="0" data-duration="4" data-track-index="2"></audio>
+</div></body></html>`);
+    const offset = (id: string) => rows.find((r) => r.id === id)?.syncOffsetFrames;
+    expect(offset("a")).toBe(12);
+    expect(offset("v")).toBe(-12);
+    expect(offset("m")).toBeNull();
+    expect(text).toContain("out-of-sync=+12f");
+  });
+
   it("reports unreadable automation instead of showing no lanes", async () => {
     const bad = (await describeProject(project())).tracks
       .flatMap((t) => t.rows)

packages/cli/src/timeline/describeProject.ts

@@ -8,7 +8,9 @@ import {
 import { HF_AUDIO_FX_ATTR, parseAudioFxChain } from "@hyperframes/core/audio-fx";
 import { HF_AUDIO_GROUP_ATTR } from "@hyperframes/core/audio-groups";
 import { byStart, type ClipFact, type ClipLane } from "@hyperframes/core/clip-facts";
-import { parseNumeric } from "@hyperframes/core";
+import { fpsToNumber, parseFpsWithDefault, parseNumeric } from "@hyperframes/core";
+import { findSyncPartner, readLinkTiming, syncOffsetFrames } from "@hyperframes/core/media-link";
+import { readCompositionFps } from "../utils/compositionFps.js";
 import {
   readMediaOffsetSeconds,
   readPlaybackRate,
@@ -60,6 +62,8 @@ export interface TimelineRow extends ClipFact {
   hostRow: RowPointer | null;
   /** Where this row's sub-composition clips are (one level only); each is a full row in its kind's `rows`. */
   children: RowPointer[];
+  /** Signed frames from its `data-sync-origin` partner (+ = late); `null` unpaired or rates differ. */
+  syncOffsetFrames: number | null;
 }
 
 export interface RowPointer {
@@ -137,6 +141,7 @@ interface DocScope {
   withProbeSlot: <T>(fn: () => Promise<T>) => Promise<T>;
   measure: MeasureMedia;
   sourceOverrides: ReadonlyMap<string, string>;
+  fps: number;
 }
 
 /** Source length in seconds of a media file. ffprobe in production; tests pass a recorded fake. */
@@ -312,9 +317,15 @@ function describeRowFields(scope: DocScope, node: DomNode, timing: RowTiming): C
     warnings: [],
     elementId: el.id || null,
     hfId: el.getAttribute("data-hf-id"),
+    syncOffsetFrames: syncOffsetOf(el, scope.fps),
   };
 }
 
+function syncOffsetOf(el: Element, fps: number): number | null {
+  const partner = findSyncPartner(el);
+  return partner ? syncOffsetFrames(readLinkTiming(el), readLinkTiming(partner), fps) : null;
+}
+
 async function describeRow(scope: DocScope, node: DomNode, depth: number): Promise<ClipDraft> {
   return describeRowFields(scope, node, await resolveRowTiming(scope, node, depth));
 }
@@ -343,6 +354,7 @@ async function readSubComposition(
     withProbeSlot: parent.withProbeSlot,
     measure: parent.measure,
     sourceOverrides: parent.sourceOverrides,
+    fps: parent.fps,
   };
   const rows = await Promise.all(
     topLevelElements(toNode(root)).map((node) => describeRow(scope, node, 1)),
@@ -416,6 +428,11 @@ function flatten(top: ClipDraft[]): TimelineTrack[] {
   }));
 }
 
+function projectFps(source: string): number {
+  const parsed = parseFpsWithDefault(readCompositionFps(source) ?? undefined);
+  return fpsToNumber(parsed.ok ? parsed.value : { num: 30, den: 1 });
+}
+
 /** Needs a global DOMParser (`ensureDOMParser`). Reads `index.html` and one level of sub-compositions. */
 export async function describeProject(
   indexPath: string,
@@ -437,6 +454,7 @@ export async function describeProject(
     withProbeSlot: createProbeGate(PROBE_CONCURRENCY),
     measure,
     sourceOverrides,
+    fps: projectFps(source),
   };
   const rows = (
     await Promise.all(topLevelElements(toNode(root)).map((node) => describeRow(scope, node, 0)))

packages/cli/src/timeline/formatTimeline.ts

@@ -29,6 +29,11 @@ function durationNote(row: TimelineRow): string | false {
   }
 }
 
+function syncNote(frames: number | null): string | false {
+  if (!frames) return false;
+  return `out-of-sync=${frames > 0 ? "+" : ""}${frames}f`;
+}
+
 function details(row: TimelineRow): string {
   const lanes = row.lanes.map(
     (l) => `${l.target}[${l.points.map((p) => `${n(p.t)}:${n(p.v)}`).join(" ")}]`,
@@ -38,6 +43,7 @@ function details(row: TimelineRow): string {
     row.volume !== null && `vol=${row.volume}`,
     row.playbackRate !== null && `rate=${n(row.playbackRate)}`,
     row.audioGroup && `group=${row.audioGroup}`,
+    syncNote(row.syncOffsetFrames),
     durationNote(row),
     row.sourceFile && !row.children.length && "children=unread",
     row.laneError && `lanes unreadable: ${row.laneError}`,

packages/cli/src/timeline/timeExpr.test.ts

@@ -32,6 +32,7 @@ const row: TimelineRow = {
   durationSource: "authored",
   pendingReason: null,
   laneError: null,
+  syncOffsetFrames: null,
 };
 
 describe("parseTimeExpression", () => {

packages/core/src/mediaLink.test.ts

@@ -1,7 +1,14 @@
 import { describe, expect, it } from "vitest";
 import {
   MEDIA_LINK_ATTR,
+  SYNC_ORIGIN_ATTR,
+  findSyncPartner,
+  formatSyncOffset,
   linkTimingMismatches,
+  moveIntoSyncStart,
+  slipIntoSyncMediaStart,
+  sourceZeroTime,
+  syncOffsetFrames,
   mintLinkId,
   readLinkTiming,
   relinkSplitHalves,
@@ -24,6 +31,11 @@ describe("readLinkTiming", () => {
   it("reads data-playback-start as the media-start alias", () => {
     expect(readLinkTiming(attrs({ "data-playback-start": "1.5" })).mediaStart).toBe(1.5);
   });
+
+  it("lets data-playback-start win over data-media-start, as playback does", () => {
+    const both = attrs({ "data-playback-start": "0", "data-media-start": "0.5" });
+    expect(readLinkTiming(both).mediaStart).toBe(0);
+  });
 });
 
 describe("linkTimingMismatches", () => {
@@ -86,6 +98,17 @@ describe("relinkSplitHalves", () => {
     expect(link("i-split")).toBeNull();
   });
 
+  it("keeps the source origin when only one member of an unlinked pair is cut", () => {
+    const d = doc(`
+      <video id="v" data-sync-origin="lk-1" data-start="0" data-duration="10"></video>
+      <audio id="a" data-sync-origin="lk-1" data-start="0" data-duration="4"></audio>
+      <audio id="a-split" data-sync-origin="lk-1" data-start="4" data-duration="6"></audio>`);
+    relinkSplitHalves(d, ["a-split"]);
+    const right = d.getElementById("a-split");
+    expect(right?.getAttribute(SYNC_ORIGIN_ATTR)).toBe("lk-1");
+    expect(right && findSyncPartner(right)?.id).toBe("v");
+  });
+
   it("mints distinct ids for distinct groups", () => {
     const d = doc(`
       <video id="v" data-link="lk-1"></video><video id="v2" data-link="lk-1"></video>
@@ -97,3 +120,100 @@ describe("relinkSplitHalves", () => {
     expect(ids).not.toContain("lk-7");
   });
 });
+
+describe("relinkSplitHalves sync origin", () => {
+  it("gives right halves their own shared sync origin, even when unlinked", () => {
+    document.body.innerHTML = `
+      <video id="v" data-sync-origin="lk-1"></video><video id="v2" data-sync-origin="lk-1"></video>
+      <audio id="a" data-sync-origin="lk-1"></audio><audio id="a2" data-sync-origin="lk-1"></audio>`;
+    relinkSplitHalves(document, ["v2", "a2"]);
+    const origin = (id: string) => document.getElementById(id)?.getAttribute(SYNC_ORIGIN_ATTR);
+    expect(origin("v")).toBe("lk-1");
+    expect(origin("a")).toBe("lk-1");
+    expect(origin("v2")).not.toBe("lk-1");
+    expect(origin("v2")).toBe(origin("a2"));
+  });
+});
+
+describe("sync offset", () => {
+  const clip = (start: number, mediaStart = 0, playbackRate = 1) => ({
+    start,
+    mediaStart,
+    playbackRate,
+  });
+
+  it("places source zero at start minus media-start over rate", () => {
+    expect(sourceZeroTime(clip(4, 2, 2))).toBe(3);
+  });
+
+  it("is zero for a pair in sync, whatever their shared media start", () => {
+    expect(syncOffsetFrames(clip(2, 1), clip(2, 1), 30)).toBe(0);
+    expect(syncOffsetFrames(clip(3, 2), clip(2, 1), 30)).toBe(0);
+  });
+
+  it("is signed from the clip's side: late is positive, and the partner reads the negation", () => {
+    expect(syncOffsetFrames(clip(2 + 10 / 30), clip(2), 30)).toBe(10);
+    expect(syncOffsetFrames(clip(2), clip(2 + 10 / 30), 30)).toBe(-10);
+  });
+
+  it("counts media start: a slipped clip is out of sync in place", () => {
+    expect(syncOffsetFrames(clip(2, 0.5), clip(2, 0), 30)).toBe(-15);
+  });
+
+  it("divides media start by the shared rate", () => {
+    expect(syncOffsetFrames(clip(2, 1, 2), clip(2, 0, 2), 30)).toBe(-15);
+  });
+
+  it("has no offset when the rates differ", () => {
+    expect(syncOffsetFrames(clip(2, 0, 1.5), clip(2, 0, 1), 30)).toBeNull();
+  });
+
+  it("formats frames, then seconds:frames past one second", () => {
+    expect(formatSyncOffset(10, 30)).toBe("+10");
+    expect(formatSyncOffset(-51, 30)).toBe("-1:21");
+    expect(formatSyncOffset(30, 30)).toBe("+1:00");
+    expect(formatSyncOffset(-3, 24)).toBe("-3");
+  });
+
+  it("moves the clip onto its partner, or refuses before zero", () => {
+    expect(moveIntoSyncStart(clip(2.5, 0.5), clip(1, 0))).toBeCloseTo(1.5);
+    expect(syncOffsetFrames(clip(1.5, 0.5), clip(1, 0), 30)).toBe(0);
+    expect(moveIntoSyncStart(clip(0, 2), clip(0, 0))).toBeCloseTo(2);
+    expect(moveIntoSyncStart(clip(1, 0), clip(0, 2))).toBeNull();
+  });
+
+  it("slips the clip's media in place, scaled by rate, or refuses before the file start", () => {
+    expect(slipIntoSyncMediaStart(clip(3, 0), clip(2, 0))).toBeCloseTo(1);
+    expect(slipIntoSyncMediaStart(clip(3, 0, 2), clip(2, 0, 2))).toBeCloseTo(2);
+    expect(syncOffsetFrames(clip(3, 2, 2), clip(2, 0, 2), 30)).toBe(0);
+    expect(slipIntoSyncMediaStart(clip(1, 0), clip(2, 0))).toBeNull();
+  });
+});
+
+describe("findSyncPartner", () => {
+  it("finds the opposite kind sharing the origin, preferring the most shared timeline", () => {
+    document.body.innerHTML = `<div data-composition-id="m">
+      <video id="v" data-sync-origin="lk-1" data-start="0" data-duration="4"></video>
+      <video id="v2" data-sync-origin="lk-1" data-start="4" data-duration="4"></video>
+      <audio id="a" data-sync-origin="lk-1" data-start="4.2" data-duration="4"></audio>
+      <audio id="x" data-sync-origin="lk-9" data-start="4" data-duration="4"></audio></div>`;
+    const byId = (id: string) => document.getElementById(id);
+    const a = byId("a");
+    const x = byId("x");
+    expect(a && findSyncPartner(a)?.id).toBe("v2");
+    expect(x && findSyncPartner(x)).toBeNull();
+  });
+
+  it.each(['data-composition-id="child"', 'data-composition-file="child.html"'])(
+    "never takes a partner from a nested composition (%s) reusing the origin",
+    (host) => {
+      document.body.innerHTML = `<div data-composition-id="m">
+      <video id="v" data-sync-origin="lk-1" data-start="0" data-duration="4"></video>
+      <div ${host}>
+        <audio id="ca" data-sync-origin="lk-1" data-start="0" data-duration="4"></audio>
+      </div></div>`;
+      const v = document.getElementById("v");
+      expect(v && findSyncPartner(v)).toBeNull();
+    },
+  );
+});