Documentation
MetricsOverlay
Create professional workout videos with real-time data overlays. Everything runs in your browser.
Getting Started
QUICK START
MetricsOverlay combines video footage with fitness device data. The workflow is simple:
- 1. Upload your video file
- 2. Import your FIT file from Garmin, COROS, or similar
- 3. Sync timestamps between video and FIT data
- 4. Add and position data overlays
- 5. Export to ProRes or PNG sequence
UPLOADING VIDEOS
Drag and drop or click to browse. Supports MP4, MOV, and WebM. Frame rate is automatically detected from 23.976 to 240fps.
Tip: For best results, use 30fps or 60fps source footage. The detected frame rate appears in the clip info panel.
FIT FILES
FIT files contain timestamped activity data. Click "Import FIT" in the sidebar and select your .fit file. Export FIT files from Garmin Connect, COROS app, Strava, or directly from your device.
Video Clips
SUPPORTED FORMATS
Recommended
- MP4 (H.264)
- MOV (H.264/HEVC)
- WebM (VP9)
Also Supported
- MKV
- AVI
- OGV
FRAME RATE DETECTION
Frame rate is detected using the browser's video frame callback API. Exports match your source exactly. Supported rates: 23.976, 24, 25, 29.97, 30, 50, 59.94, 60, 120, 240 fps.
Note: Detection requires brief video playback. Defaults to 30fps if detection fails.
TIMING & SYNCHRONIZATION
Clip start time determines which FIT data appears at each video frame. MetricsOverlay reads creation timestamps from video metadata when available.
Status badges show sync state:
FIT Data
OVERVIEW
FIT (Flexible and Interoperable Data Transfer) is a binary format developed by Garmin for fitness data. Contains timestamped records with GPS, heart rate, power, cadence, speed, altitude — typically sampled every second.
DATA FIELDS
Speed
km/h or mph
Heart Rate
BPM
Power
Watts
Cadence
RPM / SPM
Altitude
m or ft
Grade
Incline %
Distance
Cumulative
Time
Elapsed / Clock
GPS Map
Route + position
Elevation Graph
Profile chart
HR Graph
HR over time
Temperature
Ambient
TIMESTAMP MATCHING
For each video frame, the system calculates: clipStartTime + videoPosition + offset
It finds the two nearest FIT records and interpolates values for smooth transitions. If outside the activity time range, nearest edge values are used.
Overlays
TYPES
- Data Overlays — Speed, heart rate, power, cadence, altitude, grade, distance, time, temperature
- Map — GPS route with current position marker and customizable zoom
- Elevation Graph — Altitude profile with progress indicator
- Heart Rate Graph — HR over time with progress indicator
- Container — Background panel for grouping overlays
CUSTOMIZATION
- Position — Drag overlays anywhere on the preview
- Size — Adjust scale with the size slider
- Font — Choose from available font families
- Color — Pick any color or use smart colors
- Style — Minimal, badge, pill, or graph styles
- Opacity — Adjust transparency
SMART COLORS
Colors adjust automatically based on current value:
- Heart Rate Zones — Gray → Green → Yellow → Orange → Red
- Power Zones — Based on FTP percentage
- Speed — Intensity reflects current speed
PRESETS
Save and reuse overlay configurations. Built-in presets for cycling, running, minimal layouts. Export as .fitoverlay files to share.
Export
MODES
Recommended: PNG Sequence
For best quality and flexibility, export as PNG sequence and composite in your video editor. This gives you full control over layering, timing adjustments, and color grading without re-exporting.
Overlays Only (PNG Sequence) — Recommended
Transparent PNG frames. Import into DaVinci Resolve, Premiere, Final Cut for full compositing control.
Video with Overlays (ProRes)
ProRes MOV with video and overlays composited. Direct upload to social media or simple workflows.
VIDEO EXPORT
Uses ProRes encoding via FFmpeg.wasm in browser. ProRes 422 or ProRes 4444 (with alpha). Batched encoding handles long videos. No server upload — all processing is local.
PNG SEQUENCE (RECOMMENDED)
Creates a ZIP containing one PNG per frame with full transparency. This is the recommended export method because it gives you complete control in your editing software.
Why PNG Sequence is better:
- • No quality loss — Overlays stay crisp, no re-encoding artifacts
- • Full flexibility — Adjust overlay timing, opacity, or position without re-exporting
- • Color grading — Grade your video after adding overlays
- • Multi-clip edits — Export once, use across multiple clips in your timeline
Workflow:
- 1. Export PNG sequence from MetricsOverlay
- 2. Unzip the folder
- 3. Import as image sequence in your editor (DaVinci Resolve, Premiere, Final Cut)
- 4. Set the frame rate to match your source video
- 5. Place on a track above your video — transparency is automatic
Output: frame_00001.png, frame_00002.png, ... (32-bit RGBA)
RESOLUTION & FRAME RATE
Exports match source video — resolution (up to 4K), frame rate (auto-detected), and aspect ratio are preserved.
Troubleshooting
SYNCING VIDEO WITH FIT
- Use file metadata — If camera records timestamps, "From file" time aligns automatically
- Find a reference point — Distinctive moment visible in both video and data
- Use preview — Scrub through video watching data overlays to verify sync
- Fine-tune seconds — Adjust seconds field for precise alignment
PERFORMANCE
- Use Chrome or Edge — Best WebCodecs and FFmpeg.wasm support
- Close other tabs — Encoding is memory-intensive
- Use shorter clips — Split long recordings if needed
- Check memory — 8GB+ RAM recommended for 4K
COMMON ISSUES
Overlays show dashes / no data
Video timestamp outside FIT activity range. Adjust clip start time.
Export fails or freezes
Insufficient memory. Close tabs, export shorter clip, or use Chrome instead of Safari.
Wrong frame rate detected
Reload page and re-upload video. Detection requires playback.
Video won't upload
Check format (MP4, MOV, WebM). Large files (>2GB) need time to process.