The HansensThe Hansens

Troubleshooting

Symptom, cause, fix. Start with the triage section — three checks narrow almost any problem to one component before you start reading tables.

Triage: three checks first

  1. The title bar. Is cap[…] advancing? If not, capture is the problem. Is cap advancing but m[…] not? Motion is the problem. Both advancing but out[…] static? Videogen. Is Δ[0] climbing without bound? USB bandwidth.
  2. The Processes tab. Are all six of capture[0..2] and motion[0..2] Running with stable PIDs? A climbing restart count means a process is dying and being relaunched — almost always antivirus.
  3. The logs. Enable Log On in the Preview tab, reproduce the problem, then read the relevant *_debug*.log in the install directory. motion_debug_1.log is usually the most informative, since feed 1 is the trigger camera.

Two commands worth knowing

captest.exe --list checks the cameras independently of VDM entirely — it reads no settings and touches no shared memory. If captest sees three devices and VDM does not, the problem is VDM's configuration, not Windows or the hardware.

Verify-Install.ps1 re-checks the whole installation: executables, DLLs, a dependency load probe, data files, and whether settings.txt parses. Run it before debugging anything deeper.

Startup and missing DLLs

SymptomLikely causeFix
VDM.exe does nothing when double-clicked, or shows VCRUNTIME140.dll not found, or exits with code 0xc0000135 The Visual C++ 2015–2022 Redistributable (x64) is not installed. winget install --id Microsoft.VCRedist.2015+.x64, then retry. See Prerequisites.
viewer.exe or fileviewer.exe crashes at startup with SDL3.dll was not found SDL3.dll is missing from the install directory. Copy SDL3.dll into the install directory alongside the executables. Re-running the installer restores the full DLL set.
The code execution cannot proceed because XYZ.dll was not found The runtime DLL set is incomplete. Run Verify-Install.ps1, which existence-checks all 12 runtime DLLs and load-probes each one. Copy in whatever it reports missing, or re-run the installer.
A DLL is present but loading still fails, sometimes with a missing-export or ordinal error Mixed FFmpeg generations — for example avcodec-61.dll beside a leftover avutil-58.dll. Delete every av*.dll, sw*.dll and postproc*.dll from the install directory and re-run the installer so a single consistent set is written. The LoadLibraryEx probe in Verify-Install.ps1 catches this case specifically.
The controller window opens but its buttons do nothing The sibling executables cannot be found. Every .exe must be in the same directory as VDM.exe. Confirm the install is flat — there should be no app\ or config\ subdirectory inside C:\VDM\.
Overlays (jumper number, name, distance) do not render on encoded clips numbers.txt is missing from the working directory. The filename is hardcoded in every consumer, so this is the only cause. Confirm numbers.txt sits beside the executables; re-run the installer, or run Verify-Install.ps1, which checks for it. Do not attempt to fix this by editing *font_file — that key is vestigial and is read by nothing. See Configuration.

Antivirus interference

Suspect antivirus early, not late

These failures do not look like antivirus failures. Two of them present as ordinary bugs and have each cost hours. If capture is behaving strangely and you have not confirmed the exclusion is in place, confirm it before investigating anything else.

SymptomLikely causeFix
Processes tab shows capture[0..2] as Stopped with exit code 0xc0000005. Executables disappear from disk after extraction. Norton real-time scanning flagged the unsigned capture.exe and deleted it. The process could not find its own image. Add the install folder to the antivirus exclusions, restore the quarantined files, then re-run the installer. Full steps in Installation § antivirus exclusion.
capture[N] cycles Running ↔ Stopped repeatedly, with a climbing restart count. Norton SONAR is killing capture.exe shortly after each launch, and the controller keeps restarting it. Re-check that the exclusion covers the install folder, restart Norton, then restart the laptop. SONAR caches the old exclusion list until reboot.
capture[N] shows Running with a healthy PID, but Δ[0] stays at 0 and no preview ever appears. Nothing is logged as an error. SONAR is blocking Media Foundation's IMFActivate::ActivateObject call on the USB device without killing the process. The silent failure mode. Same fix — verify the exclusion, restart Norton, reboot. Confirm the diagnosis by opening capture_debug_N.log and looking for an opening device entry that never advances.
An exclusion was added to Norton but the problem persists. Defender's real-time protection is also active. Some Norton installations leave it enabled as a fallback. Add the same folder exclusion in Windows Defender as well. A folder excluded only in Norton can still be deleted by Defender.

