feat(player): aspect-ratio blanking overlay in the review player
Deploy / deploy (push) Successful in 5m39s

A shot is reviewed at the framing it was rendered at but usually delivered
cropped, so add a dropdown beside the playback-speed control that lays
delivery blanking over the video: 2.39 through 9:16, widest to tallest, with
"No blanking" as the default. Purely a viewing aid — nothing is written to
the review, and the video element is untouched.

The geometry is the awkward part. The video is object-contain, so the picture
is letterboxed inside the element and bars drawn against the element's edges
would be wrong on any panel whose shape does not match the source.
letterboxRect works out where the picture is actually painted and the bars are
positioned against that, kept current by a ResizeObserver and a loadedmetadata
listener so resizes and fullscreen stay correct. Ratios within half a pixel of
the source draw nothing rather than a hairline of rounding error.

Two modes, since blanking and crop bars are different jobs: solid black hides
the crop the way the master will, guide dims it so the excluded area is still
readable. The overlay sits under the annotation canvas — deliberately no
z-index, since the canvas sets none either and DOM order alone gives marks
drawn over a blanked area the right precedence.

Verified against real browser layout, not just unit tests: the computed
picture rect lands exactly on the image edges across three panel shapes, and
the visible area measures the requested ratio.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
twotalesanimation
2026-09-02 07:21:58 +02:00
parent 269a5cbfda
commit 75f9258b69
6 changed files with 445 additions and 1 deletions
+131
View File
@@ -0,0 +1,131 @@
"use client";
import { useEffect, useState, type RefObject } from "react";
import {
blankingInsets,
findAspectPreset,
isFullFrame,
letterboxRect,
type BlankingMode,
} from "@/lib/aspect-overlays";
interface AspectOverlayProps {
/** Preset id, or "off" — anything unknown draws nothing. */
presetId: string;
mode: BlankingMode;
videoRef: RefObject<HTMLVideoElement | null>;
}
/**
* Delivery blanking drawn over the video. Purely visual: it never touches the
* video element, sits under the annotation canvas, and passes every pointer
* event through so click-to-play still works underneath it.
*/
export function AspectOverlay({ presetId, mode, videoRef }: AspectOverlayProps) {
const preset = findAspectPreset(presetId);
const [box, setBox] = useState<{
top: number;
bottom: number;
left: number;
right: number;
rect: { left: number; top: number; width: number; height: number };
} | null>(null);
useEffect(() => {
const video = videoRef.current;
if (!video || !preset) {
setBox(null);
return;
}
const measure = () => {
const rect = letterboxRect(
video.clientWidth,
video.clientHeight,
video.videoWidth,
video.videoHeight
);
// Before metadata lands videoWidth is 0 and there is nothing to measure.
if (!rect) {
setBox(null);
return;
}
const insets = blankingInsets(rect, preset.ratio);
setBox(isFullFrame(insets) ? null : { ...insets, rect });
};
measure();
// The picture rect moves on layout changes (panel resize, fullscreen) and
// on metadata, which is when intrinsic dimensions first exist.
const observer = new ResizeObserver(measure);
observer.observe(video);
video.addEventListener("loadedmetadata", measure);
return () => {
observer.disconnect();
video.removeEventListener("loadedmetadata", measure);
};
}, [preset, videoRef]);
if (!preset || !box) return null;
const { rect } = box;
const barClass =
mode === "solid"
? "absolute bg-black"
: "absolute bg-black/60 ring-1 ring-inset ring-white/25";
// Each bar is positioned against the picture rect, not the element box, so
// blanking lands on the image itself whatever shape the player is.
const horizontal = box.top > 0;
return (
// No z-index: the annotation canvas is also absolutely positioned and comes
// later in the DOM, so it stays on top and marks drawn over a blanked area
// remain visible.
<div
className="pointer-events-none absolute inset-0"
aria-hidden="true"
data-testid="aspect-overlay"
>
{horizontal ? (
<>
<div
className={barClass}
style={{ left: rect.left, top: rect.top, width: rect.width, height: box.top }}
/>
<div
className={barClass}
style={{
left: rect.left,
top: rect.top + rect.height - box.bottom,
width: rect.width,
height: box.bottom,
}}
/>
</>
) : (
<>
<div
className={barClass}
style={{ left: rect.left, top: rect.top, width: box.left, height: rect.height }}
/>
<div
className={barClass}
style={{
left: rect.left + rect.width - box.right,
top: rect.top,
width: box.right,
height: rect.height,
}}
/>
</>
)}
<div className="absolute bottom-3 right-3 rounded bg-black/70 px-2 py-1 font-mono text-[11px] text-zinc-300">
{preset.label}
</div>
</div>
);
}
+67 -1
View File
@@ -13,6 +13,7 @@ import {
Pencil,
Eye,
EyeOff,
RectangleHorizontal,
} from "lucide-react";
import { Button } from "@/components/ui/button";
import {
@@ -20,9 +21,17 @@ import {
TooltipContent,
TooltipTrigger,
} from "@/components/ui/tooltip";
import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from "@/components/ui/select";
import {
Select,
SelectContent,
SelectItem,
SelectSeparator,
SelectTrigger,
SelectValue,
} from "@/components/ui/select";
import { useReviewStore } from "@/hooks/use-review-player";
import { frameToTimecode } from "@/lib/frame-utils";
import { ASPECT_OFF, ASPECT_PRESETS } from "@/lib/aspect-overlays";
import { cn } from "@/lib/utils";
const PLAYBACK_RATES = [0.25, 0.5, 0.75, 1, 1.25, 1.5, 2];
@@ -58,9 +67,13 @@ export function PlaybackControls({
playbackRate,
isAnnotating,
showAnnotations,
aspectPresetId,
blankingMode,
setPlaybackRate,
setAnnotating,
setShowAnnotations,
setAspectPresetId,
setBlankingMode,
} = useReviewStore();
const handleRateChange = (val: string) => {
@@ -69,6 +82,8 @@ export function PlaybackControls({
setPlaybackRate(rate);
};
const blankingOn = aspectPresetId !== ASPECT_OFF;
const timecode = frameToTimecode(currentFrame, fps);
return (
@@ -216,6 +231,57 @@ export function PlaybackControls({
</Select>
</div>
{/* Delivery blanking — hidden on mobile */}
<div className="hidden sm:contents">
<Select value={aspectPresetId} onValueChange={setAspectPresetId}>
<SelectTrigger
className={cn(
"h-7 w-24 text-xs border-0 bg-white/5 px-2",
blankingOn ? "text-amber-400" : "text-zinc-300"
)}
>
<SelectValue />
</SelectTrigger>
<SelectContent>
<SelectItem value={ASPECT_OFF} className="text-xs">
No blanking
</SelectItem>
<SelectSeparator />
{ASPECT_PRESETS.map((p) => (
<SelectItem key={p.id} value={p.id} className="text-xs">
<span className="font-mono">{p.label}</span>
<span className="ml-2 text-zinc-500">{p.note}</span>
</SelectItem>
))}
</SelectContent>
</Select>
{blankingOn && (
<Tooltip>
<TooltipTrigger asChild>
<Button
variant="ghost"
size="icon-sm"
className={cn(
"text-zinc-400 hover:text-white",
blankingMode === "guide" && "text-amber-400 bg-amber-400/10"
)}
onClick={() =>
setBlankingMode(blankingMode === "solid" ? "guide" : "solid")
}
>
<RectangleHorizontal className="h-4 w-4" />
</Button>
</TooltipTrigger>
<TooltipContent>
{blankingMode === "solid"
? "Dim the crop instead of hiding it"
: "Hide the crop behind solid bars"}
</TooltipContent>
</Tooltip>
)}
</div>
{/* Annotation toggle */}
<Tooltip>
<TooltipTrigger asChild>
+11
View File
@@ -12,6 +12,7 @@ import {
import { useReviewStore } from "@/hooks/use-review-player";
import { AnnotationCanvas } from "@/components/annotations/AnnotationCanvas";
import { AnnotationTools } from "@/components/annotations/AnnotationTools";
import { AspectOverlay } from "./AspectOverlay";
import { FrameTimeline } from "./FrameTimeline";
import { PlaybackControls } from "./PlaybackControls";
import { timeToFrame, frameToTime, durationToFrameCount } from "@/lib/frame-utils";
@@ -68,6 +69,8 @@ export const ReviewPlayer = forwardRef<ReviewPlayerRef, ReviewPlayerProps>(
currentFrame,
isAnnotating,
showAnnotations,
aspectPresetId,
blankingMode,
setPlaying,
setCurrentFrame,
setCurrentTime,
@@ -283,6 +286,14 @@ export const ReviewPlayer = forwardRef<ReviewPlayerRef, ReviewPlayerProps>(
playsInline
/>
{/* Delivery blanking — under the annotation canvas, so a reviewer
can still draw over a blanked area if they need to */}
<AspectOverlay
presetId={aspectPresetId}
mode={blankingMode}
videoRef={videoRef}
/>
{/* Annotation canvas overlay */}
<AnnotationCanvas
versionId={versionId}