Callout Positioning

Debug grids and coordinate systems for accurate arrow/annotation placement in Remotion video compositions. Essential for precise callout placement across different resolutions and aspect ratios.

Overview

• Positioning callouts, arrows, and annotations in video compositions

• Debugging coordinate misalignment in Remotion renders

• Calibrating element positions using screenshot-based workflow

• Creating responsive annotations for multi-resolution exports

• Building reusable callout components with precise positioning

Quick Start

// 1. Enable debug grid during development import { DebugGrid } from './components/DebugGrid';

<AbsoluteFill> <YourScene /> <DebugGrid enabled={process.env.NODE_ENV === 'development'} /> </AbsoluteFill>

// 2. Position callouts using grid coordinates <Callout x={960} // Center horizontal (1920/2) y={540} // Center vertical (1080/2) type="pointer" label="Click here" />

Coordinate Systems

1920x1080 (Horizontal/Landscape)

Standard YouTube/Twitter format. Origin at top-left.

Region X Range Y Range Description

Top-Left 0-640 0-360 Logo/watermark

Top-Center 640-1280 0-360 Titles

Top-Right 1280-1920 0-360 Controls/badges

Center 640-1280 360-720 Main content

Bottom 0-1920 720-1080 CTAs/captions

1080x1920 (Vertical/Portrait)

TikTok/Reels/Shorts format. Origin at top-left.

Region X Range Y Range Description

Safe-Top 0-1080 200-400 Below platform UI

Center 0-1080 640-1280 Main content

Safe-Bottom 0-1080 1520-1720 Above controls

1080x1080 (Square)

Instagram/LinkedIn format.

Region X Range Y Range Description

Center 270-810 270-810 Safe content zone

Margins 0-270 0-1080 Decorative only

Debug Grid Component

Enable during development to visualize coordinates.

import { DebugGrid } from './components/DebugGrid';

// In your composition <AbsoluteFill> <YourSceneContent />

{/* Toggle with prop or env var */} <DebugGrid enabled={showDebug} gridSize={100} // Grid cell size in pixels showCoordinates // Show X,Y at cursor position showRulers // Show pixel rulers on edges highlightCenter // Crosshair at center opacity={0.5} /> </AbsoluteFill>

See: references/debug-grid-component.md for full component implementation.

Callout Types

1. Pointer Callout

Arrow pointing to a specific location with label.

<PointerCallout targetX={400} targetY={300} labelX={600} labelY={200} label="Important feature" arrowColor="#8b5cf6" animate // Fade in with arrow draw />

2. Bracket Callout

Brackets around a region to highlight an area.

<BracketCallout x={300} y={200} width={400} height={150} label="This section" position="right" // Label position: top, right, bottom, left bracketColor="#22c55e" />

3. Highlight Callout

Colored overlay to emphasize a region.

<HighlightCallout x={500} y={400} width={200} height={100} color="rgba(139, 92, 246, 0.3)" pulse // Pulsing animation />

4. Number Badge

Numbered circle for step-by-step annotations.

<NumberBadge number={1} x={300} y={250} size={40} color="#f59e0b" />

Calibration Workflow

Step 1: Enable Debug Grid

// In your composition root const showDebug = true; // Toggle manually or via env

<DebugGrid enabled={showDebug} showCoordinates showRulers />

Step 2: Take Screenshot

Render single frame with debug grid

npx remotion still MyComposition --frame=30 --output=debug-frame.png

Step 3: Measure Coordinates

Open screenshot in image editor. Note pixel coordinates of target elements.

Step 4: Apply Coordinates

// Use measured coordinates <PointerCallout targetX={847} // Measured from screenshot targetY={312} // Measured from screenshot labelX={1000} labelY={200} label="Feature name" />

Step 5: Verify and Iterate

Re-render and compare. Adjust as needed.

See: references/calibration-workflow.md for detailed step-by-step guide.

Responsive Positioning

Scale-Based Positioning

function ResponsiveCallout({ baseWidth = 1920, baseHeight = 1080, x, y, ...props }) { const { width, height } = useVideoConfig();

// Scale coordinates proportionally const scaledX = (x / baseWidth) * width; const scaledY = (y / baseHeight) * height;

return <Callout x={scaledX} y={scaledY} {...props} />; }

Anchor-Based Positioning

// Position relative to anchors type Anchor = 'top-left' | 'top-center' | 'top-right' | 'center-left' | 'center' | 'center-right' | 'bottom-left' | 'bottom-center' | 'bottom-right';