Cameras not detected, and USB bandwidth

SymptomLikely causeFix
captest.exe --list shows 0 devices Cable not seated, capture box unpowered, driver missing, or the HDMI source is not delivering a signal the box accepts.
  1. Re-seat the USB-A cable in a different USB 3.0 port.
  2. Confirm the capture box's LED is lit.
  3. Device Manager → look under Cameras or Imaging Devices. A yellow warning triangle means the UVC driver is missing — install it from the capture-box vendor.
  4. Confirm the HDMI source is really 1080p60. Some boxes report 1080p30 or 4K input as no signal.
captest.exe --list shows 1 or 2 devices when 3 are plugged in USB bandwidth saturation. Two capture boxes are sharing one root hub and Windows can only enumerate the first. Move one capture box to a different physical port. Verify in Device Manager → View → Devices by connection that each box sits under a separate USB xHCI Compliant Host Controller.
Δ[0] grows without bound — past 100 and climbing — while everything else looks healthy USB bandwidth shortfall. Multiple capture devices are sharing a single root hub. Three 1080p60 YUY2 feeds need roughly 1.2 GB/s aggregate. Move at least one device to a port on a different physical controller. Some laptops need a Thunderbolt-attached USB hub to supply a genuinely independent fourth controller. This is a hardware topology problem and cannot be tuned away. See Prerequisites § USB.
Frames dropping or stuttering on one feed That feed's device is sharing bandwidth with another. Give each 1080p60 feed its own USB 3.0 controller. Do not use a passive hub.
Wrong resolution, or corrupted / miscoloured frames The device is not delivering 1080p60 in the expected YUV format — it may be defaulting to MJPEG or NV12. Verify the source is 1920×1080 at 60 Hz and that the device offers a YUY2 (YUV422) mode. Many cheap boxes advertise 1080p60 but do not deliver it.
Cameras are assigned to the wrong hill positions Windows' enumeration order does not match the physical layout. Tools → Select Cameras…, then use [Swap 0↔1], [Swap 0↔2] or [Swap 1↔2]. Do not re-plug cables to fix ordering — that changes the device paths.
Camera assignments do not persist across a VDM restart The stored device path was not written or was truncated. Re-assign via Tools → Select Cameras… and confirm that *camera_device_path[0..2] now appear in settings.txt with their full symbolic-link values. Note these paths contain # characters, which the parser handles deliberately — see Configuration § file format.

Green, black or frozen preview

Green is not a random colour here — it is what an uninitialised or cleared frame buffer looks like. Where the green appears tells you which stage is failing.

SymptomLikely causeFix
One feed is green in the Preview tab; no motion detected on it Capture is not writing valid frames into that feed's shared memory.
  1. Processes tab — is capture[N] Running? If not, re-assign the camera via Tools → Select Cameras….
  2. Check whether antivirus has deleted the executable — see above.
  3. Open capture_debug_N.log and look for short MF buffer warnings, which indicate partial frames arriving.
The viewer shows green or an unchanging frame, but the Preview tab looks fine Videogen is the problem — the green is its output region still in its initial cleared state. Confirm videogen is running, then read videogen_debug.log.
The viewer shows a black window There are no frames in the output buffer at all. The viewer reads the output buffer, not the feeds directly. Ensure both a frame source (capture or the practice player) and videogen are running. Press Force Video to commit a clip and give the viewer something to display.
Encoded output video is black Feed merge is reading the wrong frames. Verify all feeds are running and writing, then check the feed alignment keys — see Configuration § feed alignment.
The viewer feels sluggish The window is very large, or the GPU driver is out of date. Reduce big_window_width and big_window_height; update the GPU driver.
The Set Region buttons vanish while the preview is painting The preview blit paints over the child button controls. Switch tabs and back to force a repaint. Cosmetic only — the buttons still work where they were.

