🎧 DJ Doctor

Diagnosing your setup so you can focus on the mix.

A read-only system health check for DJs, producers, and audio engineers — it finds the driver conflicts, optimizer interference, and power settings that stop your controller from connecting before they ruin your set.

---

🤔 What is this?

You plug in your controller five minutes before doors. Nothing. Serato says "no hardware connected." You unplug, replug, reboot, swap cables, swear quietly.

Most of the time it isn't broken hardware — it's software fighting over your USB audio: a "PC optimizer" that disabled your audio services, an OEM sound suite hooking the audio stack, a USB hub that powered itself down to "save energy," or a Balanced power plan throttling your CPU mid-track.

DJ Doctor is a one-command checkup for exactly these problems. It scans your Windows system for the known culprits, tells you in plain English what's wrong and exactly how to fix it — and it never changes anything itself. You stay in control.

Run it before a gig to make sure you're ready. Run it when a controller won't connect and you need answers fast.

---

📸 What it looks like

 ____      _   ____             _
|  _ \    | | |  _ \  ___   ___| |_ ___  _ __
| | | |_  | | | | | |/ _ \ / __| __/ _ \| '__|
| |_| | |_| | | |_| | (_) | (__| || (_) | |
|____/ \___/  |____/ \___/ \___|\__\___/|_|
  v1.0.0  —  Diagnosing your setup so you can focus on the mix.
  Read-only health check · nothing is changed on your system

🎛️  USB Audio Devices
────────────────────────────────────────────────────────────
  ✔ OK: Pioneer DDJ-SB3 [VID_2B73&PID_0031] — connected, status: OK
  ℹ INFO: Known device: Pioneer DDJ-SB3 (Pioneer DJ) — generic driver

🛠️  Conflicting Services
────────────────────────────────────────────────────────────
  ✖ CRITICAL: TunedPC: 'TunedPC Service' (TunedPCSvc) — Running
      → TunedPC aggressively disables Windows services it considers
        'unnecessary', including USB Audio class support... the #1 cause of
        a controller that simply won't show up.
      → FIX: Open TunedPC -> Services and re-enable 'Windows Audio'...

  ▲ WARNING: Nahimic / A-Volute: 'Nahimic service' (NahimicService) — Running
      → Nahimic audio effects hook the audio stack at a low level...
      → FIX: Disable the Nahimic service (services.msc -> Disabled)...

🔋  Power Configuration
────────────────────────────────────────────────────────────
  ▲ WARNING: Active power plan is 'Balanced'
      → Balanced and Power Saver plans throttle the CPU... causes dropouts.
      → FIX: powercfg /setactive 8c5e7fda-e8bf-4a96-9a85-a6e23a8c635c

  ✖ CRITICAL: USB selective suspend is ENABLED
      → ...that means a disconnect mid-performance.
      → FIX: powercfg /setacvalueindex SCHEME_CURRENT 2a737441-... 0

╭───────────────────────────── 📋 Scan Summary ─────────────────────────────╮
│   ✖ Critical   2                                                           │
│   ▲ Warning    2                                                           │
│   ℹ Info       3                                                           │
│   ✔ OK         5                                                           │
│                                                                            │
│   Not gig-ready — fix the critical items above.                            │
╰────────────────────────────────────────────────────────────────────────────╯

You can also export a polished, shareable dark-mode HTML report to post when you ask for help on a forum:

dj-doctor scan --report html

📄 See a full example HTML report → (download the raw file and open it in your browser — it's a single self-contained page.)

---

🚀 Quick start

Requires Windows 10/11 and Python 3.10+.

pip install dj-doctor
dj-doctor scan

Prefer not to install anything system-wide? Use a one-off:

pip install --user dj-doctor
python -m dj_doctor scan

Or grab a standalone .exe (no Python needed) from the Releases page — just download and run.

---

🔍 What it checks

Check	What it looks for
🎛️ USB Audio Devices	Enumerates connected USB audio gear, flags devices in error/disabled states, and cross-references your controller against a database of known devices for model-specific tips.
🧩 Driver Health	Whether your device is on the right driver (generic class vs. manufacturer ASIO), and whether ASIO4ALL is needlessly layered over a native ASIO driver.
🛠️ Conflicting Services	Scans Windows services against a database of known offenders — PC optimizers, OEM audio suites, gaming boosters, antivirus, and more.
📊 Conflicting Processes	Catches problem apps that are actually running, plus any process hogging enough CPU to cause dropouts.
🔋 Power Configuration	Active power plan, USB selective suspend, minimum processor state, and PCIe link-state power management.
🔌 USB Power Management	The infamous "Allow the computer to turn off this device to save power" setting on your USB hubs, plus USB controller type (xHCI/eHCI).
⏱️ DPC Latency Indicators	A quick heuristic for drivers notorious for high DPC latency (certain network/WiFi drivers), with a pointer to LatencyMon for the full picture.
🗄️ Registry Configuration	Checks that core audio & Plug-and-Play services aren't disabled, the USB audio class driver is enabled, Fast Startup status, and third-party USB filter drivers.

Run everything, or narrow it down:

dj-doctor scan                       # full checkup
dj-doctor scan --quick               # only CRITICAL + WARNING
dj-doctor scan --verbose             # show details for OK/INFO too
dj-doctor scan --only services       # one category
dj-doctor scan --only usb --only power   # a few categories
dj-doctor scan --report html -o report.html   # export a shareable report
dj-doctor scan --report json -o report.json   # machine-readable export

dj-doctor list-conflicts             # browse the conflict database
dj-doctor list-devices               # browse the device database
dj-doctor check-device 2B73:0031     # look up a device by VID:PID

dj-doctor scan also sets a non-zero exit code when it finds problems (2 = critical, 1 = warning) — handy for a pre-gig checklist script.

---

🛟 Safety first

DJ Doctor is strictly read-only. It reads device, service, power, and registry state and reports on it. It never modifies your system — every fix is shown to you as a command or a set of steps that you choose to run. No silent "optimizations," no surprises. That's the whole point: the tools that broke your setup were the ones that changed things without asking.

It's also offline-first: no network calls, no telemetry, no update checks. Everything runs locally on your machine.

---

📚 Known conflicts database

DJ Doctor ships with 26+ known conflicts across these categories:

• PC optimizers / tuning software — TunedPC, Advanced SystemCare, IObit Driver Booster, Auslogics BoostSpeed, CCleaner…
• OEM audio suites — Nahimic / A-Volute, ASUS Sonic Studio, Waves MaxxAudio, Dolby Atmos APO, Realtek background services…
• Gaming optimizers — Razer Cortex, Wise Game Booster, Game Fire, GeForce Experience & Radeon overlays…
• Peripheral software — Razer Synapse, Corsair iCUE, Logitech G HUB, ASUS Armoury Crate, MSI Center…
• Antivirus — Webroot, Kaspersky, McAfee real-time scanning…
• Windows features — Xbox Game Bar / Game DVR, Fast Startup, Audio Device Graph Isolation…
• Network — Killer Network Service, Apple Bonjour…

…plus a device database covering popular controllers and interfaces from Pioneer DJ, Native Instruments, Focusrite, PreSonus, Behringer, Roland, Denon DJ, Hercules, and Audient.

Hit a conflict we don't know about? Adding one is a two-minute job — see docs/adding-conflicts.md, or open a conflict report issue.

---

🔧 Building from source

git clone https://github.com/SubchiBeats/dj-doctor.git
cd dj-doctor
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e ".[dev]"

dj-doctor scan        # run it
pytest                # tests (mock all OS calls — pass on any platform)
ruff check .          # lint

Build a standalone .exe (PyInstaller)

pip install -e ".[build]"
pyinstaller --onefile --name dj-doctor --collect-all rich src/dj_doctor/__main__.py
# the binary lands in dist\dj-doctor.exe

---

🤝 Contributing

PRs welcome — especially new conflicts and devices. You don't need to be a developer; the databases are plain Python lists. Start here:

• docs/CONTRIBUTING.md — dev setup & guidelines
• docs/adding-conflicts.md — add a conflict or device
• Open an issue — report a conflict, add a device, or file a bug

The one hard rule: DJ Doctor stays read-only. Diagnosis and recommendation only.

---

❓ FAQ

Will it fix my problems automatically? No — and that's intentional. DJ Doctor diagnoses and recommends. It hands you the exact command or steps and lets you decide. Safety and trust come first; a tool that quietly changes your system is how you got here in the first place.

Does it need administrator rights? No. It runs fine as a normal user. Some registry and device checks are more complete when run as Administrator — DJ Doctor clearly marks anything it couldn't read as skipped and suggests re-running elevated for a full scan.

Does it phone home / collect data? Never. No network calls, no telemetry, no auto-update. It's fully offline.

Mac / Linux support? DJ Doctor is Windows-focused — that's where these USB-audio-vs-optimizer wars happen. On other platforms the knowledge-base commands (list-conflicts, list-devices) still work, but system scans report as skipped. PRs that add macOS/Linux scanners are welcome.

It flagged something that's actually fine for me. Some entries are INFO/WARNING precisely because they're situational (RGB software, GPU overlays). If it's not causing you trouble, you can ignore it — the severity and explanation are there to help you judge.

My controller works great but DJ Doctor doesn't recognise it. The device database is curated, not exhaustive. Your gear can be perfectly fine without being listed. Consider adding it!

---

💜 Credits & motivation

DJ Doctor exists because of one very specific, very frustrating evening.

A Pioneer DDJ-SB3 that had worked for months suddenly refused to connect to Serato DJ Pro — "no hardware connected," no matter what. Hours of cable swaps, driver reinstalls, and reboots later, the culprit turned out to be a "PC optimizer" (TunedPC) that had decided Windows Audio, the USB Audio class driver, and Plug-and-Play were "unnecessary services" and helpfully disabled them.

Re-enabling a handful of services fixed everything in thirty seconds — once you knew what to look for. The realization that countless other DJs hit this exact wall, with no idea where to look, is why this tool exists. If DJ Doctor saves even one person that pre-gig panic, it did its job.

Built with 🎧 by Subchi.

---

🗺️ Roadmap (phase 2)

• 🖥️ GUI version (CustomTkinter) — the engine already supports it
• 🔄 Auto-updatable conflict database via GitHub releases
• 🛠️ Opt-in "fix it for me" mode (with explicit per-fix confirmation)
• 🌐 Community-submitted conflict reports (issue templates are already live)

---

_{DJ Doctor is read-only and offline. It diagnoses; you decide. 🎶}