livepilot 1.27.1 → 1.27.3

package/remote_script/LivePilot/__init__.py

@@ -5,7 +5,7 @@ Entry point for the ControlSurface. Ableton calls create_instance(c_instance)
 when this script is selected in Preferences > Link, Tempo & MIDI.
 """
 
-__version__ = "1.27.1"
+__version__ = "1.27.3"
 
 from _Framework.ControlSurface import ControlSurface
 from . import router
@@ -98,22 +98,28 @@ def _force_reload_handlers(cs=None):
         except Exception:
             pass
 
+    failures = []
+
     try:
         importlib.reload(router)
     except Exception as exc:
-        _log("reload(router) FAILED — %s: %s" % (type(exc).__name__, exc))
+        msg = "reload(router) FAILED — %s: %s" % (type(exc).__name__, exc)
+        _log(msg)
+        failures.append(("LivePilot.router", "%s: %s" % (type(exc).__name__, exc)))
 
     try:
         importlib.reload(utils)
     except Exception as exc:
-        _log("reload(utils) FAILED — %s: %s" % (type(exc).__name__, exc))
+        msg = "reload(utils) FAILED — %s: %s" % (type(exc).__name__, exc)
+        _log(msg)
+        failures.append(("LivePilot.utils", "%s: %s" % (type(exc).__name__, exc)))
 
     # Invalidate caches so iter_modules sees newly-added files even if
     # an importer cached the previous directory listing.
     importlib.invalidate_caches()
     pkg = _sys.modules.get("LivePilot")
     if pkg is None or getattr(pkg, "__path__", None) is None:
-        return
+        return {"discovered": 0, "reloaded": 0, "first_imported": 0, "failures": failures}
 
     discovered = reloaded = first_imported = 0
     for _finder, modname, _is_pkg in pkgutil.iter_modules(pkg.__path__):
@@ -130,8 +136,9 @@ def _force_reload_handlers(cs=None):
                 importlib.import_module(full_name)
                 first_imported += 1
         except Exception as exc:
-            _log("reload(%s) FAILED — %s: %s" % (
-                full_name, type(exc).__name__, exc))
+            msg = "reload(%s) FAILED — %s: %s" % (full_name, type(exc).__name__, exc)
+            _log(msg)
+            failures.append((full_name, "%s: %s" % (type(exc).__name__, exc)))
 
     # reload_handlers_cmd lives in __init__.py (not a handler module),
     # so the step-3 loop does not cover it. Re-register manually.
@@ -140,15 +147,21 @@ def _force_reload_handlers(cs=None):
     _log("reload complete — %d discovered (%d reloaded, %d first-imported)" % (
         discovered, reloaded, first_imported))
 
+    return {"discovered": discovered, "reloaded": reloaded,
+            "first_imported": first_imported, "failures": failures}
+
 
 def reload_handlers_cmd(song, params):
     """TCP-accessible reload trigger. Lets automation refresh handlers
     without a UI Control Surface toggle — the core dev-loop improvement.
-    Returns the handler count so the caller can assert before/after."""
-    _force_reload_handlers(cs=None)
+    Returns the handler count so the caller can assert before/after.
+    Returns any reload failures so the caller can detect silent errors."""
+    result = _force_reload_handlers(cs=None)
+    failures = result.get("failures", []) if isinstance(result, dict) else []
     return {
         "reloaded": True,
         "handler_count": len(router._handlers),
+        "errors": [{"module": m, "error": e} for m, e in failures],
     }
 
 

package/remote_script/LivePilot/arrangement.py

@@ -47,7 +47,12 @@ def create_arrangement_clip(song, params):
 
     Uses Live 12's Track.duplicate_clip_to_arrangement(clip, time) API.
     When the requested length exceeds the source clip, multiple adjacent
-    copies are placed to fill the timeline region seamlessly.
+    copies are placed to fill the timeline region seamlessly. Copies are
+    tiled every min(loop_length, source_length) beats so that a
+    loop_length larger than the source never leaves a silent gap between
+    copies. loop_length sets the internal loop region only when
+    loop_length < source_length; when larger, copies tile by source_length
+    and each plays its full native content.
 
     Required: track_index, clip_slot_index, start_time, length
     Optional: loop_length (defaults to session clip length), name, color_index
@@ -83,40 +88,61 @@ def create_arrangement_clip(song, params):
     name = str(params.get("name", ""))
     color_index = params.get("color_index")
 
