Home Hardware Quick Start Settings Troubleshooting

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:

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

See Also