livepilot 1.0.0

package/mcp_server/tools/mixing.py

@@ -0,0 +1,121 @@
+"""Mixing MCP tools — volume, pan, sends, routing, master.
+
+8 tools matching the Remote Script mixing domain.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from fastmcp import Context
+
+from ..server import mcp
+
+
+def _get_ableton(ctx: Context):
+    """Extract AbletonConnection from lifespan context."""
+    return ctx.lifespan_context["ableton"]
+
+
+def _validate_track_index(track_index: int):
+    if track_index < -100:
+        raise ValueError(
+            "track_index must be >= 0 for regular tracks, "
+            "or negative for return tracks (-1=A, -2=B)"
+        )
+    # Negative values -1..-99 are valid return track indices
+
+
+@mcp.tool()
+def set_track_volume(ctx: Context, track_index: int, volume: float) -> dict:
+    """Set a track's volume (0.0-1.0). Use negative track_index for return tracks (-1=A, -2=B)."""
+    _validate_track_index(track_index)
+    if not 0.0 <= volume <= 1.0:
+        raise ValueError("Volume must be between 0.0 and 1.0")
+    return _get_ableton(ctx).send_command("set_track_volume", {
+        "track_index": track_index,
+        "volume": volume,
+    })
+
+
+@mcp.tool()
+def set_track_pan(ctx: Context, track_index: int, pan: float) -> dict:
+    """Set a track's panning (-1.0 left to 1.0 right). Use negative track_index for return tracks (-1=A, -2=B)."""
+    _validate_track_index(track_index)
+    if not -1.0 <= pan <= 1.0:
+        raise ValueError("Pan must be between -1.0 and 1.0")
+    return _get_ableton(ctx).send_command("set_track_pan", {
+        "track_index": track_index,
+        "pan": pan,
+    })
+
+
+@mcp.tool()
+def set_track_send(
+    ctx: Context, track_index: int, send_index: int, value: float
+) -> dict:
+    """Set a send level on a track (0.0-1.0)."""
+    _validate_track_index(track_index)
+    if send_index < 0:
+        raise ValueError("send_index must be >= 0")
+    if not 0.0 <= value <= 1.0:
+        raise ValueError("Send value must be between 0.0 and 1.0")
+    return _get_ableton(ctx).send_command("set_track_send", {
+        "track_index": track_index,
+        "send_index": send_index,
+        "value": value,
+    })
+
+
+@mcp.tool()
+def get_return_tracks(ctx: Context) -> dict:
+    """Get info about all return tracks: name, volume, panning."""
+    return _get_ableton(ctx).send_command("get_return_tracks")
+
+
+@mcp.tool()
+def get_master_track(ctx: Context) -> dict:
+    """Get master track info: volume, panning, devices."""
+    return _get_ableton(ctx).send_command("get_master_track")
+
+
+@mcp.tool()
+def set_master_volume(ctx: Context, volume: float) -> dict:
+    """Set the master track volume (0.0-1.0)."""
+    if not 0.0 <= volume <= 1.0:
+        raise ValueError("Volume must be between 0.0 and 1.0")
+    return _get_ableton(ctx).send_command("set_master_volume", {"volume": volume})
+
+
+@mcp.tool()
+def get_track_routing(ctx: Context, track_index: int) -> dict:
+    """Get input/output routing info for a track. Use negative track_index for return tracks (-1=A, -2=B)."""
+    _validate_track_index(track_index)
+    return _get_ableton(ctx).send_command("get_track_routing", {
+        "track_index": track_index,
+    })
+
+
+@mcp.tool()
+def set_track_routing(
+    ctx: Context,
+    track_index: int,
+    input_type: Optional[str] = None,
+    input_channel: Optional[str] = None,
+    output_type: Optional[str] = None,
+    output_channel: Optional[str] = None,
+) -> dict:
+    """Set input/output routing for a track by display name. Use negative track_index for return tracks (-1=A, -2=B)."""
+    _validate_track_index(track_index)
+    params = {"track_index": track_index}
+    if input_type is not None:
+        params["input_type"] = input_type
+    if input_channel is not None:
+        params["input_channel"] = input_channel
+    if output_type is not None:
+        params["output_type"] = output_type
+    if output_channel is not None:
+        params["output_channel"] = output_channel
+    if len(params) == 1:
+        raise ValueError("At least one routing parameter must be provided")
+    return _get_ableton(ctx).send_command("set_track_routing", params)

