Debugging DH_MIDIVelocityCtrl: Common Issues and Solutions

Mastering DH_MIDIVelocityCtrl: Tips, Tricks, and Best Practices

What it does (brief)

DH_MIDIVelocityCtrl maps incoming MIDI note velocities (0–127) to controllable output values for devices or software that respond to velocity—e.g., synthesizer layers, drum solenoids, velocity-scaling curves, or expressive MIDI processors.

Recommended parameter defaults

• Input range: 0–127 (MIDI standard)
• Output range: 0–1.0 (normalized) or 0–255 (8-bit DAC/PWM) depending on target
• Default curve: Exponential (gamma ≈ 1.6) for natural feel
• Min output floor: 0.02–0.05 (prevents dead-zone on analog actuators)
• Max scaling: 1.0 (avoid clipping unless intentional)

Velocity curves & when to use them

• Linear — transparent mapping; use for precise dynamics and debugging.
• Exponential (recommended) — emphasizes higher velocities; good for drums and percussive instruments.
• Logarithmic — emphasizes low-velocity nuance; useful for pads, bowed strings.
• Piecewise (two-segment) — soft sensitivity at low velocities, steeper above a threshold for hybrid control.

Implementation tip: apply curve to normalized velocity: out = pow(v_norm, gamma).

Common mappings & formulas

• Normalize: v_norm = v / 127.0
• 8-bit output: out_8bit = round(255v_norm)
• Exponential: out = pow(v_norm, gamma)
• Scaled with floor: out_final = floor + (1 – floor) * out

Example (gamma=1.6, floor=0.03): out_final = 0.03 + 0.97 * pow(v/127, 1.6)

Practical tips for hardware outputs

• For PWM-driven solenoids/LEDs, map to 0–255 and use low-pass filtering or current limiting.
• Avoid driving actuators directly from microcontroller pins at high duty; use MOSFETs/drivers.
• When analogWrite doesn’t move an actuator, ensure the pin supports PWM and use appropriate voltage/current driver.
• Debounce note-on bursts and implement short envelopes (attack/release) to avoid clicking.

MIDI handling best practices

• Respect note-off (velocity=0) semantics; treat 0 as note-off.
• Implement channel and note filtering for multi-instrument setups.
• Throttle or coalesce rapid velocity-only CCs to avoid saturating downstream devices.
• Preserve MIDI timing: process on receipt and avoid blocking code in the MIDI thread.

Debugging checklist

• Verify incoming velocity values (print or log raw bytes).
• Confirm correct pin supports PWM if using analogWrite.
• Check scaling: double-check whether firmware expects 0–127 or 0–255.
• Test with known good MIDI source (DAW or hardware controller).
• If output is always full-on, ensure you’re not converting any nonzero velocity to a boolean HIGH (avoid “if v>0 then HIGH”).

Example flow (recommended)

1. Read MIDI note-on with velocity v.
2. If v == 0 → treat as note-off; trigger release.
3. Normalize v to 0–1.0.
4. Apply chosen curve and floor.
5. Scale to output resolution (0–255).
6. Send to driver (PWM/DAC/MIDI CC) and apply short envelope.

Performance & edge cases

• Use lookup tables for expensive pow() calls on MCU with limited FPU.
• Clamp inputs to [0,127] to avoid out-of-range bugs.
• If multiple notes share an output, implement priority (last-note, highest-velocity) to decide output level.

Quick reference table