NVENC and encoding failures

SymptomLikely causeFix
videogen.exe exits immediately with a version error such as Required: 13.0 Found: 12.0 The NVIDIA driver is too old. The h264_nvenc encoder needs the R570 generation or newer. Install the latest Studio or Game Ready driver from nvidia.com. Verify with nvidia-smi — the Driver Version column must read 570.xx or higher.
NVENC initialisation fails, or the wrong GPU is used *capfile_nvenc_gpu_name holds a GPU name that does not exist on this machine — it ships pinned to one specific laptop GPU. Tools → Select GPU to re-select. Blanking the name lets FFmpeg choose automatically. See Configuration § machine-specific settings.
Encoding works but CPU usage is very high and frames drop under load The software encoder is being used because disable_nvenc_encoding=1, which is the shipped default. Set disable_nvenc_encoding=0 and verify the hardware path works on this GPU. That setting is a workaround for one specific GPU, not a general recommendation. See Prerequisites § NVENC.
An FFmpeg broken-pipe error (error 232) during encode A libx264-only option was passed to the NVENC encoder. NVENC takes -cq; -crf is libx264-only and crashes h264_nvenc immediately. Check videogen_debug.log and ffmpeg_debug.log for the exact command line that was issued.
Overlay text on the output video is corrupted The frame builder was still writing while the overlay was being rendered. Check videogen_debug.log for pause-timeout warnings.
A recorded mp4 will not play in any player The file has no moov atom — capfile.exe was killed rather than stopped. Not recoverable. Always stop recording with the button, which finalises the file. See User guide § continuous recording.

Motion detection

SymptomLikely causeFix
No motion detected on a feed at all Detection disabled, or the region is misconfigured. Check feed_motion_on[N]=1 and the Feeds tab toggle. Verify the motion region actually covers the landing hill. Turn on Highlight and Circles to see what the detector sees.
Constant false triggers Thresholds too sensitive, or something moving inside the region — trees, a flag, spectators. Narrow the motion region; raise min_blob_sizes[]; raise min_motion_count[]; place an ignore rectangle over the offender with Ign Reg N.
Jumpers are missed Thresholds too strict, or the region is too narrow. Lower min_motion_count[]; lower min_blob_sizes[]; widen the region.
Motion triggers but no video is recorded Videogen is not running, or is not seeing the trigger. Start videogen from the Processes tab. Confirm the motion processes are writing by enabling logging and reading motion_debug_N.log.
Clips end too early, cutting off the landing min_nomotion_count[] is too low for that feed. Raise it for the feed concerned, and raise movie_pad or the pre/post padding keys.
One CPU core pinned at 100% A busy loop waiting on a frame-builder IPC event, which is broadcast about 180 times a second by three captures. Expected to be absent on a stock build. If you see it on a modified build, batch the pending frames rather than waking per signal.

Distance readout and grid lines

SymptomLikely causeFix
The distance readout shows --- The cursor is outside the area covered by grid lines. Move the cursor between two configured grid lines, or add anchor points to extend the covered range.
Grid lines do not line up with the hill's metre marks Anchors are uncalibrated, or a camera has moved since calibration. Verify no camera has been knocked, then recalibrate. See User guide § grid-line calibration. Also check meter_line_start and meter_line_increment for that feed.
Some grid lines are missing entirely meter_line_count[N] claims more lines than there are populated anchor pairs. A line with unset anchors has nothing to draw between. Count the populated @far[F][I] / @near[F][I] pairs for that feed and either add the missing anchors or lower the count. See Configuration § grid lines.
Clicking on an anchor point during calibration does nothing The first click only moves window focus to the viewer. Click twice. The banner says CLICK NEAR POINT TWICE for this reason.
Anchor placement raises a warning dialog You clicked in the wrong half of the frame for the feed being calibrated. Dismiss the dialog and press the anchor button again. The top half is always feed 1; the bottom half is feed 0 on type 1 frames and feed 2 on type 2 frames.
A measured distance was not recorded against the jumper A plain left-click does not record — deliberately, so a stray click cannot overwrite a result. Hold Shift and left-click. Confirm the intended jumper is the active one in the list.

