livepilot 1.9.9 → 1.9.12

package/mcp_server/tools/analyzer.py

@@ -10,7 +10,7 @@ import os
 
 from fastmcp import Context
 
-from ..server import mcp
+from ..server import mcp, _identify_port_holder
 
 CAPTURE_DIR = os.path.expanduser("~/Documents/LivePilot/captures")
 
@@ -19,7 +19,10 @@ def _get_spectral(ctx: Context):
     """Get SpectralCache from lifespan context."""
     cache = ctx.lifespan_context.get("spectral")
     if not cache:
-        raise RuntimeError("Spectral cache not initialized")
+        raise ValueError("Spectral cache not initialized — restart the MCP server")
+    # Keep the active request context attached so analyzer error paths can
+    # distinguish "device missing" from "bridge disconnected".
+    setattr(cache, "_livepilot_ctx", ctx)
     return cache
 
 
@@ -27,13 +30,46 @@ def _get_m4l(ctx: Context):
     """Get M4LBridge from lifespan context."""
     bridge = ctx.lifespan_context.get("m4l")
     if not bridge:
-        raise RuntimeError("M4L bridge not initialized")
+        raise ValueError("M4L bridge not initialized — restart the MCP server")
     return bridge
 
 
 def _require_analyzer(cache) -> None:
     """Raise a helpful error if the analyzer is not connected."""
     if not cache.is_connected:
