facecam-visual
Live visual diagnostic tool with broadcast-grade analysis overlays.
Usage
facecam-visual [--device /dev/video0] [--resolution 720] [--fps 30] [--mjpeg]
Window Layout
+---------------------------------------+
| LIVE CAMERA FEED |
| [30 FPS] [ZEBRA] |
| [FOCUS] |
| [ A/B ] |
+=======================================+
| WAVEFORM MONITOR | RGB HISTOGRAM |
+---------------------------------------+
| 30.0fps 33.3ms Brt:128 Con:5 ... |
+---------------------------------------+
| Frame Timing Waterfall |
+---------------------------------------+
Keyboard Controls
Camera Controls
| Key | Action |
|---|---|
| + / - | Brightness up/down (step 10) |
| [ / ] | Contrast up/down (step 1) |
| Z / X | Zoom in/out (step 1) |
Diagnostic Overlays
| Key | Feature | Description |
|---|---|---|
| W | Zebra stripes | Red diagonal hatching on pixels with luma > 235 (overexposure) |
| E | Focus peaking | Magenta dots on sharp edges (Sobel edge detection) |
| A | A/B capture | Freezes current frame as reference (left side) |
| D | A/B clear | Removes the reference frame |
| < / > | A/B split | Moves the comparison split line |
General
| Key | Action |
|---|---|
| S | Save snapshot (PPM format with overlays) |
| R | Force USB reset |
| Space | Pause/unpause |
| F | Toggle help text |
| Q / Esc | Quit |
Analysis Features
Waveform Monitor (bottom-left)
Plots luma distribution per video column. Standard broadcast tool for checking exposure:
- Green = safe range (16-235 IRE)
- Yellow = hot highlights (>200)
- Red = clipping (>235)
- Blue = crushed blacks (<16)
- Dashed reference lines at 0 IRE and 100 IRE
RGB Histogram (bottom-right)
Per-channel pixel value distribution with additive blending:
- Red, green, blue curves overlaid
- Left-edge blue bar = crushed blacks (>2% of pixels at 0)
- Right-edge red bar = blown highlights (>2% of pixels at 255)
Frame Timing Waterfall (bottom strip)
Scrolling timeline where each column = one frame:
- Green = delivered on time (<110% of target)
- Yellow = late (110-150% of target)
- Orange = very late (150-200%)
- Red = severely delayed or dropped (>200%)
- Dashed reference line at target frame time
Zebra Stripes
Industry-standard overexposure indicator. Red diagonal hatching overlaid on any pixel where luma exceeds 235. The pattern animates to distinguish it from image content.
Focus Peaking
Sobel edge detection with configurable sensitivity. Magenta dots mark sharp edges in the image. Since the Facecam has fixed focus, this helps verify subject distance is in the lens sweet spot.
A/B Comparison
Capture a reference frame with A, then adjust controls. The window splits: left = reference, right = live. Move the split with </>. Clear with D.
Session Summary
On exit, prints aggregate statistics:
Session summary:
Total frames: 1847
Dropped: 0
Avg FPS: 30.0
Avg frame: 33.3ms
Jitter: 0.42ms
Uptime: 61.6s