Settings not found or overwritten

SymptomLikely causeFix
VDM runs but behaves as though nothing is configured — no regions, no grid lines It did not find settings.txt and fell back to compiled-in defaults. Confirm settings.txt sits beside VDM.exe. Otherwise pass it explicitly: VDM.exe C:\VDM\settings.txt. Remember it is a positional argument — there is no --settings flag. See Configuration § discovery.
A setting you edited has no effect The key name is not recognised, and unrecognised keys are silently ignored. A typo produces no error. Save from the controller and reopen the file — saving rewrites it from the parsed state, so any key that vanishes was never recognised. Check the spelling against the key reference, including the * and @ prefixes and the % suffix.
Comments you added to settings.txt have disappeared Expected. VDM rewrites the whole file from memory whenever settings are saved. Keep notes outside the file. See Configuration § how the file is written back.
It was working yesterday. Calibration is gone on tournament morning. Auto-setup or Save Regions rewrote settings.txt since the last known-good state. Restore from settings.txt.failsafe, the automatic last-known-good snapshot, or from the settings.txt.bak.YYYYMMDD-HHMMSS series in the install directory. Then take your own copy somewhere VDM never writes.
Camera assignments were lost after editing settings by hand The device-path values were damaged — they contain # characters that a careless edit can truncate. Re-assign via Tools → Select Cameras… rather than typing the paths.

Off-screen and misplaced windows

Several windows remember their last position and size in small .ini files stored next to settings.txt in the install directory:

FileWindow
controller_window.iniThe main controller window
gridline_panel.iniThe Grid Line Setup panel
viewer.iniThe live viewer
capture_panel.iniThe file-capture panel
SymptomLikely causeFix
A window opens off-screen, or on a monitor that is no longer attached. The process is running but you cannot see or reach it. The saved geometry refers to a display arrangement that no longer exists — typically an external monitor was disconnected, or the machine was docked when the position was saved and is now undocked. Close the application, delete the corresponding .ini from the install directory, and relaunch. The window reverts to its default position. Deleting these files loses nothing but window placement.
The main window is far larger than the screen, with controls off the edges big_window_width and big_window_height are set for a different display. They ship at 2880×1620. Edit both to fit the actual panel. This is a documented machine-specific setting — see Configuration.
The Grid Line Setup panel is the wrong size Expected — its width and height are recomputed from the metre-line count each time it opens, so it changes size as you change the line counts. No action needed. Only its position is restored from gridline_panel.ini.
Windows appear in a sensible place but you want them elsewhere every session Position is saved on close. Place the window where you want it and close the application normally so the position is written.

Before an event, set up the display arrangement first

Connect the external monitors, arrange the windows where you want them, and close VDM normally so the geometry is saved with the monitors attached. Changing the display arrangement afterwards is what puts windows off-screen.

Disk space and recording

Continuous recording is the heavy consumer: tournament-day captures run 30–80 GB of mp4s per round across the three feeds. Files roll over at 2 GB, adding _part2, _part3 and so on, so a single long session produces many files per feed.

