MIDI Control Issues

Use this guide when shiloh-midi-sender is not working, or the mixer is not responding to MIDI keyboard input.

Branch 1: Device not detected

Symptom: shiloh-midi-sender exits immediately with an error like MIDI device not found, or it starts but sends no events.

List all MIDI devices visible to ALSA:

aconnect -l

Look for your MIDI keyboard in the output. A typical entry looks like:

client 24: 'USB MIDI' [type=kernel]
    0 'USB MIDI MIDI 1 '

If the device is not listed:

  • Unplug and replug the USB MIDI device.
  • Check dmesg | tail -20 for USB errors.
  • Confirm the snd_usb_audio module is loaded: lsmod | grep snd_usb.
  • Try a different USB port.

Match the device name exactly:

The --device argument to shiloh-midi-sender is matched against the ALSA client name. Use the exact string from aconnect -l (or a unique substring):

# Example: device shows as "USB MIDI"
shiloh-midi-sender --device "USB MIDI" --server HOST:19999

Branch 2: Keys not responding

Symptom: MIDI device is detected, shiloh-midi-sender is running, but pressing keys does not affect mixer faders or Ardour transport.

Verify the MIDI channel:

shiloh-midi-sender filters by MIDI channel. Check the [midi] block in ~/mixer/shiloh-mixer.toml:

[midi]
channel = 1   # MIDI channel (1-indexed)

Your keyboard must be sending on the same channel. Most keyboards default to channel 1. Check your keyboard’s global MIDI channel in its settings menu.

Check the mixer logs for incoming MIDI events:

journalctl --user -u shiloh-mixer | grep -i midi

If events are arriving, you should see lines like midi note_on ch=1 note=60. If there are no MIDI log lines, the UDP packets from shiloh-midi-sender are not reaching the mixer.

Verify UDP 19999 is open:

ss -lunp | grep 19999

The mixer listens on 0.0.0.0:19999 for MIDI. If this port is not shown, the mixer’s MIDI receiver is not configured.

Check the note mapping:

The [midi] block in the TOML defines which notes trigger which actions. The default map is documented in OPERATIONS.md. If you have a custom map, verify the note numbers match (C3 = note 48 in MIDI 0-indexed, or note 60 depending on octave convention — check your keyboard’s MIDI monitor).

Branch 3: Jitter / flickering on touch-sensitive keys

Symptom: Faders jump around rapidly, or a single key press triggers multiple actions.

Cause: Some MIDI keyboards send rapid note-on/off bursts on keys with velocity sensitivity or aftertouch. The mixer’s state machine interprets each event separately, causing rapid mode switches or repeated fader moves.

Enable debounce in the TOML config:

[midi]
debounce_ms = 50   # ignore repeated note-on events within this window (ms)

Adjust the value upward (100–200 ms) if flickering persists. Too high a value makes the keyboard feel sluggish for intentional rapid keypresses.

Check for velocity-triggered duplicates:

Some keyboards send a note-on with velocity 0 instead of a note-off. This can be misinterpreted as two separate presses. The channel and note values in the mixer logs will show this pattern — look for pairs of note_on v=0 and note_on v=N for the same note in rapid succession.