In this guide: Safe checks · Symptom lookup · Audio and beat · Picture and performance · DMX · Controllers · Network and remote · NDI and Spout · License · Logs · Reporting · Recovery
Chapter 1: Start With Safe Checks
Before changing configuration:
- Confirm DjMirror Pulse is open and note the version shown in About.
- Confirm the intended output display/window is visible and the app has not been minimized or covered.
- Check the relevant status indicator (audio meters, DMX status, NDI/Spout panel, server status) before changing settings.
- Change one setting at a time and verify whether the symptom changes. Write down what you changed.
- Do not delete or replace
config.jsonas a first troubleshooting step. If you need to edit it, make a copy first and use the effective file path in Config & CLI.
Warning
If there is an immediate lighting safety concern, use the rig's safe physical controls and follow the fixture and venue procedures. Do not troubleshoot laser, strobe or moving-beam behavior while people are in the affected area.
Chapter 2: Find The Matching Symptom
| Symptom | First checks | Section | Detailed guide |
|---|---|---|---|
| Visuals do not react to music | Select the intended audio input, check OS input level and confirm meters move | 3 | Audio Setup & Beat Sync |
| No picture, wrong crop or stretched output | Confirm a style/layer is visible; check output display and video stretch mode | 4 | Settings Tour, Layers, Shaders & FX |
| Stutter or dropped frames | Test at the target resolution, reduce layers/effects, check high-resolution media | 4 | System Requirements, Visualizers |
| Playlist item is missing | Check the selected playlist, filename and the actual media file in the matching Visuals/ folder |
4 | Content Management |
| DMX fixtures do not respond | Check the selected interface/port, close other lighting apps, verify address/mode, run Diagnose | 5 | DMX Rig Configuration |
| DMX behaves unexpectedly during silence | Check audio silence status, fixture behavior and blackout; rehearse in the simulator | 5 | DMX Rig Configuration |
| Android remote cannot pair or control | Confirm desktop server is enabled, phone and computer share a network, a license is active | 7 | Mobile Remote |
| MIDI, HID or OSC control does not fire | Confirm protocol, input device/port and mapping; test a single control | 6 | MIDI & HID Controllers, OSC Integration |
| Timecode or scheduled cue does not fire | Master and row switches on, correct source mode, cue not jumped over | 6 | Timecode Shows, Programming Schedule |
| NDI or Spout output is unavailable | Confirm platform/edition support, output configuration and receiver status | 8 | NDI & Spout Output |
| MCP client cannot connect | Keep the desktop app running, verify the companion path/config and test a read-only request | 7 | MCP Server for Users |
| API request is rejected | Check host/port, API key and response status; validate the endpoint and payload | 7 | HTTP & WebSocket API |
| Second screen / client does not follow the server | Check server flag, ports 8080/8081, API key and that media exists on the client | 7 | Multi-Screen & Client-Server |
| Professional feature appears locked | Check the active tier and restart the app after activation if needed | 9 | License & Activation |
| Recording has no sound or fails | Check the selected analysis input, hasAudio, output path and available disk space |
4 | Recording & Snapshots |
| Settings reset, content missing after reinstall | Restore from your backup; do not overwrite the effective config.json blindly |
12 | Backup & Restore |
Chapter 3: Audio And Beat Sync
| Symptom | Likely cause | Fix |
|---|---|---|
| Meters are dead | Wrong device, volume near 0, or OS input muted | Reselect the Main audio device, set volume to about 1.0, check the OS sound settings |
| Everything fires constantly | Input is clipping | Lower the capture volume or the OS input level, then watch the meters |
| Silence indicator flickers | Cooldown too short or threshold on the edge | Raise the cooldown; move the threshold away from the room noise floor |
| Beat fires twice | AND/OR policy mismatch between beat sources | Use Either, no double firing (OR) |
| Ableton Link peers are not seen | Different Wi-Fi/LAN or firewall blocking UDP | Same LAN, allow Link UDP traffic; wired is preferred |
| Link settings gone after a reset | Link settings live in QSettings, not config.json |
Re-set the Link panel after any settings reset |
Always verify the device and meters before adjusting visualizer sensitivity. Tuning sensitivity on a dead input only hides the real problem. See Audio Setup & Beat Sync.
Chapter 4: Picture, Media And Performance
Picture
| Symptom | Likely cause | Fix |
|---|---|---|
| Black output | No visible layer or style | Enable one layer (image, video or a visualizer), or apply a saved style |
| Wrong crop or stretched image | Video Stretch mode does not match the display ratio | Set Video Stretch to Crop, Fit or Stretch as needed; Crop can cut edges, Stretch changes proportions |
| Output on the wrong screen | Output display not selected or window moved | Re-select the output display; confirm the window is not minimized |
| Effects (glitch, kaleidoscope…) do nothing | Layer shader is off by default | Turn on the layer's FX (shaderEnabled) |
| App controls too small or large | UI scale, not the output | Adjust UI Scale (0.7–2.2); it does not change the audience output |
Performance
- Test at the target resolution and refresh rate of the real display, not a smaller test window.
- Reduce the number of visible layers and shader effects, then add them back one by one.
- Check for very large video or image files and prefer sizes suited to the output resolution.
- Close other GPU-heavy applications (browsers with video, capture tools).
- If you stream out via NDI or Spout, lower the frame rate or the scale before touching the visuals.
See System Requirements for sizing guidance.
Media
| Symptom | Likely cause | Fix |
|---|---|---|
| Playlist item missing | Filename in the playlist does not match a real file | Check the selected playlist and the file in the matching Visuals/ folder |
| Layers are black on a client machine | Visuals/ files absent on that machine |
Copy the server's Visuals/ tree or point documentsPath at a shared folder |
Recording
| Symptom | Likely cause | Fix |
|---|---|---|
| Recording has no sound | Wrong or silent analysis input | Check the selected analysis input and hasAudio in the recording status |
| Recording fails to start | Output path unavailable or disk full | Confirm free disk space and that the recordings folder is writable |
Chapter 5: DMX Lighting
| Symptom | Likely cause | Fix |
|---|---|---|
| Lights flicker or do not respond | Port held by another app, lagging interface, wrong protocol | Close other lighting software (one lighting app per interface); run Settings → DMX Controller → 🩺 Diagnose; check skipped frames and protocol probes |
| Fixtures respond on the wrong channels | Wrong start address or mode | Verify the patch address and the fixture mode against the fixture manual |
| Nothing lights during silence | Silence behavior set to dark, or blackout is on | Check the silence status and the blackout switch — blackout always wins |
| Unexpected movement or strobe | Pattern or automatic strobe enabled | Disable automatic strobe, test movement away from people, rehearse in the DMX Simulator |
| Simulator works but real rig does not | Interface/port problem, not a scene problem | Re-pick the interface and port; run Diagnose |
Stop unsafe output first, check the patch, then use the simulator and diagnostics. Never test laser or strobe presets with people in the beam area. See DMX Rig Configuration.
Chapter 6: MIDI, Hid And OSC Controllers
| Symptom | Likely cause | Fix |
|---|---|---|
| Controller not in the device list | Connected after the app started | Status → Refresh Devices |
| Nothing happens on a button press | No action mapped, or wrong device selected | Use Start Recording; if no Unknown_… row appears, check the device selection |
| Fader acts like an on/off switch | Input range mismatch | Set inMin/inMax correctly (MIDI 0–127, HID 0–255); for OSC send floats 0–1 |
| Button fires on press and release | Control receives both values | Use a discrete action type or set round: true |
| SHIFT does nothing | No SHIFT control, or other rows lack SHIFT actions | Mark one row as ⇧ SHIFT and define SHIFT actions on the others |
| OSC messages never arrive | OSC mode off, wrong port, or firewall blocking UDP | Check OSC mode and Listening, the sender's target host:port, and the firewall |
Port unavailable (in use?) |
Another program holds the port | Pick another port in both the app and the sender |
| Timecode cue never fires | Master/row switch off, or the cue was jumped over (> 8 s) | Enable both switches; do not locate past cues |
| Scheduled action does nothing | Target style/playlist/scene was renamed or deleted | Re-edit the row and re-pick from the live list |
| Scheduled action fires at the wrong hour | PC clock or timezone differs from the venue | Rows use local time — check the OS clock |
Details: MIDI & HID Controllers, OSC Integration, Timecode Shows, Programming Schedule.
Chapter 7: Network, API And Remote Control
| Symptom | Likely cause | Fix |
|---|---|---|
curl to the server times out |
Firewall, wrong IP, or server is off | Check the --server flag; open ports 8080 and 8081 in the firewall |
UNAUTHORIZED |
An API key is configured | Send it with X-API-Key (or Bearer); phones use their deviceToken |
| Client starts but never syncs | Wrong IP/port or missing API key | Look in the client log for UNAUTHORIZED, 401 or WebSocket errors |
| Changes arrive seconds late | WebSocket port (HTTP port + 1, default 8081) blocked | Open that port; the client is falling back to slow HTTP long-poll |
| Port already in use at startup | Two instances both have the server enabled | Start the second instance with --no-server |
| QR pairing button errors | No license, server off, or no network address | Activate a license, enable the server, join the LAN |
| QR will not scan | Glare, tiny screen, or code expired (180 s) | Generate a new code, raise brightness, scan quickly |
403 MOBILE_LIMIT_REACHED |
The tier's phone limit is reached | Unpair stale phones or upgrade the tier |
| Phone is sluggish | Crowded 2.4 GHz or weak signal | Use a 5 GHz network, place the access point near the booth, wire the PC |
APP_NOT_RUNNING (MCP) |
App closed or its HTTP server disabled | Open the app and enable its HTTP server |
| MCP feature unavailable | Standard or Trial edition | Activate a Professional or Enterprise license |
| MCP server not listed in Claude | Invalid executable path or JSON, or Claude not restarted | Fix the path/JSON and fully quit and reopen Claude Desktop |
See Multi-Screen & Client-Server, Mobile Remote, HTTP & WebSocket API and MCP Server for Users.
Chapter 8: Ndi And Spout Output
| Symptom | Likely cause | Fix |
|---|---|---|
| No NDI source in OBS/vMix | Bridge not running, firewall, or different subnet | Start the bridge from Settings → NDI Output, allow NDI through the firewall, use the same LAN/VLAN |
| NDI video black or frozen | Window title mismatch or window minimized | Check the window title substring; keep the window open and visible |
| Black frames on macOS | Missing Screen Recording permission | Enable it for DjMirrorPulseNdiBridge and DjMirror Pulse, then restart the bridge |
| Spout sender not listed | Output not started, receiver plugin missing, or different GPU | Confirm the output is active (GET /api/v1/spout/status), install the receiver's Spout plugin, use the same GPU |
| Spout image frozen | Window minimized or hidden | Restore the window; the panel reports Running, but no frames are being produced |
| Spout panel says Not available in this build | Non-Windows OS, or build without the Spout SDK | Spout is Windows-only; use NDI on other platforms |
| High CPU | High frame rate, many outputs, complex masks | Lower the frame rate (e.g. 30 fps), reduce outputs, simplify masks |
See NDI & Spout Output.
Chapter 9: License And Locked Features
| Symptom | Likely cause | Fix |
|---|---|---|
| Trial expired on a new install | A trial already ran on this machine | One trial per machine — enter a key; your content is preserved |
| Key rejected | Key belongs to a different machineId, or typo |
Re-copy the machineId; paste the full key instead of retyping |
| Pro features still locked | Standard-tier key, or app not restarted | Check Settings → Help → Active License; restart after activating |
| Temporary key stopped working | Its embedded expiry date has passed | Request a permanent or renewed key |
| New computer, old key fails | Keys are bound to one machine | Request a new key for the new machineId |
See License & Activation.
Chapter 10: Collect Diagnostic Information
When a problem needs more than the on-screen status:
Note the version from About and your operating system version.
Run with a console to see log output: start the app with
--console(Windows). To keep the log in a file from PowerShell, pipe it so the shell waits for the program:.\DjMirrorPulse.exe --console 2>&1 | Tee-Object djmirror.logThe log ends when you close DjMirror Pulse, so do not close the PowerShell window first.
For a client/server problem, start the server and the client with
--consoleand compare their logs side by side (see Multi-Screen & Client-Server).For DMX, use Diagnose and copy the report text.
For API problems, repeat the request with
curland keep the HTTP status and response body.Take a screenshot of the relevant panel and remove private details first.
All command-line flags are listed in Config & CLI.
Chapter 11: If The Problem Remains
Prepare a concise report before asking the distributor or support team:
- DjMirror Pulse version and operating system version.
- What you expected, what happened, and the exact steps that reproduce it.
- Which audio device, display, DMX interface or controller is involved, when relevant.
- The relevant status/error text and a screenshot with private details removed.
- What you already checked and whether the same issue happens with a simple test setup.
Important
Do not include API keys, AI-provider tokens, license keys, private media or unredacted configuration files. If support needs configuration data, ask what specific fields they require and remove secrets before sharing.
Chapter 12: Quick Recovery Checklist
- Audio issue: verify device and meters before adjusting visualizer sensitivity.
- Visual issue: test one visible layer/style at a time before resetting settings.
- DMX issue: stop unsafe output, check the patch and use the simulator/diagnostics.
- Network/API issue: verify server, address, port and authentication locally first.
- Control issue: test a single mapping with Start Recording before debugging the whole map.
- Data issue: stop the app and make a backup before restoring or editing files — see Backup & Restore.