-    # Place adjacent copies to fill the requested length
+    # Tile the source across [start_time, end_pos). A single duplicate only
+    # carries `source_length` beats of content, so to fill the region
+    # seamlessly we step by `min(loop_length, source_length)` — stepping by a
+    # larger loop_length would leave a silent (loop_length - source_length)
+    # gap between copies (P2-54). loop_length sets the internal loop region
+    # only when loop_length < source_length; when larger, copies tile by
+    # source_length and each plays its full native content.
+    step = min(loop_length, source_length)
+    # A zero/negative effective step would make the tiling loop below never
+    # advance -> unbounded duplicate_clip_to_arrangement on Live's main thread
+    # = DAW hard-freeze. A source clip can report length 0 (LOM state), so
+    # floor the step into a clean structured error instead of looping forever.
+    if step <= 0:
+        raise ValueError(
+            "source clip has zero/invalid length; cannot tile arrangement copies")
     song.begin_undo_step()
     try:
         pos = start_time
         end_pos = start_time + length
         clip_count = 0
-        first_clip_index = None
+        # Record only the placement position per copy. We defer
+        # name/color/loop-region edits to a single post-loop pass below so
+        # the hot loop does NOT re-materialize the full arrangement_clips
+        # vector every iteration (was O(K^2) list builds + K linear scans —
+        # P2-52). duplicate_clip_to_arrangement places the new clip at `pos`,
+        # which is the key we use to find it once afterward.
+        placements = []  # list of (pos, target_len)
 
         while pos < end_pos:
             track.duplicate_clip_to_arrangement(source_clip, pos)
+            # When loop_length < source_length, only loop_length beats of
+            # content should play per copy; otherwise the copy plays its full
+            # source content (capped at the remaining region).
+            remaining = end_pos - pos
+            target_len = min(loop_length, remaining)
+            placements.append((pos, target_len))
+            clip_count += 1
+            pos += step
 
-            # Find the new clip by position (id()-based detection is unreliable
-            # because CPython can reuse addresses of GC'd LOM wrappers)
+        # Single post-loop pass: one list() materialization, then apply
+        # name/color/loop-region to each placed clip located by start_time.
+        if placements:
             arr_clips = list(track.arrangement_clips)
-            new_clip = None
-            new_clip_idx = None
-            for i, c in enumerate(arr_clips):
-                if abs(c.start_time - pos) < 0.01:
-                    new_clip = c
-                    new_clip_idx = i
-                    break
-
-            if new_clip is not None:
-                if first_clip_index is None:
-                    first_clip_index = new_clip_idx
+            # Index clips by rounded start_time for O(1) lookup.
+            by_start = {}
+            for c in arr_clips:
+                by_start.setdefault(round(c.start_time, 2), c)
+            for place_pos, target_len in placements:
+                new_clip = by_start.get(round(place_pos, 2))
+                if new_clip is None:
+                    continue
                 if name:
                     new_clip.name = name
                 if color_index is not None:
                     new_clip.color_index = int(color_index)
-
-                # When loop_length < source_length, set the internal
-                # loop region so only loop_length beats of content play.
-                remaining = end_pos - pos
-                target_len = min(loop_length, remaining)
                 if target_len < source_length:
                     try:
                         new_clip.looping = True
@@ -125,15 +151,21 @@ def create_arrangement_clip(song, params):
                     except (AttributeError, RuntimeError):
                         pass
 
-            clip_count += 1
-            pos += loop_length
-
         # Trim the last clip's overshoot: if the last duplicate extends
         # past end_pos, remove notes beyond the requested region and
         # set loop_end so only the needed portion plays.
+        #
+        # Restrict the scan to clips THIS call placed (matched by their
+        # placement start). Scanning all arrangement_clips would also match a
+        # pre-existing clip on the same track that happens to start at/after
+        # start_time and end past end_pos — trimming/removing notes from the
+        # user's existing content (silent data loss).
         if clip_count > 0:
+            placed_starts = {round(p, 2) for p, _ in placements}
             arr_clips = list(track.arrangement_clips)
             for c in arr_clips:
+                if round(c.start_time, 2) not in placed_starts:
+                    continue
                 clip_end = c.start_time + c.length
                 if c.start_time >= start_time and clip_end > end_pos + 0.01:
                     # This clip overshoots — trim its content
