Add software chromatic quantization (12-TET) for whole-tone layouts

Allows semitones to be hit between whole-tone pads via software quantization.

New settings:
- chromatic_quantize: Enable 12-TET semitone snapping (default: false)
- whole_tone_bias: Adjust zone balance, range -1.0 to 1.0 (default: 0.0)
  - 0.15 recommended for LinnStrument speed bump surface

Requirements:
- LinnStrument Quantize=OFF, Quantize Tap=OFF, Quantize Hold=OFF
- This setting overrides hardware quantization with proper semitone support

Author: zitongcharliedeng

settings.ini.example

@@ -3,6 +3,13 @@
 
 [general]
 size=128
+
+; Software chromatic quantization (12-TET) - see settings.py for full documentation
+; REQUIRED: LinnStrument Quantize=OFF, Quantize Tap=OFF, Quantize Hold=OFF
+;chromatic_quantize=true
+;whole_tone_bias=0.4375
+;quantize_hold=medium
+
 ;velocity_curve=1.0
 ;lights=1,9,9,2,2,3,3,5,8,8,11,11
 ;split_lights=4,7,5,7,5,5,7,5,7,5,7,5

src/core.py

@@ -964,6 +964,70 @@ def cb_midi_in(self, data, timestamp, force_channel=None):
                 # NOTE: Synth must have MPE enabled for per-note slides
                 bend_val = decompose_pitch_bend((data[1], data[2]))
                 bend_val *= self.options.bend_scale
+                
+                # Software chromatic quantization (12-TET)
+                # Snaps pitch bends to nearest semitone for whole-tone layouts
+                # Requires: LinnStrument Quantize=OFF, Quantize Tap=OFF, Quantize Hold=OFF
+                if self.options.chromatic_quantize:
+                    # Semitone step size in normalized bend units
+                    # column_offset accounts for whole-tone layout (2 semitones per pad)
+                    semitone = 1.0 / (self.options.bend_range * self.options.column_offset)
+                    
+                    # Quan Hold: movement detection (allows vibrato when moving)
+                    # Based on LinnStrument firmware behavior
+                    note = self.notes[ch]
+                    hold_mode = self.options.quantize_hold
+                    
+                    # Mode settings: (rate_threshold, stationary_samples)
+                    # Lower threshold = more sensitive to movement
+                    # Higher samples = slower snap-back
+                    hold_configs = {
+                        "off": (0.0, 0),      # Always quantize
+                        "fast": (0.004, 8),   # Quick snap
+                        "medium": (0.003, 24), # Balanced
+                        "slow": (0.002, 48)   # Gradual
+                    }
+                    rate_threshold, stationary_samples = hold_configs.get(hold_mode, hold_configs["medium"])
+                    
+                    # Calculate movement rate (EMA of bend delta)
+                    delta = abs(bend_val - note.last_bend)
+                    alpha = 0.2  # EMA smoothing factor
+                    note.rate_x = note.rate_x * (1 - alpha) + delta * alpha
+                    note.last_bend = bend_val
+                    
+                    # Determine if stationary
+                    is_stationary = note.rate_x < rate_threshold
+                    
+                    if is_stationary:
+                        note.stationary_count = min(note.stationary_count + 1, stationary_samples + 10)
+                    else:
+                        note.stationary_count = max(0, note.stationary_count - 2)
+                    
+                    # Only quantize when stationary (or always if hold_mode is "off")
+                    should_quantize = hold_mode == "off" or note.stationary_count >= stationary_samples
+                    
+                    if should_quantize:
+                        semitones = bend_val / semitone
+                        bias = self.options.whole_tone_bias
+                        
+                        if bias == 0:
+                            nearest = round(semitones)
+                        else:
+                            # Biased rounding to compensate for mechanical/surface differences
+                            floor_semi = int(semitones) if semitones >= 0 else int(semitones) - 1
+                            frac = semitones - floor_semi
+                            
+                            # Even floor = whole tone (pad center), Odd = semitone (between pads)
+                            if floor_semi % 2 == 0:
+                                threshold = 0.5 + bias
+                            else:
+                                threshold = 0.5 - bias
+                            
+                            threshold = max(0.05, min(0.95, threshold))
+                            nearest = floor_semi + 1 if frac >= threshold else floor_semi
+                        
+                        bend_val = nearest * semitone
+                
                 data[1], data[2] = compose_pitch_bend(bend_val)
 
                 if self.is_split():
@@ -1401,6 +1465,14 @@ def __init__(self):
             opts, "bend_scale", DEFAULT_OPTIONS.bend_scale
         )
 
+        # Software chromatic quantization (12-TET)
+        self.options.chromatic_quantize = get_option(
+            opts, "chromatic_quantize", DEFAULT_OPTIONS.chromatic_quantize
+        )
+        self.options.whole_tone_bias = get_option(
+            opts, "whole_tone_bias", DEFAULT_OPTIONS.whole_tone_bias
+        )
+
         # self.options.mpe = get_option(
         #     opts, "mpe", DEFAULT_OPTIONS.mpe
         # ) or get_option(

src/note.py

@@ -14,6 +14,11 @@ def __init__(self):
         # apply additional bend?
         self.bend = 0.0
         self.y_bend = 0.0
+        
+        # Quantize hold state (for movement detection)
+        self.last_bend = 0.0      # previous bend value
+        self.rate_x = 0.0         # exponential moving average of bend change rate
+        self.stationary_count = 0 # how many samples we've been stationary
 
     # def logic(self, dt):
     #     if self.pressed:  # pressed, fade to pressure value

src/settings.py

@@ -109,5 +109,29 @@ class Settings:
     # octave splitting the linn and transposing octaves on the right side
     octave_split: int = 0
 
+    # Software chromatic quantization (12-TET)
+    # Snaps pitch bends to nearest semitone, allowing semitones between whole-tone pads.
+    # Without quantization, every note has slight microtonal errors from human imprecision.
+    # At this pad scale, you can only realistically aim for semitones or whole tones.
+    # Hardware quantization only snaps to pad centers (whole tones), missing semitones.
+    # This software quantization snaps to ALL 12 chromatic semitones.
+    # REQUIRED: Set LinnStrument Quantize=OFF, Quantize Tap=OFF, Quantize Hold=OFF
+    chromatic_quantize: bool = False
+    
+    # Whole tone bias: adjusts the rounding threshold between semitones and whole tones.
+    # Range: -1.0 to 1.0
+    #   0.0 = equal zones (50/50 split, standard rounding at 0.5 threshold)
+    #   Positive = larger whole-tone zones (need to aim closer to center to hit semitones)
+    #   Negative = larger semitone zones (easier to hit semitones accidentally)
+    # Recommended: 0.4375 for LinnStrument speed bump surface
+    whole_tone_bias: float = 0.0
+    
+    # Quantize Hold: movement detection for vibrato support
+    # When moving (vibrato): allow microtones to pass through
+    # When stationary: snap to nearest semitone
+    # Modes: "off" = always snap, "fast" = quick snap, "medium" = balanced, "slow" = gradual
+    # Based on LinnStrument firmware Quan Hold behavior
+    quantize_hold: str = "medium"
+
 DEFAULT_OPTIONS = Settings()
 

src/util.py

@@ -129,3 +129,6 @@ def get_color(col):
     if col.startswith("#"):
         return webcolors.hex_to_rgb(col)
     return webcolors.name_to_rgb(col)
+
+
+