package/mcp_server/tools/notes.py

@@ -0,0 +1,269 @@
+"""Notes MCP tools — add, get, remove, modify, duplicate, transpose, quantize.
+
+8 tools matching the Remote Script notes domain.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Optional
+
+from fastmcp import Context
+
+from ..server import mcp
+
+
+def _get_ableton(ctx: Context):
+    """Extract AbletonConnection from lifespan context."""
+    return ctx.lifespan_context["ableton"]
+
+
+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)
+    return value
+
+
+def _validate_track_index(track_index: int):
+    """Validate track index. Must be >= 0 for regular tracks."""
+    if track_index < 0:
+        raise ValueError("track_index must be >= 0")
+
+
+def _validate_clip_index(clip_index: int):
+    if clip_index < 0:
+        raise ValueError("clip_index must be >= 0")
+
+
+def _validate_note(note: dict):
+    """Validate a single note specification dict."""
+    pitch = note.get("pitch")
+    if pitch is None:
+        raise ValueError("Each note must have a 'pitch' field")
+    if not 0 <= int(pitch) <= 127:
+        raise ValueError("pitch must be between 0 and 127")
+
+    if "start_time" not in note:
+        raise ValueError("Each note must have a 'start_time' field")
+
+    duration = note.get("duration")
+    if duration is None:
+        raise ValueError("Each note must have a 'duration' field")
+    if float(duration) <= 0:
+        raise ValueError("duration must be > 0")
+
+    velocity = note.get("velocity")
+    if velocity is not None:
+        if not 0.0 <= float(velocity) <= 127.0:
+            raise ValueError("velocity must be between 0.0 and 127.0")
+
+    probability = note.get("probability")
+    if probability is not None:
+        if not 0.0 <= float(probability) <= 1.0:
+            raise ValueError("probability must be between 0.0 and 1.0")
+
+    velocity_deviation = note.get("velocity_deviation")
+    if velocity_deviation is not None:
+        if not -127.0 <= float(velocity_deviation) <= 127.0:
+            raise ValueError("velocity_deviation must be between -127.0 and 127.0")
+
+    release_velocity = note.get("release_velocity")
+    if release_velocity is not None:
+        if not 0.0 <= float(release_velocity) <= 127.0:
+            raise ValueError("release_velocity must be between 0.0 and 127.0")
+
+
+@mcp.tool()
+def add_notes(ctx: Context, track_index: int, clip_index: int, notes: Any) -> dict:
+    """Add MIDI notes to a clip. notes is a JSON array: [{pitch, start_time, duration, velocity?, probability?, velocity_deviation?, release_velocity?}]."""
+    _validate_track_index(track_index)
+    _validate_clip_index(clip_index)
+    notes = _ensure_list(notes)
+    if not notes:
+        raise ValueError("notes list cannot be empty")
+    for note in notes:
+        _validate_note(note)
+    return _get_ableton(ctx).send_command("add_notes", {
+        "track_index": track_index,
+        "clip_index": clip_index,
+        "notes": notes,
+    })
+
+
+@mcp.tool()
+def get_notes(
+    ctx: Context,
+    track_index: int,
+    clip_index: int,
+    from_pitch: int = 0,
+    pitch_span: int = 128,
+    from_time: float = 0.0,
+    time_span: Optional[float] = None,
+) -> dict:
+    """Get MIDI notes from a clip region. Returns note_id, pitch, start_time, duration, velocity, mute, probability."""
+    _validate_track_index(track_index)
+    _validate_clip_index(clip_index)
+    if not 0 <= from_pitch <= 127:
+        raise ValueError("from_pitch must be between 0 and 127")
+    if pitch_span < 1 or pitch_span > 128:
+        raise ValueError("pitch_span must be between 1 and 128")
+    params = {
+        "track_index": track_index,
+        "clip_index": clip_index,
+        "from_pitch": from_pitch,
+        "pitch_span": pitch_span,
+        "from_time": from_time,
+    }
+    if time_span is not None:
+        if time_span <= 0:
+            raise ValueError("time_span must be > 0")
+        params["time_span"] = time_span
+    return _get_ableton(ctx).send_command("get_notes", params)
+
+
+@mcp.tool()
+def remove_notes(
+    ctx: Context,
+    track_index: int,
+    clip_index: int,
+    from_pitch: int = 0,
+    pitch_span: int = 128,
+    from_time: float = 0.0,
+    time_span: Optional[float] = None,
+) -> dict:
+    """Remove all MIDI notes in a pitch/time region. Use undo to revert. Defaults remove ALL notes in the clip."""
+    _validate_track_index(track_index)
+    _validate_clip_index(clip_index)
+    params = {
+        "track_index": track_index,
+        "clip_index": clip_index,
+        "from_pitch": from_pitch,
+        "pitch_span": pitch_span,
+        "from_time": from_time,
+    }
+    if time_span is not None:
+        if time_span <= 0:
+            raise ValueError("time_span must be > 0")
+        params["time_span"] = time_span
+    return _get_ableton(ctx).send_command("remove_notes", params)
+
+
+@mcp.tool()
+def remove_notes_by_id(ctx: Context, track_index: int, clip_index: int, note_ids: Any) -> dict:
+    """Remove specific MIDI notes by their IDs (JSON array of ints). Use undo to revert."""
+    _validate_track_index(track_index)
+    _validate_clip_index(clip_index)
+    note_ids = _ensure_list(note_ids)
+    if not note_ids:
+        raise ValueError("note_ids list cannot be empty")
+    return _get_ableton(ctx).send_command("remove_notes_by_id", {
+        "track_index": track_index,
+        "clip_index": clip_index,
+        "note_ids": note_ids,
+    })
+
+
+@mcp.tool()
+def modify_notes(ctx: Context, track_index: int, clip_index: int, modifications: Any) -> dict:
+    """Modify existing MIDI notes by ID. modifications is a JSON array: [{note_id, pitch?, start_time?, duration?, velocity?, probability?}]."""
+    _validate_track_index(track_index)
+    _validate_clip_index(clip_index)
+    modifications = _ensure_list(modifications)
+    if not modifications:
+        raise ValueError("modifications list cannot be empty")
+    for mod in modifications:
+        if "note_id" not in mod:
+            raise ValueError("Each modification must have a 'note_id' field")
+        if "pitch" in mod and not 0 <= int(mod["pitch"]) <= 127:
+            raise ValueError("pitch must be between 0 and 127")
+        if "duration" in mod and float(mod["duration"]) <= 0:
+            raise ValueError("duration must be > 0")
+        if "velocity" in mod and not 0.0 <= float(mod["velocity"]) <= 127.0:
+            raise ValueError("velocity must be between 0.0 and 127.0")
+        if "probability" in mod and not 0.0 <= float(mod["probability"]) <= 1.0:
+            raise ValueError("probability must be between 0.0 and 1.0")
+    return _get_ableton(ctx).send_command("modify_notes", {
+        "track_index": track_index,
+        "clip_index": clip_index,
+        "modifications": modifications,
+    })
+
+
+@mcp.tool()
+def duplicate_notes(
+    ctx: Context,
+    track_index: int,
+    clip_index: int,
+    note_ids: Any,
+    time_offset: float = 0.0,
+) -> dict:
+    """Duplicate specific notes by ID (JSON array of ints), with optional time offset (in beats)."""
+    _validate_track_index(track_index)
+    _validate_clip_index(clip_index)
+    note_ids = _ensure_list(note_ids)
+    if not note_ids:
+        raise ValueError("note_ids list cannot be empty")
+    return _get_ableton(ctx).send_command("duplicate_notes", {
+        "track_index": track_index,
+        "clip_index": clip_index,
+        "note_ids": note_ids,
+        "time_offset": time_offset,
+    })
+
+
+@mcp.tool()
+def transpose_notes(
+    ctx: Context,
+    track_index: int,
+    clip_index: int,
+    semitones: int,
+    from_time: float = 0.0,
+    time_span: Optional[float] = None,
+    arrangement: bool = False,
+) -> dict:
+    """Transpose notes in a time range by semitones (positive=up, negative=down).
+
+    Set arrangement=True to target an arrangement clip by its index in
+    track.arrangement_clips instead of a session clip slot.
+    """
+    _validate_track_index(track_index)
+    _validate_clip_index(clip_index)
+    if not -127 <= semitones <= 127:
+        raise ValueError("semitones must be between -127 and 127")
+    params = {
+        "track_index": track_index,
+        "clip_index": clip_index,
+        "semitones": semitones,
+        "from_time": from_time,
+    }
+    if arrangement:
+        params["arrangement"] = True
+    if time_span is not None:
+        if time_span <= 0:
+            raise ValueError("time_span must be > 0")
+        params["time_span"] = time_span
+    return _get_ableton(ctx).send_command("transpose_notes", params)
+
+
+@mcp.tool()
+def quantize_clip(
+    ctx: Context,
+    track_index: int,
+    clip_index: int,
+    grid: int,
+    amount: float = 1.0,
+) -> dict:
+    """Quantize a clip's notes to a grid. grid is a RecordQuantization enum: 0=None, 1=1/4, 2=1/8, 3=1/8T, 4=1/8+T, 5=1/16, 6=1/16T, 7=1/16+T, 8=1/32. amount 0.0-1.0."""
+    _validate_track_index(track_index)
+    _validate_clip_index(clip_index)
+    if not 0 <= grid <= 8:
+        raise ValueError("grid must be between 0 and 8 (RecordQuantization enum)")
+    if not 0.0 <= amount <= 1.0:
+        raise ValueError("amount must be between 0.0 and 1.0")
+    return _get_ableton(ctx).send_command("quantize_clip", {
+        "track_index": track_index,
+        "clip_index": clip_index,
+        "grid": grid,
+        "amount": amount,
+    })

