Skip to content

Write HTML. Render video. Built for agents.

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

Vance Ingalls45b8e171e279
diff --git a/packages/cli/src/timeline/describeProject.test.ts b/packages/cli/src/timeline/describeProject.test.ts
index ec0e22e15d..94538fd178 100644
--- a/packages/cli/src/timeline/describeProject.test.ts
+++ b/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)
diff --git a/packages/cli/src/timeline/describeProject.ts b/packages/cli/src/timeline/describeProject.ts
index 988138f027..1475a6e7b9 100644
--- a/packages/cli/src/timeline/describeProject.ts
+++ b/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)))
diff --git a/packages/cli/src/timeline/formatTimeline.ts b/packages/cli/src/timeline/formatTimeline.ts
index c412feb6fd..2b8b0862c4 100644
--- a/packages/cli/src/timeline/formatTimeline.ts
+++ b/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}`,
diff --git a/packages/cli/src/timeline/timeExpr.test.ts b/packages/cli/src/timeline/timeExpr.test.ts
index 99c51e634e..31b7730742 100644
--- a/packages/cli/src/timeline/timeExpr.test.ts
+++ b/packages/cli/src/timeline/timeExpr.test.ts
@@ -32,6 +32,7 @@ const row: TimelineRow = {
durationSource: "authored",
pendingReason: null,
laneError: null,
+ syncOffsetFrames: null,
};
describe("parseTimeExpression", () => {
diff --git a/packages/core/src/mediaLink.test.ts b/packages/core/src/mediaLink.test.ts
index 568c7f930d..c8465b6f97 100644
--- a/packages/core/src/mediaLink.test.ts
+++ b/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();
+ },
+ );
+});
diff --git a/packages/core/src/mediaLink.ts b/packages/core/src/mediaLink.ts
index a74e24b224..7cdf736e5d 100644
--- a/packages/core/src/mediaLink.ts
+++ b/packages/core/src/mediaLink.ts
@@ -1,3 +1,5 @@
+import { readMediaOffsetSeconds } from "@hyperframes/parsers/media-duration";
+
/**
* Linked clips: members sharing a `data-link` id are edited as one (a detached
* video + its audio). An editing contract only; playback and render ignore it.
@@ -38,7 +40,7 @@ export function readLinkTiming(el: AttributeReader): LinkTiming {
return {
start: readNumber(el, ["data-start"], 0),
duration: readNumber(el, ["data-duration"], 0),
- mediaStart: readNumber(el, ["data-media-start", "data-playback-start"], 0),
+ mediaStart: readMediaOffsetSeconds((name) => el.getAttribute(name)),
playbackRate: readNumber(el, ["data-playback-rate"], 1),
};
}
@@ -53,9 +55,11 @@ export function linkTimingMismatches(members: readonly AttributeReader[]): strin
).map(([, field]) => field);
}
+const LINK_SCOPE_SELECTOR = "[data-composition-id], [data-composition-file]";
+
/** The composition a link group stays inside: the nearest inline composition or file host. */
export function linkScopeOf(el: Element): Element | null {
- return el.parentElement?.closest("[data-composition-id], [data-composition-file]") ?? null;
+ return el.parentElement?.closest(LINK_SCOPE_SELECTOR) ?? null;
}
export function mintLinkId(taken: Iterable<string>): string {
@@ -66,30 +70,138 @@ export function mintLinkId(taken: Iterable<string>): string {
}
function takenLinkIds(doc: Document): string[] {
- return Array.from(doc.querySelectorAll(`[id], [${MEDIA_LINK_ATTR}]`)).flatMap((el) => [
+ return Array.from(
+ doc.querySelectorAll(`[id], [${MEDIA_LINK_ATTR}], [${SYNC_ORIGIN_ATTR}]`),
+ ).flatMap((el) => [
el.id,
el.getAttribute(MEDIA_LINK_ATTR) ?? "",
+ el.getAttribute(SYNC_ORIGIN_ATTR) ?? "",
]);
}
-/**
- * After a split, the right halves are clones still carrying the left halves'
- * link id. Give each group's right halves one fresh shared id, so each half of
- * a linked pair is its own pair.
- */
-export function relinkSplitHalves(doc: Document, rightHalfIds: readonly string[]): void {
- const taken = new Set(takenLinkIds(doc));
+function renameShared(
+ doc: Document,
+ ids: readonly string[],
+ attr: string,
+ taken: Set<string>,
+): void {
const renamed = new Map<string, string>();
- for (const id of rightHalfIds) {
+ for (const id of ids) {
const el = doc.getElementById(id);
- const oldLink = el?.getAttribute(MEDIA_LINK_ATTR);
- if (!el || !oldLink) continue;
- let fresh = renamed.get(oldLink);
+ const old = el?.getAttribute(attr);
+ if (!el || !old) continue;
+ let fresh = renamed.get(old);
if (!fresh) {
fresh = mintLinkId(taken);
taken.add(fresh);
- renamed.set(oldLink, fresh);
+ renamed.set(old, fresh);
+ }
+ el.setAttribute(attr, fresh);
+ }
+}
+
+/** Split right halves get a fresh link id; a sync origin is reminted only when video and audio were both cut. */
+export function relinkSplitHalves(doc: Document, rightHalfIds: readonly string[]): void {
+ const taken = new Set(takenLinkIds(doc));
+ renameShared(doc, rightHalfIds, MEDIA_LINK_ATTR, taken);
+ renameShared(doc, idsWithBothSidesCut(doc, rightHalfIds), SYNC_ORIGIN_ATTR, taken);
+}
+
+function idsWithBothSidesCut(doc: Document, rightHalfIds: readonly string[]): string[] {
+ const tagsByOrigin = new Map<string, Set<string>>();
+ const originOf = (id: string) => doc.getElementById(id)?.getAttribute(SYNC_ORIGIN_ATTR) ?? null;
+ for (const id of rightHalfIds) {
+ const origin = originOf(id);
+ const tag = doc.getElementById(id)?.tagName.toLowerCase();
+ if (!origin || !tag) continue;
+ tagsByOrigin.set(origin, (tagsByOrigin.get(origin) ?? new Set()).add(tag));
+ }
+ return rightHalfIds.filter((id) => {
+ const tags = tagsByOrigin.get(originOf(id) ?? "");
+ return tags?.has("video") === true && tags.has("audio");
+ });
+}
+
+/** Shared by a detached or linked video + audio of one file; it survives Unlink so a drifted pair can resync. */
+export const SYNC_ORIGIN_ATTR = "data-sync-origin";
+
+export type SyncTiming = Pick<LinkTiming, "start" | "mediaStart" | "playbackRate">;
+
+const rateOf = (timing: SyncTiming) => (timing.playbackRate > 0 ? timing.playbackRate : 1);
+
+/** Where source time zero lands on the timeline: `start − mediaStart / rate`. */
+export function sourceZeroTime(timing: SyncTiming): number {
+ return timing.start - timing.mediaStart / rateOf(timing);
+}
+
+/** Frames `clip` sits from `partner`, positive when it plays late; null when their rates differ. */
+export function syncOffsetFrames(
+ clip: SyncTiming,
+ partner: SyncTiming,
+ fps: number,
+): number | null {
+ if (Math.abs(rateOf(clip) - rateOf(partner)) > 1e-6) return null;
+ const frames = Math.round((sourceZeroTime(clip) - sourceZeroTime(partner)) * fps);
+ return Object.is(frames, -0) ? 0 : frames;
+}
+
+/** `+10`, `-1:21` (seconds:frames once past one second). */
+export function formatSyncOffset(frames: number, fps: number): string {
+ const sign = frames < 0 ? "-" : "+";
+ const whole = Math.abs(frames);
+ const perSecond = Math.max(1, Math.round(fps));
+ if (whole < perSecond) return `${sign}${whole}`;
+ const seconds = Math.floor(whole / perSecond);
+ const rest = String(whole % perSecond).padStart(2, "0");
+ return `${sign}${seconds}:${rest}`;
+}
+
+/** Move into Sync: the start that puts `clip` back on `partner`, or null before zero. */
+export function moveIntoSyncStart(clip: SyncTiming, partner: SyncTiming): number | null {
+ const start = clip.start - (sourceZeroTime(clip) - sourceZeroTime(partner));
+ return start >= -SYNC_TOLERANCE_S ? Math.max(0, start) : null;
+}
+
+/** Slip into Sync: the media start that syncs `clip` in place, or null before the file's start. */
+export function slipIntoSyncMediaStart(clip: SyncTiming, partner: SyncTiming): number | null {
+ const mediaStart = (clip.start - sourceZeroTime(partner)) * rateOf(clip);
+ return mediaStart >= -SYNC_TOLERANCE_S ? Math.max(0, mediaStart) : null;
+}
+
+interface PairableElement extends AttributeReader {
+ tagName: string;
+ closest(selectors: string): Element | null;
+ ownerDocument: Document;
+}
+
+function sharedSeconds(a: LinkTiming, b: LinkTiming): number {
+ return Math.min(a.start + a.duration, b.start + b.duration) - Math.max(a.start, b.start);
+}
+
+/** `el`'s source partner (same sync origin, other tag): most shared timeline, then nearest start. */
+function sameOriginInScope(el: PairableElement, tag: string, origin: string): Element[] {
+ const scopeOf = (node: PairableElement) => node.closest(LINK_SCOPE_SELECTOR) ?? el.ownerDocument;
+ const scope = scopeOf(el);
+ return Array.from(scope.querySelectorAll(tag)).filter(
+ (candidate) =>
+ candidate.getAttribute(SYNC_ORIGIN_ATTR) === origin && scopeOf(candidate) === scope,
+ );
+}
+
+export function findSyncPartner(el: PairableElement): Element | null {
+ const origin = el.getAttribute(SYNC_ORIGIN_ATTR);
+ const tag = el.tagName.toLowerCase();
+ if (!origin || (tag !== "video" && tag !== "audio")) return null;
+ const partnerTag = tag === "video" ? "audio" : "video";
+ const own = readLinkTiming(el);
+ let best: { el: Element; shared: number; distance: number } | null = null;
+ for (const candidate of sameOriginInScope(el, partnerTag, origin)) {
+ const timing = readLinkTiming(candidate);
+ const shared = sharedSeconds(own, timing);
+ const distance = Math.abs(timing.start - own.start);
+ if (!best || shared > best.shared || (shared === best.shared && distance < best.distance)) {
+ best = { el: candidate, shared, distance };
}
- el.setAttribute(MEDIA_LINK_ATTR, fresh);
}
+ return best?.el ?? null;
}
diff --git a/packages/lint/src/rules/linkedClips.ts b/packages/lint/src/rules/linkedClips.ts
index 90c5a57c23..49ff9cdb4c 100644
--- a/packages/lint/src/rules/linkedClips.ts
+++ b/packages/lint/src/rules/linkedClips.ts
@@ -6,7 +6,7 @@ const SYNC_TOLERANCE_S = 1e-3;
const LINKED_TIMING_FIELDS: ReadonlyArray<{ field: string; attrs: string[]; fallback: number }> = [
{ field: "start", attrs: ["data-start"], fallback: 0 },
{ field: "duration", attrs: ["data-duration"], fallback: 0 },
- { field: "media-start", attrs: ["data-media-start", "data-playback-start"], fallback: 0 },
+ { field: "media-start", attrs: ["data-playback-start", "data-media-start"], fallback: 0 },
{ field: "playback-rate", attrs: ["data-playback-rate"], fallback: 1 },
];
diff --git a/packages/sdk/src/engine/syncTiming.ts b/packages/sdk/src/engine/syncTiming.ts
new file mode 100644
index 0000000000..cb7ef6a314
--- /dev/null
+++ b/packages/sdk/src/engine/syncTiming.ts
@@ -0,0 +1,50 @@
+import {
+ findSyncPartner,
+ moveIntoSyncStart,
+ readLinkTiming,
+ slipIntoSyncMediaStart,
+ syncOffsetFrames,
+} from "@hyperframes/core/media-link";
+import type { HfId } from "../types.js";
+import { resolveScoped } from "./model.js";
+
+export type SyncFix =
+ | { kind: "move"; start: number }
+ | { kind: "slip"; name: "data-media-start" | "data-playback-start"; value: string };
+
+function pairOf(document: Document, id: HfId): { own: Element; partner: Element } | null {
+ const own = resolveScoped(document, id);
+ const partner = own ? findSyncPartner(own) : null;
+ return own && partner ? { own, partner } : null;
+}
+
+/** Frames `id` sits from its source partner; null when unpaired or at another rate. */
+export function syncOffsetOf(document: Document, id: HfId, fps: number): number | null {
+ const pair = pairOf(document, id);
+ if (!pair) return null;
+ return syncOffsetFrames(readLinkTiming(pair.own), readLinkTiming(pair.partner), fps);
+}
+
+const formatSeconds = (value: number) => String(Number(value.toFixed(6)));
+
+/** The one attribute write that brings `id` back into sync, by moving or slipping it. */
+export function syncFixFor(document: Document, id: HfId, mode: "move" | "slip"): SyncFix {
+ const pair = pairOf(document, id);
+ if (!pair) throw new Error(`${id} has no source partner (data-sync-origin)`);
+ const own = readLinkTiming(pair.own);
+ const partner = readLinkTiming(pair.partner);
+ if (syncOffsetFrames(own, partner, 1000) === null) {
+ throw new Error(`${id} and its partner play at different rates; no single sync exists`);
+ }
+ if (mode === "move") {
+ const start = moveIntoSyncStart(own, partner);
+ if (start === null) throw new Error(`moving ${id} into sync would put it before 0`);
+ return { kind: "move", start: Number(start.toFixed(6)) };
+ }
+ const mediaStart = slipIntoSyncMediaStart(own, partner);
+ if (mediaStart === null) throw new Error(`slipping ${id} into sync would start before its file`);
+ const name = pair.own.hasAttribute("data-playback-start")
+ ? "data-playback-start"
+ : "data-media-start";
+ return { kind: "slip", name, value: formatSeconds(mediaStart) };
+}
diff --git a/packages/sdk/src/session.sync.test.ts b/packages/sdk/src/session.sync.test.ts
new file mode 100644
index 0000000000..b9121c77fe
--- /dev/null
+++ b/packages/sdk/src/session.sync.test.ts
@@ -0,0 +1,60 @@
+import { describe, expect, it } from "vitest";
+import { readMediaOffsetSeconds } from "@hyperframes/parsers/media-duration";
+import { openComposition } from "./session.js";
+
+const DRIFTED = `
+<div data-hf-id="hf-stage" data-hf-root style="width:1280px;height:720px" data-duration="10">
+ <video data-hf-id="hf-talk" src="talk.mp4" muted data-sync-origin="lk-1" data-start="2" data-duration="6" data-track-index="0"></video>
+ <audio data-hf-id="hf-talk-audio" src="talk.mp4" data-sync-origin="lk-1" data-start="2.5" data-duration="6" data-media-start="0" data-track-index="1"></audio>
+</div>
+`.trim();
+
+function attr(html: string, hfId: string, name: string): string | null {
+ const tag = new RegExp(`<[^>]*data-hf-id="${hfId}"[^>]*>`).exec(html)?.[0] ?? "";
+ return new RegExp(`\\b${name}="([^"]*)"`).exec(tag)?.[1] ?? null;
+}
+
+describe("sync origin on the SDK", () => {
+ it("reports each half's signed offset in frames", async () => {
+ const comp = await openComposition(DRIFTED);
+ expect(comp.syncOffset("hf-talk-audio")).toBe(15);
+ expect(comp.syncOffset("hf-talk", 24)).toBe(-12);
+ });
+
+ it("moveIntoSync moves that clip alone, and undo restores it", async () => {
+ const comp = await openComposition(DRIFTED);
+ comp.moveIntoSync("hf-talk-audio");
+ expect(attr(comp.serialize(), "hf-talk-audio", "data-start")).toBe("2");
+ expect(attr(comp.serialize(), "hf-talk", "data-start")).toBe("2");
+ expect(comp.syncOffset("hf-talk-audio")).toBe(0);
+ comp.undo();
+ expect(attr(comp.serialize(), "hf-talk-audio", "data-start")).toBe("2.5");
+ });
+
+ it("slipIntoSync keeps the start and slips the media", async () => {
+ const comp = await openComposition(DRIFTED);
+ comp.slipIntoSync("hf-talk-audio");
+ const html = comp.serialize();
+ expect(attr(html, "hf-talk-audio", "data-start")).toBe("2.5");
+ expect(attr(html, "hf-talk-audio", "data-media-start")).toBe("0.5");
+ expect(comp.syncOffset("hf-talk-audio")).toBe(0);
+ });
+
+ it("slips the attribute playback reads when both in-point attributes are authored", async () => {
+ const both = DRIFTED.replace(
+ 'data-media-start="0"',
+ 'data-playback-start="0" data-media-start="0"',
+ );
+ const comp = await openComposition(both);
+ comp.slipIntoSync("hf-talk-audio");
+ const html = comp.serialize();
+ const played = readMediaOffsetSeconds((name) => attr(html, "hf-talk-audio", name));
+ expect(played).toBeCloseTo(0.5, 6);
+ expect(comp.syncOffset("hf-talk-audio")).toBe(0);
+ });
+
+ it("refuses a slip that would start before the file", async () => {
+ const comp = await openComposition(DRIFTED);
+ expect(() => comp.slipIntoSync("hf-talk")).toThrow(/before its file/);
+ });
+});
diff --git a/packages/sdk/src/session.ts b/packages/sdk/src/session.ts
index 1a77c7cc7e..86d096126d 100644
--- a/packages/sdk/src/session.ts
+++ b/packages/sdk/src/session.ts
@@ -31,6 +31,7 @@ import type {
} from "./types.js";
import { ORIGIN_APPLY_PATCHES, ORIGIN_LOCAL } from "./types.js";
import { buildRoots, flatElements, parsedAnimationIds } from "./document.js";
+import { syncFixFor, syncOffsetOf } from "./engine/syncTiming.js";
import type { PersistAdapter, PreviewAdapter } from "./adapters/types.js";
import { parseMutable } from "./engine/model.js";
import type { ParsedDocument } from "./engine/model.js";
@@ -169,6 +170,23 @@ class CompositionImpl implements Composition {
this.dispatch({ type: "setTiming", target: id, ...timing, ...opts });
}
+ syncOffset(id: HfId, fps = 30): number | null {
+ return syncOffsetOf(this.parsed.document, id, fps);
+ }
+
+ /** Moves `id` alone; a link group it belongs to is left (as `setTiming` `linked: false`). */
+ moveIntoSync(id: HfId): void {
+ const fix = syncFixFor(this.parsed.document, id, "move");
+ if (fix.kind === "move")
+ this.dispatch({ type: "setTiming", target: id, start: fix.start, linked: false });
+ }
+
+ slipIntoSync(id: HfId): void {
+ const fix = syncFixFor(this.parsed.document, id, "slip");
+ if (fix.kind === "slip")
+ this.dispatch({ type: "setAttribute", target: id, name: fix.name, value: fix.value });
+ }
+
removeElement(id: HfId): void {
this.dispatch({ type: "removeElement", target: id });
}
diff --git a/packages/sdk/src/types.ts b/packages/sdk/src/types.ts
index d4599cabc9..52e078f238 100644
--- a/packages/sdk/src/types.ts
+++ b/packages/sdk/src/types.ts
@@ -435,6 +435,10 @@ export interface Composition {
timing: { start?: number; duration?: number; trackIndex?: number },
opts?: { linked?: boolean },
): void;
+ /** Frames `id` sits from its `data-sync-origin` partner, positive when late; null if unpaired or rates differ. */
+ syncOffset(id: HfId, fps?: number): number | null;
+ moveIntoSync(id: HfId): void;
+ slipIntoSync(id: HfId): void;
removeElement(id: HfId): void;
/**
* Insert an HTML fragment as a child of `parent` at `index` (WS-D).
diff --git a/packages/studio-server/src/helpers/freezeFrame.test.ts b/packages/studio-server/src/helpers/freezeFrame.test.ts
index 8767d1bc85..e7a70ce3ec 100644
--- a/packages/studio-server/src/helpers/freezeFrame.test.ts
+++ b/packages/studio-server/src/helpers/freezeFrame.test.ts
@@ -142,8 +142,8 @@ describe("applyFreezeFrameToHtml", () => {
it("splits the linked audio, leaving a silent gap, and links the right halves together", () => {
expect(timing(html, "talk-audio")).toEqual(["1", "2.2"]);
expect(timing(html, "talk-audio-split")).toEqual(["5.2", "3.8"]);
- expect(at(html, "talk-split")?.getAttribute("data-link")).toBe("L-2");
- expect(at(html, "talk-audio-split")?.getAttribute("data-link")).toBe("L-2");
+ expect(at(html, "talk-split")?.getAttribute("data-link")).toBe("lk-1");
+ expect(at(html, "talk-audio-split")?.getAttribute("data-link")).toBe("lk-1");
expect(at(html, "talk-audio")?.getAttribute("data-link")).toBe("L");
});
diff --git a/packages/studio-server/src/helpers/freezeFrame.ts b/packages/studio-server/src/helpers/freezeFrame.ts
index 4630f5551e..583e964af1 100644
--- a/packages/studio-server/src/helpers/freezeFrame.ts
+++ b/packages/studio-server/src/helpers/freezeFrame.ts
@@ -2,6 +2,7 @@ import { createHash, randomBytes } from "node:crypto";
import { ensureHfIds } from "@hyperframes/parsers/hf-ids";
import { readMediaOffsetSeconds } from "@hyperframes/parsers/media-duration";
import { resolveRateSpec, sourceTimeAt } from "@hyperframes/core/speed-ramp";
+import { MEDIA_LINK_ATTR as LINK_ATTR, relinkSplitHalves } from "@hyperframes/core/media-link";
import {
findTargetElement,
isHTMLElement,
@@ -11,7 +12,6 @@ import {
} from "./sourceMutation.js";
const FREEZE_HOLD_SECONDS = 2;
-const LINK_ATTR = "data-link";
const EPSILON = 1e-3;
const round3 = (value: number) => Math.round(value * 1000) / 1000;
@@ -195,12 +195,6 @@ function splitAll(
return { html: next, rightHalfIds };
}
-function relinkRightHalves(document: Document, link: string | null, ids: readonly string[]): void {
- if (!link) return;
- const rightLink = uniqueLink(document, link);
- for (const id of ids) document.getElementById(id)?.setAttribute(LINK_ATTR, rightLink);
-}
-
/**
* Split the video at the playhead, put a still of that frame in the gap and push the rest of its
* track (and a linked partner's, which is split too and left silent for the hold) right by the hold.
@@ -228,7 +222,7 @@ export function applyFreezeFrameToHtml(
if (!cut) return null;
const { document, wrappedFragment } = parseSourceDocument(cut.html);
- relinkRightHalves(document, video.getAttribute(LINK_ATTR), cut.rightHalfIds);
+ relinkSplitHalves(document, cut.rightHalfIds);
shiftTracks(document, tracks, input.playhead, hold);
const leftHalf = findTargetElement(document, input.target);
if (!leftHalf?.parentElement) return null;
@@ -246,12 +240,3 @@ export function applyFreezeFrameToHtml(
freezeId,
};
}
-
-function uniqueLink(document: Document, base: string): string {
- const taken = new Set(
- Array.from(document.querySelectorAll(`[${LINK_ATTR}]`)).map((el) => el.getAttribute(LINK_ATTR)),
- );
- let candidate = `${base}-2`;
- for (let n = 3; taken.has(candidate); n++) candidate = `${base}-${n}`;
- return candidate;
-}
diff --git a/packages/studio-server/src/helpers/sourceMutation.ts b/packages/studio-server/src/helpers/sourceMutation.ts
index 66873d43bc..ccf8216846 100644
--- a/packages/studio-server/src/helpers/sourceMutation.ts
+++ b/packages/studio-server/src/helpers/sourceMutation.ts
@@ -702,10 +702,14 @@ export function unwrapElementsFromHtml(
};
}
-/** After a cut, give each linked group's right halves their own shared `data-link`. */
+/** After a cut, give each linked group's right halves their own `data-link` and `data-sync-origin`. */
export function relinkSplitHalvesInHtml(source: string, rightHalfIds: readonly string[]): string {
const { document, wrappedFragment } = parseSourceDocument(source);
- if (!rightHalfIds.some((id) => document.getElementById(id)?.hasAttribute("data-link"))) {
+ const carriesPairing = (id: string) => {
+ const el = document.getElementById(id);
+ return Boolean(el?.hasAttribute("data-link") || el?.hasAttribute("data-sync-origin"));
+ };
+ if (!rightHalfIds.some(carriesPairing)) {
return source;
}
relinkSplitHalves(document, rightHalfIds);
diff --git a/packages/studio-server/src/helpers/sourceMutationSplitAndGroup.test.ts b/packages/studio-server/src/helpers/sourceMutationSplitAndGroup.test.ts
index 2ed4297a8d..47208de26e 100644
--- a/packages/studio-server/src/helpers/sourceMutationSplitAndGroup.test.ts
+++ b/packages/studio-server/src/helpers/sourceMutationSplitAndGroup.test.ts
@@ -411,6 +411,19 @@ describe("relinkSplitHalvesInHtml", () => {
expect(link("a-split")).toBe("lk-2");
});
+ it("gives an unlinked pair's right halves their own sync origin", () => {
+ const source =
+ '<div data-composition-id="c"><video id="v" src="t.mp4" muted data-sync-origin="lk-1" data-start="0" data-duration="4"></video><audio id="a" src="t.mp4" data-sync-origin="lk-1" data-start="0" data-duration="4"></audio></div>';
+ const first = splitElementInHtml(source, { id: "v" }, 2, "v-split");
+ const second = splitElementInHtml(first.html, { id: "a" }, 2, "a-split");
+ const html = relinkSplitHalvesInHtml(second.html, ["v-split", "a-split"]);
+ const origin = (id: string) =>
+ new RegExp(`id="${id}"[^>]*data-sync-origin="([^"]+)"`).exec(html)?.[1];
+ expect(origin("v")).toBe("lk-1");
+ expect(origin("v-split")).not.toBe("lk-1");
+ expect(origin("v-split")).toBe(origin("a-split"));
+ });
+
it("leaves unlinked splits byte-identical", () => {
const source = '<div><img id="i" data-start="0" data-duration="4"></div>';
expect(relinkSplitHalvesInHtml(source, ["i"])).toBe(source);
diff --git a/packages/studio/src/components/LinkedSelectionToggle.tsx b/packages/studio/src/components/LinkedSelectionToggle.tsx
new file mode 100644
index 0000000000..8f01a2d144
--- /dev/null
+++ b/packages/studio/src/components/LinkedSelectionToggle.tsx
@@ -0,0 +1,73 @@
+import { useCallback, useState } from "react";
+import { createPortal } from "react-dom";
+import { LinkSimple } from "@phosphor-icons/react";
+import { useContextMenuDismiss } from "../hooks/useContextMenuDismiss";
+import { useMenuKeyboardNav } from "../player/components/menuKeyboardNav";
+import { useLinkedClipPreferences } from "../utils/linkedClipPreferences";
+import { Tooltip } from "./ui";
+import { flatActive, flatIdle } from "./timelineToolbarStyles";
+
+function SyncIndicatorMenu({ x, y, onClose }: { x: number; y: number; onClose: () => void }) {
+ const menuRef = useContextMenuDismiss(onClose);
+ useMenuKeyboardNav(menuRef);
+ const visible = useLinkedClipPreferences((s) => s.syncIndicatorsVisible);
+ const setVisible = useLinkedClipPreferences((s) => s.setSyncIndicatorsVisible);
+ return createPortal(
+ <div
+ ref={menuRef}
+ role="menu"
+ aria-label="Linked clips"
+ className="fixed z-200 min-w-[200px] rounded-sm border border-neutral-700 bg-neutral-900 py-1 shadow-lg"
+ style={{ left: x, top: y }}
+ >
+ <button
+ type="button"
+ role="menuitemcheckbox"
+ aria-checked={visible}
+ className="flex w-full items-center gap-2 px-3 py-1.5 text-left text-xs text-neutral-300 outline-hidden hover:bg-neutral-800 focus-visible:bg-neutral-800"
+ onClick={() => {
+ setVisible(!visible);
+ onClose();
+ }}
+ >
+ <span className="w-3 text-studio-accent">{visible ? "✓" : ""}</span>
+ Show out-of-sync indicators
+ </button>
+ </div>,
+ document.body,
+ );
+}
+
+/** Premiere's Linked Selection; right-click holds the out-of-sync indicator preference. */
+export function LinkedSelectionToggle() {
+ const linkedSelection = useLinkedClipPreferences((s) => s.linkedSelection);
+ const setLinkedSelection = useLinkedClipPreferences((s) => s.setLinkedSelection);
+ const [menuAt, setMenuAt] = useState<{ x: number; y: number } | null>(null);
+ const closeMenu = useCallback(() => setMenuAt(null), []);
+ return (
+ <>
+ <Tooltip
+ label={
+ linkedSelection
+ ? "Linked Selection on — a click selects both halves (⌥-click for one)"
+ : "Linked Selection off — a click selects one clip"
+ }
+ >
+ <button
+ type="button"
+ onClick={() => setLinkedSelection(!linkedSelection)}
+ onContextMenu={(e) => {
+ e.preventDefault();
+ setMenuAt({ x: e.clientX, y: e.clientY });
+ }}
+ aria-label="Linked Selection"
+ aria-pressed={linkedSelection}
+ className={linkedSelection ? flatActive : flatIdle}
+ >
+ <LinkSimple size={16} weight="bold" aria-hidden="true" />
+ </button>
+ </Tooltip>
+ {menuAt && <SyncIndicatorMenu x={menuAt.x} y={menuAt.y} onClose={closeMenu} />}
+ </>
+ );
+}
diff --git a/packages/studio/src/components/TimelineToolbar.test.tsx b/packages/studio/src/components/TimelineToolbar.test.tsx
index 778194ab62..d9de1d7fe4 100644
--- a/packages/studio/src/components/TimelineToolbar.test.tsx
+++ b/packages/studio/src/components/TimelineToolbar.test.tsx
@@ -391,3 +391,34 @@ describe("TimelineToolbar add beat", () => {
act(() => root.unmount());
});
});
+
+describe("TimelineToolbar Linked Selection", () => {
+ it("is on by default, first among the editing toggles, and persists a click", async () => {
+ const { useLinkedClipPreferences } = await import("../utils/linkedClipPreferences");
+ const { host } = renderToolbar();
+ const button = host.querySelector<HTMLButtonElement>('button[aria-label="Linked Selection"]');
+ expect(button?.getAttribute("aria-pressed")).toBe("true");
+ const snapping = host.querySelector('button[aria-label="Toggle timeline snapping"]');
+ expect(snapping && button?.compareDocumentPosition(snapping)).toBe(
+ Node.DOCUMENT_POSITION_FOLLOWING,
+ );
+ act(() => button?.dispatchEvent(new MouseEvent("click", { bubbles: true })));
+ expect(button?.getAttribute("aria-pressed")).toBe("false");
+ expect(readStudioUiPreferences().linkedSelectionEnabled).toBe(false);
+ act(() => useLinkedClipPreferences.getState().setLinkedSelection(true));
+ });
+
+ it("right-click toggles the out-of-sync indicator preference", async () => {
+ const { useLinkedClipPreferences } = await import("../utils/linkedClipPreferences");
+ const { host } = renderToolbar();
+ const button = host.querySelector('button[aria-label="Linked Selection"]');
+ act(() => button?.dispatchEvent(new MouseEvent("contextmenu", { bubbles: true })));
+ const item = document.querySelector<HTMLButtonElement>('[role="menuitemcheckbox"]');
+ expect(item?.textContent).toContain("Show out-of-sync indicators");
+ expect(item?.getAttribute("aria-checked")).toBe("true");
+ act(() => item?.click());
+ expect(useLinkedClipPreferences.getState().syncIndicatorsVisible).toBe(false);
+ expect(readStudioUiPreferences().syncIndicatorsVisible).toBe(false);
+ act(() => useLinkedClipPreferences.getState().setSyncIndicatorsVisible(true));
+ });
+});
diff --git a/packages/studio/src/components/TimelineToolbar.tsx b/packages/studio/src/components/TimelineToolbar.tsx
index fc4424f6d9..7f0da96b33 100644
--- a/packages/studio/src/components/TimelineToolbar.tsx
+++ b/packages/studio/src/components/TimelineToolbar.tsx
@@ -31,6 +31,7 @@ import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
import type { DomEditSelection } from "./editor/domEditingTypes";
import { canSplitElement } from "../utils/timelineElementSplit";
import { useAudioMetersVisible } from "../utils/audioMeterVisibility";
+import { LinkedSelectionToggle } from "./LinkedSelectionToggle";
import { useProjectHasAudio } from "../utils/audioMeterMath";
import { canAddBeatAt, addBeatAtCompositionTime } from "../utils/beatEditActions";
import { isTypingTarget } from "../utils/typingTarget";
@@ -218,6 +219,7 @@ export function TimelineToolbar({
<TimelineToolPicker showSelectAroundPlayhead={showSelectAroundPlayhead} />
{/* Divider: tool-mode | editing-actions */}
<div aria-hidden="true" className="mx-1 h-4 w-px bg-neutral-800" />
+ <LinkedSelectionToggle />
<Tooltip label={timelineSnapEnabled ? "Snapping on (N)" : "Snapping off (N)"}>
<button
type="button"
diff --git a/packages/studio/src/components/editor/PropertyPanelFlat.tsx b/packages/studio/src/components/editor/PropertyPanelFlat.tsx
index a33deaacd8..035a4a3dc4 100644
--- a/packages/studio/src/components/editor/PropertyPanelFlat.tsx
+++ b/packages/studio/src/components/editor/PropertyPanelFlat.tsx
@@ -5,6 +5,7 @@ import { DesignPanelInputProvider } from "../../contexts/DesignPanelInputContext
import { slugifyDesignInput } from "../../utils/designInputTracking";
import { isTextEditableSelection } from "./domEditing";
import type { PropertyPanelFlatProps } from "./propertyPanelFlatProps";
+import { useLinkedSpeedCommit, withLinkedPlaybackRate } from "./linkedSpeedEdits";
import { formatPxMetricValue } from "./propertyPanelHelpers";
import { audioFxSummary } from "./audioFxSummary";
import { resolveAudioGroups } from "@hyperframes/core/audio-groups";
@@ -289,10 +290,12 @@ export function PropertyPanelFlat({
const showMotionEffects = gsapEffectHandlers !== null && !audioSelection;
const showMotionGroup = showMotionTiming || showMotionEffects;
+ const linkedSpeed = useLinkedSpeedCommit(element, forwardedProps.onSetAttributeBatch);
const volumeAutomation = useVolumeAutomation(
element,
currentTime,
onSetAttributeQuiet ?? onSetAttributeLive,
+ linkedSpeed,
);
// The group this clip belongs to, if any — the Audio FX summary reads
@@ -505,7 +508,7 @@ export function PropertyPanelFlat({
element={element}
styles={styles}
onSetStyle={onSetStyle}
- onSetAttribute={onSetAttribute}
+ onSetAttribute={withLinkedPlaybackRate(onSetAttribute, linkedSpeed)}
{...volumeAutomation}
/>
),
diff --git a/packages/studio/src/components/editor/linkedSpeedEdits.test.tsx b/packages/studio/src/components/editor/linkedSpeedEdits.test.tsx
new file mode 100644
index 0000000000..b6d7cf14c0
--- /dev/null
+++ b/packages/studio/src/components/editor/linkedSpeedEdits.test.tsx
@@ -0,0 +1,164 @@
+// @vitest-environment happy-dom
+import { act } from "react";
+import { describe, expect, it, vi } from "vitest";
+import { createHappyDomRootHarness } from "../../player/components/testRootHarness";
+import { usePlayerStore, type TimelineElement } from "../../player/store/playerStore";
+import type { CommitDomAttributeBatch } from "../../hooks/domEditCommitTypes";
+import type { DomEditSelection } from "./domEditingTypes";
+import {
+ fanOutAttributeInSource,
+ linkedPartnerTargets,
+ useLinkedSpeedCommit,
+ withLinkedPlaybackRate,
+ type LinkedSpeedCommit,
+} from "./linkedSpeedEdits";
+import { useVolumeAutomation } from "./useVolumeAutomation";
+import { useLinkedClipPreferences } from "../../utils/linkedClipPreferences";
+
+const clip = (id: string, tag: string, link?: string): TimelineElement => ({
+ id,
+ domId: id,
+ tag,
+ start: 0,
+ duration: 4,
+ track: 0,
+ ...(link ? { link } : {}),
+});
+
+const elements = [
+ clip("talk", "video", "lk-1"),
+ clip("talk-audio", "audio", "lk-1"),
+ clip("music", "audio"),
+];
+
+const source = `<div data-composition-id="main">
+<video id="talk" data-start="0" data-duration="4" data-link="lk-1" muted></video>
+<audio id="talk-audio" data-start="0" data-duration="4" data-link="lk-1" data-automation="{&quot;version&quot;:1,&quot;lanes&quot;:[]}"></audio>
+<audio id="music" data-start="0" data-duration="4"></audio>
+</div>`;
+
+function selection(id: string, dataAttributes: Record<string, string> = {}): DomEditSelection {
+ const element = document.createElement("video");
+ element.id = id;
+ return {
+ id,
+ element,
+ label: id,
+ tagName: "video",
+ sourceFile: "index.html",
+ compositionPath: "index.html",
+ isCompositionHost: false,
+ isInsideLockedComposition: false,
+ boundingBox: { x: 0, y: 0, width: 0, height: 0 },
+ textContent: null,
+ dataAttributes: { start: "0", duration: "4", ...dataAttributes },
+ inlineStyles: {},
+ computedStyles: {},
+ textFields: [],
+ capabilities: {
+ canSelect: true,
+ canEditStyles: true,
+ canCrop: true,
+ canMove: true,
+ canResize: true,
+ canApplyManualOffset: true,
+ canApplyManualSize: true,
+ canApplyManualRotation: true,
+ },
+ };
+}
+
+describe("linkedPartnerTargets", () => {
+ it("returns the other data-link members and nothing for an unlinked clip", () => {
+ expect(linkedPartnerTargets({ id: "talk" }, elements)).toEqual([{ id: "talk-audio" }]);
+ expect(linkedPartnerTargets({ id: "music" }, elements)).toEqual([]);
+ });
+
+ it("reaches no partner with Linked Selection off", () => {
+ useLinkedClipPreferences.getState().setLinkedSelection(false);
+ try {
+ expect(linkedPartnerTargets({ id: "talk" }, elements)).toEqual([]);
+ } finally {
+ useLinkedClipPreferences.getState().setLinkedSelection(true);
+ }
+ });
+});
+
+describe("fanOutAttributeInSource", () => {
+ it("writes each partner from its own current value", () => {
+ const seen: Array<string | undefined> = [];
+ const next = fanOutAttributeInSource(
+ source,
+ [{ id: "talk-audio" }],
+ "data-automation",
+ (raw) => {
+ seen.push(raw);
+ return "rate-lane";
+ },
+ );
+ expect(seen).toEqual(['{"version":1,"lanes":[]}']);
+ expect(next).toContain(
+ 'id="talk-audio" data-start="0" data-duration="4" data-link="lk-1" data-automation="rate-lane"',
+ );
+ expect(next).not.toContain('id="music" data-start="0" data-duration="4" data-automation');
+ });
+});
+
+const harness = createHappyDomRootHarness();
+
+function renderLinked(sel: DomEditSelection, commit: CommitDomAttributeBatch) {
+ let linked: LinkedSpeedCommit | null = null;
+ let rate: ReturnType<typeof useVolumeAutomation>["rate"] | null = null;
+ function Probe() {
+ linked = useLinkedSpeedCommit(sel, commit);
+ rate = useVolumeAutomation(sel, 0, vi.fn(), linked).rate;
+ return null;
+ }
+ const host = document.createElement("div");
+ document.body.appendChild(host);
+ act(() => harness.mount(host).render(<Probe />));
+ return { linked: () => linked, rate: () => rate };
+}
+
+describe("linked speed edits", () => {
+ it("fans a playback-rate edit out to the partner in one batch commit", async () => {
+ usePlayerStore.getState().setElements(elements);
+ const commit = vi.fn<CommitDomAttributeBatch>(async () => true);
+ const onSetAttribute = vi.fn();
+ const probe = renderLinked(selection("talk"), commit);
+ await withLinkedPlaybackRate(onSetAttribute, probe.linked())("playback-rate", "2");
+ expect(onSetAttribute).not.toHaveBeenCalled();
+ expect(commit).toHaveBeenCalledTimes(1);
+ const [, ops, options] = commit.mock.calls[0] ?? [];
+ expect(ops).toEqual([{ type: "attribute", property: "playback-rate", value: "2" }]);
+ expect(options?.prepareContent?.(source)).toContain(
+ 'id="talk-audio" data-start="0" data-duration="4" data-link="lk-1" data-automation="{&quot;version&quot;:1,&quot;lanes&quot;:[]}" data-playback-rate="2"',
+ );
+ });
+
+ it("fans a ramp preset out as one commit carrying each member's rate lane", () => {
+ usePlayerStore.getState().setElements(elements);
+ const commit = vi.fn<CommitDomAttributeBatch>(async () => true);
+ const probe = renderLinked(selection("talk"), commit);
+ act(() => probe.rate()?.onApplyPreset("ramp-in"));
+ expect(commit).toHaveBeenCalledTimes(1);
+ const [, ops, options] = commit.mock.calls[0] ?? [];
+ expect(ops?.[0]?.property).toBe("automation");
+ expect(String(ops?.[0]?.value)).toContain('"target":"rate"');
+ const partner = /id="talk-audio"[^>]*data-automation="([^"]*)"/.exec(
+ options?.prepareContent?.(source) ?? "",
+ )?.[1];
+ expect(partner).toContain("rate");
+ });
+
+ it("leaves an unlinked clip on its usual write path", async () => {
+ usePlayerStore.getState().setElements(elements);
+ const commit = vi.fn<CommitDomAttributeBatch>(async () => true);
+ const onSetAttribute = vi.fn();
+ const probe = renderLinked(selection("music"), commit);
+ expect(probe.linked()).toBeNull();
+ await withLinkedPlaybackRate(onSetAttribute, probe.linked())("playback-rate", "2");
+ expect(onSetAttribute).toHaveBeenCalledWith("playback-rate", "2");
+ expect(commit).not.toHaveBeenCalled();
+ });
+});
diff --git a/packages/studio/src/components/editor/linkedSpeedEdits.ts b/packages/studio/src/components/editor/linkedSpeedEdits.ts
new file mode 100644
index 0000000000..3814454752
--- /dev/null
+++ b/packages/studio/src/components/editor/linkedSpeedEdits.ts
@@ -0,0 +1,94 @@
+import { usePlayerStore, type TimelineElement } from "../../player/store/playerStore";
+import { expandToLinkedMembers } from "../../player/components/audioClipLink";
+import { isLinkedSelectionOn } from "../../utils/linkedClipPreferences";
+import {
+ applyPatchByTarget,
+ readAttributeByTarget,
+ type PatchTarget,
+} from "../../utils/sourcePatcher";
+import type { CommitDomAttributeBatch } from "../../hooks/domEditCommitTypes";
+import { buildPatchTarget } from "../../hooks/timelineEditingHelpers";
+import type { DomEditSelection } from "./domEditingTypes";
+
+type AttributeValueFor = (current: string | undefined) => string | null;
+
+/** Writes a speed attribute on the selection and every `data-link` partner as one undo step. */
+export interface LinkedSpeedCommit {
+ commitAttribute: (attr: string, valueFor: AttributeValueFor, label: string) => Promise<boolean>;
+}
+
+const keyOf = (el: TimelineElement) => el.key ?? el.id;
+const dataProperty = (attr: string) => (attr.startsWith("data-") ? attr.slice(5) : attr);
+
+function isSelected(el: TimelineElement, selection: PatchTarget): boolean {
+ if (selection.hfId && el.hfId) return el.hfId === selection.hfId;
+ return selection.id != null && (el.domId ?? el.id) === selection.id;
+}
+
+export function linkedPartnerTargets(
+ selection: PatchTarget,
+ elements: readonly TimelineElement[],
+): PatchTarget[] {
+ const self = elements.find((el) => isSelected(el, selection));
+ if (!self?.link) return [];
+ const members = expandToLinkedMembers([keyOf(self)], elements, isLinkedSelectionOn());
+ members.delete(keyOf(self));
+ return elements
+ .filter((el) => members.has(keyOf(el)))
+ .map(buildPatchTarget)
+ .filter((target): target is NonNullable<typeof target> => target !== null);
+}
+
+export function fanOutAttributeInSource(
+ source: string,
+ targets: readonly PatchTarget[],
+ attr: string,
+ valueFor: AttributeValueFor,
+): string {
+ const property = dataProperty(attr);
+ return targets.reduce(
+ (html, target) =>
+ applyPatchByTarget(html, target, {
+ type: "attribute",
+ property,
+ value: valueFor(readAttributeByTarget(html, target, attr)),
+ }),
+ source,
+ );
+}
+
+/** Null when the selection has no link partner, so unlinked clips keep their usual write path. */
+export function useLinkedSpeedCommit(
+ selection: DomEditSelection,
+ commit: CommitDomAttributeBatch | undefined,
+): LinkedSpeedCommit | null {
+ const elements = usePlayerStore((s) => s.elements);
+ if (!commit) return null;
+ const partners = linkedPartnerTargets(selection, elements);
+ if (partners.length === 0) return null;
+ return {
+ commitAttribute: (attr, valueFor, label) => {
+ const property = dataProperty(attr);
+ return commit(
+ selection,
+ [{ type: "attribute", property, value: valueFor(selection.dataAttributes[property]) }],
+ {
+ label,
+ prepareContent: (html) => fanOutAttributeInSource(html, partners, attr, valueFor),
+ },
+ );
+ },
+ };
+}
+
+/** Routes `playback-rate` through the linked commit; every other attribute keeps `onSetAttribute`. */
+export function withLinkedPlaybackRate(
+ onSetAttribute: (attr: string, value: string) => void | Promise<void>,
+ linked: LinkedSpeedCommit | null,
+): (attr: string, value: string) => void | Promise<void> {
+ if (!linked) return onSetAttribute;
+ return async (attr, value) => {
+ if (attr !== "playback-rate") return onSetAttribute(attr, value);
+ await linked.commitAttribute("data-playback-rate", () => value, "Edit speed");
+ };
+}
diff --git a/packages/studio/src/components/editor/mediaAudioEdits.test.ts b/packages/studio/src/components/editor/mediaAudioEdits.test.ts
index 199d0f49ac..bca8dc7449 100644
--- a/packages/studio/src/components/editor/mediaAudioEdits.test.ts
+++ b/packages/studio/src/components/editor/mediaAudioEdits.test.ts
@@ -177,6 +177,8 @@ describe("buildKeepSoundCutoutEdit", () => {
]);
expect(audio.getAttribute("data-link")).toBe(video.getAttribute("data-link"));
expect(video.getAttribute("data-link")).toBe("lk-1");
+ expect(video.getAttribute("data-sync-origin")).toBe("lk-1");
+ expect(audio.getAttribute("data-sync-origin")).toBe("lk-1");
expect(audio.parentElement).toBe(video.parentElement);
});
diff --git a/packages/studio/src/components/editor/mediaAudioEdits.ts b/packages/studio/src/components/editor/mediaAudioEdits.ts
index 7b22ce7bb6..7949291e90 100644
--- a/packages/studio/src/components/editor/mediaAudioEdits.ts
+++ b/packages/studio/src/components/editor/mediaAudioEdits.ts
@@ -23,7 +23,11 @@ import type { CommitDomAttributeBatch } from "../../hooks/domEditCommitTypes";
import { buildDomEditPatchTarget, type DomEditSelection } from "./domEditing";
import { generateId } from "../../utils/generateId";
-import { MEDIA_LINK_ATTR, mintLinkId as mintLinkIdFrom } from "@hyperframes/core/media-link";
+import {
+ MEDIA_LINK_ATTR,
+ SYNC_ORIGIN_ATTR,
+ mintLinkId as mintLinkIdFrom,
+} from "@hyperframes/core/media-link";
const SOUND_KEPT_ON_LINKED_AUDIO_STAGE = "Background removed. Sound kept on a linked audio track.";
const SOUND_NOT_KEPT_MESSAGE =
@@ -100,10 +104,14 @@ export function firstFreeName(base: string, taken: Set<string>): string {
export function mintLinkId(doc: Document): string {
const taken = new Set<string>();
- for (const el of Array.from(doc.querySelectorAll(`[id], [${MEDIA_LINK_ATTR}]`))) {
- if (el.id) taken.add(el.id);
- const link = el.getAttribute(MEDIA_LINK_ATTR);
- if (link) taken.add(link);
+ const selector = `[id], [${MEDIA_LINK_ATTR}], [${SYNC_ORIGIN_ATTR}]`;
+ for (const el of Array.from(doc.querySelectorAll(selector))) {
+ for (const value of [
+ el.id,
+ el.getAttribute(MEDIA_LINK_ATTR),
+ el.getAttribute(SYNC_ORIGIN_ATTR),
+ ])
+ if (value) taken.add(value);
}
return mintLinkIdFrom(taken);
}
@@ -187,7 +195,10 @@ export function buildKeepSoundCutoutEdit(input: {
movedSound.push([HF_AUDIO_AUTOMATION_ATTR, audioTakes]);
ops.push(dataAttr(stripDataPrefix(HF_AUDIO_AUTOMATION_ATTR), videoKeeps));
}
- ops.push(dataAttr(stripDataPrefix(MEDIA_LINK_ATTR), linkId));
+ ops.push(
+ dataAttr(stripDataPrefix(MEDIA_LINK_ATTR), linkId),
+ dataAttr(stripDataPrefix(SYNC_ORIGIN_ATTR), linkId),
+ );
const prepareContent = (source: string): string => {
const originalSrc = readAuthoredSrc(source, target);
@@ -208,6 +219,7 @@ export function buildKeepSoundCutoutEdit(input: {
...timing,
["data-track-index", String(firstFreeTrackIndex(source))],
[MEDIA_LINK_ATTR, linkId],
+ [SYNC_ORIGIN_ATTR, linkId],
...movedSound,
];
if (video.hasAttribute("loop")) attrs.push(["loop", ""]);
diff --git a/packages/studio/src/components/editor/mediaLinkEdits.test.ts b/packages/studio/src/components/editor/mediaLinkEdits.test.ts
index 70c7fbb017..5fbc15e534 100644
--- a/packages/studio/src/components/editor/mediaLinkEdits.test.ts
+++ b/packages/studio/src/components/editor/mediaLinkEdits.test.ts
@@ -54,6 +54,7 @@ describe("detachAudioInSource", () => {
"data-playback-rate": "1",
"data-track-index": "2",
"data-link": result?.linkId,
+ "data-sync-origin": result?.linkId,
"data-volume": "0.5",
"data-fade-in": "0.3",
"data-fade-out": "0.2",
@@ -68,6 +69,7 @@ describe("detachAudioInSource", () => {
const after = attrsOf(result?.html ?? "", "video#talk");
expect(after).toHaveProperty("muted");
expect(after["data-link"]).toBe(result?.linkId);
+ expect(after["data-sync-origin"]).toBe(result?.linkId);
for (const gone of [
"data-has-audio",
"data-volume",
@@ -179,7 +181,14 @@ describe("removeElementInSource", () => {
describe("linkInSource", () => {
it("mints an id no element or link already uses", () => {
const src = '<video id="lk-1" data-link="lk-2"></video><audio id="a"></audio>';
- expect(linkInSource(src, [{ id: "a" }])).toContain('<audio id="a" data-link="lk-3">');
+ expect(linkInSource(src, [{ id: "a" }])).toContain(
+ '<audio id="a" data-link="lk-3" data-sync-origin="lk-3">',
+ );
+ });
+
+ it("skips ids already used as a sync origin", () => {
+ const src = '<video id="v" data-sync-origin="lk-1"></video><audio id="a"></audio>';
+ expect(linkInSource(src, [{ id: "a" }])).toContain('data-link="lk-2"');
});
});
@@ -192,6 +201,17 @@ describe("setLinkInSource", () => {
);
expect(setLinkInSource(linked, [{ id: "v" }, { id: "a" }], null)).toBe(src);
});
+
+ it("keeps the sync origin when unlinking", () => {
+ const linked = linkInSource('<video id="v"></video><audio id="a"></audio>', [
+ { id: "v" },
+ { id: "a" },
+ ]);
+ const unlinked = setLinkInSource(linked, [{ id: "v" }, { id: "a" }], null);
+ expect(unlinked).toBe(
+ '<video id="v" data-sync-origin="lk-1"></video><audio id="a" data-sync-origin="lk-1"></audio>',
+ );
+ });
});
const el = (id: string, tag: string, extra: Record<string, unknown> = {}) => ({
diff --git a/packages/studio/src/components/editor/mediaLinkEdits.ts b/packages/studio/src/components/editor/mediaLinkEdits.ts
index f98c26c87a..999895e721 100644
--- a/packages/studio/src/components/editor/mediaLinkEdits.ts
+++ b/packages/studio/src/components/editor/mediaLinkEdits.ts
@@ -1,5 +1,5 @@
import { HF_AUDIO_AUTOMATION_ATTR } from "@hyperframes/core/audio-automation";
-import { MEDIA_LINK_ATTR, mintLinkId } from "@hyperframes/core/media-link";
+import { MEDIA_LINK_ATTR, SYNC_ORIGIN_ATTR, mintLinkId } from "@hyperframes/core/media-link";
import { sameCompositionScope, type TimelineElement } from "../../player/store/timelineElement";
import { mediaAssetIdentity, sharesLinkGroup } from "../../player/components/audioClipLink";
import {
@@ -23,6 +23,7 @@ import {
const LINK_PROPERTY = MEDIA_LINK_ATTR.slice("data-".length);
const HIDDEN_ATTR = "data-hidden";
+const SYNC_ORIGIN_PROPERTY = SYNC_ORIGIN_ATTR.slice("data-".length);
const SYNC_TOLERANCE_S = 1e-3;
const dataOp = (property: string, value: string | null): PatchOperation => ({
@@ -43,7 +44,7 @@ function applyOps(source: string, target: PatchTarget, ops: readonly PatchOperat
function mintLinkIdForSource(source: string): string {
const links = Array.from(
- source.matchAll(/\bdata-link=["']([^"']+)["']/g),
+ source.matchAll(/\bdata-(?:link|sync-origin)=["']([^"']+)["']/g),
(match) => match[1] ?? "",
);
return mintLinkId([...collectHtmlIds(source), ...links]);
@@ -61,9 +62,14 @@ export function setLinkInSource(
);
}
-/** Link the targets under one freshly minted id. */
+/** Link the targets under one freshly minted id, which is also their sync origin. */
export function linkInSource(source: string, targets: readonly PatchTarget[]): string {
- return setLinkInSource(source, targets, mintLinkIdForSource(source));
+ const linkId = mintLinkIdForSource(source);
+ return targets.reduce(
+ (html, target) =>
+ applyOps(html, target, [dataOp(LINK_PROPERTY, linkId), dataOp(SYNC_ORIGIN_PROPERTY, linkId)]),
+ source,
+ );
}
/** Remove one element (open tag through its matching close tag) and its line's indentation. */
@@ -126,7 +132,7 @@ export function detachAudioInSource(
moved.push([HF_AUDIO_AUTOMATION_ATTR, audioTakes]);
videoOps.push(dataOp(HF_AUDIO_AUTOMATION_ATTR, videoKeeps));
}
- videoOps.push(dataOp(LINK_PROPERTY, linkId));
+ videoOps.push(dataOp(LINK_PROPERTY, linkId), dataOp(SYNC_ORIGIN_PROPERTY, linkId));
const timing: Array<[string, string]> = [];
for (const name of COPIED_TIMING_ATTRS) {
@@ -141,6 +147,7 @@ export function detachAudioInSource(
...timing,
["data-track-index", String(input.track)],
[MEDIA_LINK_ATTR, linkId],
+ [SYNC_ORIGIN_ATTR, linkId],
...moved,
];
if (hasBooleanAttr(source, target, "loop")) attrs.push(["loop", ""]);
@@ -172,7 +179,12 @@ export function mergeAudioInSource(
}
const automation = readAttributeByTarget(source, audioTarget, HF_AUDIO_AUTOMATION_ATTR);
if (automation !== undefined) videoOps.push(dataOp(HF_AUDIO_AUTOMATION_ATTR, automation));
- videoOps.push(htmlOp("muted", null), dataOp(LINK_PROPERTY, null), dataOp("has-audio", "true"));
+ videoOps.push(
+ htmlOp("muted", null),
+ dataOp(LINK_PROPERTY, null),
+ dataOp(SYNC_ORIGIN_PROPERTY, null),
+ dataOp("has-audio", "true"),
+ );
return applyOps(removeElementInSource(source, audioTarget), videoTarget, videoOps);
}
diff --git a/packages/studio/src/components/editor/propertyPanelFlatMediaSection.test.tsx b/packages/studio/src/components/editor/propertyPanelFlatMediaSection.test.tsx
index b479e00f44..64aa15308a 100644
--- a/packages/studio/src/components/editor/propertyPanelFlatMediaSection.test.tsx
+++ b/packages/studio/src/components/editor/propertyPanelFlatMediaSection.test.tsx
@@ -880,6 +880,7 @@ describe.each<PanelKind>(["flat", "design"])("%s panel — cutout keeps the soun
dataOp("has-audio", null),
dataOp("volume", null),
dataOp("link", "lk-1"),
+ dataOp("sync-origin", "lk-1"),
]);
const source =
'<div data-composition-id="main"><video id="s1-bg" src="assets/intro-loop.mp4" muted data-start="2" data-duration="3" data-track-index="0" data-link="lk-1"></video></div>';
diff --git a/packages/studio/src/components/editor/propertyPanelMediaSection.tsx b/packages/studio/src/components/editor/propertyPanelMediaSection.tsx
index c86db6461d..a8b57892d7 100644
--- a/packages/studio/src/components/editor/propertyPanelMediaSection.tsx
+++ b/packages/studio/src/components/editor/propertyPanelMediaSection.tsx
@@ -24,6 +24,7 @@ import {
audioGainToText,
} from "@hyperframes/core/audio-gain";
import type { CommitDomAttributeBatch } from "../../hooks/domEditCommitTypes";
+import { useLinkedSpeedCommit, withLinkedPlaybackRate } from "./linkedSpeedEdits";
import { commitCutout, commitHasAudioToggle, commitMutedToggle } from "./mediaAudioEdits";
// fallow-ignore-next-line complexity
@@ -56,6 +57,10 @@ export function MediaSection({
) => Promise<BackgroundRemovalResult>;
}) {
const track = useTrackDesignInput();
+ const setRate = withLinkedPlaybackRate(
+ onSetAttribute,
+ useLinkedSpeedCommit(element, onSetAttributeBatch),
+ );
const isVideo = element.tagName === "video";
const isAudio = element.tagName === "audio";
const isImage = element.tagName === "img";
@@ -279,7 +284,7 @@ export function MediaSection({
displayValue={`${formatNumericValue(playbackRate)}x`}
formatDisplayValue={(next) => `${formatNumericValue(next / 100)}x`}
onCommit={(next) => {
- void onSetAttribute("playback-rate", formatNumericValue(next / 100));
+ void setRate("playback-rate", formatNumericValue(next / 100));
}}
/>
</div>
diff --git a/packages/studio/src/components/editor/useVolumeAutomation.ts b/packages/studio/src/components/editor/useVolumeAutomation.ts
index f0fe065dc4..f45e2617bf 100644
--- a/packages/studio/src/components/editor/useVolumeAutomation.ts
+++ b/packages/studio/src/components/editor/useVolumeAutomation.ts
@@ -26,6 +26,8 @@ import {
import { deriveElementTiming } from "./propertyPanelFlatTimingDerivation";
import { SPEED_PRESETS, speedPresetLane, type SpeedPresetId } from "@hyperframes/core/speed-ramp";
import { clampNumber } from "../../utils/studioHelpers";
+import type { HfAutomation } from "@hyperframes/core/audio-automation";
+import type { LinkedSpeedCommit } from "./linkedSpeedEdits";
export interface LaneBinding {
automated: boolean;
@@ -59,6 +61,7 @@ export function useVolumeAutomation(
element: DomEditSelection,
currentTime: number,
onSetAttributeQuiet: (attr: string, value: string | null) => void | Promise<void>,
+ linkedSpeed: LinkedSpeedCommit | null = null,
): VolumeAutomationBinding {
// The chain is not needed to resolve a volume or rate lane: both are always valid
// targets, so this deliberately does not parse it.
@@ -77,7 +80,22 @@ export function useVolumeAutomation(
// playing track, while the same click on an effect parameter did not.
void onSetAttributeQuiet(HF_AUDIO_AUTOMATION_ATTR, automationAttrValue(next) || null);
};
- const laneBinding = (target: string, seed: number): LaneBinding => {
+ type Edit = (current: HfAutomation) => HfAutomation;
+ const writeOwn = (edit: Edit) => write(edit(automation));
+ // Speed moves every data-link member together, so a linked clip's rate lane edits fan out.
+ const writeRate = (edit: Edit) => {
+ if (!linkedSpeed) return writeOwn(edit);
+ void linkedSpeed.commitAttribute(
+ HF_AUDIO_AUTOMATION_ATTR,
+ (raw) => automationAttrValue(edit(readPanelAutomation(raw, undefined))) || null,
+ "Edit speed",
+ );
+ };
+ const laneBinding = (
+ target: string,
+ seed: number,
+ writeLane: (edit: Edit) => void,
+ ): LaneBinding => {
const lane = automation.lanes.find((l) => l.target === target);
return {
automated: lane !== undefined,
@@ -85,9 +103,9 @@ export function useVolumeAutomation(
? sampleAutomationLane(lane, clipTimeSec, resolveAutomationRange(target, undefined)?.scale)
: undefined,
// Seeded at the level the control already shows, so automating does not change it.
- onAutomate: () => write(withSeededLane(automation, target, seed)),
- onRemoveAutomation: () => write(withoutLane(automation, target)),
- onCommitAt: (v: number) => write(withPointAt(automation, target, clipTimeSec, v)),
+ onAutomate: () => writeLane((a) => withSeededLane(a, target, seed)),
+ onRemoveAutomation: () => writeLane((a) => withoutLane(a, target)),
+ onCommitAt: (v: number) => writeLane((a) => withPointAt(a, target, clipTimeSec, v)),
};
};
// `??` alone would let an empty `data-volume` through as Number("") === 0, so
@@ -96,9 +114,13 @@ export function useVolumeAutomation(
const raw = element.dataAttributes?.["volume"];
const parsed = raw ? Number(raw) : 1;
const current = Number.isFinite(parsed) ? parsed : 1;
- const volume = laneBinding(VOLUME_TARGET, current);
+ const volume = laneBinding(VOLUME_TARGET, current, writeOwn);
const rateAttr = Number.parseFloat(element.dataAttributes?.["playback-rate"] ?? "");
- const rate = laneBinding(RATE_TARGET, Number.isFinite(rateAttr) && rateAttr > 0 ? rateAttr : 1);
+ const rate = laneBinding(
+ RATE_TARGET,
+ Number.isFinite(rateAttr) && rateAttr > 0 ? rateAttr : 1,
+ writeRate,
+ );
return {
volumeAutomated: volume.automated,
automatedVolumeValue: volume.automatedValue,
@@ -109,7 +131,7 @@ export function useVolumeAutomation(
...rate,
canApplyPreset: elDuration > 0,
onApplyPreset: (id) => {
- if (elDuration > 0) write(withLane(automation, speedPresetLane(id, elDuration)));
+ if (elDuration > 0) writeRate((a) => withLane(a, speedPresetLane(id, elDuration)));
},
},
};
diff --git a/packages/studio/src/contexts/TimelineEditContext.tsx b/packages/studio/src/contexts/TimelineEditContext.tsx
index 3ec34a8889..3144ee661f 100644
--- a/packages/studio/src/contexts/TimelineEditContext.tsx
+++ b/packages/studio/src/contexts/TimelineEditContext.tsx
@@ -45,6 +45,7 @@ const EDIT_CALLBACK_KEY_SET: Record<keyof TimelineEditCallbacks, true> = {
onRazorSplit: true,
onRazorSplitAll: true,
onFreezeFrame: true,
+ onNotice: true,
onDeleteKeyframe: true,
onDeleteAllKeyframes: true,
onMoveKeyframeToPlayhead: true,
diff --git a/packages/studio/src/hooks/timelineLinkEditPlan.test.ts b/packages/studio/src/hooks/timelineLinkEditPlan.test.ts
index 0513e12a41..5c95035193 100644
--- a/packages/studio/src/hooks/timelineLinkEditPlan.test.ts
+++ b/packages/studio/src/hooks/timelineLinkEditPlan.test.ts
@@ -78,3 +78,36 @@ describe("planLinkEdit", () => {
expect(out).toContain('data-track-index="1"');
});
});
+
+describe("planLinkEdit into sync", () => {
+ const drifted =
+ '<div data-composition-id="main" data-duration="10"><video id="talk" src="talk.mp4" muted data-sync-origin="lk-1" data-start="2" data-duration="6"></video><audio id="talk-audio" src="talk.mp4" data-sync-origin="lk-1" data-start="2.5" data-duration="6" data-media-start="0"></audio></div>';
+ const late = clip("talk-audio", "audio", { start: 2.5, playbackStart: 0 });
+
+ it("moves one clip's start, leaving its partner and link alone", () => {
+ const plan = planLinkEdit({ kind: "move-into-sync", element: late, start: 2 }, [video, late]);
+ expect(plan?.label).toBe("Move into Sync");
+ const html = plan?.transform(drifted) ?? "";
+ expect(html).toContain('id="talk-audio" src="talk.mp4" data-sync-origin="lk-1" data-start="2"');
+ expect(html).toContain('id="talk" src="talk.mp4" muted data-sync-origin="lk-1" data-start="2"');
+ });
+
+ it("slips one clip's media start in place", () => {
+ const plan = planLinkEdit({ kind: "slip-into-sync", element: late, mediaStart: 0.5 }, [
+ video,
+ late,
+ ]);
+ expect(plan?.label).toBe("Slip into Sync");
+ const html = plan?.transform(drifted) ?? "";
+ expect(html).toContain('data-start="2.5" data-duration="6" data-media-start="0.5"');
+ });
+
+ it("slips the legacy playback-start attribute when that is what the clip uses", () => {
+ const legacy = { ...late, playbackStartAttr: "playback-start" as const };
+ const html =
+ planLinkEdit({ kind: "slip-into-sync", element: legacy, mediaStart: 0.5 }, [])?.transform(
+ '<audio id="talk-audio" data-playback-start="0"></audio>',
+ ) ?? "";
+ expect(html).toBe('<audio id="talk-audio" data-playback-start="0.5"></audio>');
+ });
+});
diff --git a/packages/studio/src/hooks/timelineLinkEditPlan.ts b/packages/studio/src/hooks/timelineLinkEditPlan.ts
index 65b0c25f0d..c3d6bce414 100644
--- a/packages/studio/src/hooks/timelineLinkEditPlan.ts
+++ b/packages/studio/src/hooks/timelineLinkEditPlan.ts
@@ -2,6 +2,11 @@ import type { TimelineElement } from "../player";
import type { TimelineLinkEdit } from "../player/components/timelineCallbacks";
import { buildPatchTarget, type PatchTarget } from "./timelineEditingHelpers";
import { sharesLinkGroup } from "../player/components/audioClipLink";
+import { toAuthoredStart } from "../player/store/timelineElement";
+import { formatTimelineMediaOffset } from "../player/components/timelineEditing";
+import { applyPatchByTarget } from "../utils/sourcePatcher";
+import { setCompositionDurationToContent } from "../utils/timelineAssetDrop";
+import { furthestClipEndFromSource } from "../player/lib/timelineElementHelpers";
import {
detachAudioInSource,
linkInSource,
@@ -42,6 +47,35 @@ export function clipsToUnlink(
return [...removed.filter((el) => el.link), ...orphans.values()];
}
+type SyncEdit = Extract<TimelineLinkEdit, { kind: "move-into-sync" | "slip-into-sync" }>;
+
+function planSyncEdit(edit: SyncEdit): LinkEditPlan | null {
+ const target = buildPatchTarget(edit.element);
+ if (!target) return null;
+ if (edit.kind === "move-into-sync") {
+ const value = formatTimelineMediaOffset(toAuthoredStart(edit.element, edit.start));
+ return {
+ label: "Move into Sync",
+ anchor: edit.element,
+ transform: (s) => {
+ const moved = applyPatchByTarget(s, target, {
+ type: "attribute",
+ property: "start",
+ value,
+ });
+ return setCompositionDurationToContent(moved, furthestClipEndFromSource(moved));
+ },
+ };
+ }
+ const property = edit.element.playbackStartAttr ?? "media-start";
+ const value = formatTimelineMediaOffset(edit.mediaStart);
+ return {
+ label: "Slip into Sync",
+ anchor: edit.element,
+ transform: (s) => applyPatchByTarget(s, target, { type: "attribute", property, value }),
+ };
+}
+
export function planLinkEdit(
edit: TimelineLinkEdit,
elements: readonly TimelineElement[],
@@ -72,6 +106,9 @@ export function planLinkEdit(
null,
};
}
+ case "move-into-sync":
+ case "slip-into-sync":
+ return planSyncEdit(edit);
case "merge": {
const videoTarget = buildPatchTarget(edit.video);
const audioTarget = buildPatchTarget(edit.audio);
diff --git a/packages/studio/src/hooks/useRazorSplit.ts b/packages/studio/src/hooks/useRazorSplit.ts
index 29b9113c01..1769211825 100644
--- a/packages/studio/src/hooks/useRazorSplit.ts
+++ b/packages/studio/src/hooks/useRazorSplit.ts
@@ -5,6 +5,7 @@ import { getTimelineElementLabel } from "../utils/studioHelpers";
import { trackStudioRazorSplit } from "../telemetry/events";
import { canSplitElementAt, selectSplittableElements } from "../utils/timelineElementSplit";
import { linkedMembersOf } from "../player/components/audioClipLink";
+import { isLinkedSelectionOn } from "../utils/linkedClipPreferences";
import { buildAtomicCutIntents, runAtomicCutTransaction } from "../utils/razorSplitTransaction";
import type { RecordEditInput } from "./timelineEditingHelpers";
import { useFreezeFrame } from "./useFreezeFrame";
@@ -104,7 +105,11 @@ export function useRazorSplit({
}
if (!canSplitElementAt(element, splitTime)) return;
try {
- const members = linkedMembersOf(element, usePlayerStore.getState().elements);
+ const members = linkedMembersOf(
+ element,
+ usePlayerStore.getState().elements,
+ isLinkedSelectionOn(),
+ );
const result = await runCut(
members.filter((member) => canSplitElementAt(member, splitTime)),
splitTime,
diff --git a/packages/studio/src/hooks/useRenderClipContent.test.ts b/packages/studio/src/hooks/useRenderClipContent.test.ts
index 0edcc303c0..9528406fb0 100644
--- a/packages/studio/src/hooks/useRenderClipContent.test.ts
+++ b/packages/studio/src/hooks/useRenderClipContent.test.ts
@@ -196,7 +196,7 @@ describe("useRenderClipContent", () => {
}
});
- it("marks audio linked by data-link, and muted when hidden", () => {
+ it("marks hidden audio muted and leaves the link to the chain badge", () => {
usePlayerStore.setState({
thumbnailMode: "hidden",
elements: [
@@ -220,9 +220,9 @@ describe("useRenderClipContent", () => {
link: "lk-1",
hidden: true,
});
- expect(isValidElement<{ linked: boolean; muted: boolean }>(linked)).toBe(true);
- if (isValidElement<{ linked: boolean; muted: boolean }>(linked)) {
- expect(linked.props.linked).toBe(true);
+ expect(isValidElement<{ linked?: boolean; muted: boolean }>(linked)).toBe(true);
+ if (isValidElement<{ linked?: boolean; muted: boolean }>(linked)) {
+ expect(linked.props.linked).toBeUndefined();
expect(linked.props.muted).toBe(true);
}
});
@@ -250,6 +250,7 @@ describe("useRenderClipContent", () => {
expect(isValidElement<{ waveformUrl: string }>(waveform) && waveform.props.waveformUrl).toBe(
"/api/projects/my-project/waveform/talk.mp4",
);
+ expect(isValidElement<{ labelInset?: number }>(waveform) && waveform.props.labelInset).toBe(0);
});
it("keeps a muted or silent video to thumbnails only", () => {
diff --git a/packages/studio/src/hooks/useRenderClipContent.ts b/packages/studio/src/hooks/useRenderClipContent.ts
index a929e6ac3a..87d4d7a657 100644
--- a/packages/studio/src/hooks/useRenderClipContent.ts
+++ b/packages/studio/src/hooks/useRenderClipContent.ts
@@ -63,6 +63,7 @@ function renderAudioClip(
labelColor: string,
context: TimelineClipRenderContext,
elements: readonly TimelineElement[],
+ labelInset?: number,
): ReactNode {
const audioUrl = resolveMediaPreviewUrl(el.src ?? "", pid, window.location.origin);
const srcRelative = resolvePreviewRelative(audioUrl, pid, window.location.origin);
@@ -84,6 +85,7 @@ function renderAudioClip(
projectId: pid,
sessionEpoch,
priority: context.priority,
+ labelInset,
...audioPillFlags(el, elements),
});
return createElement(
@@ -103,10 +105,10 @@ function renderAudioClip(
function withSoundStrip(
el: TimelineElement,
thumbnail: ReactNode,
- waveform: () => ReactNode,
+ waveform: (labelInset: number) => ReactNode,
): ReactNode {
if (el.tag !== "video" || !clipHasSound(el)) return thumbnail;
- return createElement(AudibleVideoClipContent, { thumbnail, waveform: waveform() });
+ return createElement(AudibleVideoClipContent, { thumbnail, waveform: waveform(0) });
}
export interface UseRenderClipContentOptions {
@@ -141,7 +143,8 @@ export function useRenderClipContent({
// Thumbnail generation disabled (perf) -> plain clip bars. Audio still shows
// its waveform (cheap, not a frame thumbnail). Toggle: timeline toolbar.
- const waveform = () => renderAudioClip(el, pid, sessionEpoch, style.label, context, elements);
+ const waveform = (labelInset?: number) =>
+ renderAudioClip(el, pid, sessionEpoch, style.label, context, elements, labelInset);
if (effectiveMode === "hidden") {
return rendersWaveform(el) ? waveform() : withSoundStrip(el, null, waveform);
}
diff --git a/packages/studio/src/hooks/useTimelineLinkEditing.test.tsx b/packages/studio/src/hooks/useTimelineLinkEditing.test.tsx
index 06808aec51..de7d0cd473 100644
--- a/packages/studio/src/hooks/useTimelineLinkEditing.test.tsx
+++ b/packages/studio/src/hooks/useTimelineLinkEditing.test.tsx
@@ -4,6 +4,7 @@ import { createRoot } from "react-dom/client";
import { afterEach, describe, expect, it, vi } from "vitest";
import { usePlayerStore, type TimelineElement } from "../player";
import { useTimelineLinkEditing, withLinkPartners } from "./useTimelineLinkEditing";
+import { useLinkedClipPreferences } from "../utils/linkedClipPreferences";
(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
@@ -74,6 +75,20 @@ describe("useTimelineLinkEditing", () => {
unmount();
});
+ it("with Linked Selection off, delete removes the clip alone and unlinks the survivor", async () => {
+ const del = vi.fn().mockResolvedValue(undefined);
+ const { api, unmount } = await renderLinkEditing(del);
+ useLinkedClipPreferences.getState().setLinkedSelection(false);
+ try {
+ expect(withLinkPartners([video])).toEqual([video]);
+ await act(async () => api.handleLinkedElementDelete(video));
+ expect(del).toHaveBeenCalledWith([video], [audio]);
+ } finally {
+ useLinkedClipPreferences.getState().setLinkedSelection(true);
+ }
+ unmount();
+ });
+
it("delete-only removes one member and unlinks the survivor", async () => {
const del = vi.fn().mockResolvedValue(undefined);
const { api, unmount } = await renderLinkEditing(del);
diff --git a/packages/studio/src/hooks/useTimelineLinkEditing.ts b/packages/studio/src/hooks/useTimelineLinkEditing.ts
index b8fadcd919..6423e3acee 100644
--- a/packages/studio/src/hooks/useTimelineLinkEditing.ts
+++ b/packages/studio/src/hooks/useTimelineLinkEditing.ts
@@ -2,6 +2,7 @@ import { useCallback, type MutableRefObject } from "react";
import { usePlayerStore, type TimelineElement } from "../player";
import type { TimelineLinkEdit } from "../player/components/timelineCallbacks";
import { expandToLinkedMembers } from "../player/components/audioClipLink";
+import { isLinkedSelectionOn } from "../utils/linkedClipPreferences";
import { saveProjectFilesWithHistory, type RecordEditInput } from "../utils/studioFileHistory";
import { getStudioSaveErrorMessage } from "../utils/studioSaveDiagnostics";
import { readFileContent } from "./timelineEditingHelpers";
@@ -33,6 +34,8 @@ export function linkEditTargets(edit: TimelineLinkEdit): TimelineElement[] {
case "link":
return [...edit.elements];
case "detach":
+ case "move-into-sync":
+ case "slip-into-sync":
return [edit.element];
case "merge":
return [edit.video, edit.audio];
@@ -41,7 +44,7 @@ export function linkEditTargets(edit: TimelineLinkEdit): TimelineElement[] {
export function withLinkPartners(selection: readonly TimelineElement[]): TimelineElement[] {
const elements = usePlayerStore.getState().elements;
- const keys = expandToLinkedMembers(selection.map(keyOf), elements);
+ const keys = expandToLinkedMembers(selection.map(keyOf), elements, isLinkedSelectionOn());
const known = new Set(selection.map(keyOf));
return [...selection, ...elements.filter((el) => keys.has(keyOf(el)) && !known.has(keyOf(el)))];
}
@@ -115,13 +118,20 @@ export function useTimelineLinkEditing({
);
const handleLinkedElementsDelete = useCallback(
- (selection: TimelineElement[]) => handleTimelineElementsDelete(withLinkPartners(selection)),
+ (selection: TimelineElement[]) => {
+ if (isLinkedSelectionOn()) return handleTimelineElementsDelete(withLinkPartners(selection));
+ const removed = new Set(selection.map(keyOf));
+ const orphans = clipsToUnlink(selection, usePlayerStore.getState().elements).filter(
+ (el) => !removed.has(keyOf(el)),
+ );
+ return handleTimelineElementsDelete(selection, orphans);
+ },
[handleTimelineElementsDelete],
);
const handleLinkedElementDelete = useCallback(
- (element: TimelineElement) => handleTimelineElementsDelete(withLinkPartners([element])),
- [handleTimelineElementsDelete],
+ (element: TimelineElement) => handleLinkedElementsDelete([element]),
+ [handleLinkedElementsDelete],
);
const handleDeleteElementOnly = useCallback(
diff --git a/packages/studio/src/index.ts b/packages/studio/src/index.ts
index b79b3d6df6..b891063737 100644
--- a/packages/studio/src/index.ts
+++ b/packages/studio/src/index.ts
@@ -31,6 +31,7 @@ export {
liveTime,
formatTime,
} from "./player";
+export { usePreviewIframeStore } from "./player/store/previewIframeStore";
export type {
PlayerHandle,
PlayerHandleElement,
diff --git a/packages/studio/src/player/components/AudioWaveform.test.tsx b/packages/studio/src/player/components/AudioWaveform.test.tsx
index f03c11df92..89f6a8e813 100644
--- a/packages/studio/src/player/components/AudioWaveform.test.tsx
+++ b/packages/studio/src/player/components/AudioWaveform.test.tsx
@@ -96,7 +96,7 @@ describe("AudioWaveform", () => {
act(() => root.unmount());
});
- it("greys the clip in place when muted and draws the parent tick when linked", () => {
+ it("greys the clip in place when muted", () => {
const host = document.createElement("div");
host.className = "timeline-clip is-audio";
document.body.append(host);
@@ -112,15 +112,42 @@ describe("AudioWaveform", () => {
sessionEpoch={1}
priority="visible"
muted
- linked
/>,
);
});
expect(host.getAttribute("data-audio-muted")).toBe("true");
- expect(host.querySelector(".timeline-audio-link")).not.toBeNull();
act(() => root.unmount());
expect(host.hasAttribute("data-audio-muted")).toBe(false);
});
+
+ it("fills a short sound strip when the label band is dropped", () => {
+ const heights = [16, 0].map((labelInset) => {
+ const host = document.createElement("div");
+ document.body.append(host);
+ const root = createRoot(host);
+ act(() => {
+ root.render(
+ <AudioWaveform
+ audioUrl="/media/talk.mp4"
+ label=""
+ labelColor="#fff"
+ projectId="project-a"
+ sessionEpoch={1}
+ priority="visible"
+ {...(labelInset === 16 ? {} : { labelInset })}
+ />,
+ );
+ });
+ const canvas = host.querySelector("canvas");
+ const box = { top: canvas?.style.top, height: canvas?.style.height };
+ act(() => root.unmount());
+ return box;
+ });
+ expect(heights).toEqual([
+ { top: "16px", height: "calc(100% - 16px)" },
+ { top: "0px", height: "calc(100% - 0px)" },
+ ]);
+ });
});
diff --git a/packages/studio/src/player/components/AudioWaveform.tsx b/packages/studio/src/player/components/AudioWaveform.tsx
index 2d8eef38f9..0a2ce9dee4 100644
--- a/packages/studio/src/player/components/AudioWaveform.tsx
+++ b/packages/studio/src/player/components/AudioWaveform.tsx
@@ -18,8 +18,7 @@ export interface AudioWaveformProps {
priority: ThumbnailPriority;
/** `data-hidden` or a muted audio group. Greys the pill; the clip stays. */
muted?: boolean;
- /** Same media file as a video clip. Draws the 1px parent tick. */
- linked?: boolean;
+ labelInset?: number;
}
const BAR_STEP = 3;
@@ -167,7 +166,7 @@ export const AudioWaveform = memo(function AudioWaveform({
sessionEpoch,
priority,
muted = false,
- linked = false,
+ labelInset = 16,
}: AudioWaveformProps) {
const rootRef = useRef<HTMLDivElement | null>(null);
const canvasRef = useRef<HTMLCanvasElement | null>(null);
@@ -236,17 +235,17 @@ export const AudioWaveform = memo(function AudioWaveform({
return (
<div ref={rootRef} className="absolute inset-0">
- {linked ? <span className="timeline-audio-link" aria-hidden="true" /> : null}
<div className="absolute inset-0 overflow-hidden" style={{ zIndex: 10 }}>
<canvas
ref={setCanvasRef}
className="absolute inset-x-0 bottom-0 w-full"
- style={{ top: 16, height: "calc(100% - 16px)" }}
+ style={{ top: labelInset, height: `calc(100% - ${labelInset}px)` }}
/>
{snapshot.status === "loading" && (
<div
- className="absolute inset-x-0 bottom-0 top-4 animate-pulse"
+ className="absolute inset-x-0 bottom-0 animate-pulse"
style={{
+ top: labelInset,
background: "var(--timeline-thumbnail-shimmer)",
}}
/>
@@ -256,7 +255,7 @@ export const AudioWaveform = memo(function AudioWaveform({
{snapshot.status === "error" && (
<div
className="absolute inset-x-0 flex items-center justify-center gap-1.5"
- style={{ top: 16, bottom: 0 }}
+ style={{ top: labelInset, bottom: 0 }}
>
<div
className="absolute inset-x-0"
diff --git a/packages/studio/src/player/components/ClipContextMenu.groups.test.tsx b/packages/studio/src/player/components/ClipContextMenu.groups.test.tsx
new file mode 100644
index 0000000000..dd3f660b49
--- /dev/null
+++ b/packages/studio/src/player/components/ClipContextMenu.groups.test.tsx
@@ -0,0 +1,102 @@
+// @vitest-environment happy-dom
+import { act } from "react";
+import { describe, expect, it, vi } from "vitest";
+import { createHappyDomRootHarness } from "./testRootHarness";
+import { ClipContextMenu } from "./ClipContextMenu";
+import { usePlayerStore, type TimelineElement } from "../store/playerStore";
+import { TimelineEditProvider } from "../../contexts/TimelineEditContext";
+
+const iframe = document.createElement("iframe");
+vi.mock("../../contexts/StudioContext", () => ({
+ useStudioShellContextOptional: () => ({
+ projectId: "p1",
+ showToast: vi.fn(),
+ previewIframeRef: { current: iframe },
+ }),
+}));
+
+const harness = createHappyDomRootHarness();
+
+const talk: TimelineElement = {
+ id: "talk",
+ domId: "talk",
+ tag: "video",
+ src: "talk.mp4",
+ start: 0,
+ duration: 6,
+ track: 0,
+ hasAudio: true,
+ link: "lk-1",
+};
+const talkAudio: TimelineElement = {
+ ...talk,
+ id: "talk-a",
+ domId: "talk-a",
+ tag: "audio",
+ track: 1,
+};
+
+function renderMenu(element: TimelineElement) {
+ usePlayerStore.getState().setElements([talk, talkAudio]);
+ document.body.appendChild(iframe);
+ const node = iframe.contentDocument?.createElement("video");
+ if (node) {
+ node.id = "talk";
+ node.setAttribute("data-has-audio", "true");
+ iframe.contentDocument?.body.appendChild(node);
+ }
+ const host = document.createElement("div");
+ document.body.appendChild(host);
+ const noop = vi.fn();
+ act(() =>
+ harness.mount(host).render(
+ <TimelineEditProvider
+ value={{
+ onSetElementAttributeQuiet: vi.fn(async () => undefined),
+ onFreezeFrame: noop,
+ onLinkEdit: noop,
+ onDeleteElementOnly: noop,
+ }}
+ >
+ <ClipContextMenu
+ x={10}
+ y={10}
+ element={element}
+ currentTime={2}
+ onClose={noop}
+ onSplit={noop}
+ onDelete={noop}
+ />
+ </TimelineEditProvider>,
+ ),
+ );
+}
+
+function menuLabels(): string[] {
+ return Array.from(document.querySelectorAll('[role="menuitem"], [role="menuitemcheckbox"]')).map(
+ (item) => item.querySelector("span")?.textContent ?? "",
+ );
+}
+
+describe("ClipContextMenu order", () => {
+ it("groups time, sound, picture, then delete for a linked video with sound", () => {
+ renderMenu(talk);
+ const expected = [
+ "Split at 2.00s",
+ "Freeze frame",
+ "Normalize loudness",
+ "Voice",
+ "Detach audio",
+ "Unlink from audio",
+ "Look",
+ "Crop",
+ "Delete",
+ "Delete this clip only",
+ ];
+ expect(menuLabels().filter((label) => expected.includes(label))).toEqual(expected);
+ const groups = Array.from(document.querySelectorAll('[role="group"]')).map((group) =>
+ group.getAttribute("aria-label"),
+ );
+ expect(groups).toEqual(["Time", "Sound", "Picture", "Clipboard", "Delete"]);
+ });
+});
diff --git a/packages/studio/src/player/components/ClipContextMenu.test.tsx b/packages/studio/src/player/components/ClipContextMenu.test.tsx
index b72291631c..4d28e77835 100644
--- a/packages/studio/src/player/components/ClipContextMenu.test.tsx
+++ b/packages/studio/src/player/components/ClipContextMenu.test.tsx
@@ -60,9 +60,14 @@ describe("ClipContextMenu host items", () => {
unmount();
});
- it("counts host rows and their divider when keeping the menu inside the window", () => {
+ it("keeps the menu, host rows included, inside the window by its measured height", () => {
const innerHeight = Object.getOwnPropertyDescriptor(window, "innerHeight");
Object.defineProperty(window, "innerHeight", { configurable: true, value: 600 });
+ const offsetHeight = vi
+ .spyOn(HTMLElement.prototype, "offsetHeight", "get")
+ .mockImplementation(function (this: HTMLElement) {
+ return this.getAttribute("role") === "menu" ? 150 : 0;
+ });
try {
const host = document.createElement("div");
document.body.appendChild(host);
@@ -86,10 +91,11 @@ describe("ClipContextMenu host items", () => {
/>,
),
);
- // Four 30 px rows, two 9 px dividers and 8 px of padding end 96 px below the window.
- expect(document.body.querySelector<HTMLElement>("[role=menu]")!.style.top).toBe("446px");
+ // 150 px measured from y 550 ends 100 px below the window, kept 8 px off its edge.
+ expect(document.body.querySelector<HTMLElement>("[role=menu]")!.style.top).toBe("442px");
act(() => root.unmount());
} finally {
+ offsetHeight.mockRestore();
if (innerHeight) Object.defineProperty(window, "innerHeight", innerHeight);
}
});
@@ -106,7 +112,7 @@ describe("ClipContextMenu host items", () => {
it("shows only Studio's items when the host adds none", () => {
const { items, unmount } = renderMenu([]);
expect(items().map((item) => item.textContent)).toEqual(["Copy⌘C", "Delete⌫"]);
- expect(document.body.querySelectorAll(".border-t")).toHaveLength(1);
+ expect(document.body.querySelector("[role=group][aria-label=Host]")).toBeNull();
unmount();
});
});
diff --git a/packages/studio/src/player/components/ClipContextMenu.tsx b/packages/studio/src/player/components/ClipContextMenu.tsx
index 7aef774d9c..438b09def5 100644
--- a/packages/studio/src/player/components/ClipContextMenu.tsx
+++ b/packages/studio/src/player/components/ClipContextMenu.tsx
@@ -1,4 +1,4 @@
-import { memo } from "react";
+import { memo, useLayoutEffect, useState, type RefObject } from "react";
import { createPortal } from "react-dom";
import { usePlayerStore, type TimelineElement } from "../store/playerStore";
import { canSplitElement } from "../../utils/timelineElementSplit";
@@ -9,6 +9,24 @@ import { ClipMenuToolItems } from "./clipMenuToolItems";
import { ClipMenuAudioItems } from "./clipMenuAudioItems";
import { ClipMenuLinkItems } from "./clipMenuLinkItems";
+const MENU_MARGIN = 8;
+// Empty groups collapse; every non-empty group before the always-present Delete group ends in a divider.
+const GROUP_CLASS = "empty:hidden mb-1 pb-1 border-b border-neutral-700/60";
+
+function useMeasuredHeight(ref: RefObject<HTMLDivElement | null>, anchorKey: string): number {
+ const [height, setHeight] = useState(0);
+ useLayoutEffect(() => {
+ const node = ref.current;
+ if (!node) return;
+ setHeight(node.offsetHeight);
+ if (typeof ResizeObserver === "undefined") return;
+ const observer = new ResizeObserver(() => setHeight(node.offsetHeight));
+ observer.observe(node);
+ return () => observer.disconnect();
+ }, [ref, anchorKey]);
+ return height;
+}
+
interface ClipContextMenuProps {
x: number;
y: number;
@@ -63,7 +81,6 @@ function HostItems({
)}
</button>
))}
- <div className="my-1 border-t border-neutral-700/60" />
</>
);
}
@@ -106,16 +123,11 @@ export const ClipContextMenu = memo(function ClipContextMenu({
? `Split at ${currentTime.toFixed(2)}s`
: "Split (move playhead inside clip)";
- const clipboardItemCount = [onCopy, onPaste, onDuplicate].filter(Boolean).length;
- const hostRows = hostItems.length;
- const rowCount = hostRows + (splitLabel ? 1 : 0) + clipboardItemCount + 1; // + Delete, always present
- const dividerCount =
- (hostRows > 0 ? 1 : 0) + (splitLabel ? 1 : 0) + (clipboardItemCount > 0 ? 1 : 0);
const menuWidth = 200;
- const menuHeight = rowCount * 30 + dividerCount * 9 + 8;
- const overflowY = y + menuHeight - window.innerHeight;
const adjustedX = x + menuWidth > window.innerWidth ? x - menuWidth : x;
- const adjustedY = overflowY > 0 ? y - overflowY - 8 : y;
+ const menuHeight = useMeasuredHeight(menuRef, `${x},${y},${element.key ?? element.id}`);
+ const overflowY = y + menuHeight - window.innerHeight;
+ const adjustedY = overflowY > 0 ? Math.max(MENU_MARGIN, y - overflowY - MENU_MARGIN) : y;
return createPortal(
<div
@@ -125,9 +137,13 @@ export const ClipContextMenu = memo(function ClipContextMenu({
className="fixed z-200 bg-neutral-900 border border-neutral-700 rounded-md shadow-lg py-1 min-w-[180px]"
style={{ left: adjustedX, top: adjustedY }}
>
- {hostRows > 0 && <HostItems items={hostItems} onClose={onClose} />}
- {splitLabel && (
- <>
+ {hostItems.length > 0 && (
+ <div role="group" aria-label="Host" className={GROUP_CLASS}>
+ <HostItems items={hostItems} onClose={onClose} />
+ </div>
+ )}
+ <div role="group" aria-label="Time" className={GROUP_CLASS}>
+ {splitLabel && (
<button
type="button"
role="menuitem"
@@ -147,93 +163,100 @@ export const ClipContextMenu = memo(function ClipContextMenu({
<span>{splitLabel}</span>
<span className="text-neutral-500 text-[10px] ml-3">S</span>
</button>
+ )}
+ {splitLabel && (
<ClipMenuToolItems
group="time"
element={element}
currentTime={currentTime}
onClose={onClose}
/>
- <div className="my-1 border-t border-neutral-700/60" />
- </>
- )}
+ )}
+ </div>
- <ClipMenuAudioItems element={element} onClose={onClose} />
- <ClipMenuLinkItems element={element} onClose={onClose} />
+ <div role="group" aria-label="Sound" className={GROUP_CLASS}>
+ <ClipMenuAudioItems part="normalize" element={element} onClose={onClose} />
+ <ClipMenuToolItems
+ group="sound"
+ element={element}
+ currentTime={currentTime}
+ onClose={onClose}
+ />
+ <ClipMenuLinkItems part="link" element={element} onClose={onClose} />
+ <ClipMenuAudioItems part="duck" element={element} onClose={onClose} />
+ </div>
- {(onCopy || onPaste || onDuplicate) && (
- <>
- {onCopy && (
- <button
- type="button"
- role="menuitem"
- className={itemClass(true)}
- onClick={() => {
- onCopy();
- onClose();
- }}
- >
- <span>{selectionSize > 1 ? `Copy ${selectionSize} clips` : "Copy"}</span>
- <span className="text-neutral-500 text-[10px] ml-3">⌘C</span>
- </button>
- )}
- {onPaste && (
- <button
- type="button"
- role="menuitem"
- className={itemClass(!!canPaste)}
- disabled={!canPaste}
- onClick={() => {
- if (!canPaste) return;
- void onPaste();
- onClose();
- }}
- >
- <span>Paste</span>
- <span className="text-neutral-500 text-[10px] ml-3">⌘V</span>
- </button>
- )}
- {onDuplicate && (
- <button
- type="button"
- role="menuitem"
- className={itemClass(true)}
- onClick={() => {
- void onDuplicate();
- onClose();
- }}
- >
- <span>{selectionSize > 1 ? `Duplicate ${selectionSize} clips` : "Duplicate"}</span>
- <span className="text-neutral-500 text-[10px] ml-3">⌘D</span>
- </button>
- )}
- <div className="my-1 border-t border-neutral-700/60" />
- </>
- )}
+ <div role="group" aria-label="Picture" className={GROUP_CLASS}>
+ <ClipMenuToolItems
+ group="picture"
+ element={element}
+ currentTime={currentTime}
+ onClose={onClose}
+ />
+ </div>
+
+ <div role="group" aria-label="Clipboard" className={GROUP_CLASS}>
+ {onCopy && (
+ <button
+ type="button"
+ role="menuitem"
+ className={itemClass(true)}
+ onClick={() => {
+ onCopy();
+ onClose();
+ }}
+ >
+ <span>{selectionSize > 1 ? `Copy ${selectionSize} clips` : "Copy"}</span>
+ <span className="text-neutral-500 text-[10px] ml-3">⌘C</span>
+ </button>
+ )}
+ {onPaste && (
+ <button
+ type="button"
+ role="menuitem"
+ className={itemClass(!!canPaste)}
+ disabled={!canPaste}
+ onClick={() => {
+ if (!canPaste) return;
+ void onPaste();
+ onClose();
+ }}
+ >
+ <span>Paste</span>
+ <span className="text-neutral-500 text-[10px] ml-3">⌘V</span>
+ </button>
+ )}
+ {onDuplicate && (
+ <button
+ type="button"
+ role="menuitem"
+ className={itemClass(true)}
+ onClick={() => {
+ void onDuplicate();
+ onClose();
+ }}
+ >
+ <span>{selectionSize > 1 ? `Duplicate ${selectionSize} clips` : "Duplicate"}</span>
+ <span className="text-neutral-500 text-[10px] ml-3">⌘D</span>
+ </button>
+ )}
+ </div>
- <ClipMenuToolItems
- group="sound"
- element={element}
- currentTime={currentTime}
- onClose={onClose}
- />
- <ClipMenuToolItems
- group="picture"
- element={element}
- currentTime={currentTime}
- onClose={onClose}
- />
- <button
- type="button"
- role="menuitem"
- className="w-full flex items-center justify-between px-3 py-1.5 text-xs text-danger-ink hover:bg-neutral-800 focus-visible:bg-neutral-800 outline-hidden cursor-pointer text-left"
- onClick={() => {
- onDelete(element);
- onClose();
- }}
- >
- <span>Delete</span>
- <span className="text-neutral-500 text-[10px] ml-3">⌫</span>
- </button>
+ <div role="group" aria-label="Delete">
+ <button
+ type="button"
+ role="menuitem"
+ className="w-full flex items-center justify-between px-3 py-1.5 text-xs text-danger-ink hover:bg-neutral-800 focus-visible:bg-neutral-800 outline-hidden cursor-pointer text-left"
+ onClick={() => {
+ onDelete(element);
+ onClose();
+ }}
+ >
+ <span>Delete</span>
+ <span className="text-neutral-500 text-[10px] ml-3">⌫</span>
+ </button>
+ <ClipMenuLinkItems part="delete" element={element} onClose={onClose} />
+ </div>
</div>,
document.body,
);
diff --git a/packages/studio/src/player/components/OutOfSyncBadge.test.tsx b/packages/studio/src/player/components/OutOfSyncBadge.test.tsx
new file mode 100644
index 0000000000..40021f35e8
--- /dev/null
+++ b/packages/studio/src/player/components/OutOfSyncBadge.test.tsx
@@ -0,0 +1,91 @@
+// @vitest-environment happy-dom
+import React, { act } from "react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { TimelineEditProvider } from "../../contexts/TimelineEditContext";
+import { useLinkedClipPreferences } from "../../utils/linkedClipPreferences";
+import { usePlayerStore, type TimelineElement } from "../store/playerStore";
+import { OutOfSyncBadge } from "./OutOfSyncBadge";
+import { createHappyDomRootHarness } from "./testRootHarness";
+
+(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+const harness = createHappyDomRootHarness();
+const clip = (id: string, tag: string, start: number): TimelineElement => ({
+ id,
+ domId: id,
+ tag,
+ start,
+ duration: 4,
+ track: 0,
+ playbackStart: 0,
+ syncOrigin: "lk-1",
+});
+const video = clip("talk", "video", 1);
+const lateAudio = clip("talk-audio", "audio", 1 + 51 / 30);
+
+afterEach(() =>
+ useLinkedClipPreferences.setState({ syncIndicatorsVisible: true, compositionFps: 30 }),
+);
+
+function render(el: TimelineElement, onLinkEdit = vi.fn()) {
+ usePlayerStore.getState().setElements([video, lateAudio]);
+ const host = document.body.appendChild(document.createElement("div"));
+ act(() =>
+ harness.mount(host).render(
+ <TimelineEditProvider value={{ onLinkEdit }}>
+ <OutOfSyncBadge el={el} />
+ </TimelineEditProvider>,
+ ),
+ );
+ const badge = () => document.querySelector('[data-testid="out-of-sync-badge"]');
+ return { badge, onLinkEdit };
+}
+
+describe("OutOfSyncBadge", () => {
+ it("shows the signed offset on both halves", () => {
+ useLinkedClipPreferences.setState({ compositionFps: 30 });
+ expect(render(lateAudio).badge()?.textContent).toBe("+1:21");
+ document.body.innerHTML = "";
+ expect(render(video).badge()?.textContent).toBe("-1:21");
+ });
+
+ it("hides when the preference is off", () => {
+ useLinkedClipPreferences.setState({ syncIndicatorsVisible: false });
+ expect(render(lateAudio).badge()).toBeNull();
+ });
+
+ it("opens Move / Slip into Sync from a click anywhere on the badge", () => {
+ const { badge, onLinkEdit } = render(lateAudio);
+ act(() => badge()?.dispatchEvent(new MouseEvent("click", { bubbles: true })));
+ const items = Array.from(document.querySelectorAll<HTMLButtonElement>('[role="menuitem"]'));
+ expect(items.map((item) => item.textContent)).toEqual(["Move into Sync", "Slip into Sync"]);
+ act(() => items[0]?.click());
+ expect(onLinkEdit).toHaveBeenCalledWith(
+ expect.objectContaining({ kind: "move-into-sync", element: lateAudio, start: 1 }),
+ );
+ });
+
+ it("slips from a right-click, and the click never reaches the clip", () => {
+ const clipClick = vi.fn();
+ document.body.addEventListener("contextmenu", clipClick);
+ const { badge, onLinkEdit } = render(lateAudio);
+ act(() => badge()?.dispatchEvent(new MouseEvent("contextmenu", { bubbles: true })));
+ expect(clipClick).not.toHaveBeenCalled();
+ const slip = document.querySelectorAll<HTMLButtonElement>('[role="menuitem"]')[1];
+ act(() => slip?.click());
+ const edit = onLinkEdit.mock.calls[0]?.[0];
+ expect(edit.kind).toBe("slip-into-sync");
+ expect(edit.mediaStart).toBeCloseTo(51 / 30);
+ document.body.removeEventListener("contextmenu", clipClick);
+ });
+
+ it("flips the menu above the pointer near the bottom edge", () => {
+ const { badge } = render(lateAudio);
+ const y = window.innerHeight - 10;
+ act(() => badge()?.dispatchEvent(new MouseEvent("click", { bubbles: true, clientY: y })));
+ const menu = document.querySelector<HTMLElement>('[role="menu"]');
+ const top = Number.parseFloat(menu?.style.top ?? "");
+ expect(top).toBeLessThan(y);
+ expect(top).toBeGreaterThanOrEqual(0);
+ });
+});
diff --git a/packages/studio/src/player/components/OutOfSyncBadge.tsx b/packages/studio/src/player/components/OutOfSyncBadge.tsx
new file mode 100644
index 0000000000..49fc8c4339
--- /dev/null
+++ b/packages/studio/src/player/components/OutOfSyncBadge.tsx
@@ -0,0 +1,119 @@
+import { memo, useCallback, useState, type SyntheticEvent } from "react";
+import { createPortal } from "react-dom";
+import { formatSyncOffset } from "@hyperframes/core/media-link";
+import { useContextMenuDismiss } from "../../hooks/useContextMenuDismiss";
+import { useTimelineEditContextOptional } from "../../contexts/TimelineEditContext";
+import { useLinkedClipPreferences } from "../../utils/linkedClipPreferences";
+import { usePlayerStore, type TimelineElement } from "../store/playerStore";
+import { clipSyncState, type ClipSyncState } from "./clipSync";
+import { useMenuKeyboardNav } from "./menuKeyboardNav";
+
+const stop = (e: SyntheticEvent) => e.stopPropagation();
+
+const MENU_ROW =
+ "block w-full px-3 py-1.5 text-left text-xs text-neutral-300 outline-hidden hover:bg-neutral-800 focus-visible:bg-neutral-800 disabled:opacity-40";
+
+function SyncMenu({
+ x,
+ y,
+ el,
+ sync,
+ onClose,
+}: {
+ x: number;
+ y: number;
+ el: TimelineElement;
+ sync: ClipSyncState<TimelineElement>;
+ onClose: () => void;
+}) {
+ const menuRef = useContextMenuDismiss(onClose);
+ useMenuKeyboardNav(menuRef);
+ const { onLinkEdit } = useTimelineEditContextOptional();
+ const { moveStart, slipMediaStart } = sync;
+ const menuWidth = 170;
+ const menuHeight = 66;
+ const left = x + menuWidth > window.innerWidth ? x - menuWidth : x;
+ const top = y + menuHeight > window.innerHeight ? Math.max(0, y - menuHeight) : y;
+ return createPortal(
+ <div
+ ref={menuRef}
+ role="menu"
+ aria-label="Out of sync"
+ className="fixed z-200 min-w-[170px] rounded-sm border border-neutral-700 bg-neutral-900 py-1 shadow-lg"
+ style={{ left, top }}
+ >
+ <button
+ type="button"
+ role="menuitem"
+ className={MENU_ROW}
+ disabled={!onLinkEdit || moveStart === null}
+ title={moveStart === null ? "Would move the clip before 0:00" : undefined}
+ onClick={() => {
+ if (moveStart !== null)
+ void onLinkEdit?.({ kind: "move-into-sync", element: el, start: moveStart });
+ onClose();
+ }}
+ >
+ Move into Sync
+ </button>
+ <button
+ type="button"
+ role="menuitem"
+ className={MENU_ROW}
+ disabled={!onLinkEdit || slipMediaStart === null}
+ title={slipMediaStart === null ? "Would slip before the start of the file" : undefined}
+ onClick={() => {
+ if (slipMediaStart !== null) {
+ void onLinkEdit?.({ kind: "slip-into-sync", element: el, mediaStart: slipMediaStart });
+ }
+ onClose();
+ }}
+ >
+ Slip into Sync
+ </button>
+ </div>,
+ document.body,
+ );
+}
+
+/**
+ * Premiere's red out-of-sync number, at the start of each half of a source pair
+ * that drifted. The whole badge opens Move / Slip into Sync (Premiere's own hit
+ * target is a sliver at the badge edge, a known complaint).
+ */
+export const OutOfSyncBadge = memo(function OutOfSyncBadge({ el }: { el: TimelineElement }) {
+ const visible = useLinkedClipPreferences((s) => s.syncIndicatorsVisible);
+ const fps = useLinkedClipPreferences((s) => s.compositionFps);
+ const elements = usePlayerStore((s) => s.elements);
+ const [menuAt, setMenuAt] = useState<{ x: number; y: number } | null>(null);
+ const closeMenu = useCallback(() => setMenuAt(null), []);
+ const sync = visible ? clipSyncState(el, elements, fps) : null;
+ if (!sync) return null;
+ const label = formatSyncOffset(sync.frames, fps);
+ const partnerName = sync.partner.label || sync.partner.id;
+ const open = (e: React.MouseEvent) => {
+ e.preventDefault();
+ e.stopPropagation();
+ setMenuAt({ x: e.clientX, y: e.clientY });
+ };
+ return (
+ <>
+ <span
+ role="button"
+ tabIndex={-1}
+ aria-haspopup="menu"
+ aria-label={`Out of sync with ${partnerName} by ${label} frames`}
+ title={`Out of sync with ${partnerName} by ${label} — click for Move or Slip into Sync`}
+ data-testid="out-of-sync-badge"
+ className="absolute bottom-0.5 left-1 z-[7] cursor-pointer rounded-[3px] bg-red-600 px-1 font-mono text-[9px] leading-[14px] text-white tabular-nums"
+ onPointerDown={stop}
+ onDoubleClick={stop}
+ onClick={open}
+ onContextMenu={open}
+ >
+ {label}
+ </span>
+ {menuAt && <SyncMenu x={menuAt.x} y={menuAt.y} el={el} sync={sync} onClose={closeMenu} />}
+ </>
+ );
+});
diff --git a/packages/studio/src/player/components/TimelineClip.test.tsx b/packages/studio/src/player/components/TimelineClip.test.tsx
index 0e2de43a3c..3c4786be67 100644
--- a/packages/studio/src/player/components/TimelineClip.test.tsx
+++ b/packages/studio/src/player/components/TimelineClip.test.tsx
@@ -105,6 +105,23 @@ describe("TimelineClip", () => {
expect(seen).toEqual([{ fadeIn: 1, fadeOut: 0.5, duration: 4 }, null]);
});
+ it("gives both halves of a link group the same label colour, and unlinked clips none", () => {
+ const colorOf = (element: TimelineElement) => {
+ const { host, root } = renderClip({ element });
+ const clip = host.querySelector<HTMLElement>(".timeline-clip");
+ const color = clip?.getAttribute("data-link-color") ?? null;
+ expect(clip?.style.getPropertyValue("--clip-link-color") || null).toBe(color);
+ act(() => root.unmount());
+ return color;
+ };
+ const base = { start: 0, duration: 2, track: 0 };
+ const video = colorOf({ id: "v", tag: "video", link: "lk-3", ...base });
+ expect(video).not.toBeNull();
+ expect(colorOf({ id: "a", tag: "audio", link: "lk-3", ...base })).toBe(video);
+ expect(colorOf({ id: "b", tag: "audio", link: "lk-4", ...base })).not.toBe(video);
+ expect(colorOf({ id: "c", tag: "audio", ...base })).toBeNull();
+ });
+
it("renders the clip label above custom content without showing default timecode", () => {
const { host, root } = renderClip({
element: { id: "hero", label: "Hero", tag: "div", start: 1, duration: 1, track: 0 },
diff --git a/packages/studio/src/player/components/TimelineClip.tsx b/packages/studio/src/player/components/TimelineClip.tsx
index 5030bfdce2..2b63755c05 100644
--- a/packages/studio/src/player/components/TimelineClip.tsx
+++ b/packages/studio/src/player/components/TimelineClip.tsx
@@ -12,6 +12,8 @@ import { timelineClipFocusId } from "./timelineNavigationIdentity";
import { ClipFadesContext, TimelineClipFades, useClipFadeDraft } from "./TimelineClipFades";
import { rendersWaveform } from "./AudioWaveform";
import { ClipBadges } from "./ClipBadges";
+import { linkLabelColor } from "./linkLabelColor";
+import { OutOfSyncBadge } from "./OutOfSyncBadge";
interface TimelineClipProps {
el: TimelineElement;
@@ -83,6 +85,8 @@ export const TimelineClip = memo(function TimelineClip({
"--clip-border-active": theme.clipBorderActive,
"--clip-handle": theme.handleColor,
} as CSSProperties;
+ const linkColor = linkLabelColor(el.link);
+ if (linkColor) Object.assign(themeVariables, { "--clip-link-color": linkColor });
const isAudioClip = isAudioTimelineElement(el);
const hasFades = (isAudioClip || Boolean(el.hasAudio)) && !isGestureActor;
const fade = useClipFadeDraft(el);
@@ -124,6 +128,7 @@ export const TimelineClip = memo(function TimelineClip({
data-clip-start={el.start}
data-clip-end={el.start + el.duration}
data-clip-hidden={el.hidden ? "true" : undefined}
+ data-link-color={linkColor ?? undefined}
data-ladder={ladder}
data-active={isActive ? "" : undefined}
aria-hidden={isGestureActor ? "true" : undefined}
@@ -206,6 +211,7 @@ export const TimelineClip = memo(function TimelineClip({
)}
{showLabel && <span className="timeline-clip__label">{displayLabel}</span>}
{showLabel && !isGestureActor && <ClipBadges el={el} />}
+ {!isGestureActor && el.syncOrigin && <OutOfSyncBadge el={el} />}
{showDefaultText && (
<span className="timeline-clip__timecode">
{startLabel}-{endLabel}s
diff --git a/packages/studio/src/player/components/audioClipLink.test.ts b/packages/studio/src/player/components/audioClipLink.test.ts
index 42f5743dde..c4e81bb248 100644
--- a/packages/studio/src/player/components/audioClipLink.test.ts
+++ b/packages/studio/src/player/components/audioClipLink.test.ts
@@ -17,11 +17,6 @@ const plain = { id: "title" };
const elements = [video, audio, other, otherAudio, plain];
describe("audioPillFlags", () => {
- it("is linked only by data-link, never by a shared file name", () => {
- expect(audioPillFlags({ link: "lk-1" }).linked).toBe(true);
- expect(audioPillFlags({}).linked).toBe(false);
- });
-
it("greys a hidden clip and a muted group", () => {
expect(audioPillFlags({ hidden: true }).muted).toBe(true);
expect(audioPillFlags({ audioGroupHidden: true }).muted).toBe(true);
@@ -163,6 +158,12 @@ describe("linkedGestureKeys", () => {
);
});
+ it("Linked Selection off edits the grabbed clip alone without Alt", () => {
+ expect(linkedGestureKeys(new Set(["talk"]), video, elements, false, false)).toEqual(
+ new Set(["talk"]),
+ );
+ });
+
it("Alt edits the grabbed clip alone", () => {
expect(linkedGestureKeys(new Set(["talk", "talk-audio"]), video, elements, true)).toEqual(
new Set(["talk"]),
@@ -202,3 +203,29 @@ describe("selectClipWithLinks", () => {
expect(usePlayerStore.getState().selectedElementId).toBe("talk");
});
});
+
+describe("Linked Selection off", () => {
+ const linkedPair = [
+ { id: "talk", tag: "video", start: 0, duration: 4, track: 0, link: "lk-1" },
+ { id: "talk-audio", tag: "audio", start: 0, duration: 4, track: 1, link: "lk-1" },
+ ];
+
+ it("expands and lists nothing past the clip itself", () => {
+ expect(expandToLinkedMembers(["talk"], linkedPair, false)).toEqual(new Set(["talk"]));
+ expect(linkedMembersOf(linkedPair[0], linkedPair, false)).toEqual([linkedPair[0]]);
+ });
+
+ it("a click selects only the clicked clip", async () => {
+ const { usePlayerStore } = await import("../store/playerStore");
+ const { selectClipWithLinks } = await import("./timelineLinkSelection");
+ const { useLinkedClipPreferences } = await import("../../utils/linkedClipPreferences");
+ usePlayerStore.getState().setElements(linkedPair);
+ useLinkedClipPreferences.getState().setLinkedSelection(false);
+ try {
+ selectClipWithLinks("talk", false, usePlayerStore.getState().setSelectedElementId);
+ expect(usePlayerStore.getState().selectedElementIds).toEqual(new Set(["talk"]));
+ } finally {
+ useLinkedClipPreferences.getState().setLinkedSelection(true);
+ }
+ });
+});
diff --git a/packages/studio/src/player/components/audioClipLink.ts b/packages/studio/src/player/components/audioClipLink.ts
index ee6cdc338f..355659d0b6 100644
--- a/packages/studio/src/player/components/audioClipLink.ts
+++ b/packages/studio/src/player/components/audioClipLink.ts
@@ -34,17 +34,18 @@ export function sharesLinkGroup(
}
export function audioPillFlags(
- audio: Pick<TimelineElement, "hidden" | "audioGroupHidden" | "link">,
+ audio: Pick<TimelineElement, "hidden" | "audioGroupHidden">,
_elements?: readonly unknown[],
-): { muted: boolean; linked: boolean } {
- return {
- muted: audio.hidden === true || audio.audioGroupHidden === true,
- linked: isLinked(audio),
- };
+): { muted: boolean } {
+ return { muted: audio.hidden === true || audio.audioGroupHidden === true };
}
-export function linkedMembersOf<T extends LinkedElement>(element: T, elements: readonly T[]): T[] {
- if (!isLinked(element)) return [element];
+export function linkedMembersOf<T extends LinkedElement>(
+ element: T,
+ elements: readonly T[],
+ linked = true,
+): T[] {
+ if (!linked || !isLinked(element)) return [element];
const members = elements.filter((candidate) => sharesLinkGroup(candidate, element));
return members.some((member) => keyOf(member) === keyOf(element))
? members
@@ -54,8 +55,10 @@ export function linkedMembersOf<T extends LinkedElement>(element: T, elements: r
export function expandToLinkedMembers(
keys: Iterable<string>,
elements: readonly LinkedElement[],
+ linked = true,
): Set<string> {
const expanded = new Set(keys);
+ if (!linked) return expanded;
const seeds = elements.filter((el) => expanded.has(keyOf(el)) && isLinked(el));
for (const element of elements) {
if (seeds.some((seed) => sharesLinkGroup(seed, element))) expanded.add(keyOf(element));
@@ -68,9 +71,10 @@ export function linkedGestureKeys(
grabbed: LinkedElement,
elements: readonly LinkedElement[],
altKey: boolean,
+ linked = true,
): Set<string> {
const grabbedKey = keyOf(grabbed);
if (altKey) return new Set([grabbedKey]);
const base = selected.has(grabbedKey) ? selected : [grabbedKey];
- return expandToLinkedMembers(base, elements);
+ return expandToLinkedMembers(base, elements, linked);
}
diff --git a/packages/studio/src/player/components/clipMenuAudioItems.noShell.test.tsx b/packages/studio/src/player/components/clipMenuAudioItems.noShell.test.tsx
new file mode 100644
index 0000000000..a91d2e4768
--- /dev/null
+++ b/packages/studio/src/player/components/clipMenuAudioItems.noShell.test.tsx
@@ -0,0 +1,78 @@
+// @vitest-environment happy-dom
+import { act } from "react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { createHappyDomRootHarness } from "./testRootHarness";
+import { ClipMenuAudioItems } from "./clipMenuAudioItems";
+import { usePlayerStore } from "../store/playerStore";
+import { usePreviewIframeStore } from "../store/previewIframeStore";
+import type { TimelineElement } from "../store/timelineElement";
+
+const onNotice = vi.fn();
+const setQuiet = vi.fn(async () => {});
+
+vi.mock("../../contexts/StudioContext", () => ({
+ useStudioShellContextOptional: () => null,
+}));
+vi.mock("../../contexts/TimelineEditContext", () => ({
+ useTimelineEditContextOptional: () => ({ onSetElementAttributeQuiet: setQuiet, onNotice }),
+}));
+
+const harness = createHappyDomRootHarness();
+const tour: TimelineElement = {
+ id: "tour",
+ tag: "video",
+ start: 0,
+ duration: 4,
+ track: 0,
+ hasAudio: true,
+ src: "tour.mp4",
+};
+
+function mountPreview(): void {
+ const iframe = document.createElement("iframe");
+ document.body.appendChild(iframe);
+ const doc = iframe.contentDocument;
+ if (!doc) throw new Error("iframe has no document");
+ doc.body.innerHTML =
+ '<video id="tour" src="tour.mp4" data-has-audio="true" data-start="0" data-duration="4"></video><audio id="voiceover" src="vo.wav" data-start="1" data-duration="2"></audio>';
+ usePreviewIframeStore.getState().setIframe(iframe);
+}
+
+function render(part: "normalize" | "duck") {
+ const host = document.createElement("div");
+ document.body.appendChild(host);
+ act(() =>
+ harness
+ .mount(host)
+ .render(<ClipMenuAudioItems part={part} element={tour} onClose={() => {}} />),
+ );
+ return host;
+}
+
+afterEach(() => {
+ usePreviewIframeStore.getState().setIframe(null);
+ vi.unstubAllGlobals();
+});
+
+describe("ClipMenuAudioItems in a host without Studio's shell", () => {
+ it("offers Normalize and Duck from the timeline session and the live preview", () => {
+ usePlayerStore.getState().beginTimelineSession("p1");
+ mountPreview();
+ expect(render("normalize").textContent).toContain("Normalize loudness");
+ expect(render("duck").textContent).toContain("Duck under voice");
+ });
+
+ it("normalizes through the session's project and reports through onNotice", async () => {
+ usePlayerStore.getState().beginTimelineSession("p1");
+ mountPreview();
+ const plan = { targetLufs: -16, projectedLufs: -16, volume: 2, changeDb: 6, limitedBy: null };
+ const fetchSpy = vi.fn(async (_url: string) => Response.json({ plan }));
+ vi.stubGlobal("fetch", fetchSpy);
+ const button = render("normalize").querySelector("button");
+ await act(async () => button?.click());
+ await vi.waitFor(() => expect(onNotice).toHaveBeenCalled());
+ expect(String(fetchSpy.mock.calls[0]?.[0])).toContain("/api/projects/p1/loudness/normalize");
+ expect(setQuiet).toHaveBeenCalledWith(tour, "data-volume", "2", "Normalize loudness");
+ expect(onNotice).toHaveBeenCalledWith("Normalized to −16 LUFS (+6.0 dB)", "info");
+ });
+});
diff --git a/packages/studio/src/player/components/clipMenuAudioItems.test.tsx b/packages/studio/src/player/components/clipMenuAudioItems.test.tsx
index 7b1a35820e..a73119a647 100644
--- a/packages/studio/src/player/components/clipMenuAudioItems.test.tsx
+++ b/packages/studio/src/player/components/clipMenuAudioItems.test.tsx
@@ -7,7 +7,12 @@ import type { TimelineElement } from "../store/timelineElement";
const showToast = vi.fn();
const setQuiet = vi.fn<(...args: unknown[]) => Promise<unknown>>(async () => {});
-const iframe = document.createElement("iframe");
+let previewDoc: Document | null = null;
+const iframe = {
+ get contentDocument() {
+ return previewDoc;
+ },
+};
vi.mock("../../contexts/StudioContext", () => ({
useStudioShellContextOptional: () => ({
@@ -22,11 +27,13 @@ vi.mock("../../contexts/TimelineEditContext", () => ({
const harness = createHappyDomRootHarness();
-function render(element: TimelineElement) {
+function render(element: TimelineElement, part: "normalize" | "duck" = "normalize") {
const host = document.createElement("div");
document.body.appendChild(host);
act(() =>
- harness.mount(host).render(<ClipMenuAudioItems element={element} onClose={() => {}} />),
+ harness
+ .mount(host)
+ .render(<ClipMenuAudioItems part={part} element={element} onClose={() => {}} />),
);
return host;
}
@@ -50,6 +57,44 @@ describe("ClipMenuAudioItems", () => {
expect(host.textContent).toBe("");
});
+ describe("Duck under voice", () => {
+ const duckLabel = (host: HTMLElement) =>
+ [...host.querySelectorAll("button")].find((b) => b.textContent?.includes("Duck under voice"));
+ const compose = (body: string) => {
+ previewDoc = document.implementation.createHTMLDocument("c");
+ previewDoc.body.innerHTML = body;
+ };
+ const music: TimelineElement = { ...base, id: "music", tag: "audio", src: "music.mp3" };
+
+ it("is hidden on a lone video with sound", () => {
+ compose(
+ `<video id="a-roll" src="a.mp4" data-start="0" data-duration="4" data-has-audio="true"></video>`,
+ );
+ const host = render(
+ { ...base, id: "a-roll", tag: "video", hasAudio: true, src: "a.mp4" },
+ "duck",
+ );
+ expect(duckLabel(host)).toBeUndefined();
+ });
+
+ it("shows for a music bed with an overlapping voice", () => {
+ compose(`<audio id="music" src="music.mp3" data-start="0" data-duration="4"></audio>
+ <audio id="voiceover" src="vo.wav" data-start="1" data-duration="2"></audio>`);
+ const host = render(music, "duck");
+ expect(duckLabel(host)?.getAttribute("aria-checked")).toBe("false");
+ });
+
+ it("stays available, checked, once ducked even with the voice gone", () => {
+ compose(
+ `<audio id="music" src="music.mp3" data-start="0" data-duration="4" data-fx-carve='{"enabled":true,"sources":["voiceover"],"strength":0.25}'></audio>`,
+ );
+ const host = render(music, "duck");
+ const item = duckLabel(host);
+ expect(item?.getAttribute("aria-checked")).toBe("true");
+ expect(item?.textContent).toBe("Duck under voice✓");
+ });
+ });
+
it("normalizes a video with sound by writing data-volume as one edit", async () => {
const plan = { targetLufs: -16, projectedLufs: -16, volume: 2, changeDb: 6, limitedBy: null };
vi.stubGlobal(
@@ -104,22 +149,20 @@ describe("ClipMenuAudioItems", () => {
});
it("stops ducking at the first refused save and says why", async () => {
- document.body.appendChild(iframe);
- const doc = iframe.contentDocument;
- if (!doc) throw new Error("fixture");
- doc.body.innerHTML = `<audio id="music" src="music.mp3" data-start="0" data-duration="10"></audio>
+ previewDoc = document.implementation.createHTMLDocument("c");
+ previewDoc.body.innerHTML = `<audio id="music" src="music.mp3" data-start="0" data-duration="10"></audio>
<audio id="voiceover" src="vo.wav" data-start="1" data-duration="3"></audio>`;
setQuiet.mockResolvedValue({
status: "refused",
reason: "Cannot edit timeline while recording",
});
- const host = render({ ...base, id: "music", tag: "audio", src: "music.mp3" });
+ const host = render({ ...base, id: "music", tag: "audio", src: "music.mp3" }, "duck");
await clickItem(host, "Duck under voice");
await vi.waitFor(() =>
expect(showToast).toHaveBeenCalledWith("Cannot edit timeline while recording", "error"),
);
expect(setQuiet).toHaveBeenCalledTimes(1);
expect(showToast).not.toHaveBeenCalledWith(expect.stringContaining("Ducks under"), "info");
- iframe.remove();
+ previewDoc = null;
});
});
diff --git a/packages/studio/src/player/components/clipMenuAudioItems.tsx b/packages/studio/src/player/components/clipMenuAudioItems.tsx
index 0df27dd0f2..5488d84301 100644
--- a/packages/studio/src/player/components/clipMenuAudioItems.tsx
+++ b/packages/studio/src/player/components/clipMenuAudioItems.tsx
@@ -2,6 +2,8 @@ import { formatAudioGain } from "@hyperframes/core/audio-gain";
import type { TimelineElement } from "../store/timelineElement";
import { useTimelineEditContextOptional } from "../../contexts/TimelineEditContext";
import { useStudioShellContextOptional } from "../../contexts/StudioContext";
+import { usePlayerStore } from "../store/playerStore";
+import { useLivePreviewIframe } from "../store/previewIframeStore";
import {
clipHasSound,
normalizeToastText,
@@ -11,7 +13,7 @@ import {
VOLUME_LANE_REFUSAL,
volumeLaneOwnsGain,
} from "./clipMenuNormalize";
-import { isDuckableBed, readBedCarve, setDuckUnderVoice, type DuckOutcome } from "./clipMenuDuck";
+import { offersDuck, readBedCarve, setDuckUnderVoice, type DuckOutcome } from "./clipMenuDuck";
const ITEM_CLASS =
"w-full flex items-center justify-between px-3 py-1.5 text-xs text-left outline-hidden text-neutral-300 hover:bg-neutral-800 focus-visible:bg-neutral-800 cursor-pointer";
@@ -23,21 +25,28 @@ const DUCK_TOAST: Record<DuckOutcome, string> = {
aborted: "Could not group the voices to duck under.",
};
-/** Sound group of the clip menu: Normalize loudness (one-shot) and Duck under voice (toggle). */
+/** Normalize loudness (one-shot) or Duck under voice (toggle), placed separately in the sound group. */
export function ClipMenuAudioItems({
+ part,
element,
onClose,
}: {
+ part: "normalize" | "duck";
element: TimelineElement;
onClose: () => void;
}) {
const shell = useStudioShellContextOptional();
- const { onSetElementAttributeQuiet, onGroupClips } = useTimelineEditContextOptional();
- const doc = shell?.previewIframeRef.current?.contentDocument ?? null;
+ const { onSetElementAttributeQuiet, onGroupClips, onNotice } = useTimelineEditContextOptional();
+ const liveIframe = useLivePreviewIframe();
+ const sessionProjectId = usePlayerStore((s) => s.timelineProjectId);
+ const projectId = shell?.projectId ?? sessionProjectId;
+ const showToast = shell?.showToast ?? onNotice;
+ const doc = (shell?.previewIframeRef.current ?? liveIframe)?.contentDocument ?? null;
const bed = doc?.getElementById(element.domId ?? element.id) ?? null;
const ducked = bed ? readBedCarve(bed)?.enabled === true : false;
- if (!clipHasSound(element) || !shell || !onSetElementAttributeQuiet) return null;
- const { showToast, projectId } = shell;
+ if (!clipHasSound(element) || !projectId || !showToast || !onSetElementAttributeQuiet) {
+ return null;
+ }
const normalize = async () => {
onClose();
@@ -84,25 +93,24 @@ export function ClipMenuAudioItems({
showToast(DUCK_TOAST[outcome], outcome === "aborted" ? "error" : "info");
};
- return (
- <>
+ if (part === "normalize") {
+ return (
<button type="button" role="menuitem" className={ITEM_CLASS} onClick={() => void normalize()}>
<span>Normalize loudness</span>
</button>
- {isDuckableBed(bed) && (
- <button
- type="button"
- role="menuitemcheckbox"
- aria-checked={ducked}
- className={ITEM_CLASS}
- onClick={() => void toggleDuck()}
- >
- <span>
- <span className="inline-block w-3">{ducked ? "✓" : ""}</span>Duck under voice
- </span>
- </button>
- )}
- <div className="my-1 border-t border-neutral-700/60" />
- </>
+ );
+ }
+ if (!offersDuck(doc, bed)) return null;
+ return (
+ <button
+ type="button"
+ role="menuitemcheckbox"
+ aria-checked={ducked}
+ className={ITEM_CLASS}
+ onClick={() => void toggleDuck()}
+ >
+ <span>Duck under voice</span>
+ <span aria-hidden="true">{ducked ? "✓" : ""}</span>
+ </button>
);
}
diff --git a/packages/studio/src/player/components/clipMenuDuck.ts b/packages/studio/src/player/components/clipMenuDuck.ts
index 6b8b258ed0..4af9a1ccac 100644
--- a/packages/studio/src/player/components/clipMenuDuck.ts
+++ b/packages/studio/src/player/components/clipMenuDuck.ts
@@ -83,6 +83,11 @@ export function duckVoiceSources(doc: Document, bed: Element): string[] {
.map((candidate) => candidate.id);
}
+export function offersDuck(doc: Document | null, bed: Element | null): boolean {
+ if (!doc || !isDuckableBed(bed)) return false;
+ return readBedCarve(bed)?.enabled === true || duckVoiceSources(doc, bed).length > 0;
+}
+
async function writeMeasuredCarve(
doc: Document,
bed: Element,
diff --git a/packages/studio/src/player/components/clipMenuLinkItems.test.ts b/packages/studio/src/player/components/clipMenuLinkItems.test.ts
index 98ef1c1971..2c94db56b1 100644
--- a/packages/studio/src/player/components/clipMenuLinkItems.test.ts
+++ b/packages/studio/src/player/components/clipMenuLinkItems.test.ts
@@ -32,7 +32,7 @@ describe("resolveLinkMenuItems", () => {
const video = clip("talk", "video", { muted: true, link: "lk-1" });
const audio = clip("talk-audio", "audio", { link: "lk-1" });
expect(labels(audio, [video, audio])).toEqual([
- "Unlink",
+ "Unlink from video",
"Merge audio back into video",
"Delete this clip only",
]);
@@ -42,9 +42,26 @@ describe("resolveLinkMenuItems", () => {
const video = clip("talk", "video", { muted: true });
const audio = clip("talk-audio", "audio");
expect(labels(video, [video, audio], ["talk", "talk-audio"])).toEqual([
- "Link",
+ "Link to audio",
"Merge audio back into video",
]);
+ expect(labels(audio, [video, audio], ["talk", "talk-audio"])[0]).toBe("Link to video");
+ });
+
+ it("names the audio partner when unlinking from the video side", () => {
+ const video = clip("talk", "video", { muted: true, link: "lk-1" });
+ const audio = clip("talk-audio", "audio", { link: "lk-1" });
+ expect(labels(video, [video, audio])[0]).toBe("Unlink from audio");
+ });
+
+ it("falls back to plain Unlink for groups of three or same-kind partners", () => {
+ const video = clip("talk", "video", { muted: true, link: "lk-1" });
+ const audio = clip("talk-audio", "audio", { link: "lk-1" });
+ const second = clip("talk-audio2", "audio", { link: "lk-1" });
+ expect(labels(video, [video, audio, second])[0]).toBe("Unlink");
+ const twin = clip("talk2", "video", { muted: true, link: "lk-2" });
+ const twin2 = clip("talk3", "video", { muted: true, link: "lk-2" });
+ expect(labels(twin, [twin, twin2])[0]).toBe("Unlink");
});
it("offers nothing for a silent video or without a link handler", () => {
diff --git a/packages/studio/src/player/components/clipMenuLinkItems.tsx b/packages/studio/src/player/components/clipMenuLinkItems.tsx
index a5ca0d0daa..4931b09d7e 100644
--- a/packages/studio/src/player/components/clipMenuLinkItems.tsx
+++ b/packages/studio/src/player/components/clipMenuLinkItems.tsx
@@ -13,6 +13,16 @@ interface LinkMenuItem {
const keyOf = (el: TimelineElement) => el.key ?? el.id;
+const tagOf = (el: TimelineElement) => el.tag.trim().toLowerCase();
+
+function partnerSuffix(element: TimelineElement, others: readonly TimelineElement[]): string {
+ const partners = others.filter((el) => keyOf(el) !== keyOf(element));
+ const [partner] = partners;
+ if (partners.length !== 1 || !partner) return "";
+ const pair = [tagOf(element), tagOf(partner)].sort().join("+");
+ return pair === "audio+video" ? ` ${tagOf(partner)}` : "";
+}
+
/** The link-model items for a clip, in wireframe order (detach · unlink/link · merge · delete-one). */
export function resolveLinkMenuItems(input: {
element: TimelineElement;
@@ -36,13 +46,13 @@ export function resolveLinkMenuItems(input: {
const selected = elements.filter((el) => selectedKeys.has(keyOf(el)));
if (linked) {
items.push({
- label: "Unlink",
+ label: `Unlink${partnerSuffix(element, members) && ` from${partnerSuffix(element, members)}`}`,
shortcut: "⌘L",
run: () => onLinkEdit({ kind: "unlink", elements: members }),
});
} else if (canLinkPair(selected) && selectedKeys.has(keyOf(element))) {
items.push({
- label: "Link",
+ label: `Link${partnerSuffix(element, selected) && ` to${partnerSuffix(element, selected)}`}`,
shortcut: "⌘L",
run: () => onLinkEdit({ kind: "link", elements: selected }),
});
@@ -66,9 +76,11 @@ export function resolveLinkMenuItems(input: {
}
export function ClipMenuLinkItems({
+ part,
element,
onClose,
}: {
+ part: "link" | "delete";
element: TimelineElement;
onClose: () => void;
}) {
@@ -81,7 +93,7 @@ export function ClipMenuLinkItems({
selectedKeys,
onLinkEdit,
onDeleteElementOnly,
- });
+ }).filter((item) => (item.destructive === true) === (part === "delete"));
if (items.length === 0) return null;
return (
<>
@@ -104,7 +116,6 @@ export function ClipMenuLinkItems({
)}
</button>
))}
- <div className="my-1 border-t border-neutral-700/60" />
</>
);
}
diff --git a/packages/studio/src/player/components/clipMenuToolItems.tsx b/packages/studio/src/player/components/clipMenuToolItems.tsx
index bb372f3251..4acffdca5a 100644
--- a/packages/studio/src/player/components/clipMenuToolItems.tsx
+++ b/packages/studio/src/player/components/clipMenuToolItems.tsx
@@ -175,7 +175,7 @@ function FreezeFrameItem({ element, currentTime, onClose }: Omit<ClipMenuToolIte
);
}
-/** Freeze (time), Voice (sound), Look and Crop (picture); sound and picture end in their own divider. */
+/** Freeze (time), Voice (sound), Look and Crop (picture). */
export function ClipMenuToolItems(props: ClipMenuToolItemsProps) {
if (props.group === "time") return <FreezeFrameItem {...props} />;
return <ClipMenuAttributeItems {...props} />;
@@ -204,7 +204,6 @@ function ClipMenuAttributeItems({ group, element, onClose }: ClipMenuToolItemsPr
write(HF_AUDIO_FX_ATTR, chainWithVoicePreset(state.fxChain, id), "Voice preset")
}
/>
- <div className="my-1 border-t border-neutral-700/60" />
</>
);
}
@@ -229,7 +228,6 @@ function ClipMenuAttributeItems({ group, element, onClose }: ClipMenuToolItemsPr
>
<span>Crop</span>
</button>
- <div className="my-1 border-t border-neutral-700/60" />
</>
);
}
diff --git a/packages/studio/src/player/components/clipSync.test.ts b/packages/studio/src/player/components/clipSync.test.ts
new file mode 100644
index 0000000000..9d9fe557e3
--- /dev/null
+++ b/packages/studio/src/player/components/clipSync.test.ts
@@ -0,0 +1,67 @@
+import { describe, expect, it } from "vitest";
+import { clipSyncState, syncPartnerOf } from "./clipSync";
+
+const clip = (id: string, tag: string, start: number, extra: Record<string, unknown> = {}) => ({
+ id,
+ tag,
+ start,
+ duration: 4,
+ track: 0,
+ syncOrigin: "lk-1",
+ ...extra,
+});
+
+describe("syncPartnerOf", () => {
+ it("pairs a video with the audio sharing its sync origin, not another video", () => {
+ const v = clip("v", "video", 0);
+ const a = clip("a", "audio", 0);
+ const other = clip("v2", "video", 0);
+ expect(syncPartnerOf(a, [v, a, other])?.id).toBe("v");
+ expect(syncPartnerOf(v, [v, a, other])?.id).toBe("a");
+ });
+
+ it("ignores clips with no or another origin", () => {
+ const v = clip("v", "video", 0);
+ expect(syncPartnerOf(v, [v, clip("a", "audio", 0, { syncOrigin: "lk-2" })])).toBeNull();
+ expect(syncPartnerOf({ ...v, syncOrigin: undefined }, [v])).toBeNull();
+ });
+
+ it.each([{ sourceFile: "child.html" }, { compositionScope: "child" }])(
+ "never pairs across compositions reusing an origin (%o)",
+ (scope) => {
+ const v = clip("v", "video", 0);
+ expect(syncPartnerOf(v, [v, clip("a", "audio", 0, scope)])).toBeNull();
+ },
+ );
+
+ it("after a split, picks the partner sharing the most timeline", () => {
+ const a = clip("a", "audio", 4.2);
+ const left = clip("v", "video", 0);
+ const right = clip("v-split", "video", 4);
+ expect(syncPartnerOf(a, [left, right, a])?.id).toBe("v-split");
+ });
+});
+
+describe("clipSyncState", () => {
+ it("is null in sync and signed per side when drifted", () => {
+ const v = clip("v", "video", 1);
+ expect(clipSyncState(v, [v, clip("a", "audio", 1)], 30)).toBeNull();
+ const late = clip("a", "audio", 1 + 10 / 30);
+ expect(clipSyncState(late, [v, late], 30)?.frames).toBe(10);
+ expect(clipSyncState(v, [v, late], 30)?.frames).toBe(-10);
+ });
+
+ it("offers move and slip targets that each restore sync", () => {
+ const v = clip("v", "video", 1, { playbackStart: 0 });
+ const a = clip("a", "audio", 1.5, { playbackStart: 0 });
+ const state = clipSyncState(a, [v, a], 30);
+ expect(state?.moveStart).toBeCloseTo(1);
+ expect(state?.slipMediaStart).toBeCloseTo(0.5);
+ });
+
+ it("has no badge when the halves play at different rates", () => {
+ const v = clip("v", "video", 1, { playbackRate: 2 });
+ const a = clip("a", "audio", 2);
+ expect(clipSyncState(a, [v, a], 30)).toBeNull();
+ });
+});
diff --git a/packages/studio/src/player/components/clipSync.ts b/packages/studio/src/player/components/clipSync.ts
new file mode 100644
index 0000000000..f36705ce9d
--- /dev/null
+++ b/packages/studio/src/player/components/clipSync.ts
@@ -0,0 +1,80 @@
+import {
+ moveIntoSyncStart,
+ slipIntoSyncMediaStart,
+ syncOffsetFrames,
+ type SyncTiming,
+} from "@hyperframes/core/media-link";
+import { sameCompositionScope, type TimelineElement } from "../store/timelineElement";
+
+type SyncElement = Pick<
+ TimelineElement,
+ "id" | "key" | "tag" | "start" | "duration" | "playbackStart" | "playbackRate" | "syncOrigin"
+> &
+ Pick<TimelineElement, "sourceFile" | "compositionScope">;
+
+const keyOf = (el: Pick<TimelineElement, "id" | "key">) => el.key ?? el.id;
+const kindOf = (el: Pick<TimelineElement, "tag">) => el.tag.trim().toLowerCase();
+
+function syncTimingOf(el: SyncElement): SyncTiming {
+ return { start: el.start, mediaStart: el.playbackStart ?? 0, playbackRate: el.playbackRate ?? 1 };
+}
+
+function overlap(a: SyncElement, b: SyncElement): number {
+ return Math.min(a.start + a.duration, b.start + b.duration) - Math.max(a.start, b.start);
+}
+
+/**
+ * The other half of `el`'s source pair: a video for an audio and the reverse,
+ * sharing its sync origin. After splits several may qualify; the one sharing the
+ * most timeline wins, then the nearest start.
+ */
+export function syncPartnerOf<T extends SyncElement>(el: T, elements: readonly T[]): T | null {
+ const kind = kindOf(el);
+ if (!el.syncOrigin || (kind !== "video" && kind !== "audio")) return null;
+ const partnerKind = kind === "video" ? "audio" : "video";
+ const candidates = elements.filter(
+ (other) =>
+ keyOf(other) !== keyOf(el) &&
+ other.syncOrigin === el.syncOrigin &&
+ sameCompositionScope(other, el) &&
+ kindOf(other) === partnerKind,
+ );
+ const rank = (other: T) => [overlap(el, other), -Math.abs(other.start - el.start)] as const;
+ let best: T | null = null;
+ for (const candidate of candidates) {
+ if (!best) best = candidate;
+ else {
+ const [o1, d1] = rank(candidate);
+ const [o2, d2] = rank(best);
+ if (o1 > o2 || (o1 === o2 && d1 > d2)) best = candidate;
+ }
+ }
+ return best;
+}
+
+export interface ClipSyncState<T> {
+ partner: T;
+ frames: number;
+ moveStart: number | null;
+ slipMediaStart: number | null;
+}
+
+/** `el`'s drift from its source partner, or null when in sync, unpaired or at a different rate. */
+export function clipSyncState<T extends SyncElement>(
+ el: T,
+ elements: readonly T[],
+ fps: number,
+): ClipSyncState<T> | null {
+ const partner = syncPartnerOf(el, elements);
+ if (!partner) return null;
+ const self = syncTimingOf(el);
+ const other = syncTimingOf(partner);
+ const frames = syncOffsetFrames(self, other, fps);
+ if (frames === null || frames === 0) return null;
+ return {
+ partner,
+ frames,
+ moveStart: moveIntoSyncStart(self, other),
+ slipMediaStart: slipIntoSyncMediaStart(self, other),
+ };
+}
diff --git a/packages/studio/src/player/components/linkLabelColor.test.ts b/packages/studio/src/player/components/linkLabelColor.test.ts
new file mode 100644
index 0000000000..e94d49e44f
--- /dev/null
+++ b/packages/studio/src/player/components/linkLabelColor.test.ts
@@ -0,0 +1,20 @@
+import { describe, expect, it } from "vitest";
+import { LINK_LABEL_COLORS, linkLabelColor } from "./linkLabelColor";
+
+describe("linkLabelColor", () => {
+ it("has no colour for an unlinked clip", () => {
+ expect(linkLabelColor(undefined)).toBeNull();
+ expect(linkLabelColor("")).toBeNull();
+ });
+
+ it("walks the palette in lk-N order, wrapping", () => {
+ expect(linkLabelColor("lk-1")).toBe(LINK_LABEL_COLORS[0]);
+ expect(linkLabelColor("lk-2")).toBe(LINK_LABEL_COLORS[1]);
+ expect(linkLabelColor(`lk-${LINK_LABEL_COLORS.length + 1}`)).toBe(LINK_LABEL_COLORS[0]);
+ });
+
+ it("is deterministic for hand-written ids", () => {
+ expect(linkLabelColor("talk-pair")).toBe(linkLabelColor("talk-pair"));
+ expect(LINK_LABEL_COLORS).toContain(linkLabelColor("talk-pair"));
+ });
+});
diff --git a/packages/studio/src/player/components/linkLabelColor.ts b/packages/studio/src/player/components/linkLabelColor.ts
new file mode 100644
index 0000000000..58131814e9
--- /dev/null
+++ b/packages/studio/src/player/components/linkLabelColor.ts
@@ -0,0 +1,24 @@
+/** Link-group label colours; teal, violet, white and red belong to clips, selection and the sync badge. */
+export const LINK_LABEL_COLORS = [
+ "var(--color-amber-500)",
+ "var(--color-sky-400)",
+ "var(--color-green-400)",
+ "var(--color-pink-400)",
+ "var(--color-orange-400)",
+ "var(--color-amber-300)",
+] as const;
+
+function stableIndex(link: string): number {
+ const numbered = /^lk-(\d+)$/.exec(link);
+ if (numbered) return Number(numbered[1]) - 1;
+ let hash = 0;
+ for (const char of link) hash = (hash * 31 + char.charCodeAt(0)) >>> 0;
+ return hash;
+}
+
+/** The same colour for every member of a link group, from its id alone. */
+export function linkLabelColor(link: string | undefined): string | null {
+ if (!link) return null;
+ const count = LINK_LABEL_COLORS.length;
+ return LINK_LABEL_COLORS[((stableIndex(link) % count) + count) % count] ?? null;
+}
diff --git a/packages/studio/src/player/components/timelineCallbacks.ts b/packages/studio/src/player/components/timelineCallbacks.ts
index 812e6ca022..56b96dacc8 100644
--- a/packages/studio/src/player/components/timelineCallbacks.ts
+++ b/packages/studio/src/player/components/timelineCallbacks.ts
@@ -43,7 +43,9 @@ export type TimelineLinkEdit =
| { kind: "unlink"; elements: readonly TimelineElement[] }
| { kind: "link"; elements: readonly TimelineElement[] }
| { kind: "detach"; element: TimelineElement }
- | { kind: "merge"; video: TimelineElement; audio: TimelineElement };
+ | { kind: "merge"; video: TimelineElement; audio: TimelineElement }
+ | { kind: "move-into-sync"; element: TimelineElement; start: number }
+ | { kind: "slip-into-sync"; element: TimelineElement; mediaStart: number };
export interface TimelineEditCallbacks {
onMoveElement?: (
@@ -127,6 +129,7 @@ export interface TimelineEditCallbacks {
onRazorSplit?: (element: TimelineElement, splitTime: number) => Promise<void> | void;
onRazorSplitAll?: (splitTime: number) => Promise<void> | void;
onFreezeFrame?: (element: TimelineElement, time: number) => Promise<void> | void;
+ onNotice?: (message: string, tone?: "error" | "info") => void;
onDeleteKeyframe?: (elementId: string, keyframe: TimelineKeyframeTarget) => void;
onDeleteAllKeyframes?: (element: TimelineElement, animationId?: string) => void;
onMoveKeyframeToPlayhead?: (element: TimelineElement, keyframe: TimelineKeyframeTarget) => void;
diff --git a/packages/studio/src/player/components/timelineLinkSelection.ts b/packages/studio/src/player/components/timelineLinkSelection.ts
index 1ed00acc8c..231ee2df94 100644
--- a/packages/studio/src/player/components/timelineLinkSelection.ts
+++ b/packages/studio/src/player/components/timelineLinkSelection.ts
@@ -1,9 +1,10 @@
import { usePlayerStore } from "../store/playerStore";
import { expandToLinkedMembers } from "./audioClipLink";
+import { isLinkedSelectionOn } from "../../utils/linkedClipPreferences";
/**
* Select `key` the way a clip click does, then widen to link partners; Alt
- * selects `key` alone even when it sat inside a larger selection.
+ * (or Linked Selection off) selects `key` alone, even inside a larger selection.
*/
export function selectClipWithLinks(
key: string,
@@ -11,7 +12,7 @@ export function selectClipWithLinks(
setSelectedElementId: (id: string) => void,
): void {
const state = usePlayerStore.getState();
- if (altKey) {
+ if (altKey || !isLinkedSelectionOn()) {
state.setSelection([key], key);
return;
}
diff --git a/packages/studio/src/player/components/useTimelineClipDrag.ts b/packages/studio/src/player/components/useTimelineClipDrag.ts
index 41a21dd815..327e1ca247 100644
--- a/packages/studio/src/player/components/useTimelineClipDrag.ts
+++ b/packages/studio/src/player/components/useTimelineClipDrag.ts
@@ -28,6 +28,7 @@ import type {
} from "./timelineClipDragTypes";
import { getTimelineElementIndexes } from "../lib/timelineElementIndexes";
import { linkedGestureKeys } from "./audioClipLink";
+import { isLinkedSelectionOn } from "../../utils/linkedClipPreferences";
import type { TimelineRowGeometry } from "./timelineLayout";
import {
mountTimelineClipDragGestureLifecycle,
@@ -228,6 +229,7 @@ export function useTimelineClipDrag({
next.element,
elementsRef.current,
next.altKey === true,
+ isLinkedSelectionOn(),
);
publishDraggedClip(next);
},
@@ -245,6 +247,7 @@ export function useTimelineClipDrag({
next.element,
elementsRef.current,
next.altKey === true,
+ isLinkedSelectionOn(),
);
publishResizingClip(next);
},
diff --git a/packages/studio/src/player/hooks/timelinePlayerSync.test.ts b/packages/studio/src/player/hooks/timelinePlayerSync.test.ts
index 1ced1ee283..1f0df8de61 100644
--- a/packages/studio/src/player/hooks/timelinePlayerSync.test.ts
+++ b/packages/studio/src/player/hooks/timelinePlayerSync.test.ts
@@ -13,9 +13,15 @@ describe("timelineElementsChanged", () => {
["audio group hidden", { audioGroupHidden: true }],
["fade in", { fadeIn: 1 }],
["fade out", { fadeOut: 1 }],
+ ["link", { link: "lk-1" }],
["source (re-pointed at its preview copy)", { src: "clip1.mp4?hf-proxy=h264" }],
])("sees a clip whose %s changed with no timing change", (_name, change) => {
expect(timelineElementsChanged([clip], [{ ...clip, ...change }])).toBe(true);
expect(timelineElementsChanged([{ ...clip, ...change }], [{ ...clip, ...change }])).toBe(false);
});
+
+ it("sees an unlink: the same clips re-derived without their link", () => {
+ const linked = { ...clip, link: "lk-1" };
+ expect(timelineElementsChanged([linked], [clip])).toBe(true);
+ });
});
diff --git a/packages/studio/src/player/hooks/timelinePlayerSync.ts b/packages/studio/src/player/hooks/timelinePlayerSync.ts
index 6991979acc..4bba7f1572 100644
--- a/packages/studio/src/player/hooks/timelinePlayerSync.ts
+++ b/packages/studio/src/player/hooks/timelinePlayerSync.ts
@@ -16,6 +16,7 @@ const RENDERED_FIELDS: readonly (keyof TimelineElement)[] = [
"fadeIn",
"fadeOut",
"src",
+ "link",
];
/** Whether a derived timeline changes any field that affects rendering. */
diff --git a/packages/studio/src/player/hooks/useTimelineSyncCallbacks.ts b/packages/studio/src/player/hooks/useTimelineSyncCallbacks.ts
index 089312cf4c..e0231bf32b 100644
--- a/packages/studio/src/player/hooks/useTimelineSyncCallbacks.ts
+++ b/packages/studio/src/player/hooks/useTimelineSyncCallbacks.ts
@@ -15,6 +15,7 @@ import type { PlaybackAdapter, IframeWindow } from "../lib/playbackTypes";
import { readTimelineDurationFromDocument } from "../lib/timelineDOM";
import { buildMissingCompositionElements } from "../lib/timelineIframeHelpers";
import { acceptedRuntimeMessageFps } from "../lib/runtimeProtocol";
+import { useLinkedClipPreferences } from "../../utils/linkedClipPreferences";
import {
buildTimelineElementsFromClips,
syncManifestTimeline,
@@ -196,8 +197,10 @@ export function useTimelineSyncCallbacks({
// at the authored root `data-duration` so a runtime that measures only the
// furthest clip end (shorter than the authored window) can't leave a stale,
// too-short total in the transport (the "0:44/0:40" bug).
+ const fps = acceptedRuntimeMessageFps(data);
+ useLinkedClipPreferences.getState().setCompositionFps(fps);
const newDuration = resolveTimelineTotalDuration({
- manifestDurationSeconds: data.durationInFrames / acceptedRuntimeMessageFps(data),
+ manifestDurationSeconds: data.durationInFrames / fps,
authoredRootDurationSeconds: readTimelineDurationFromDocument(iframeDoc),
});
syncManifestTimeline(
diff --git a/packages/studio/src/player/lib/timelineDOM.test.ts b/packages/studio/src/player/lib/timelineDOM.test.ts
index f0b03876ef..3b5790b1e0 100644
--- a/packages/studio/src/player/lib/timelineDOM.test.ts
+++ b/packages/studio/src/player/lib/timelineDOM.test.ts
@@ -282,13 +282,15 @@ describe("parseTimelineFromDOM — hfId from data-hf-id", () => {
expect(element.hidden).toBe(true);
});
- it("reads data-link on both the DOM and manifest paths", () => {
+ it("reads data-link and data-sync-origin on both the DOM and manifest paths", () => {
const doc = makeDoc(`
<div data-composition-id="root">
- <video id="talk" class="clip" src="t.mp4" muted data-link="lk-1" data-start="0" data-duration="5"></video>
+ <video id="talk" class="clip" src="t.mp4" muted data-link="lk-1" data-sync-origin="lk-1" data-start="0" data-duration="5"></video>
</div>
`);
- expect(parseTimelineFromDOM(doc, 10).find((el) => el.domId === "talk")?.link).toBe("lk-1");
+ const fromDom = parseTimelineFromDOM(doc, 10).find((el) => el.domId === "talk");
+ expect(fromDom?.link).toBe("lk-1");
+ expect(fromDom?.syncOrigin).toBe("lk-1");
const element = createTimelineElementFromManifestClip({
clip: {
id: "talk",
@@ -308,6 +310,7 @@ describe("parseTimelineFromDOM — hfId from data-hf-id", () => {
hostEl: doc.getElementById("talk"),
});
expect(element.link).toBe("lk-1");
+ expect(element.syncOrigin).toBe("lk-1");
});
});
diff --git a/packages/studio/src/player/lib/timelineDOM.ts b/packages/studio/src/player/lib/timelineDOM.ts
index 1efa59e438..23b8b68ff9 100644
--- a/packages/studio/src/player/lib/timelineDOM.ts
+++ b/packages/studio/src/player/lib/timelineDOM.ts
@@ -155,6 +155,8 @@ export function createTimelineElementFromManifestClip(params: {
if (link) entry.link = link;
const compositionScope = linkScopeOf(hostEl)?.getAttribute("data-composition-id");
if (compositionScope) entry.compositionScope = compositionScope;
+ const syncOrigin = hostEl.getAttribute("data-sync-origin");
+ if (syncOrigin) entry.syncOrigin = syncOrigin;
const audioGroup = hostEl.getAttribute("data-audio-group");
if (audioGroup) {
entry.audioGroup = audioGroup;
@@ -346,6 +348,8 @@ export function parseTimelineFromDOM(
if (domLink) entry.link = domLink;
const domCompositionScope = linkScopeOf(el)?.getAttribute("data-composition-id");
if (domCompositionScope) entry.compositionScope = domCompositionScope;
+ const domSyncOrigin = el.getAttribute("data-sync-origin");
+ if (domSyncOrigin) entry.syncOrigin = domSyncOrigin;
const domAudioGroup = el.getAttribute("data-audio-group");
if (domAudioGroup) {
diff --git a/packages/studio/src/player/store/timelineElement.ts b/packages/studio/src/player/store/timelineElement.ts
index 90f7a85206..33b612c145 100644
--- a/packages/studio/src/player/store/timelineElement.ts
+++ b/packages/studio/src/player/store/timelineElement.ts
@@ -85,6 +85,7 @@ export interface TimelineElement {
audioGroupAutomation?: string;
link?: string;
compositionScope?: string;
+ syncOrigin?: string;
/**
* Master start of the composition this row runs in, which its tweens and its
* `data-start` are local to; 0 at the root. Writes go through toAuthoredStart.
diff --git a/packages/studio/src/styles/components.css b/packages/studio/src/styles/components.css
index 72af960356..f08933159c 100644
--- a/packages/studio/src/styles/components.css
+++ b/packages/studio/src/styles/components.css
@@ -296,17 +296,6 @@
transition: none;
}
-.timeline-audio-link {
- position: absolute;
- z-index: 4;
- top: -9px;
- left: 50%;
- width: 1px;
- height: 10px;
- background: var(--timeline-audio-link);
- pointer-events: none;
-}
-
.timeline-clip.is-hovered {
background-color: var(--clip-bg-hover);
}
@@ -362,6 +351,16 @@
white-space: nowrap;
}
+/* Link groups share a label colour on the border and the name chip. */
+.timeline-clip[data-link-color] {
+ border-color: var(--clip-link-color);
+}
+
+.timeline-clip[data-link-color] .timeline-clip__label {
+ box-shadow: inset 3px 0 0 var(--clip-link-color);
+ padding-left: 8px;
+}
+
.timeline-clip.is-audio .timeline-clip__label {
top: 11px;
left: 9px;
diff --git a/packages/studio/src/styles/theme.css b/packages/studio/src/styles/theme.css
index 6486f033fa..bb5a48cfd6 100644
--- a/packages/studio/src/styles/theme.css
+++ b/packages/studio/src/styles/theme.css
@@ -117,7 +117,6 @@
--timeline-clip-audio-bg-hover: oklch(0.49 0.12 300);
--timeline-clip-audio-bg-dragging: oklch(0.42 0.12 300 / 0.96);
--timeline-clip-audio-muted-bg: rgb(72, 74, 78);
- --timeline-audio-link: light-dark(#626d66, #a0aaa4);
--timeline-clip-selection: light-dark(#0f766e, rgba(255, 255, 255, 0.85));
--timeline-clip-selection-highlight: rgb(255 255 255 / 0.55);
--timeline-clip-radius: 8px;
diff --git a/packages/studio/src/utils/linkedClipPreferences.ts b/packages/studio/src/utils/linkedClipPreferences.ts
new file mode 100644
index 0000000000..acb8b99a7c
--- /dev/null
+++ b/packages/studio/src/utils/linkedClipPreferences.ts
@@ -0,0 +1,34 @@
+import { create } from "zustand";
+import { STUDIO_PREVIEW_FPS } from "../player/lib/time";
+import { readStudioUiPreferences, writeStudioUiPreferences } from "./studioUiPreferences";
+
+interface LinkedClipPreferences {
+ /** Premiere's Linked Selection: clicks and edits reach every link partner. */
+ linkedSelection: boolean;
+ setLinkedSelection: (enabled: boolean) => void;
+ /** Red offset badges on a video and audio from one source that drifted apart. */
+ syncIndicatorsVisible: boolean;
+ setSyncIndicatorsVisible: (visible: boolean) => void;
+ compositionFps: number;
+ setCompositionFps: (fps: number) => void;
+}
+
+export const useLinkedClipPreferences = create<LinkedClipPreferences>((set) => ({
+ linkedSelection: readStudioUiPreferences().linkedSelectionEnabled ?? true,
+ setLinkedSelection: (enabled) => {
+ writeStudioUiPreferences({ linkedSelectionEnabled: enabled });
+ set({ linkedSelection: enabled });
+ },
+ syncIndicatorsVisible: readStudioUiPreferences().syncIndicatorsVisible ?? true,
+ setSyncIndicatorsVisible: (visible) => {
+ writeStudioUiPreferences({ syncIndicatorsVisible: visible });
+ set({ syncIndicatorsVisible: visible });
+ },
+ compositionFps: STUDIO_PREVIEW_FPS,
+ setCompositionFps: (fps) => {
+ if (Number.isFinite(fps) && fps > 0) set({ compositionFps: fps });
+ },
+}));
+
+export const isLinkedSelectionOn = (): boolean =>
+ useLinkedClipPreferences.getState().linkedSelection;
diff --git a/packages/studio/src/utils/studioUiPreferences.ts b/packages/studio/src/utils/studioUiPreferences.ts
index 4e1fdc9f99..4c72902705 100644
--- a/packages/studio/src/utils/studioUiPreferences.ts
+++ b/packages/studio/src/utils/studioUiPreferences.ts
@@ -45,6 +45,8 @@ export interface StudioUiPreferences {
theme?: StudioTheme;
/** The dock's serialized panel tree; parsed by `parseDockLayout` on read. */
dockLayout?: SerializedDockview;
+ linkedSelectionEnabled?: boolean;
+ syncIndicatorsVisible?: boolean;
}
const STUDIO_UI_PREFERENCES_KEY = "hf-studio-ui-preferences";
@@ -146,6 +148,12 @@ function readStorage(storage: Storage | null, key: string): StudioUiPreferences
if (typeof parsed.agentToolsEnabled === "boolean") {
preferences.agentToolsEnabled = parsed.agentToolsEnabled;
}
+ if (typeof parsed.linkedSelectionEnabled === "boolean") {
+ preferences.linkedSelectionEnabled = parsed.linkedSelectionEnabled;
+ }
+ if (typeof parsed.syncIndicatorsVisible === "boolean") {
+ preferences.syncIndicatorsVisible = parsed.syncIndicatorsVisible;
+ }
const dockLayout = parseDockLayout(parsed.dockLayout);
if (dockLayout) preferences.dockLayout = dockLayout;
return preferences;
diff --git a/skills-manifest.json b/skills-manifest.json
index f380caf3df..bfe3e58016 100644
--- a/skills-manifest.json
+++ b/skills-manifest.json
@@ -34,7 +34,7 @@
"files": 11
},
"hyperframes-core": {
- "hash": "3bc49ffe4697122b",
+ "hash": "539de2110ccdaa43",
"files": 11
},
"hyperframes-creative": {
diff --git a/skills/hyperframes-core/references/data-attributes.md b/skills/hyperframes-core/references/data-attributes.md
index 7949c27dd8..83d9943707 100644
--- a/skills/hyperframes-core/references/data-attributes.md
+++ b/skills/hyperframes-core/references/data-attributes.md
@@ -36,6 +36,7 @@ The root should be `position: relative`, have explicit pixel dimensions, and hid
| `data-volume` | No | Static audio gain, default `1` (0 dB). `0` is silence and values above `1` boost, up to `3.98` (+12 dB) — Studio's fader writes this. For fades and ducking, use the `data-automation` volume lane (see `creator-editing-recipes.md`). |
| `data-has-audio` | Required on a timed `<video>` unless it is `muted` | `"true"` keeps the file's sound on this clip (the default for footage with sound). Silent footage uses `muted` instead; a video with neither fails lint (`video_missing_muted`). |
| `data-link` | No | Editing contract only (render ignores it): clips sharing an id, e.g. a video and the `<audio>` detached from it in Studio, are edited as one. Keep every member's `data-start`, `data-duration`, `data-media-start` and `data-playback-rate` equal; to unlink, remove the attribute from all members. See [tracks-and-clips.md](tracks-and-clips.md#linked-clips). |
+| `data-sync-origin` | No | Editing contract only: a video and audio from one source file share it (written by Detach and Link, kept by Unlink). Studio flags the pair out of sync when their source-zero points differ. See [tracks-and-clips.md](tracks-and-clips.md#linked-clips). |
**The visibility window is half-open: `[start, start + duration)`.** A clip shows while `start ≤ t < start + duration` and is hidden at exactly `t = start + duration`. Land an animation's resolved end state slightly **before** `data-duration`, not on it, or its last frame is never rendered. Two clips can therefore be authored back to back (`b.start === a.start + a.duration`) with no overlapping frame.
diff --git a/skills/hyperframes-core/references/tracks-and-clips.md b/skills/hyperframes-core/references/tracks-and-clips.md
index 93f7023177..72b1a51f49 100644
--- a/skills/hyperframes-core/references/tracks-and-clips.md
+++ b/skills/hyperframes-core/references/tracks-and-clips.md
@@ -58,6 +58,7 @@ Each video segment keeps its sound: the sound stays on the clip (`data-has-audio
src="talk.mp4"
muted
data-link="lk-1"
+ data-sync-origin="lk-1"
data-start="2"
data-duration="6"
data-media-start="1"
@@ -67,6 +68,7 @@ Each video segment keeps its sound: the sound stays on the clip (`data-has-audio
id="talk-audio"
src="talk.mp4"
data-link="lk-1"
+ data-sync-origin="lk-1"
data-start="2"
data-duration="6"
data-media-start="1"
@@ -78,6 +80,7 @@ Each video segment keeps its sound: the sound stays on the clip (`data-has-audio
- **Unlink** by removing `data-link` from every member. Removing it from one leaves the other alone with the id, which `lint` flags as `linked_clip_orphan`.
- The render ignores `data-link`: an out-of-sync pair still plays exactly what its timings say.
- Prefer a single `<video data-has-audio="true">` for footage with sound. Link only when the sound needs its own clip (its own track, volume or FX); to undo a detach, move the audio attributes back onto the video and delete the `<audio>`.
+- **Sync origin.** `data-sync-origin="<id>"` marks a video and an audio from one source file; Detach and Link write it, and Unlink keeps it. When the pair drifts (their source-zero points, `data-start − data-media-start / data-playback-rate`, differ), Studio shows a red offset in frames on both halves with Move into Sync / Slip into Sync, `hyperframes timeline` prints `out-of-sync=±Nf`, and the SDK offers `syncOffset`, `moveIntoSync` and `slipIntoSync`. Leave it alone when retiming by hand; remove it only when the clips are no longer one source.
- `@hyperframes/sdk` `setTiming` applies to link partners by default; pass `{ linked: false }` to edit one member, which unlinks it.
## Relative Timing