SymptomLikely causeFix
Recording stops unexpectedly part-way through a session The destination volume filled up. Check free space on the recording volume. Move completed events off the machine between rounds. Point *capfile_output_dir at a larger volume.
Recording files written before the disk filled will not play The in-progress file could not be finalised, so it has no moov atom. Not recoverable. Completed rollover parts written before the disk filled should still play. Stop recording cleanly before the volume gets tight.
Encoded jump clips stop appearing in the archive directory No space to write, or the archive directory is on a full volume. Free space, or repoint *archive_dir. Note that failed uploads also leave clips accumulating locally — see Upload failures.
Free space disappears faster than expected Both recording paths are running at once — continuous capfile recording plus per-jumper clips — which is the normal tournament configuration. Plan for it. The prerequisite is 250 GB free minimum, about 500 GB recommended. See Prerequisites.
Recording quality is higher or lower than wanted, affecting file sizes capfile_quality_cq is at its default of 35. Adjust it — valid range 15–40, lower means higher quality and larger files. At the default, expect roughly 3 hours per 2 GB per feed.

Shared memory

SymptomLikely causeFix
Failed to create shared memory Not enough available RAM, or insufficient permissions. The rings need about 10 GB. Close other applications. 32 GB of RAM is the practical minimum for the whole system.
Failed to open shared memory No process has created the region yet. Something has to create it before others can attach. Start capture (or the practice player) first, then the rest. Using Start All handles the ordering for you.
Access denied on shared memory Processes are running under different user accounts or integrity levels. Run everything as the same user. Children launched by the controller inherit its permissions, so launching everything from VDM avoids this.
shmem_diag.exe reports unhealthy regions when nothing is running A crashed process left a handle open. Windows keeps a named shared-memory object alive until the last handle closes. In Task Manager, end every VDM-related process — VDM, capture, motion, videogen, practice_player, capfile, viewer, fileviewer. Once all handles are closed the region is reclaimed. Then relaunch VDM.
Out-of-memory failures during a session Insufficient RAM for the ring buffers plus everything else. Close unnecessary applications before starting. Reduce viewer_ring_channels from its default of 4 if the viewer is the pressure point.

Upload failures

SymptomLikely causeFix
530 Login incorrect %USERPROFILE%\.netrc is missing, malformed, or saved with a .txt extension appended by Notepad. Check for a stray extension first — it is the usual cause. Verify the credentials with curl.exe --netrc -v ftp://thehansens.com/. See Installation § upload credentials.
Clips accumulate locally and are not uploaded All three upload attempts failed. The script retries three times with a 10-second pause. Read upload_video.log for the failure reason. After fixing the network, re-run by hand: .\upload_video.bat output_videos\jump_20260612_141530_007.mp4
Uploads are attempted when they should not be upload_enabled defaults to 1. Set upload_enabled=0 for venue testing on a closed network. The encode still happens; only the upload spawn is skipped.
Files upload to the wrong remote directory *upload_path resolves to a server-side symlink that the tournament admin repoints per event. Out of VDM's control — confirm with the tournament administrator that the symlink points at the current event.

Log files

All processes run with CREATE_NO_WINDOW, so nothing is printed to a console. Every diagnostic goes to a log file in the install directory.

Log fileCovers
controller_debug.logThe main UI and process manager
capture_debug_N.logPer-feed capture (N = 0, 1, 2). Look here for Media Foundation device-open failures and short-buffer warnings.
motion_debug_N.logPer-feed motion detection. motion_debug_1.log is usually the most informative, feed 1 being the trigger camera.
videogen_debug.logMerge and encode
ffmpeg_debug.logRaw FFmpeg child output — the exact encoder command line and its errors
viewer_debug.logThe live viewer
capfile_debug.logContinuous recording
practice_player_debug.logPractice mode
captest_debug.logThe standalone capture diagnostic
upload_video.logUpload attempts and failures

The verbose logs only fill when logging is enabled, so turn on Log On in the Preview tab before reproducing a problem. Some diagnostics also write CSV traces such as motion_diag_feedN.csv.

What to send with a bug report

Zip every *_debug*.log from the install directory plus settings.txt and pixel_frames.txt. That bundle is enough for a developer to reproduce most issues offline. Add the Verify-Install.ps1 output if the problem looks installation-related.