+        ctx = getattr(cache, "_livepilot_ctx", None)
+        try:
+            track = (
+                ctx.lifespan_context["ableton"].send_command("get_master_track")
+                if ctx else {}
+            )
+        except Exception:
+            track = {}
+
+        devices = track.get("devices", []) if isinstance(track, dict) else []
+        analyzer_loaded = False
+        for device in devices:
+            normalized = " ".join(
+                str(device.get("name") or "").replace("_", " ").replace("-", " ").lower().split()
+            )
+            if normalized == "livepilot analyzer":
+                analyzer_loaded = True
+                break
+
+        if analyzer_loaded:
+            holder = _identify_port_holder(9880)
+            detail = (
+                "LivePilot Analyzer is loaded on the master track, but its UDP bridge is not connected. "
+            )
+            if holder:
+                detail += (
+                    "UDP port 9880 is currently held by another LivePilot instance "
+                    f"({holder}). Close the other client/server, then retry."
+                )
+            else:
+                detail += "Reload the analyzer device or restart the MCP server."
+            raise ValueError(detail)
+
         raise ValueError(
             "LivePilot Analyzer not detected. "
             "Drag 'LivePilot Analyzer' onto the master track from "
@@ -140,7 +176,7 @@ async def get_hidden_parameters(
     cache = _get_spectral(ctx)
     _require_analyzer(cache)
     bridge = _get_m4l(ctx)
-    return await bridge.send_command("get_hidden_params", track_index, device_index)
+    return await bridge.send_command("get_hidden_params", track_index, device_index, timeout=15.0)
 
 
 @mcp.tool()
@@ -161,7 +197,7 @@ async def get_automation_state(
     cache = _get_spectral(ctx)
     _require_analyzer(cache)
     bridge = _get_m4l(ctx)
-    return await bridge.send_command("get_auto_state", track_index, device_index)
+    return await bridge.send_command("get_auto_state", track_index, device_index, timeout=10.0)
 
 
 @mcp.tool()
@@ -267,25 +303,34 @@ async def load_sample_to_simpler(
 
     # Step 1: Load a sample from the browser to create Simpler with content
     ableton = ctx.lifespan_context["ableton"]
-    search = ableton.send_command("search_browser", {
-        "path": "samples",
-        "name_filter": "kick",
-        "loadable_only": True,
-        "max_results": 1,
-    })
+    try:
+        search = ableton.send_command("search_browser", {
+            "path": "samples",
+            "name_filter": "kick",
+            "loadable_only": True,
+            "max_results": 1,
+        })
+    except Exception as exc:
+        return {"error": f"Browser search failed: {exc}"}
     results = search.get("results", [])
     if not results:
         return {"error": "No samples found in browser to bootstrap Simpler"}
 
     # Load the dummy sample — Ableton auto-creates Simpler
     uri = results[0]["uri"]
-    ableton.send_command("load_browser_item", {
-        "track_index": track_index,
-        "uri": uri,
-    })
+    try:
+        ableton.send_command("load_browser_item", {
+            "track_index": track_index,
+            "uri": uri,
+        })
+    except Exception as exc:
+        return {"error": f"Failed to load bootstrap sample: {exc}"}
 
     # Step 2: Find the newly created device (it's at the end of the chain)
-    track_info = ableton.send_command("get_track_info", {"track_index": track_index})
+    try:
+        track_info = ableton.send_command("get_track_info", {"track_index": track_index})
+    except Exception as exc:
+        return {"error": f"Failed to read track after loading sample: {exc}"}
     actual_device_index = len(track_info.get("devices", [])) - 1
     if actual_device_index < 0:
         actual_device_index = 0
@@ -515,7 +560,7 @@ async def get_display_values(
     cache = _get_spectral(ctx)
     _require_analyzer(cache)
     bridge = _get_m4l(ctx)
-    return await bridge.send_command("get_display_values", track_index, device_index)
+    return await bridge.send_command("get_display_values", track_index, device_index, timeout=15.0)
 
 
 # ── Phase 3: Audio Capture ─────────────────────────────────────────────
@@ -545,7 +590,18 @@ async def capture_audio(
     if source not in ("master",):
         raise ValueError(f"Unsupported source '{source}'. Valid: 'master'")
 
+    # Sanitize filename — strip directory components to prevent path traversal
+    if filename:
+        safe_name = os.path.basename(filename)
+        if not safe_name or safe_name != filename:
+            raise ValueError(
+                f"Filename must not contain path separators or '..' segments: {filename!r}"
+            )
+        filename = safe_name
+
     bridge = _get_m4l(ctx)
+    # Ensure captures directory exists before sending to bridge
+    os.makedirs(CAPTURE_DIR, exist_ok=True)
     duration_ms = duration_seconds * 1000
     result = await bridge.send_capture(
         "capture_audio",
@@ -568,7 +624,7 @@ async def capture_stop(ctx: Context) -> dict:
     _require_analyzer(cache)
     bridge = _get_m4l(ctx)
     # Cancel the capture future so send_capture doesn't hang forever
-    bridge.cancel_capture_future()
+    await bridge.cancel_capture_future()
     return await bridge.send_command("capture_stop")
 
 

package/mcp_server/tools/arrangement.py

@@ -162,7 +162,10 @@ def add_arrangement_notes(
     _validate_track_index(track_index)
     _validate_clip_index(clip_index)
     if isinstance(notes, str):
-        notes = json.loads(notes)
+        try:
+            notes = json.loads(notes)
+        except json.JSONDecodeError as exc:
+            raise ValueError(f"Invalid JSON in notes parameter: {exc}") from exc
     for note in notes:
         _validate_note(note)
     return _get_ableton(ctx).send_command("add_arrangement_notes", {
@@ -206,7 +209,10 @@ def set_arrangement_automation(
     if parameter_type == "send" and send_index is None:
         raise ValueError("send_index required for parameter_type='send'")
     if isinstance(points, str):
-        points = json.loads(points)
+        try:
+            points = json.loads(points)
+        except json.JSONDecodeError as exc:
+            raise ValueError(f"Invalid JSON in points parameter: {exc}") from exc
     if not points:
         raise ValueError("points list cannot be empty")
     params: dict = {
@@ -352,7 +358,10 @@ def remove_arrangement_notes_by_id(
     _validate_track_index(track_index)
     _validate_clip_index(clip_index)
     if isinstance(note_ids, str):
-        note_ids = json.loads(note_ids)
+        try:
+            note_ids = json.loads(note_ids)
+        except json.JSONDecodeError as exc:
+            raise ValueError(f"Invalid JSON in note_ids parameter: {exc}") from exc
     if not note_ids:
         raise ValueError("note_ids list cannot be empty")
     return _get_ableton(ctx).send_command("remove_arrangement_notes_by_id", {
@@ -374,7 +383,10 @@ def modify_arrangement_notes(
     _validate_track_index(track_index)
     _validate_clip_index(clip_index)
     if isinstance(modifications, str):
-        modifications = json.loads(modifications)
+        try:
+            modifications = json.loads(modifications)
+        except json.JSONDecodeError as exc:
+            raise ValueError(f"Invalid JSON in modifications parameter: {exc}") from exc
     if not modifications:
         raise ValueError("modifications list cannot be empty")
     for mod in modifications:
@@ -407,7 +419,10 @@ def duplicate_arrangement_notes(
     _validate_track_index(track_index)
     _validate_clip_index(clip_index)
     if isinstance(note_ids, str):
-        note_ids = json.loads(note_ids)
+        try:
+            note_ids = json.loads(note_ids)
+        except json.JSONDecodeError as exc:
+            raise ValueError(f"Invalid JSON in note_ids parameter: {exc}") from exc
     if not note_ids:
         raise ValueError("note_ids list cannot be empty")
     return _get_ableton(ctx).send_command("duplicate_arrangement_notes", {

package/mcp_server/tools/automation.py

@@ -22,7 +22,10 @@ def _get_ableton(ctx: Context):
 def _ensure_list(v: Any) -> list:
     if isinstance(v, str):
         import json
-        return json.loads(v)
+        try:
+            return json.loads(v)
+        except json.JSONDecodeError as exc:
+            raise ValueError(f"Invalid JSON in parameter: {exc}") from exc
     if isinstance(v, list):
         return v
     return [v]
@@ -40,6 +43,10 @@ def get_clip_automation(
     parameter name, and type (mixer/send/device). Use this to see
     what's already automated before writing new curves.
     """
+    if track_index < 0:
+        raise ValueError("track_index must be >= 0")
+    if clip_index < 0:
+        raise ValueError("clip_index must be >= 0")
     return _get_ableton(ctx).send_command("get_clip_automation", {
         "track_index": track_index,
         "clip_index": clip_index,
@@ -69,6 +76,17 @@ def set_clip_automation(
     Tip: Use apply_automation_shape to generate points from curves/recipes
     instead of calculating points manually.
     """
+    if track_index < 0:
+        raise ValueError("track_index must be >= 0")
+    if clip_index < 0:
+        raise ValueError("clip_index must be >= 0")
+    if parameter_type not in ("device", "volume", "panning", "send"):
+        raise ValueError("parameter_type must be 'device', 'volume', 'panning', or 'send'")
+    if parameter_type == "device":
+        if device_index is None or parameter_index is None:
+            raise ValueError("device_index and parameter_index required for parameter_type='device'")
+    if parameter_type == "send" and send_index is None:
+        raise ValueError("send_index required for parameter_type='send'")
     params: dict = {
         "track_index": track_index,
         "clip_index": clip_index,
@@ -99,11 +117,22 @@ def clear_clip_automation(
     If parameter_type is omitted, clears ALL envelopes.
     If provided, clears only that parameter's envelope.
     """
+    if track_index < 0:
+        raise ValueError("track_index must be >= 0")
+    if clip_index < 0:
+        raise ValueError("clip_index must be >= 0")
     params: dict = {
         "track_index": track_index,
         "clip_index": clip_index,
     }
     if parameter_type is not None:
+        if parameter_type not in ("device", "volume", "panning", "send"):
+            raise ValueError("parameter_type must be 'device', 'volume', 'panning', or 'send'")
+        if parameter_type == "device":
+            if device_index is None or parameter_index is None:
+                raise ValueError("device_index and parameter_index required for parameter_type='device'")
+        if parameter_type == "send" and send_index is None:
+            raise ValueError("send_index required for parameter_type='send'")
         params["parameter_type"] = parameter_type
     if device_index is not None:
         params["device_index"] = device_index
@@ -187,6 +216,19 @@ def apply_automation_shape(
     - Throws: use spike with short duration (1-2 beats)
     - Tremolo/pan: use sine with frequency in musical divisions
     """
+    # Validate indices and parameter_type (same rules as set_clip_automation)
+    if track_index < 0:
+        raise ValueError("track_index must be >= 0")
+    if clip_index < 0:
+        raise ValueError("clip_index must be >= 0")
+    if parameter_type not in ("device", "volume", "panning", "send"):
+        raise ValueError("parameter_type must be 'device', 'volume', 'panning', or 'send'")
+    if parameter_type == "device":
+        if device_index is None or parameter_index is None:
+            raise ValueError("device_index and parameter_index required for parameter_type='device'")
+    if parameter_type == "send" and send_index is None:
+        raise ValueError("send_index required for parameter_type='send'")
+
     # Generate the curve
     points = generate_curve(
         curve_type=curve_type,
@@ -269,6 +311,19 @@ def apply_automation_recipe(
     - vinyl_crackle: slow bit reduction movement
     - stereo_narrow: collapse to mono before drop
     """
+    # Validate indices and parameter_type (same rules as set_clip_automation)
+    if track_index < 0:
+        raise ValueError("track_index must be >= 0")
+    if clip_index < 0:
+        raise ValueError("clip_index must be >= 0")
+    if parameter_type not in ("device", "volume", "panning", "send"):
+        raise ValueError("parameter_type must be 'device', 'volume', 'panning', or 'send'")
+    if parameter_type == "device":
+        if device_index is None or parameter_index is None:
+            raise ValueError("device_index and parameter_index required for parameter_type='device'")
+    if parameter_type == "send" and send_index is None:
+        raise ValueError("send_index required for parameter_type='send'")
+
     points = generate_from_recipe(recipe, duration=duration, density=density)
 
     if time_offset > 0:

package/mcp_server/tools/devices.py

@@ -10,13 +10,16 @@ from typing import Any, Optional
 
 from fastmcp import Context
 
-from ..server import mcp
+from ..server import mcp, _identify_port_holder
 
 
 def _ensure_list(value: Any) -> list:
     """Parse JSON strings into lists. MCP clients may serialize list params as strings."""
     if isinstance(value, str):
-        return json.loads(value)
+        try:
+            return json.loads(value)
+        except json.JSONDecodeError as exc:
+            raise ValueError(f"Invalid JSON in parameter: {exc}") from exc
     return value
 
 
@@ -26,16 +29,162 @@ def _get_ableton(ctx: Context):
 
 
 MASTER_TRACK_INDEX = -1000
+_PLUGIN_CLASS_NAMES = {"PluginDevice", "AuPluginDevice"}
+_SAMPLE_DEPENDENT_DEVICE_NAMES = {
+    "idensity": "Requires source audio loaded inside the plugin UI before MIDI can produce sound.",
+    "tardigrain": "Requires source audio loaded inside the plugin UI before MIDI can produce sound.",
+    "koala sampler": "Requires source audio loaded inside the plugin UI before MIDI can produce sound.",
+    "burns audio granular": "Requires source audio loaded inside the plugin UI before MIDI can produce sound.",
+    "audiolayer": "Requires samples loaded inside the plugin UI before MIDI can produce sound.",
+    "segments": "Requires source audio loaded inside the plugin UI before MIDI can produce sound.",
+    "segments (instr)": "Requires source audio loaded inside the plugin UI before MIDI can produce sound.",
+}
+
+
+def _sample_dependency_reason(device_name: str) -> Optional[str]:
+    lowered = device_name.strip().lower()
+    for candidate, reason in _SAMPLE_DEPENDENT_DEVICE_NAMES.items():
+        if candidate in lowered:
+            return reason
+    return None
+
+
+def _annotate_device_info(result: dict) -> dict:
+    """Attach MCP-focused health hints to raw get_device_info results."""
+    if not isinstance(result, dict):
+        return result
+
+    class_name = str(result.get("class_name") or "")
+    device_name = str(result.get("name") or "")
+    parameter_count = int(result.get("parameter_count") or 0)
+    is_plugin = class_name in _PLUGIN_CLASS_NAMES
+
+    plugin_host_status = "not_plugin"
+    if is_plugin:
+        plugin_host_status = "host_visible" if parameter_count > 1 else "opaque_or_failed"
+
+    flags: list[str] = []
+    warnings: list[str] = []
+
+    sample_reason = _sample_dependency_reason(device_name)
+    if sample_reason:
+        flags.append("sample_dependent")
+        warnings.append(sample_reason)
+
+    if plugin_host_status == "opaque_or_failed":
+        flags.append("opaque_or_failed_plugin")
+        warnings.append(
+            "Ableton only sees %d host parameter(s) for this plugin. "
+            "If auditioning produces no audio, the plugin likely failed to initialize. "
+            "If audio is flowing, the plugin is usable but opaque to MCP sound design."
+            % parameter_count
+        )
+
+    annotated = dict(result)
+    annotated["is_plugin"] = is_plugin
+    annotated["plugin_host_status"] = plugin_host_status
+    annotated["health_flags"] = flags
+    annotated["mcp_sound_design_ready"] = len(flags) == 0
+    if warnings:
+        annotated["warnings"] = warnings
+    return annotated
+
+
+def _annotate_loaded_device_result(result: dict) -> dict:
+    """Attach preflight warnings to load results based on loaded device names."""
+    if not isinstance(result, dict):
+        return result
+
+    loaded_name = str(result.get("loaded") or "")
+    sample_reason = _sample_dependency_reason(loaded_name)
+    if not sample_reason:
+        return result
+
+    annotated = dict(result)
+    annotated["health_flags"] = ["sample_dependent"]
+    annotated["warnings"] = [sample_reason]
+    annotated["mcp_sound_design_ready"] = False
+    return annotated
+
+
+def _merge_unique(base: list[str], extra: list[str]) -> list[str]:
+    merged = list(base)
+    for item in extra:
+        if item not in merged:
+            merged.append(item)
+    return merged
+
+
+def _postflight_loaded_device(ctx: Context, result: dict) -> dict:
+    """Attach post-load health info by inspecting the newly loaded device."""
+    annotated = _annotate_loaded_device_result(result)
+    if not isinstance(annotated, dict):
+        return annotated
+
+    track_index = annotated.get("track_index")
+    loaded_name = str(annotated.get("loaded") or "")
+    if track_index is None or not loaded_name:
+        return annotated
+
+    try:
+        track_info = _get_ableton(ctx).send_command("get_track_info", {
+            "track_index": int(track_index),
+        })
+    except Exception:
+        return annotated
+
+    devices = track_info.get("devices", []) if isinstance(track_info, dict) else []
+    if not isinstance(devices, list) or not devices:
+        return annotated
+
+    match = None
+    for device in reversed(devices):
+        if str(device.get("name") or "") == loaded_name:
+            match = device
+            break
+    if match is None:
+        match = devices[-1]
+
+    device_info = _annotate_device_info({
+        "name": match.get("name"),
+        "class_name": match.get("class_name"),
+        "is_active": match.get("is_active"),
+        "parameter_count": len(match.get("parameters", [])),
+    })
+
+    merged = dict(annotated)
+    merged["device_index"] = match.get("index")
+    merged["class_name"] = device_info.get("class_name")
+    merged["parameter_count"] = device_info.get("parameter_count")
+    merged["is_plugin"] = device_info.get("is_plugin")
+    merged["plugin_host_status"] = device_info.get("plugin_host_status")
+    merged["mcp_sound_design_ready"] = (
+        merged.get("mcp_sound_design_ready", True)
+        and device_info.get("mcp_sound_design_ready", True)
+    )
+
+    merged["health_flags"] = _merge_unique(
+        annotated.get("health_flags", []),
+        device_info.get("health_flags", []),
+    )
+
+    warnings = _merge_unique(
+        annotated.get("warnings", []),
+        device_info.get("warnings", []),
+    )
+    if warnings:
+        merged["warnings"] = warnings
+
+    return merged
 
 
 def _validate_track_index(track_index: int):
     if track_index < 0 and track_index != MASTER_TRACK_INDEX:
-        if track_index < -100:
+        if not (-99 <= track_index <= -1):
             raise ValueError(
                 "track_index must be >= 0 for regular tracks, "
-                "negative for return tracks (-1=A, -2=B), or -1000 for master"
+                "-1..-99 for return tracks (-1=A, -2=B), or -1000 for master"
             )
-        # Negative values -1..-99 are valid return track indices
 
 
 def _validate_device_index(device_index: int):
@@ -54,10 +203,11 @@ def get_device_info(ctx: Context, track_index: int, device_index: int) -> dict:
     track_index: 0+ for regular tracks, -1/-2/... for return tracks (A/B/...), -1000 for master."""
     _validate_track_index(track_index)
     _validate_device_index(device_index)
-    return _get_ableton(ctx).send_command("get_device_info", {
+    result = _get_ableton(ctx).send_command("get_device_info", {
         "track_index": track_index,
         "device_index": device_index,
     })
+    return _annotate_device_info(result)
 
 
 @mcp.tool()
@@ -157,10 +307,11 @@ def load_device_by_uri(ctx: Context, track_index: int, uri: str) -> dict:
     _validate_track_index(track_index)
     if not uri.strip():
         raise ValueError("URI cannot be empty")
-    return _get_ableton(ctx).send_command("load_device_by_uri", {
+    result = _get_ableton(ctx).send_command("load_device_by_uri", {
         "track_index": track_index,
         "uri": uri,
     })
+    return _postflight_loaded_device(ctx, result)
 
 
 @mcp.tool()
@@ -170,10 +321,11 @@ def find_and_load_device(ctx: Context, track_index: int, device_name: str) -> di
     _validate_track_index(track_index)
     if not device_name.strip():
         raise ValueError("device_name cannot be empty")
-    return _get_ableton(ctx).send_command("find_and_load_device", {
+    result = _get_ableton(ctx).send_command("find_and_load_device", {
         "track_index": track_index,
         "device_name": device_name,
     })
+    return _postflight_loaded_device(ctx, result)
 
 
 @mcp.tool()
@@ -263,7 +415,7 @@ def _get_m4l(ctx: Context):
     """Get M4LBridge from lifespan context."""
     bridge = ctx.lifespan_context.get("m4l")
     if not bridge:
-        raise RuntimeError("M4L bridge not initialized")
+        raise ValueError("M4L bridge not initialized — restart the MCP server")
     return bridge
 
 
@@ -271,12 +423,48 @@ def _get_spectral(ctx: Context):
     """Get SpectralCache from lifespan context."""
     cache = ctx.lifespan_context.get("spectral")
     if not cache:
-        raise RuntimeError("Spectral cache not initialized")
+        raise ValueError("Spectral cache not initialized — restart the MCP server")
+    # Keep the active request context attached so analyzer error paths can
+    # distinguish "device missing" from "bridge disconnected".
+    setattr(cache, "_livepilot_ctx", ctx)
     return cache
 
 
 def _require_analyzer(cache) -> None:
     if not cache.is_connected:
+        ctx = getattr(cache, "_livepilot_ctx", None)
+        try:
+            track = (
+                ctx.lifespan_context["ableton"].send_command("get_master_track")
+                if ctx else {}
+            )
+        except Exception:
+            track = {}
+
+        devices = track.get("devices", []) if isinstance(track, dict) else []
+        analyzer_loaded = False
+        for device in devices:
+            normalized = " ".join(
+                str(device.get("name") or "").replace("_", " ").replace("-", " ").lower().split()
+            )
+            if normalized == "livepilot analyzer":
+                analyzer_loaded = True
+                break
+
+        if analyzer_loaded:
+            holder = _identify_port_holder(9880)
+            detail = (
+                "LivePilot Analyzer is loaded on the master track, but its UDP bridge is not connected. "
+            )
+            if holder:
+                detail += (
+                    "UDP port 9880 is currently held by another LivePilot instance "
+                    f"({holder}). Close the other client/server, then retry."
+                )
+            else:
+                detail += "Reload the analyzer device or restart the MCP server."
+            raise ValueError(detail)
+
         raise ValueError(
             "LivePilot Analyzer not detected. "
             "Drag 'LivePilot Analyzer' onto the master track."
@@ -302,7 +490,7 @@ async def get_plugin_parameters(
     cache = _get_spectral(ctx)
     _require_analyzer(cache)
     bridge = _get_m4l(ctx)
-    return await bridge.send_command("get_plugin_params", track_index, device_index)
+    return await bridge.send_command("get_plugin_params", track_index, device_index, timeout=20.0)
 
 
 @mcp.tool()
@@ -326,7 +514,7 @@ async def map_plugin_parameter(
     cache = _get_spectral(ctx)
     _require_analyzer(cache)
     bridge = _get_m4l(ctx)
-    return await bridge.send_command("map_plugin_param", track_index, device_index, parameter_index)
+    return await bridge.send_command("map_plugin_param", track_index, device_index, parameter_index, timeout=10.0)
 
 
 @mcp.tool()
@@ -346,4 +534,4 @@ async def get_plugin_presets(
     cache = _get_spectral(ctx)
     _require_analyzer(cache)
     bridge = _get_m4l(ctx)
-    return await bridge.send_command("get_plugin_presets", track_index, device_index)
+    return await bridge.send_command("get_plugin_presets", track_index, device_index, timeout=15.0)

package/mcp_server/tools/generative.py

@@ -17,7 +17,10 @@ from . import _theory_engine as theory
 
 def _ensure_list(value: Any) -> list:
     if isinstance(value, str):
-        return json.loads(value)
+        try:
+            return json.loads(value)
+        except json.JSONDecodeError as exc:
+            raise ValueError(f"Invalid JSON in parameter: {exc}") from exc
     return value
 
 
@@ -91,6 +94,10 @@ def layer_euclidean_rhythms(
     for layer in layers:
         p = int(layer["pulses"])
         s = int(layer["steps"])
+        if s < 1 or s > 64:
+            raise ValueError(f"steps must be between 1 and 64, got {s}")
+        if p < 0 or p > s:
+            raise ValueError(f"pulses must be between 0 and steps ({s}), got {p}")
         rot = int(layer.get("rotation", 0))
         pitch = int(layer["pitch"])
         vel = int(layer.get("velocity", 100))