function AnchoredCallout({ anchor, offsetX = 0, offsetY = 0, ...props }) { const { width, height } = useVideoConfig();

const anchors = { 'top-left': { x: 0, y: 0 }, 'center': { x: width / 2, y: height / 2 }, 'bottom-right': { x: width, y: height }, // ... other anchors };

const base = anchors[anchor]; return <Callout x={base.x + offsetX} y={base.y + offsetY} {...props} />; }

Format-Specific Presets

// Presets for common positions per format const CALLOUT_PRESETS = { '1920x1080': { title: { x: 960, y: 100 }, centerContent: { x: 960, y: 540 }, bottomCTA: { x: 960, y: 950 }, topRightBadge: { x: 1800, y: 100 }, }, '1080x1920': { title: { x: 540, y: 300 }, centerContent: { x: 540, y: 960 }, bottomCTA: { x: 540, y: 1700 }, }, '1080x1080': { title: { x: 540, y: 150 }, centerContent: { x: 540, y: 540 }, bottomCTA: { x: 540, y: 930 }, }, };

function useCalloutPreset(position: string) { const { width, height } = useVideoConfig(); const format = ${width}x${height}; return CALLOUT_PRESETS[format]?.[position] ?? { x: width/2, y: height/2 }; }

Arrow Styling

Arrow Variants

// Solid arrow <Arrow fromX={100} fromY={100} toX={300} toY={200} strokeColor="#8b5cf6" strokeWidth={3} headSize={12} />

// Curved arrow <CurvedArrow fromX={100} fromY={100} toX={300} toY={200} curve={0.3} // Curve amount (0 = straight, 1 = max curve) strokeColor="#22c55e" />

// Dashed arrow <Arrow fromX={100} fromY={100} toX={300} toY={200} strokeDasharray="5,5" strokeColor="#f59e0b" />

Animated Arrows

<AnimatedArrow fromX={100} fromY={100} toX={300} toY={200} startFrame={30} drawDuration={15} // Frames to draw arrow strokeColor="#8b5cf6" />

Best Practices

1. Use Debug Grid During Development

Always enable debug grid when positioning callouts. Disable for final renders.

const DEBUG = process.env.DEBUG_GRID === 'true'; <DebugGrid enabled={DEBUG} />

2. Document Coordinates

Comment coordinates with context.

<Callout x={847} // Terminal window top-left corner y={312} // First line of output label="Result" />

3. Test All Formats

Verify callout positions in all target formats before finalizing.

Render test frames for each format

npx remotion still MyComposition-Horizontal --frame=60 --output=test-h.png npx remotion still MyComposition-Vertical --frame=60 --output=test-v.png npx remotion still MyComposition-Square --frame=60 --output=test-s.png

4. Use Relative Positioning When Possible

Prefer anchor-based or percentage positioning over hardcoded pixels for reusability.

5. Layer Callouts Properly

Ensure callouts appear above content but below UI overlays.

Layer order (top to bottom):

1. UI Overlays (watermark, progress)
2. Callouts/Annotations
3. Main Content
4. Background

Common Pitfalls

Pitfall Problem Solution

Hardcoded coordinates Breaks on format change Use responsive positioning

No debug grid Guessing coordinates Enable DebugGrid during dev

Wrong layer order Callouts hidden Check z-index/layer stack

Missing safe zones Content cut off on mobile Use safe zone margins

No calibration Misaligned annotations Follow calibration workflow

References

• references/debug-grid-component.md

• Full React/Remotion debug grid component

• references/coordinate-systems.md

• Grid systems for different resolutions

• references/calibration-workflow.md

• Step-by-step positioning workflow

Related Skills

• remotion-composer

• Core Remotion composition patterns

• video-storyboarding

• Scene planning and structure

• video-pacing

• Timing and rhythm for animations

Key Decisions

Decision Choice Rationale

Coordinate origin Top-left (0,0) Standard screen coordinate convention

Debug grid default Disabled Performance in production

Position units Pixels Direct mapping to render resolution

Responsive method Scale-based Works across all formats consistently

Skill Version: 1.0.0 Last Updated: 2026-01-25

Capability Details

debug-grid

Keywords: debug, grid, overlay, coordinates, ruler, measurement Solves:

• How do I see coordinates in my Remotion composition?

• Debug grid for video positioning

• Visualize pixel coordinates during development

callout-placement

Keywords: callout, annotation, arrow, pointer, label, highlight Solves:

• How do I add callouts to my video?

• Position arrows and labels in Remotion

• Annotate video content with pointers

coordinate-calibration

Keywords: calibrate, measure, screenshot, position, align Solves:

• How do I find exact coordinates for elements?

• Screenshot-based coordinate calibration

• Measure pixel positions in video frames

responsive-positioning

Keywords: responsive, scale, anchor, format, resolution Solves:

• How do I make callouts work across formats?

• Responsive positioning for 1080p and 4K

• Anchor-based positioning in Remotion