package/mcp_server/tools/scenes.py

@@ -0,0 +1,89 @@
+"""Scene MCP tools — list, create, delete, duplicate, fire, rename, color, tempo.
+
+8 tools matching the Remote Script scenes domain.
+"""
+
+from fastmcp import Context
+
+from ..server import mcp
+
+
+def _get_ableton(ctx: Context):
+    """Extract AbletonConnection from lifespan context."""
+    return ctx.lifespan_context["ableton"]
+
+
+def _validate_scene_index(scene_index: int):
+    if scene_index < 0:
+        raise ValueError("scene_index must be >= 0")
+
+
+@mcp.tool()
+def get_scenes_info(ctx: Context) -> dict:
+    """Get info for all scenes: name, tempo, color."""
+    return _get_ableton(ctx).send_command("get_scenes_info")
+
+
+@mcp.tool()
+def create_scene(ctx: Context, index: int = -1) -> dict:
+    """Create a new scene. index=-1 appends at end."""
+    return _get_ableton(ctx).send_command("create_scene", {"index": index})
+
+
+@mcp.tool()
+def delete_scene(ctx: Context, scene_index: int) -> dict:
+    """Delete a scene by index. Use undo to revert if needed."""
+    _validate_scene_index(scene_index)
+    return _get_ableton(ctx).send_command("delete_scene", {"scene_index": scene_index})
+
+
+@mcp.tool()
+def duplicate_scene(ctx: Context, scene_index: int) -> dict:
+    """Duplicate a scene (copies all clip slots)."""
+    _validate_scene_index(scene_index)
+    return _get_ableton(ctx).send_command("duplicate_scene", {"scene_index": scene_index})
+
+
+@mcp.tool()
+def fire_scene(ctx: Context, scene_index: int) -> dict:
+    """Fire (launch) a scene, triggering all its clips."""
+    _validate_scene_index(scene_index)
+    return _get_ableton(ctx).send_command("fire_scene", {"scene_index": scene_index})
+
+
+@mcp.tool()
+def set_scene_name(ctx: Context, scene_index: int, name: str) -> dict:
+    """Rename a scene. Pass empty string to clear the name."""
+    _validate_scene_index(scene_index)
+    return _get_ableton(ctx).send_command("set_scene_name", {
+        "scene_index": scene_index,
+        "name": name,
+    })
+
+
+def _validate_color_index(color_index: int):
+    if not 0 <= color_index <= 69:
+        raise ValueError("color_index must be between 0 and 69")
+
+
+@mcp.tool()
+def set_scene_color(ctx: Context, scene_index: int, color_index: int) -> dict:
+    """Set scene color (0-69, Ableton's color palette)."""
+    _validate_scene_index(scene_index)
+    _validate_color_index(color_index)
+    return _get_ableton(ctx).send_command("set_scene_color", {
+        "scene_index": scene_index,
+        "color_index": color_index,
+    })
+
+
+@mcp.tool()
+def set_scene_tempo(ctx: Context, scene_index: int, tempo: float) -> dict:
+    """Set scene tempo in BPM (20-999). Fires when the scene launches."""
+    _validate_scene_index(scene_index)
+    if tempo < 20 or tempo > 999:
+        raise ValueError("Tempo must be between 20.0 and 999.0 BPM")
+    return _get_ableton(ctx).send_command("set_scene_tempo", {
+        "scene_index": scene_index,
+        "tempo": tempo,
+    })

