Verify everything works

Three checks, two minutes, zero ambiguity — a structured loopback test that proves the full chain is live: controller → app → virtual MIDI port → DAW → audio out. Run this before mapping or templating; it pinpoints which link is broken so you don't waste an hour chasing the wrong layer.

Step 1 — Controller is alive

Open the app. The top-bar status chip should be coloured and named (e.g. DualSense 02). Press any face button — the corresponding tile in the Live view should pulse teal for ~120 ms.

If nothing pulses, the OS isn't routing events to the app. Go back to connect USB or connect Bluetooth and re-verify OS-level detection.

Step 2 — MIDI is leaving the app

Use a standalone MIDI monitor outside your DAW. MIDI Monitor on macOS or PocketMIDI on Windows both work.

Open the monitor, select the Universal Controller port as input, and press a button. You should see a Note On with velocity, immediately followed by a Note Off when you release.

# Linux equivalent — aseqdump
aseqdump -p "Universal Controller"

# macOS CLI equivalent — receivemidi (companion to sendmidi)
receivemidi dev "Universal Controller"

# Windows CLI — using the PocketMIDI bundled CLI
pocketmidi --listen "Universal Controller"

Tools you can throw at this

If you're a CLI person, here's the toolchain we lean on. All are free and worth keeping installed for future debugging.

Step 3 — DAW hears it

In your DAW, arm a MIDI track that listens to the Universal Controller input, then drop a default instrument on it (Logic's E-Piano, Ableton's Operator, FL's FLEX, doesn't matter). Press a face button.

You should hear a note. If you see the MIDI activity meter twitch but get no sound, the track's instrument or monitoring is the issue — not the bridge.

Quick smoke test from scratch

If you want a one-shot script to confirm the whole chain — useful for CI rigs or remote-debugging a friend — fire a programmatic note through the bridge and listen for it on the other end:

# macOS / Linux — needs sendmidi + receivemidi from gbevin
# Open one terminal:
receivemidi dev "Universal Controller" --timestamp &

# In a second terminal — fire 5 notes, one per second
for note in 60 62 64 65 67; do
  sendmidi dev "Universal Controller" on $note 100
  sleep 0.4
  sendmidi dev "Universal Controller" off $note 0
  sleep 0.6
done

# Expect 5 NoteOn + 5 NoteOff lines on the listener terminal, total elapsed ~5 s

What if it doesn't work?

Each step failing maps to a specific cause. Use this list to jump straight to the fix:

• Step 1 fails — Live tiles don't pulse — OS isn't seeing the controller. Run the OS-level detection commands in connect USB and check for a process grabbing the HID stream.
• Step 2 fails — Monitor shows nothing — UCM's output is muted or pointed at the wrong port. Settings → MIDI output → confirm Universal Controller (or your renamed port) is selected and the "Output enabled" toggle is on.
• Step 3 fails — DAW meter twitches, no sound — instrument not loaded, track not armed, or monitoring off. Check the track's input monitoring icon is lit; load a default synth fresh.
• Notes hang after testing on Linux — ALSA didn't deliver the Note Off. Hit Panic in the app, or run aconnect -x to drop all connections and re-arm.
• Audio plays but is ~80 ms late — DAW buffer too high. Drop your audio interface buffer to 64 or 128 samples; latency is the buffer, not the bridge.

You're done

If all three steps passed, the install is good. From here, head into the fun part — the mapping editor or browse templates for ready-made setups.

If any step failed, the diagnostics panel inside the app (cog icon → Diagnostics) bundles up logs, OS info, and detected devices into a single export ready for a support ticket.