Skip to content

Commit 7859c0f

Browse files
fix(studio): trimming keeps the playhead still; clips snap to the ruler grid (#4986)
* fix(studio): trimming keeps the playhead still; clips snap to the ruler grid * fix(studio): an edge frame never becomes the playhead time; grid snaps where clips save * ci(studio): run the trim and grid snap walk with the other Studio browser checks * fix(studio): snap guides only where the clip saves; play keeps an explicit rewind * fix(studio): a snap guide shows only where the saved clip lands; preview frame gets its own store * fix(studio): judge a moved clip's guide by the duration the move keeps * chore(studio): trim comments the names already say
1 parent b04081b commit 7859c0f

21 files changed

Lines changed: 657 additions & 135 deletions

‎.github/workflows/ci.yml‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -848,6 +848,8 @@ jobs:
848848
packages/studio/data/projects/studio-open
849849
cp -R packages/studio/tests/e2e/fixtures/fade-handles \
850850
packages/studio/data/projects/fade-handles
851+
cp -R packages/studio/tests/e2e/fixtures/timeline-trim-snap \
852+
packages/studio/data/projects/timeline-trim-snap
851853
cp -R packages/studio/tests/e2e/fixtures/inline-text-caret \
852854
packages/studio/data/projects/inline-text-caret
853855
cp -R packages/studio/tests/e2e/fixtures/undo-socket-pool \
@@ -960,7 +962,7 @@ jobs:
960962
node packages/studio/tests/e2e/perf-ratchet.mjs check \
961963
packages/studio/tests/e2e/perf-ceilings.json studio-open /tmp/studio-open-counts.json \
962964
/tmp/base-perf-ceilings.json
963-
- name: Check fade handles, render selects and thumbnail connection release
965+
- name: Check fade handles, render selects, thumbnail connection release and trim snapping
964966
if: success() || failure()
965967
run: |
966968
set -euo pipefail
@@ -983,6 +985,8 @@ jobs:
983985
node packages/studio/tests/e2e/render-selects.mjs || rc=1
984986
STUDIO_URL="http://localhost:5316/" \
985987
node packages/studio/tests/e2e/thumbnail-save.mjs || rc=1
988+
STUDIO_URL="http://localhost:5316/#project/timeline-trim-snap" \
989+
node packages/studio/tests/e2e/timeline-trim-snap.mjs || rc=1
986990
exit "$rc"
987991
- name: Measure the caret of a text edited in place
988992
if: success() || failure()

‎packages/studio/src/player/components/TimelineClipFades.tsx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -48,6 +48,7 @@ const SNAP_LABEL: Record<TimelineSnapType, string> = {
4848
playhead: "playhead",
4949
"clip-edge": "clip edge",
5050
beat: "beat",
51+
grid: "grid line",
5152
};
5253

5354
export type ClipFadeShape = AudioFades & { duration: number };

‎packages/studio/src/player/components/timelineClipDragPreview.test.ts‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@ import type { TimelineElement } from "../store/playerStore";
33
import {
44
computeDragPreview,
55
computeResizePreview,
6+
guideIfSaved,
67
getTimelineDragOverlayPosition,
78
type DragPreviewContext,
89
} from "./timelineClipDragPreview";
@@ -293,6 +294,52 @@ describe("computeDragPreview — a clip landing on an empty main track keeps its
293294
});
294295
});
295296