@@ -840,14 +872,33 @@ def force_arrangement(song, params):
         song.stop_playing()
 
     # 2. Stop playing clip slots individually to release session overrides
-    #    (track.stop_all_clips() throws STATE_ERROR when tracks have no clips)
-    for track in list(song.tracks) + list(song.return_tracks):
-        try:
-            for slot in track.clip_slots:
-                if slot.has_clip and slot.is_playing:
+    #    (track.stop_all_clips() throws STATE_ERROR when tracks have no clips).
+    #    §9c: a session clip that fails to stop re-asserts the override and
+    #    makes playback start mid-song, so genuine stop failures must NOT be
+    #    silently discarded — collect them and surface to the caller (P2-53).
+    stop_errors = []
+    # Only regular tracks hold session clips. Return tracks (and the master)
+    # cannot have clip slots — iterating their `clip_slots` raises
+    # AttributeError on the Live 12.4.x LOM, which would either crash this
+    # tool or (when guarded) inject one spurious stop-error per return track,
+    # forcing arrangement_active=False on a clean run and breaking the §9c
+    # finalize workflow. Session overrides only ever come from song.tracks.
+    for track_idx, track in enumerate(song.tracks):
+        for slot_idx, slot in enumerate(track.clip_slots):
+            try:
+                # ClipSlot.is_playing is not exposed on every Live build —
+                # guard it (mirrors the defensive read elsewhere in this file)
+                # so a missing attribute isn't logged as a spurious stop-error
+                # for every clip-bearing slot, which would force
+                # arrangement_active=False on a clean run (P2-53).
+                if slot.has_clip and getattr(slot, "is_playing", False):
                     slot.clip.stop()
-        except Exception:
-            pass
+            except Exception as exc:
+                stop_errors.append({
+                    "track": track_idx,
+                    "slot": slot_idx,
+                    "error": str(exc),
+                })
 
     # 3. Global back-to-arranger
     song.back_to_arranger = True
@@ -867,12 +918,21 @@ def force_arrangement(song, params):
     if play:
         song.start_playing()
 
-    return {
-        "arrangement_active": True,
+    # A clip that failed to stop may still be overriding the arrangement, so
+    # report partial failure rather than claiming unconditional success (P2-53).
+    result = {
+        "arrangement_active": not stop_errors,
         "position": song.current_song_time,
         "is_playing": song.is_playing,
         "loop": song.loop,
+        "stop_errors": stop_errors,
     }
+    if stop_errors:
+        result["warning"] = (
+            "%d session clip(s) failed to stop and may still override the "
+            "arrangement — playback could start mid-song" % len(stop_errors)
+        )
+    return result
 
 
 # ── Session-record arrangement automation (T5 workaround) ────────────

package/remote_script/LivePilot/browser.py

@@ -282,6 +282,10 @@ def load_browser_item(song, params):
                 "loaded": True,
                 "name": found.name,
                 "device_count": device_count,
+                # Live appends the loaded device at the END of the chain, so the
+                # just-loaded device is the last one. The MCP wrapper applies
+                # role-defaults / hygiene to THIS index (see tools/browser.py).
+                "device_index": device_count - 1 if device_count > 0 else 0,
             }
 
     # ── Strategy 2: extract name from URI, search by name ────────────
@@ -337,6 +341,8 @@ def load_browser_item(song, params):
                     "loaded": True,
                     "name": found.name,
                     "device_count": device_count,
+                    # Loaded device is appended last → its index is count-1.
+                    "device_index": device_count - 1 if device_count > 0 else 0,
                 }
 
         raise ValueError(
@@ -394,6 +400,10 @@ def load_browser_item(song, params):
                 "loaded": True,
                 "name": found.name,
                 "device_count": device_count,
+                # Live appends the loaded device at the END of the chain, so the
+                # just-loaded device is the last one. The MCP wrapper applies
+                # role-defaults / hygiene to THIS index (see tools/browser.py).
+                "device_index": device_count - 1 if device_count > 0 else 0,
             }
 
     raise ValueError(
@@ -401,6 +411,13 @@ def load_browser_item(song, params):
     )
 
 
