Skip to content

Troubleshooting

Start with View > Diagnostics (Ctrl+D). Select Reset, reproduce the problem once, then select Copy. The copied text provides a useful snapshot without requiring screenshots of every preference page.

Controll3r does not start

  1. Confirm that you launched the installed x64 application.
  2. Check Task Manager for another Controll3r.exe.
  3. If another UI instance is running, activate that window instead of opening a second hardware owner.
  4. If a headless instance is running, use the takeover prompt or stop the headless process deliberately.
  5. Check %LocalAppData%\Controll3r\logs\ for the latest startup error.
  6. Restart the Controll3r Interface if the log shows repeated control-channel timeouts.

The MSI includes .NET, so installing a separate .NET runtime should not be necessary.

The UI says another instance or service is running

Only one process may own the capture and input hardware.

  • If the desktop UI is already open, use it.
  • If headless mode is running, accept the takeover prompt to transfer ownership.
  • If a previous process is unresponsive, close it from Task Manager before trying again.

Do not run the UI and headless host as independent hardware owners.

No video signal

General checks:

  1. confirm the target is powered on and awake
  2. verify the video cable and selected target output
  3. confirm the capture device is visible in Windows
  4. close other capture applications
  5. open Preferences > Video
  6. select Rescan devices
  7. reselect the intended device

For UVC:

  1. choose a capture mode supported by both source and capture device
  2. use Match source format
  3. try a common source mode such as 1080p60 or 1080p30
  4. update the capture-device driver and firmware

For DeckLink:

  1. install or update Blackmagic Desktop Video
  2. confirm the signal in Blackmagic Media Express
  3. note the mode Media Express detects
  4. close Media Express
  5. restart Controll3r and select the native DeckLink: entry

DeckLink cards do not scale arbitrary signals. The source must send a mode the card supports.

A Blackmagic device appears twice

When the native DeckLink runtime and card are available, use the entry prefixed with DeckLink:. The other Windows-provided entry for the same card supports fewer formats and can reject broadcast signals the native entry accepts.

Current builds normally suppress the duplicate WDM source when a corresponding native DeckLink source is available. If both remain, include the device names and Desktop Video version in a support report.

Video is black but diagnostics show frames

  1. verify that the selected capture mode matches the source
  2. check whether another application changed the card configuration
  3. for DeckLink, compare the detected pixel format with Media Express
  4. update the graphics driver
  5. copy diagnostics, especially video path, format, frame rate, and latency

Video is delayed or uneven

  • Run Tools > Latency Test to measure the input-to-captured-frame delay.
  • Compare with another capture device or mode.
  • Prefer a native DeckLink path when low latency is critical.
  • Avoid USB hubs and oversubscribed USB controllers for high-bandwidth UVC.
  • Update capture and GPU drivers.
  • Lower capture resolution or frame rate as a diagnostic.
  • Check whether recording or Visual Anchor polling changes the behavior.

The displayed video-latency counter is an internal measurement of the capture path, not what you perceive on screen. The Latency Test instead measures from a pointer command to the corresponding captured frame change; it does not include the local UI compositor or monitor.

Keyboard or mouse does not reach the target

  1. open Preferences > Device
  2. confirm that the Controll3r Interface is connected
  3. use Device > Connect
  4. confirm that the target-facing USB cable is connected
  5. inspect the target USB/configured status and keyboard LED state
  6. capture input again and verify the release chord shown in the banner
  7. restart the Controll3r Interface if control requests repeatedly time out

Live mouse uses the relative pointer. Macros use the absolute pointer. A live mouse can work even when the automation pointer is still disabled.

Input is captured but the local cursor disappeared

This is expected while Controll3r owns input. Hold the configured release chord, initially Left Ctrl + Left Alt, to return control to the operator desktop.

If release does not work:

  1. press and release both keys
  2. try the exact left-side modifiers
  3. check Preferences > Input after regaining control
  4. use Alt+Tab only as an emergency recovery, then inspect the configured chord and diagnostics

The target misses pasted characters

  1. increase Optional typing throttle under Input preferences
  2. start with a small increase
  3. verify the selected keyboard layout
  4. avoid characters the target layout cannot produce

