# Troubleshooting

## Startup Issues

Problem | Cause | Solution
--- | --- | ---
Program deleted on launch | Antivirus (Norton, etc.) flags unsigned executables | Add the `bin\` directory to your antivirus exclusion list. Rebuild after exclusion is set.
"SDL3.dll not found" | SDL3 DLL not in same directory as viewer/fileviewer | Copy `SDL3.dll` to the `bin\` directory next to the executables.
"Failed to create shared memory" | Insufficient memory or permissions | The system needs ~16GB RAM. Close other applications. Run as Administrator if needed.
"Failed to open shared memory" | No process has created the shared memory yet | Start the first process (capture or fileplayer) which creates shared memory, then start other processes.
Controller window appears but buttons don't work | Cannot find sibling executables | Ensure all .exe files are in the same directory as controller.exe.

## Video Capture

Problem | Cause | Solution
--- | --- | ---
No devices found | USB capture device not recognized | Check Device Manager for the capture device. Try a different USB 3.0 port. Install device drivers if needed.
Frames dropping / stuttering | USB bandwidth saturation | Each 1080p60 uncompressed feed needs its own USB 3.0 controller. Don't share a USB hub between feeds.
Wrong resolution or format | Device not set to 1080p60 YUV | Verify the HDMI source outputs 1920x1080 at 60Hz. Check capture device supports YUV422.
Green or corrupted frames | YUV format mismatch | Ensure the capture device is sending YUY2/UYVY (YUV422). Some devices default to NV12 or MJPEG.

## Motion Detection

Problem | Cause | Solution
--- | --- | ---
No motion detected | Detection disabled or region misconfigured | Check `feed_motion_on[N]=1`. Verify motion region covers the landing hill. Try `debug_motion=1`.
Constant false triggers | Thresholds too sensitive | Narrow the motion region. Increase `min_blob_sizes`. Lower `max_diff_y%`. See Motion Tuning.
Motion triggers but no video recorded | videogen not running or not receiving signals | Start videogen. Check that motion processes are writing to shared memory (use `debug_motion=1`).
Clips too short | No-motion threshold too low | Increase `min_nomotion_count` (e.g., 15 or 20). Increase `movie_pad`.

## Video Generation / Encoding

Problem | Cause | Solution
--- | --- | ---
"FFmpeg not found" | FFmpeg not installed or not at expected path | Install FFmpeg to `C:\ffmpeg\` or place `ffmpeg.exe` in the same directory as videogen.exe.
NVENC encoding fails | No NVIDIA GPU or outdated drivers | Install latest NVIDIA drivers. The system falls back to libx264 (software) if NVENC is unavailable.
Output video is black | Feed merge reading wrong frames | Verify feeds are running and writing frames. Check `feed_offset` values.
Upload fails | Upload script error or network issue | Test the upload script manually. Check network connectivity.

## Viewer

Problem | Cause | Solution
--- | --- | ---
Black window | No frames in output buffer | Ensure capture (or fileplayer) and videogen are running. The viewer reads from the output buffer, not directly from feeds.
Tearing or flickering | Concurrent writes to shared memory | The viewer copies frames to a local buffer before rendering. If tearing persists, check that only one videogen instance is running.
Grid lines misaligned | Anchor points not calibrated | Calibrate grid lines. See Grid Line Calibration.
Distance readout says "---" | Cursor outside grid line coverage | Move cursor to an area between two configured grid lines. Add more anchor points if needed.
Window won't resize | SDL3 renderer issue | Check SDL3.dll version matches the build. Try setting `big_window_width/height` in settings.

## File Playback

Problem | Cause | Solution
--- | --- | ---
File player exits immediately | File not found or unsupported format | Verify the file path. Convert to H.264 MP4: `ffmpeg -i input.avi -c:v libx264 output.mp4`
Feeds out of sync | Frame offsets not calibrated | Find a common event in all feeds and calculate frame offsets. See Testing with Video Files.
Playback too fast/slow | File frame rate differs from 60fps | The file player writes at 60fps. Source files at different frame rates will play at altered speed.

## Shared Memory

Problem | Cause | Solution
--- | --- | ---
"Access denied" on shared memory | Different user accounts or integrity levels | Run all processes under the same user account. If using the controller, it launches child processes which inherit its permissions.
Stale shared memory after crash | Named mapping persists until all handles close | Close all VideoDistanceMarking processes and restart. Windows cleans up named objects when the last handle closes.
Out of memory | System has less than 16GB RAM | The full system with 3 feeds needs ~16GB for shared memory. Close other applications or reduce to fewer feeds.

## Performance

Problem | Cause | Solution
--- | --- | ---
Periodic freezes | Memory allocation during frame processing | This should not occur with the standard build. If using modified code, ensure no malloc/free calls in frame processing loops.
High CPU usage | Software encoding or motion detection | Use NVENC hardware encoding. Narrow motion regions to reduce detection workload.
Slow viewer response | Large window or slow GPU | Reduce `big_window_width/height`. Ensure GPU drivers are up to date.

## Getting Help

If the troubleshooting steps above don't resolve your issue:

1. Enable debug output (`debug_motion=1`, `debug_distance=1`, `debug_build=1`)
2. Capture the console output from the failing program
3. Note your hardware configuration (GPU, RAM, USB devices)
4. Note the exact error message and when it occurs

## See Also

- Motion Detection Tuning
- Settings Reference
- Testing with Video Files
- Hardware Setup