+# Global safety bound on total LOM child-accesses across the ENTIRE scan
+# (all categories combined) — see P3-47. This used to reset per category
+# because `_counter` defaulted to a fresh [0] on every top-level
+# `_scan_recursive` call, so the real worst case was
+# _SCAN_MAX_ITERATIONS * len(categories) synchronous main-thread LOM
+# accesses. scan_browser_deep now threads a single shared counter through
+# every category's recursion so this constant is an honest total budget.
 _SCAN_MAX_ITERATIONS = 100000
 
 
@@ -438,22 +455,61 @@ def scan_browser_deep(song, params):
     Parameters
     ----------
     max_per_category : int, optional
-        Maximum items to collect per top-level category (default 1000).
+        Maximum items to collect per top-level category (default 25000).
+        Raised from the original 1000 (BUG-2026-06-21 #11 /
+        DEEP_REVIEW P1-11): a default of 1000 silently truncated large
+        alphabetically-ordered categories before reaching most of the
+        alphabet — e.g. drum_kits stopped at "Crash" (0 kicks, 2 hats),
+        and `sounds` stopped inside "Brass" (no Pads/Keys/Leads at all).
+        25000 comfortably covers every known category in the full
+        factory + pack library while `_SCAN_MAX_ITERATIONS` still bounds
+        worst-case main-thread work.
     max_depth : int, optional
         Maximum recursion depth into the browser tree (default 4).