Controll3r already confirms delivery of every keystroke to the Controll3r Interface. The throttle is for a target console that processes input slowly, not for ordinary USB pacing.

Paste stops or skips characters

Smart punctuation is converted to ASCII. Remaining untypable characters are skipped by default with a non-blocking count.

If paste stops at the first such character, clear Stop pasting if a character can't be typed under Input preferences.

The target keyboard layout must match the layout selected in Controll3r.

No audio

  1. confirm the target is producing audio over the captured connection
  2. open Preferences > Audio
  3. select the intended capture and local playback endpoints
  4. confirm that Mute is off
  5. raise Controll3r's monitoring volume
  6. verify the Windows playback device is active

For DeckLink embedded audio, start the DeckLink video session first. Video and audio must come from the same live DeckLink source.

Recording cannot start

Recording requires live video.

  1. confirm the viewport is updating
  2. stop any prior recording cleanly
  3. verify the output folder is writable
  4. select H.264 if HEVC is unavailable
  5. ensure enough disk space remains
  6. copy diagnostics including recording queue state

Do not terminate the app while an MP4 is finalizing.

Recorded audio is quieter than what I heard

Recordings capture the target's audio before monitoring volume, Mute, and loudness leveling are applied. If loudness leveling was boosting a quiet source while you listened, the recording preserves the original quiet level. The audio is intact — raise its gain in any media editor. For the same reason, Mute does not silence recordings.

Snapshot or recording is not where expected

Defaults:

  • snapshots: %UserProfile%\Pictures\Screenshots\
  • recordings: %UserProfile%\Videos\

Both destinations can be changed under Preferences > Video.

A Visual Anchor is not found

  1. confirm current capture resolution and format match the recorded context
  2. verify that the target control still looks the same
  3. ensure the anchor did not include a cursor, animation, clock, or changing text
  4. recapture a tighter but more distinctive region
  5. include color and shape that distinguish similar controls
  6. use the failure evidence to compare expected and current images

Do not simply lower confidence until unrelated controls begin matching. A false positive can be more dangerous than a safe failure.

Await Anchor returns immediately

The anchor is already considered present at the configured confidence. Check the expected/current evidence and recapture a more distinctive region if it is matching the wrong element.

Wait Until Clear never finishes

The saved anchor is still present somewhere in the search region, or the captured region contains mostly unchanged background.

Recapture a region centered on the part that actually disappears or visibly changes. Set a positive timeout while developing the macro so a mistake does not wait indefinitely.

Macro playback reports a resolution or format mismatch

Visual Anchors are exact-context in version 1. Restore the recorded capture resolution/format or recapture the anchors using the new context.

API returns an empty response or connection failure

  1. test GET /v1/health first
  2. confirm the configured port
  3. confirm the server is enabled, or start --headless
  4. use HTTP for loopback mode
  5. use HTTPS for LAN mode
  6. inspect firewall and certificate trust for LAN access

An authenticated endpoint should return JSON or file content. Use curl.exe in PowerShell to avoid aliases with different argument behavior.

API returns 401

Copy the current token from Preferences > Webserver and send:

Authorization: Bearer <token>

If the token was regenerated, restart the webserver before retesting.

Headless takeover or restart fails

  1. confirm only one Controll3r process is starting
  2. check %LocalAppData%\Controll3r\logs\
  3. verify that the configured API port is free
  4. remove and reinstall per-user autostart if its launch path is stale
  5. use /v1/health to verify the restarted host passively

The health check never takes over the hardware, so it is safe to call while another process still owns it.

Collect a useful support report

Include:

  • Controll3r version from About
  • Windows version
  • capture-device model and driver version
  • target signal resolution and refresh rate
  • Blackmagic Desktop Video version when applicable
  • Controll3r Interface firmware version shown in Preferences
  • copied diagnostics after Reset and one reproduction
  • relevant log excerpt
  • exact steps and whether the issue is repeatable

Do not publish bearer tokens, private screenshots, macros, or recordings without reviewing them first.