package/mcp_server/tools/tracks.py

@@ -0,0 +1,175 @@
+"""Track MCP tools — create, delete, rename, mute, solo, arm, group fold, monitor.
+
+14 tools matching the Remote Script tracks domain.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from fastmcp import Context
+
+from ..server import mcp
+
+
+def _get_ableton(ctx: Context):
+    """Extract AbletonConnection from lifespan context."""
+    return ctx.lifespan_context["ableton"]
+
+
+def _validate_track_index(track_index: int):
+    """Validate track index. Must be >= 0 for regular tracks."""
+    if track_index < 0:
+        raise ValueError("track_index must be >= 0")
+
+
+def _validate_color_index(color_index: int):
+    if not 0 <= color_index <= 69:
+        raise ValueError("color_index must be between 0 and 69")
+
+
+@mcp.tool()
+def get_track_info(ctx: Context, track_index: int) -> dict:
+    """Get detailed info about a track: clips, devices, mixer state."""
+    _validate_track_index(track_index)
+    return _get_ableton(ctx).send_command("get_track_info", {"track_index": track_index})
+
+
+@mcp.tool()
+def create_midi_track(
+    ctx: Context,
+    index: int = -1,
+    name: Optional[str] = None,
+    color: Optional[int] = None,
+) -> dict:
+    """Create a new MIDI track. index=-1 appends at end."""
+    params = {"index": index}
+    if name is not None:
+        if not name.strip():
+            raise ValueError("Track name cannot be empty")
+        params["name"] = name
+    if color is not None:
+        _validate_color_index(color)
+        params["color_index"] = color
+    return _get_ableton(ctx).send_command("create_midi_track", params)
+
+
+@mcp.tool()
+def create_audio_track(
+    ctx: Context,
+    index: int = -1,
+    name: Optional[str] = None,
+    color: Optional[int] = None,
+) -> dict:
+    """Create a new audio track. index=-1 appends at end."""
+    params = {"index": index}
+    if name is not None:
+        if not name.strip():
+            raise ValueError("Track name cannot be empty")
+        params["name"] = name
+    if color is not None:
+        _validate_color_index(color)
+        params["color_index"] = color
+    return _get_ableton(ctx).send_command("create_audio_track", params)
+
+
+@mcp.tool()
+def create_return_track(ctx: Context) -> dict:
+    """Create a new return track."""
+    return _get_ableton(ctx).send_command("create_return_track")
+
+
+@mcp.tool()
+def delete_track(ctx: Context, track_index: int) -> dict:
+    """Delete a track by index. Use undo to revert if needed."""
+    _validate_track_index(track_index)
+    return _get_ableton(ctx).send_command("delete_track", {"track_index": track_index})
+
+
+@mcp.tool()
+def duplicate_track(ctx: Context, track_index: int) -> dict:
+    """Duplicate a track (copies all clips, devices, and settings)."""
+    _validate_track_index(track_index)
+    return _get_ableton(ctx).send_command("duplicate_track", {"track_index": track_index})
+
+
+@mcp.tool()
+def set_track_name(ctx: Context, track_index: int, name: str) -> dict:
+    """Rename a track."""
+    _validate_track_index(track_index)
+    if not name.strip():
+        raise ValueError("Track name cannot be empty")
+    return _get_ableton(ctx).send_command("set_track_name", {
+        "track_index": track_index,
+        "name": name,
+    })
+
+
+@mcp.tool()
+def set_track_color(ctx: Context, track_index: int, color_index: int) -> dict:
+    """Set track color (0-69, Ableton's color palette)."""
+    _validate_track_index(track_index)
+    _validate_color_index(color_index)
+    return _get_ableton(ctx).send_command("set_track_color", {
+        "track_index": track_index,
+        "color_index": color_index,
+    })
+
+
+@mcp.tool()
+def set_track_mute(ctx: Context, track_index: int, muted: bool) -> dict:
+    """Mute or unmute a track."""
+    _validate_track_index(track_index)
+    return _get_ableton(ctx).send_command("set_track_mute", {
+        "track_index": track_index,
+        "mute": muted,
+    })
+
+
+@mcp.tool()
+def set_track_solo(ctx: Context, track_index: int, soloed: bool) -> dict:
+    """Solo or unsolo a track."""
+    _validate_track_index(track_index)
+    return _get_ableton(ctx).send_command("set_track_solo", {
+        "track_index": track_index,
+        "solo": soloed,
+    })
+
+
+@mcp.tool()
+def set_track_arm(ctx: Context, track_index: int, armed: bool) -> dict:
+    """Arm or disarm a track for recording."""
+    _validate_track_index(track_index)
+    return _get_ableton(ctx).send_command("set_track_arm", {
+        "track_index": track_index,
+        "arm": armed,
+    })
+
+
+@mcp.tool()
+def stop_track_clips(ctx: Context, track_index: int) -> dict:
+    """Stop all playing clips on a track."""
+    _validate_track_index(track_index)
+    return _get_ableton(ctx).send_command("stop_track_clips", {"track_index": track_index})
+
+
+@mcp.tool()
+def set_group_fold(ctx: Context, track_index: int, folded: bool) -> dict:
+    """Fold or unfold a group track to show/hide its children."""
+    _validate_track_index(track_index)
+    return _get_ableton(ctx).send_command("set_group_fold", {
+        "track_index": track_index,
+        "folded": folded,
+    })
+
+
+@mcp.tool()
+def set_track_input_monitoring(ctx: Context, track_index: int, state: int) -> dict:
+    """Set input monitoring (0=In, 1=Auto, 2=Off). Only for regular tracks, not return tracks."""
+    _validate_track_index(track_index)
+    if state not in (0, 1, 2):
+        raise ValueError("Monitoring state must be 0=In, 1=Auto, or 2=Off")
+    return _get_ableton(ctx).send_command("set_track_input_monitoring", {
+        "track_index": track_index,
+        "state": state,
+    })