feat(review): flag handles in the review player (metadata only)
Deploy / deploy (push) Successful in 3m31s

Renders run 8 frames past the cut at each end. Directors were flagging
glitches in unfixed handles as shot problems, so the player now marks
them — without trimming or burning anything into the EXRs/MOV/MP4.

- Version.handleHead/handleTail/pictureStartFrame, Export.handleHead/
  handleTail; migration backfills pipeline exports and their preview
  versions from the manifest's handleFrames (else 8)
- AE panel: "Includes handles [8] frames each end" -> manifest.review;
  older manifests fall back to source.handleFrames
- finalize copies handles onto the Version; worker 1.6.4 reports the
  head slate length (pictureStartSeconds), else the player infers it
  as MP4 frames - EXR frameCount
- Player: hatched HANDLE / SLATE regions and cut marks on the timeline,
  "HEAD/TAIL HANDLE · NOT IN EDIT" overlay on handle frames, HANDLE badge
  on notes, "Edit range only" toggle (default on in the client portal)
- Staff Handles editor on the review page for manual uploads/corrections

Also fixes two player bugs found while testing: timeToFrame floored
float error (every seek landed a frame early), and J/reverse never ran
(the keyboard effect's cleanup stopped it on the next render).

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
twotalesanimation
2026-09-22 15:07:29 +02:00
parent 2817c7e815
commit 2e9fa45580
27 changed files with 938 additions and 23 deletions
+110 -11
View File
@@ -15,10 +15,12 @@ import { AnnotationTools } from "@/components/annotations/AnnotationTools";
import { AspectOverlay } from "./AspectOverlay";
import { FrameTimeline } from "./FrameTimeline";
import { PlaybackControls } from "./PlaybackControls";
import { HandleOverlay } from "./HandleOverlay";
import { useZoomPan } from "@/hooks/use-zoom-pan";
import { Minus, Plus } from "lucide-react";
import { timeToFrame, frameToTime, durationToFrameCount } from "@/lib/frame-utils";
import { cn } from "@/lib/utils";
import { computeEditRange, frameRegion, type VersionHandles } from "@/lib/handles";
import type { CommentWithReplies } from "@/types";
export interface ReviewPlayerRef {
@@ -40,6 +42,10 @@ interface ReviewPlayerProps {
saveAnnotationFn?: (data: { versionId: string; frameNumber: number; drawingData: unknown; color: string }) => Promise<void>;
/** Override the default server action used to create the companion comment */
addCommentFn?: (data: { versionId: string; frameNumber: number; timestamp: number; text: string }) => Promise<void>;
/** The version's handle metadata — frames past the cut get flagged. */
handles?: VersionHandles | null;
/** Start with playback kept to the edit (the client portal's default). */
defaultEditRangeOnly?: boolean;
}
export const ReviewPlayer = forwardRef<ReviewPlayerRef, ReviewPlayerProps>(
@@ -55,6 +61,8 @@ export const ReviewPlayer = forwardRef<ReviewPlayerRef, ReviewPlayerProps>(
onAnnotationSaved,
saveAnnotationFn,
addCommentFn,
handles,
defaultEditRangeOnly = false,
},
ref
) {
@@ -66,6 +74,7 @@ export const ReviewPlayer = forwardRef<ReviewPlayerRef, ReviewPlayerProps>(
const stageRef = useRef<HTMLDivElement>(null);
const zoomLayerRef = useRef<HTMLDivElement>(null);
const reverseIntervalRef = useRef<ReturnType<typeof setInterval> | null>(null);
const openedAtCut = useRef(false);
const [isReversing, setIsReversing] = useState(false);
const {
@@ -81,8 +90,38 @@ export const ReviewPlayer = forwardRef<ReviewPlayerRef, ReviewPlayerProps>(
setDuration,
setFps,
setTotalFrames,
totalFrames,
editRange,
editRangeOnly,
setEditRange,
setEditRangeOnly,
} = useReviewStore();
// ── Handles ──────────────────────────────────────────────────────────────
// Where the cut sits in this media. Recomputed from primitives so a parent
// re-render with a fresh `handles` object does not churn the store.
const handleHead = handles?.handleHead ?? null;
const handleTail = handles?.handleTail ?? null;
const pictureStartFrame = handles?.pictureStartFrame ?? null;
const handleFrameCount = handles?.frameCount ?? null;
useEffect(() => {
setEditRange(
computeEditRange(
{ handleHead, handleTail, pictureStartFrame, frameCount: handleFrameCount },
totalFrames
)
);
}, [handleHead, handleTail, pictureStartFrame, handleFrameCount, totalFrames, setEditRange]);
useEffect(() => () => setEditRange(null), [setEditRange]);
useEffect(() => {
setEditRangeOnly(defaultEditRangeOnly);
}, [defaultEditRangeOnly, setEditRangeOnly]);
// Read inside event handlers / intervals without re-binding them.
const keepToEdit = useRef<{ range: typeof editRange; on: boolean }>({ range: null, on: false });
keepToEdit.current = { range: editRange, on: editRangeOnly && !!editRange };
const zoom = useZoomPan(stageRef, zoomLayerRef, {
gesturesEnabled: !isAnnotating,
});
@@ -102,6 +141,7 @@ export const ReviewPlayer = forwardRef<ReviewPlayerRef, ReviewPlayerProps>(
setDuration(0);
setTotalFrames(0);
resetZoom();
openedAtCut.current = false;
}, [videoUrl, setCurrentFrame, setCurrentTime, setDuration, setTotalFrames, resetZoom]);
// ── Playback state sync ──────────────────────────────────────────────────
@@ -121,6 +161,57 @@ export const ReviewPlayer = forwardRef<ReviewPlayerRef, ReviewPlayerProps>(
setTotalFrames(frames);
}, [fps, setDuration, setTotalFrames]);
/**
* Play — when keeping to the edit, from the cut in-point if the playhead
* is outside the cut (slate, a handle, or parked on the last cut frame).
*/
const startPlayback = useCallback(() => {
const video = videoRef.current;
if (!video) return;
const { range, on } = keepToEdit.current;
if (on && range) {
const frame = timeToFrame(video.currentTime, fps);
if (frame < range.cutIn || frame >= range.tailStart - 1) {
video.currentTime = frameToTime(range.cutIn, fps);
}
}
// A pause() or power-saving pause before playback starts rejects this;
// that's expected, not an error.
video.play().catch(() => {});
}, [fps]);
// Keeping to the edit: stop on the last frame of the cut rather than
// playing into the tail handle. Checked every animation frame — the
// video's own timeupdate only fires ~4x a second.
useEffect(() => {
if (!isPlaying || !editRangeOnly || !editRange) return;
const lastCutFrame = editRange.tailStart - 1;
let raf = 0;
const tick = () => {
const video = videoRef.current;
if (!video || video.paused) return;
if (timeToFrame(video.currentTime, fps) >= editRange.tailStart) {
video.pause();
video.currentTime = frameToTime(lastCutFrame, fps);
return;
}
raf = requestAnimationFrame(tick);
};
raf = requestAnimationFrame(tick);
return () => cancelAnimationFrame(raf);
}, [isPlaying, editRangeOnly, editRange, fps]);
// Keeping to the edit: open on the first frame of the cut rather than on
// the slate. Once per video, so it never moves the playhead afterwards.
useEffect(() => {
const video = videoRef.current;
if (!video || openedAtCut.current || !editRangeOnly || !editRange) return;
openedAtCut.current = true;
if (video.paused && timeToFrame(video.currentTime, fps) < editRange.cutIn) {
video.currentTime = frameToTime(editRange.cutIn, fps);
}
}, [editRange, editRangeOnly, fps]);
const handlePlay = useCallback(() => setPlaying(true), [setPlaying]);
const handlePause = useCallback(() => setPlaying(false), [setPlaying]);
@@ -132,7 +223,7 @@ export const ReviewPlayer = forwardRef<ReviewPlayerRef, ReviewPlayerProps>(
video.currentTime = frameToTime(frame, fps);
if (!video.paused) video.pause();
},
play: () => videoRef.current?.play(),
play: () => startPlayback(),
pause: () => videoRef.current?.pause(),
}));
@@ -163,11 +254,14 @@ export const ReviewPlayer = forwardRef<ReviewPlayerRef, ReviewPlayerProps>(
video.pause();
setIsReversing(true);
reverseIntervalRef.current = setInterval(() => {
if (!videoRef.current || videoRef.current.currentTime <= 0) {
// Keeping to the edit, reverse stops at the cut in-point.
const { range, on } = keepToEdit.current;
const floor = on && range ? frameToTime(range.cutIn, fps) : 0;
if (!videoRef.current || videoRef.current.currentTime <= floor) {
stopReverse();
return;
}
videoRef.current.currentTime = Math.max(0, videoRef.current.currentTime - 1 / fps);
videoRef.current.currentTime = Math.max(floor, videoRef.current.currentTime - 1 / fps);
}, 1000 / fps);
}, [fps, stopReverse]);
@@ -176,11 +270,11 @@ export const ReviewPlayer = forwardRef<ReviewPlayerRef, ReviewPlayerProps>(
if (!video) return;
stopReverse();
if (video.paused) {
video.play();
startPlayback();
} else {
video.pause();
}
}, [stopReverse]);
}, [stopReverse, startPlayback]);
// ── Keyboard shortcuts (JKL + arrows + space + F) ───────────────────────
useEffect(() => {
@@ -213,7 +307,7 @@ export const ReviewPlayer = forwardRef<ReviewPlayerRef, ReviewPlayerProps>(
case "l":
e.preventDefault();
stopReverse();
if (videoRef.current?.paused) videoRef.current.play();
if (videoRef.current?.paused) startPlayback();
break;
case "arrowleft":
e.preventDefault();
@@ -250,11 +344,13 @@ export const ReviewPlayer = forwardRef<ReviewPlayerRef, ReviewPlayerProps>(
};
window.addEventListener("keydown", handleKeyDown);
return () => {
window.removeEventListener("keydown", handleKeyDown);
stopReverse();
};
}, [isReversing, stepFrame, startReverse, stopReverse, togglePlayback, zoomBy, resetZoom]);
return () => window.removeEventListener("keydown", handleKeyDown);
}, [isReversing, stepFrame, startReverse, stopReverse, togglePlayback, startPlayback, zoomBy, resetZoom]);
// Stop a running reverse only on unmount. This used to live in the
// cleanup above, which re-runs whenever isReversing changes — so starting
// reverse immediately stopped it, and J never did anything.
useEffect(() => stopReverse, [stopReverse]);
// ── Fullscreen ───────────────────────────────────────────────────────────
const toggleFullscreen = () => {
@@ -350,6 +446,9 @@ export const ReviewPlayer = forwardRef<ReviewPlayerRef, ReviewPlayerProps>(
/>
</div>
{/* Handle flag — drawn over the player, never into the media */}
<HandleOverlay region={frameRegion(editRange, currentFrame)} />
{/* Zoom badge — only while zoomed */}
{zoom.zoomed && (
<div