+
+    Returns
+    -------
+    dict
+        ``categories``: ``{cat_name: [{"name", "uri", "is_loadable"}, ...]}``
+        ``counts``: ``{cat_name: <item count>}`` — per-category item counts,
+            always present so callers can detect truncation without
+            recomputing `len()` on the (potentially large) categories dict.
+        ``category_truncated``: ``{cat_name: bool}`` — True when a category
+            either hit `max_per_category` directly, OR the scan overall ran
+            out of its shared `_SCAN_MAX_ITERATIONS` iteration budget before
+            finishing that category (P3-47) — in both cases the category's
+            item list is a lower bound, not the true total.
     """
-    max_per_category = int(params.get("max_per_category", 1000))
+    max_per_category = int(params.get("max_per_category", 25000))
     max_depth = int(params.get("max_depth", 4))
     browser = _get_browser()
     categories = _get_categories(browser)
 
     result = {}
+    counts = {}
+    truncated = {}
+    # P3-47 fix: ONE counter object shared across every top-level category's
+    # _scan_recursive call, instead of a fresh [0] per category. This makes
+    # _SCAN_MAX_ITERATIONS a true global ceiling on main-thread LOM accesses
+    # for the whole scan_browser_deep call, not a per-category one.
+    shared_counter = [0]
     for cat_name, cat_item in categories.items():
         items = []
-        _scan_recursive(cat_item, items, 0, max_depth, max_per_category)
+        _scan_recursive(
+            cat_item, items, 0, max_depth, max_per_category, shared_counter
+        )
         result[cat_name] = items
+        counts[cat_name] = len(items)
+        truncated[cat_name] = (
+            len(items) >= max_per_category
+            or shared_counter[0] > _SCAN_MAX_ITERATIONS
+        )
 
-    return {"categories": result}
+    return {
+        "categories": result,
+        "counts": counts,
+        "category_truncated": truncated,
+    }
 
 
 @register("get_device_presets")

package/remote_script/LivePilot/devices.py

@@ -14,6 +14,30 @@ def _get_browser():
     return Live.Application.get_application().browser
 
 
+def _safe_value_string(param):
+    """Best-effort ``str_for_value`` readback that never raises.
+
+    Live raises RuntimeError("Invalid display value") from str_for_value on
+    Operator / Compressor2 / AutoFilter2 for some in-range values. On the
+    write path the ``param.value`` assignment has ALREADY landed before this
+    readback runs, so a raise here would convert a successful write into a
+    reported error (the agent then wrongly retries/undoes). Fall back to None
+    so a display-string failure never masks an applied write.
+    """
+    try:
+        return param.str_for_value(param.value)
+    except Exception:
+        return None
+
+
+def _safe_display_value(param):
+    """Best-effort ``display_value`` readback that never raises (see above)."""
+    try:
+        return param.display_value
+    except Exception:
+        return None
+
+
 @register("get_device_info")
 def get_device_info(song, params):
     """Return detailed info for a single device."""
@@ -118,24 +142,33 @@ def set_device_parameter(song, params):
         raise ValueError("Must provide parameter_name or parameter_index")
 
     param.value = value
+    # Readbacks are best-effort: the write above already landed, so a
+    # str_for_value / display_value failure must not surface a successful
+    # write as an error.
     result = {
         "name": param.name,
         "value": param.value,
-        "value_string": param.str_for_value(param.value),
+        "value_string": _safe_value_string(param),
         "min": param.min,
         "max": param.max,
+        "display_value": _safe_display_value(param),
     }
-    # 12.2+: include display_value
-    try:
-        result["display_value"] = param.display_value
-    except AttributeError:
-        pass
     return result
 
 
 @register("batch_set_parameters")
 def batch_set_parameters(song, params):
-    """Set multiple device parameters in one call."""
+    """Set multiple device parameters in one call.
+
+    Partial-success contract: LOM cannot truly roll back per-parameter
+    writes, so a mid-batch failure (typo'd name, out-of-range index) must
+    NOT abort the call and strand earlier writes as an opaque exception.
+    Instead every entry gets an ``{ok, ...}`` / ``{ok: False, error}`` result,
+    the whole loop is wrapped in one begin/end_undo_step so the applied
+    writes are a single undo unit, and the response reports ``applied`` /
+    ``failed`` counts plus a top-level ``ok`` that is True only if all
+    entries succeeded.
+    """
     track_index = int(params["track_index"])
     device_index = int(params["device_index"])
     parameters = params["parameters"]
@@ -144,58 +177,86 @@ def batch_set_parameters(song, params):
 
     dev_params = list(device.parameters)
     results = []
-    for entry in parameters:
-        value = float(entry["value"])
-        name_or_index = entry.get("name_or_index")
-
-        if isinstance(name_or_index, int) or (
-            isinstance(name_or_index, str) and name_or_index.isdigit()
-        ):
-            idx = int(name_or_index)
-            if idx < 0 or idx >= len(dev_params):
-                raise IndexError(
-                    "Parameter index %d out of range (0..%d)"
-                    % (idx, len(dev_params) - 1)
-                )
-            param = dev_params[idx]
-        else:
-            param = None
-            target = str(name_or_index)
-            # Try exact match first
-            for p in dev_params:
-                if p.name == target:
-                    param = p
-                    break
-            # Fallback: case-insensitive match
-            if param is None:
-                target_lower = target.lower()
-                for p in dev_params:
-                    if p.name.lower() == target_lower:
-                        param = p
-                        break
-            if param is None:
-                # List similar parameter names for debugging
-                available = [p.name for p in dev_params[:20]]
-                raise ValueError(
-                    "Parameter '%s' not found on device '%s'. "
-                    "Available (first 20): %s"
-                    % (name_or_index, device.name, ", ".join(available))
-                )
-
-        param.value = value
-        result_entry = {
-            "name": param.name,
-            "value": param.value,
-            "value_string": param.str_for_value(param.value),
-        }
-        # 12.2+: include display_value
-        try:
-            result_entry["display_value"] = param.display_value
-        except AttributeError:
-            pass
-        results.append(result_entry)
+    applied = 0
+    failed = 0
+    song.begin_undo_step()
+    try:
+        for entry in parameters:
+            name_or_index = entry.get("name_or_index")
+            try:
+                # A missing key would otherwise fall through to the name-search
+                # branch as str(None) == "None" and surface as a misleading
+                # "Parameter 'None' not found" — making the agent retry a
+                # phantom name instead of fixing the malformed entry.
+                if name_or_index is None:
+                    raise ValueError(
+                        "entry missing required 'name_or_index' key (got keys: %s)"
+                        % sorted(entry.keys())
+                    )
+                value = float(entry["value"])
+
+                if isinstance(name_or_index, int) or (
+                    isinstance(name_or_index, str) and name_or_index.isdigit()
+                ):
+                    idx = int(name_or_index)
+                    if idx < 0 or idx >= len(dev_params):
+                        raise IndexError(
+                            "Parameter index %d out of range (0..%d)"
+                            % (idx, len(dev_params) - 1)
+                        )
+                    param = dev_params[idx]
+                else:
+                    param = None
+                    target = str(name_or_index)
+                    # Try exact match first
+                    for p in dev_params:
+                        if p.name == target:
+                            param = p
+                            break
+                    # Fallback: case-insensitive match
+                    if param is None:
+                        target_lower = target.lower()
+                        for p in dev_params:
+                            if p.name.lower() == target_lower:
+                                param = p
+                                break
+                    if param is None:
+                        # List similar parameter names for debugging
+                        available = [p.name for p in dev_params[:20]]
+                        raise ValueError(
+                            "Parameter '%s' not found on device '%s'. "
+                            "Available (first 20): %s"
+                            % (name_or_index, device.name, ", ".join(available))
+                        )
+
+                param.value = value
+                # Readbacks are best-effort: the write already landed, so a
+                # str_for_value / display_value failure must not flip this
+                # entry to failed.
+                results.append({
+                    "ok": True,
+                    "name": param.name,
+                    "value": param.value,
+                    "value_string": _safe_value_string(param),
+                    "display_value": _safe_display_value(param),
+                })
+                applied += 1
+            except Exception as exc:
+                results.append({
+                    "ok": False,
+                    "name_or_index": name_or_index,
+                    "error": str(exc),
+                })
+                failed += 1
+    finally:
+        song.end_undo_step()
 
-    return {"parameters": results}
+    return {
+        "ok": failed == 0,
+        "applied": applied,
+        "failed": failed,
+        "parameters": results,
+    }
 
 
 @register("toggle_device")
@@ -1299,10 +1360,19 @@ def _get_wavetable(song, params):
     track = get_track(song, int(params["track_index"]))
     device = get_device(track, int(params["device_index"]))
     class_name = str(getattr(device, "class_name", ""))
-    if "Wavetable" not in class_name:
-        raise ValueError("Device at index %d is not Wavetable (class_name=%s)"
-                         % (int(params["device_index"]), class_name))
-    return device
+    # Fast path: explicit Wavetable class_name.
+    if "Wavetable" in class_name:
+        return device
+    # Ableton reports the Wavetable instrument as "InstrumentVector" in some
+    # Live versions.  Accept it only when a Wavetable-specific parameter
+    # ("Osc 1 Pos") is present so that M4L devices that also use the
+    # InstrumentVector class (e.g. Vector FM / Vector Grain) are rejected.
+    if class_name == "InstrumentVector":
+        param_names = {str(getattr(p, "name", "")) for p in getattr(device, "parameters", [])}
+        if any("Osc 1 Pos" in n for n in param_names):
+            return device
+    raise ValueError("Device at index %d is not Wavetable (class_name=%s)"
+                     % (int(params["device_index"]), class_name))
 
 
 @register("get_wavetable_mod_targets")

package/remote_script/LivePilot/mixing.py

@@ -426,6 +426,36 @@ def _collect_routing_diagnostic(device):
     return " | ".join(parts) if parts else "<none>"
 
 
+def _match_routing_type(available, source_type):
+    """Resolve a caller-supplied sidechain source against Live's routing menu.
+
+    Matching ladder (first hit wins):
+      1. Exact display-name match — preserves the "1-KICK" contract.
+      2. Case-insensitive exact match — Live 12.4 routing menus can show the
+         BARE track name with no index prefix ("Kick"), so a lowercase caller
+         ("kick") must still resolve. Found live 2026-07-10: the suffix
+         fallback below never fires for unprefixed display names.
+      3. Case-insensitive "-<name>" suffix match — callers (e.g. the
+         semantic-move compilers) may pass a bare track name while the menu
+         is index-prefixed ("1-Kick"); casefold both sides so "1-KICK" /
+         "1-Kick" / "1-kick" all resolve regardless of menu case convention.
+
+    Returns the matched routing object, or None.
+    """
+    for rt in available:
+        if rt.display_name == source_type:
+            return rt
+    want_cf = str(source_type).casefold()
+    for rt in available:
+        if rt.display_name.casefold() == want_cf:
+            return rt
+    suffix = "-" + want_cf
+    for rt in available:
+        if rt.display_name.casefold().endswith(suffix):
+            return rt
+    return None
+
+
 @register("set_compressor_sidechain")
 def set_compressor_sidechain(song, params):
     """Configure a Compressor's sidechain input routing (BUG-A3).
@@ -497,11 +527,7 @@ def set_compressor_sidechain(song, params):
 
     if want_type:
         available = surface["types"]
-        matched = None
-        for rt in available:
-            if rt.display_name == source_type:
-                matched = rt
-                break
+        matched = _match_routing_type(available, source_type)
         if matched is None:
             options = [rt.display_name for rt in available]
             raise ValueError(