297+
describe("guideIfSaved — a guide only where the clip saves", () => {
298+
const grid = { time: 3.25, type: "grid" as const };
299+
300+
it("drops the guide when start and duration round apart from the target", () => {
301+
// 1440 px/s: 1.125s + 2.125s saves as 1.13s + 2.13s, 14px past the 3.25s guide.
302+
const el = clip("a", 0, 1.125, 2, 0, "div");
303+
expect(guideIfSaved(el, { start: 1.125, duration: 2.125 }, grid, 1440)).toBeNull();
304+
});
305+
306+
it("drops the guide when a nested clip's local start rounds off it", () => {
307+
const el = { ...clip("a", 0, 2, 1, 0, "div"), parentCompositionStart: 1 / 30 };
308+
const target = { time: 2.1, type: "playhead" as const };
309+
expect(guideIfSaved(el, { start: 2.1, duration: 1 }, target, 1440)).toBeNull();
310+
});
311+
312+
it("keeps the guide when the saved edge is on it", () => {
313+
const el = clip("a", 0, 1, 2, 0, "div");
314+
expect(guideIfSaved(el, { start: 1, duration: 2.25 }, grid, 1440)).toBe(grid);
315+
});
316+
317+
it("judges a move by the duration it keeps, not a rounded one", () => {
318+
// A 31/30 s clip moved so its end meets 3.25s saves its start at 2.22s and ends 4.8px past.
319+
const el = clip("a", 0, 1, 31 / 30, 0, "div");
320+
const edge = { time: 3.25, type: "clip-edge" as const };
321+
expect(guideIfSaved(el, { start: 2.217 }, edge, 1440)).toBeNull();
322+
});
323+
324+
it("draws no guide for a move whose saved start misses the target", () => {
325+
const nested = { ...moodboard, parentCompositionStart: 1 / 30 };
326+
const { drag } = horizontalDrag(nested, 0.5, 0);
327+
const context = {
328+
...ctx(),
329+
pps: 1440,
330+
buildSnapTargets: () => [{ time: 21, type: "playhead" as const }],
331+
};
332+
const next = computeDragPreview(
333+
drag,
334+
drag.originClientX + 2 * 1440,
335+
drag.originClientY,
336+
context,
337+
);
338+
expect(next.previewStart).toBe(21);
339+
expect(next.snapTime).toBeNull();
340+
});
341+
});
342+
296343
describe("computeResizePreview — composition source continuity", () => {
297344
it("seeds a legacy composition offset and advances it at playback rate", () => {
298345
const element = {
@@ -320,6 +367,27 @@ describe("computeResizePreview — composition source continuity", () => {
320367
});
321368
});
322369

370+
it("draws no guide when the trimmed start cannot save onto the target", () => {
371+
// 1440 px/s: a playhead on frame 31 (1.033s) saves a start of 1.03s, 4px off the guide.
372+
const result = computeResizePreview(
373+
{
374+
element: clip("a", 0, 1, 2, 0, "div"),
375+
edge: "start",
376+
originClientX: 0,
377+
previewStart: 1,
378+
previewDuration: 2,
379+
started: true,
380+
},
381+
48,
382+
{
383+
scroll: fakeScroll(),
384+
pps: 1440,
385+
buildSnapTargets: () => [{ time: 1.033, type: "playhead" }],
386+
},
387+
);
388+
expect(result).toMatchObject({ previewStart: 1.03, snapTime: null, snapType: null });
389+
});
390+
323391
it("does not let a tail snap shrink a clip below the drag's minimum duration", () => {
324392
const result = computeResizePreview(
325393
{

‎packages/studio/src/player/components/timelineClipDragPreview.ts‎

Lines changed: 39 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ import {
55
resolveTimelineMinDuration,
66
} from "./timelineGroupEditing";
77
import type { TimelineElement } from "../store/playerStore";
8-
import { clampToHostStart } from "../store/timelineElement";
8+
import { clampToHostStart, savedClipEdges } from "../store/timelineElement";
99
import {
1010
CLIP_Y,
1111
TRACK_H,
@@ -34,7 +34,6 @@ import { heldAudioShiftRange, heldPartnerVideoBounds } from "./audioClipLink";
3434
type BuildSnapTargets = (
3535
excludeElementKey: string | null,
3636
includeBeats: boolean,
37-
includePlayhead?: boolean,
3837
) => TimelineSnapTarget[];
3938

4039
export interface DragPreviewContext {
@@ -56,6 +55,8 @@ export interface DragPreviewContext {
5655
* on demand from `elements`, so the result is identical either way.
5756
*/
5857
audioTracks?: ReadonlySet<number>;
58+
/** Seconds between the ruler's lines; 0 or absent when snapping is off. */
59+
gridStep?: number;
5960
}
6061

6162
export function createKeyboardClipDrag(
@@ -248,6 +249,7 @@ export function computeDragPreview(
248249
// Relaxed clamp: allow the snapped start past the content, up to the
249250
// rendered extent (see dragMaxStart) — the composition grows on commit.
250251
dragMaxStart + drag.element.duration,
252+
ctx.gridStep,
251253
);
252254
// A group moves rigidly: the grabbed clip stops where any mover would cross its host's start.
253255
const group = resolveGroupDrag(drag, ctx);
@@ -266,6 +268,11 @@ export function computeDragPreview(
266268
return { ...drag, started: true };
267269
}
268270
const { track: previewTrack, insertRow } = placement;
271+
const target =
272+
placement.start === snap.start && snap.snapTime !== null && snap.snapType !== null
273+
? { time: snap.snapTime, type: snap.snapType }
274+
: null;
275+
const guide = guideIfSaved(drag.element, { start: snap.start }, target, pps);
269276
return {
270277
...drag,
271278
started: true,
@@ -277,11 +284,24 @@ export function computeDragPreview(
277284
// tell a deliberate vertical lane change from a horizontal drag.
278285
desiredTrack: nextMove.track,
279286
insertRow,
280-
snapTime: placement.start === snap.start ? snap.snapTime : null,
281-
snapType: placement.start === snap.start ? snap.snapType : null,
287+
snapTime: guide?.time ?? null,
288+
snapType: guide?.type ?? null,
282289
};
283290
}
284291

292+
/** A snap's guide, kept only when the clip's edge as its file will save it is within a pixel of it. */
293+
export function guideIfSaved(
294+
element: TimelineElement,
295+
clip: { start: number; duration?: number },
296+
target: TimelineSnapTarget | null,
297+
pps: number,
298+
): TimelineSnapTarget | null {
299+
if (!target) return null;
300+
const saved = savedClipEdges(element, clip.start, clip.duration);
301+
const off = Math.min(Math.abs(saved.start - target.time), Math.abs(saved.end - target.time));
302+
return off * pps < 1 ? target : null;
303+
}
304+
285305
/** One frame: the last visible frame of a clip sits just before its end time. */
286306
const TRIM_END_FRAME_LEAD_S = 1 / STUDIO_PREVIEW_FPS;
287307

@@ -296,6 +316,8 @@ export interface ResizePreviewContext {
296316
buildSnapTargets: BuildSnapTargets;
297317
elements?: readonly TimelineElement[];
298318
gestureKeys?: ReadonlySet<string>;
319+
/** Seconds between the ruler's lines; 0 or absent when snapping is off. */
320+
gridStep?: number;
299321
}
300322

301323
export interface ResizePreviewResult {
@@ -362,21 +384,19 @@ export function computeResizePreview(
362384
effectiveClientX,
363385
);
364386

365-
// Snap to beats and clip edges, never the playhead (the dragged edge drives
366-
// its own preview seek, so that would be circular). Stay inside the same
367-
// limits resolveTimelineResize enforces. The music track defines the
368-
// beats, so it must not snap to them, but still snaps to clip edges.
387+
// Snap within the same limits resolveTimelineResize enforces. The music
388+
// track defines the beats, so it must not snap to them.
369389
const trimTargets = buildSnapTargets(
370390
resize.element.key ?? resize.element.id,
371391
!isMusicTrack(resize.element),
372-
false,
373392
);
393+
const gridStep = ctx.gridStep ?? 0;
374394
let snap: TimelineSnapTarget | null = null;
375-
if (trimTargets.length > 0) {
395+
if (trimTargets.length > 0 || gridStep > 0) {
376396
const snapSecs = TIMELINE_SNAP_PX / Math.max(pps, 1);
377397
if (resize.edge === "end") {
378398
const edgeTime = nextResize.start + nextResize.duration;
379-
const { time: snapped, target } = snapTimelineTime(edgeTime, trimTargets, snapSecs);
399+
const { time: snapped, target } = snapTimelineTime(edgeTime, trimTargets, snapSecs, gridStep);
380400
// Stay within [start+minDuration, maxEnd] so the snap can't create a
381401
// degenerate clip or run past the source/composition limit.
382402
const snappedDuration = Math.round((snapped - nextResize.start) * 1000) / 1000;
@@ -387,16 +407,21 @@ export function computeResizePreview(
387407
) {
388408
// An edge already on the target still owns the guide; only move it when off.
389409
if (snapped !== edgeTime) nextResize = { ...nextResize, duration: snappedDuration };
390-
snap = target;
410+
snap = guideIfSaved(resize.element, nextResize, target, pps);
391411
}
392412
} else {
393-
const { time: snapped, target } = snapTimelineTime(nextResize.start, trimTargets, snapSecs);
413+
const { time: snapped, target } = snapTimelineTime(
414+
nextResize.start,
415+
trimTargets,
416+
snapSecs,
417+
gridStep,
418+
);
394419
const clip = { ...nextResize, playbackRate: resize.element.playbackRate };
395420
const delta = snapped - nextResize.start;
396421
const bounds = clipStartTrimDeltaBounds(clip, minStart, resolveTimelineMinDuration());
397422
if (target && delta >= bounds.minDelta - 1e-6 && delta <= bounds.maxDelta + 1e-6) {
398423
if (snapped !== nextResize.start) nextResize = applyClipStartTrimDelta(clip, delta);
399-
snap = target;
424+
snap = guideIfSaved(resize.element, nextResize, target, pps);
400425
}
401426
}
402427
}

‎packages/studio/src/player/components/timelineLayout.test.ts‎

Lines changed: 24 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,11 @@ import {
1818
resolveTimelineAssetDrop,
1919
getTimelineBeatEntries,
2020
} from "./timelineLayout";
21-
import { generateTicks, getTimelineMajorTickInterval } from "./timelineRulerGeometry";
21+
import {
22+
generateTicks,
23+
getTimelineGridStep,
24+
getTimelineMajorTickInterval,
25+
} from "./timelineRulerGeometry";
2226
import { resolveInsertRow } from "./timelineCollision";
2327
import { getTimelineRenderTimeRange } from "./timelineViewportGeometry";
2428

@@ -42,6 +46,25 @@ describe("horizontal timeline window", () => {
4246
expect(ticks.major.length + ticks.minor.length).toBeLessThan(100);
4347
});
4448

49+
it("spaces the snap grid exactly like the ruler's drawn lines at each zoom", () => {
50+
for (const [pps, fps] of [
51+
[100, undefined],
52+
[12, undefined],
53+
[900, undefined],
54+
[100, 30],
55+
[3, 30],
56+
] as const) {
57+
const { major, minor } = generateTicks(60, pps, fps);
58+
const lines = [...major, ...minor].sort((a, b) => a - b);
59+
expect(getTimelineGridStep(60, pps, fps)).toBeCloseTo(lines[1]! - lines[0]!, 6);
60+
}
61+
});
62+
63+
it("has no snap grid where the ruler draws no lines", () => {
64+
expect(generateTicks(20_000, 100)).toEqual({ major: [], minor: [] });
65+
expect(getTimelineGridStep(20_000, 100)).toBe(0);
66+
});
67+
4568
it("slices beat records with original strength indexes and unions a pinned beat", () => {
4669
expect(
4770
getTimelineBeatEntries(

‎packages/studio/src/player/components/timelineRulerGeometry.ts‎

Lines changed: 24 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
1-
import { formatTime } from "../lib/time";
1+
import { formatTime, STUDIO_PREVIEW_FPS } from "../lib/time";
2+
import type { TimelineTimeDisplayMode } from "../../utils/studioUiPreferences";
23
import type { TimelineTimeRange } from "../lib/timelineClipIndex";
34

45
// fallow-ignore-next-line complexity
@@ -87,15 +88,35 @@ function appendMinorTicks(
8788
}
8889
}
8990

91+
function tickSpacing(duration: number, pixelsPerSecond?: number, frameRate?: number) {
92+
const majorInterval = getTimelineMajorTickInterval(duration, pixelsPerSecond, frameRate);
93+
const subdivisions = getMinorSubdivisions(majorInterval, pixelsPerSecond, frameRate);
94+
return { majorInterval, subdivisions };
95+
}
96+
97+
export function rulerFrameRate(mode: TimelineTimeDisplayMode): number | undefined {
98+
return mode === "frame" ? STUDIO_PREVIEW_FPS : undefined;
99+
}
100+
101+
/** Seconds between neighbouring ruler lines (minor ticks when drawn, else major): the snap grid. */
102+
export function getTimelineGridStep(
103+
duration: number,
104+
pixelsPerSecond?: number,
105+
frameRate?: number,
106+
): number {
107+
if (!isSupportedTickDuration(duration)) return 0;
108+
const { majorInterval, subdivisions } = tickSpacing(duration, pixelsPerSecond, frameRate);
109+
return subdivisions > 0 ? majorInterval / subdivisions : majorInterval;
110+
}
111+
90112
export function generateTicks(
91113
duration: number,
92114
pixelsPerSecond?: number,
93115
frameRate?: number,
94116
range?: TimelineTimeRange,
95117
): { major: number[]; minor: number[] } {
96118
if (!isSupportedTickDuration(duration)) return { major: [], minor: [] };
97-
const majorInterval = getTimelineMajorTickInterval(duration, pixelsPerSecond, frameRate);
98-
const subdivisions = getMinorSubdivisions(majorInterval, pixelsPerSecond, frameRate);
119+
const { majorInterval, subdivisions } = tickSpacing(duration, pixelsPerSecond, frameRate);
99120
const minorInterval = subdivisions > 0 ? majorInterval / subdivisions : 0;
100121
const major: number[] = [];
101122
const minor: number[] = [];

0 commit comments

Comments
 (0)