MIDI learn that survives the next session

Learn an identity, not a stray message

Begin with a narrow feature: learn one absolute MIDI Control Change message for one parameter. Web MIDI supplies messages from input ports, while the MIDI Association’s message summary describes their status and data bytes. Keep the input port, message type, channel and controller number together as the binding. A controller number alone is not enough to distinguish several devices or channels.

Make Learn an explicit temporary state. The musician selects a destination, arms learning and moves the intended control. Accept the expected message family, show what was captured and leave learning mode. Ignore unrelated clock or note traffic for this particular feature rather than binding whichever message happened to arrive first.

Display a readable summary beside the parameter. Include enough information to identify the binding and provide Clear and Relearn actions. A hidden mapping may feel convenient for the first minute, then become difficult to repair when the same control appears to move two unrelated things.

Choose what the first movement means

Map the incoming value into the destination’s musical range. A frequency control may need a different curve from a mix control. Store the range and curve as part of the mapping rather than treating all destinations as zero-to-one sliders. Let the interface show the parameter’s effective value, not only the raw MIDI number.

Now recall a preset whose value differs from the physical knob. Decide whether the next movement jumps immediately, waits until the knob reaches the stored value, or uses another documented takeover strategy. A pickup approach can prevent a large jump, but the interface should explain why movement is temporarily not changing the sound.

Relative encoders require their own interpretation. Do not silently treat every encoder as an absolute value source. Different controllers can use different relative encodings, so support the modes you have implemented and make the selected mode explicit. A restricted feature with clear behaviour is more useful than a learn button that makes unsupported guesses.

Test the minimum, maximum and a slow sweep through the centre. Then move the control quickly while sound is playing. Listen for abrupt parameter transitions and apply suitable smoothing in the engine where needed. Keep smoothing separate from takeover: one controls the trajectory of a change, while the other decides when the physical control takes ownership.

Handle the missing controller

Web MIDI access requires a secure context and may be affected by permissions and browser support. The API also provides state-change events for ports becoming available or unavailable. Use those events to update the interface instead of leaving a disconnected device looking active.

Save mappings in a versioned form and give the user a way to inspect or reset them. Do not assume that a device name uniquely identifies a controller in every setup. If a saved binding cannot be resolved confidently, mark it unresolved and ask for a deliberate reassignment within the interface.

Rehearse unplugging and reconnecting the controller, opening the page without it and using two devices with similar names. Check that mouse, touch or keyboard controls still provide a coherent fallback. A missing controller should not turn a parameter into an unexplained frozen value.

Finish with a five-minute performance using only a few learned controls. Note which mappings are actually useful and remove the rest. The value of MIDI learn is not the number of assignments it can store. It is the confidence that a physical gesture will reach the intended parameter, in the intended way, when the next session begins.