livepilot 1.0.0

package/plugin/skills/livepilot-core/references/overview.md

@@ -0,0 +1,209 @@
+# LivePilot Architecture & Tool Reference
+
+LivePilot is an MCP server that controls Ableton Live 12 in real-time through 104 tools across 10 domains. This document maps every tool to what it actually does in Ableton, so you know exactly which tool to reach for.
+
+## Architecture
+
+```
+AI Client  ──MCP──►  FastMCP Server  ──TCP/9878──►  Remote Script (inside Ableton)
+                        (validates)                    (executes on main thread)
+```
+
+- **MCP Server** validates inputs (ranges, types) before sending
+- **Remote Script** runs inside Ableton's Python environment, executes on the main thread via `schedule_message`
+- **Protocol**: JSON over TCP, newline-delimited. Every command gets a response.
+- **Thread safety**: All Live Object Model (LOM) access happens on Ableton's main thread
+
+## The 104 Tools — What Each One Does
+
+### Transport (12) — Playback, tempo, global state, diagnostics
+
+| Tool | What it does | Key params |
+|------|-------------|------------|
+| `get_session_info` | Returns tempo, time sig, playing state, track count, scene count, song length | — |
+| `set_tempo` | Changes BPM | `tempo` (20-999) |
+| `set_time_signature` | Changes time signature | `numerator` (1-99), `denominator` (1,2,4,8,16) |
+| `start_playback` | Starts from current position | — |
+| `stop_playback` | Stops playback | — |
+| `continue_playback` | Resumes from where it stopped | — |
+| `toggle_metronome` | Toggles click on/off | — |
+| `set_session_loop` | Sets loop region | `loop_start` (beats), `loop_length` (beats) |
+| `undo` | Undoes last action | — |
+| `redo` | Redoes last undone action | — |
+| `get_recent_actions` | Returns log of recent commands sent to Ableton (newest first) | `limit` (1-50, default 20) |
+| `get_session_diagnostics` | Analyzes session for issues: armed tracks, solo leftovers, unnamed tracks, empty clips | — |
+
+### Tracks (14) — Create, delete, configure, group tracks
+
+| Tool | What it does | Key params |
+|------|-------------|------------|
+| `get_track_info` | Returns clips, devices, mixer state, group/fold info for one track | `track_index` (0-based) |
+| `create_midi_track` | Creates a new MIDI track | `index` (-1=end), `name`, `color` (0-69) |
+| `create_audio_track` | Creates a new audio track | `index` (-1=end), `name`, `color` (0-69) |
+| `create_return_track` | Creates a new return track | — |
+| `delete_track` | Deletes a track | `track_index` |
+| `duplicate_track` | Duplicates track with all contents | `track_index` |
+| `set_track_name` | Renames a track | `track_index`, `name` |
+| `set_track_color` | Sets track color | `track_index`, `color_index` (0-69) |
+| `set_track_mute` | Mutes/unmutes | `track_index`, `muted` (bool) |
+| `set_track_solo` | Solos/unsolos | `track_index`, `soloed` (bool) |
+| `set_track_arm` | Arms/disarms for recording | `track_index`, `armed` (bool) |
+| `stop_track_clips` | Stops all playing clips on track | `track_index` |
+| `set_group_fold` | Folds/unfolds a group track | `track_index`, `folded` (bool) |
+| `set_track_input_monitoring` | Sets input monitoring state | `track_index`, `state` (0=In, 1=Auto, 2=Off) |
+
+### Clips (11) — Clip lifecycle, properties, warp
+
+| Tool | What it does | Key params |
+|------|-------------|------------|
+| `get_clip_info` | Returns clip name, length, loop settings, playing state, is_midi/is_audio, warp info | `track_index`, `clip_index` |
+| `create_clip` | Creates empty MIDI clip | `track_index`, `clip_index`, `length` (beats) |
+| `delete_clip` | Removes a clip from its slot | `track_index`, `clip_index` |
+| `duplicate_clip` | Copies clip to next slot | `track_index`, `clip_index` |
+| `fire_clip` | Launches a clip | `track_index`, `clip_index` |
+| `stop_clip` | Stops a playing clip | `track_index`, `clip_index` |
+| `set_clip_name` | Renames a clip | `track_index`, `clip_index`, `name` |
+| `set_clip_color` | Sets clip color | `track_index`, `clip_index`, `color_index` (0-69) |
+| `set_clip_loop` | Configures loop region | `track_index`, `clip_index`, `loop_start`, `loop_end`, `looping` |
+| `set_clip_launch` | Sets launch mode and quantization | `track_index`, `clip_index`, `launch_mode`, `quantization` |
+| `set_clip_warp_mode` | Sets warp mode for audio clips | `track_index`, `clip_index`, `mode` (0=Beats,1=Tones,2=Texture,3=Re-Pitch,4=Complex,6=Complex Pro) |
+
+### Notes (8) — MIDI note manipulation (Live 12 API)
+
+| Tool | What it does | Key params |
+|------|-------------|------------|
+| `add_notes` | Adds MIDI notes to a clip | `track_index`, `clip_index`, `notes` (array) |
+| `get_notes` | Reads all notes in a region | `track_index`, `clip_index`, `start_time`, `length` |
+| `remove_notes` | Removes notes in a region | `track_index`, `clip_index`, `start_time`, `pitch_start`, etc. |
+| `remove_notes_by_id` | Removes specific notes by ID | `track_index`, `clip_index`, `note_ids` |
+| `modify_notes` | Changes existing notes (pitch, time, velocity, probability) | `track_index`, `clip_index`, `modifications` |
+| `duplicate_notes` | Copies notes in a region | `track_index`, `clip_index`, region params |
+| `transpose_notes` | Shifts pitch of notes in a region | `track_index`, `clip_index`, `semitones`, region params |
+| `quantize_clip` | Snaps notes to grid | `track_index`, `clip_index`, `grid` (int 0-8: 0=None,1=1/4,2=1/8,5=1/16,8=1/32), `amount` (0-1) |
+
+**Note format** (for `add_notes`):
+```json
+{"pitch": 60, "start_time": 0.0, "duration": 0.5, "velocity": 100, "mute": false}
+```
+
+**Extended note fields** (returned by `get_notes`):
+- `note_id` — unique identifier for modify/remove operations
+- `probability` — 0.0-1.0, per-note trigger probability (Live 12)
+- `velocity_deviation` — -127.0 to 127.0
+- `release_velocity` — 0.0-127.0
+
+### Devices (12) — Instruments, effects, racks
+
+| Tool | What it does | Key params |
+|------|-------------|------------|
+| `get_device_info` | Returns device name, class, active state, all parameters | `track_index`, `device_index` |
+| `get_device_parameters` | Lists all parameters with values and ranges | `track_index`, `device_index` |
+| `set_device_parameter` | Sets a single parameter | `track_index`, `device_index`, `parameter_index`, `value` |
+| `batch_set_parameters` | Sets multiple parameters at once | `track_index`, `device_index`, `parameters` (array) |
+| `toggle_device` | Enables/disables a device | `track_index`, `device_index` |
+| `delete_device` | Removes a device from the chain | `track_index`, `device_index` |
+| `load_device_by_uri` | Loads a device by browser URI | `track_index`, `uri` |
+| `find_and_load_device` | Searches browser and loads first match | `track_index`, `name` |
+| `get_rack_chains` | Lists chains in an Instrument/Effect Rack | `track_index`, `device_index` |
+| `set_simpler_playback_mode` | Switches Simpler mode (Classic/One-Shot/Slice) | `track_index`, `device_index`, `playback_mode` (0/1/2), `slice_by`, `sensitivity` |
+| `set_chain_volume` | Sets volume of a rack chain | `track_index`, `device_index`, `chain_index`, `volume` |
+| `get_device_presets` | Lists presets for a device (audio effects, instruments, MIDI effects) | `device_name` |
+
+### Scenes (8) — Scene management
+
+| Tool | What it does | Key params |
+|------|-------------|------------|
+| `get_scenes_info` | Lists all scenes with names, tempo, and color | — |
+| `create_scene` | Creates a new scene | `index` (-1=end) |
+| `delete_scene` | Deletes a scene | `scene_index` |
+| `duplicate_scene` | Duplicates a scene | `scene_index` |
+| `fire_scene` | Launches all clips in a scene | `scene_index` |
+| `set_scene_name` | Renames a scene | `scene_index`, `name` |
+| `set_scene_color` | Sets scene color | `scene_index`, `color_index` (0-69) |
+| `set_scene_tempo` | Sets tempo that triggers when scene fires | `scene_index`, `tempo` (20-999 BPM) |
+
+### Mixing (8) — Levels, panning, routing
+
+| Tool | What it does | Key params |
+|------|-------------|------------|
+| `set_track_volume` | Sets track volume | `track_index`, `volume` (0.0-1.0, where 0.85≈0dB) |
+| `set_track_pan` | Sets stereo position | `track_index`, `pan` (-1.0 left to 1.0 right) |
+| `set_track_send` | Sets send level to return track | `track_index`, `send_index`, `value` (0.0-1.0) |
+| `get_return_tracks` | Lists all return tracks | — |
+| `get_master_track` | Returns master track info | — |
+| `set_master_volume` | Sets master output level | `volume` (0.0-1.0) |
+| `get_track_routing` | Returns input/output routing config | `track_index` |
+| `set_track_routing` | Configures input/output routing | `track_index`, routing params |
+
+### Browser (4) — Finding and loading presets/devices
+
+| Tool | What it does | Key params |
+|------|-------------|------------|
+| `get_browser_tree` | Returns top-level browser categories | — |
+| `get_browser_items` | Lists items in a browser path | `path` |
+| `search_browser` | Searches the browser | `query` |
+| `load_browser_item` | Loads a browser item onto a track — **`uri` MUST come from `search_browser` results, NEVER invented** | `track_index`, `uri` |
+
+### Arrangement (19) — Timeline, recording, cue points, arrangement notes
+
+| Tool | What it does | Key params |
+|------|-------------|------------|
+| `get_arrangement_clips` | Lists clips in arrangement view | `track_index` |
+| `create_arrangement_clip` | Duplicates session clip into arrangement at a beat position | `track_index`, `clip_slot_index`, `start_time`, `length` |
+| `add_arrangement_notes` | Adds MIDI notes to an arrangement clip | `track_index`, `clip_index`, `notes` |
+| `get_arrangement_notes` | Reads notes from an arrangement clip | `track_index`, `clip_index`, region params |
+| `remove_arrangement_notes` | Removes notes in a region of an arrangement clip | `track_index`, `clip_index`, region params |
+| `remove_arrangement_notes_by_id` | Removes specific notes by ID | `track_index`, `clip_index`, `note_ids` |
+| `modify_arrangement_notes` | Modifies notes by ID (pitch, time, velocity, probability) | `track_index`, `clip_index`, `modifications` |
+| `duplicate_arrangement_notes` | Copies notes by ID with optional time offset | `track_index`, `clip_index`, `note_ids`, `time_offset` |
+| `transpose_arrangement_notes` | Transposes notes in an arrangement clip | `track_index`, `clip_index`, `semitones`, region params |
+| `set_arrangement_clip_name` | Renames an arrangement clip | `track_index`, `clip_index`, `name` |
+| `set_arrangement_automation` | Writes automation envelope to an arrangement clip | `track_index`, `clip_index`, `parameter_type`, `points` |
+| `back_to_arranger` | Switches playback from session back to arrangement | — |
+| `jump_to_time` | Moves playhead to a beat position | `beat_time` (beats) |
+| `capture_midi` | Captures recently played MIDI | — |
+| `start_recording` | Starts recording (session or arrangement) | `arrangement` (bool) |
+| `stop_recording` | Stops all recording | — |
+| `get_cue_points` | Lists all cue markers | — |
+| `jump_to_cue` | Jumps to a cue point by index | `cue_index` |
+| `toggle_cue_point` | Creates/removes cue point at current position | — |
+
+### Memory (8) — Technique library persistence
+
+| Tool | What it does | Key params |
+|------|-------------|------------|
+| `memory_learn` | Saves a technique with stylistic qualities | `name`, `type`, `qualities`, `payload`, `tags` |
+| `memory_recall` | Searches library by text and filters | `query`, `type`, `tags`, `limit` |
+| `memory_get` | Fetches full technique including payload | `technique_id` |
+| `memory_replay` | Returns technique with replay plan for agent | `technique_id`, `adapt` (bool) |
+| `memory_list` | Browses library with filtering/sorting | `type`, `tags`, `sort_by`, `limit` |
+| `memory_favorite` | Stars and/or rates a technique | `technique_id`, `favorite`, `rating` (0-5) |
+| `memory_update` | Updates name, tags, or qualities | `technique_id`, `name`, `tags`, `qualities` |
+| `memory_delete` | Removes technique (backs up first) | `technique_id` |
+
+## Units & Ranges Quick Reference
+
+| Concept | Unit/Range | Notes |
+|---------|-----------|-------|
+| Tempo | 20-999 BPM | — |
+| Volume | 0.0-1.0 | 0.85 ≈ 0dB, 0.0 = -inf |
+| Pan | -1.0 to 1.0 | -1 = full left, 0 = center |
+| Time/Position | Beats (float) | 1.0 = quarter note at any tempo |
+| Clip length | Beats (float) | 4.0 = 1 bar at 4/4 |
+| Pitch | 0-127 (MIDI) | 60 = C3 (middle C) |
+| Velocity | 1-127 | 1 = softest, 127 = loudest |
+| Probability | 0.0-1.0 | 1.0 = always triggers |
+| Color index | 0-69 | Ableton's fixed palette |
+| Track index | 0-based | Negative for return tracks (-1=A, -2=B), -1000 for master |
+| Grid (quantize) | Integer enum (0-8) | 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 |
+| Time signature | num/denom | denom must be power of 2 |
+
+## Common Patterns
+
+**"Read before write"** — Always `get_session_info` or `get_track_info` before making changes.
+
+**"Verify after write"** — Re-read state after mutations to confirm the change took effect.
+
+**"Undo is your safety net"** — The `undo` tool reverts the last operation. Mention it to users.
+
+**"One step at a time"** — Don't batch unrelated operations. Verify between steps.

package/plugin/skills/livepilot-core/references/sound-design.md

@@ -0,0 +1,392 @@
+# Sound Design — Instruments, Effects & Recipes
+
+Ableton Live's stock instruments and effects with key parameters, typical values, and sound design starting points. Use these as launch pads — every sound should be shaped by context.
+
+## Stock Instruments
+
+### Analog (Subtractive Synth)
+Two oscillators + noise → two filters → two amplifiers. Classic analog-modeled subtractive synthesis.
+
+**Key parameters:**
+- `Osc1 Shape` / `Osc2 Shape` — Saw, Square/Pulse, Sine, Noise
+- `Osc1 Octave` / `Osc2 Octave` — -3 to +3
+- `Osc2 Detune` — Fine detune for thickness (-1.0 to 1.0 semitones)
+- `Filter1 Type` — LP12, LP24, BP, HP, Notch
+- `Filter1 Freq` — Cutoff frequency (20 Hz - 20 kHz)
+- `Filter1 Res` — Resonance (0 to 1.0)
+- `Fil1 Env Amount` — Filter envelope depth
+- `Amp1 Attack` / `Decay` / `Sustain` / `Release` — ADSR envelope
+- `LFO1 Rate` / `Amount` — Modulation speed and depth
+
+### Wavetable (Wavetable Synth)
+Two wavetable oscillators with continuous morphing, sub oscillator, and powerful modulation.
+
+**Key parameters:**
+- `Osc 1 Pos` — Wavetable position (0-1, morphs through waveforms)
+- `Osc 1 Effect` — FM, Classic, Modern, formant effects on the wavetable
+- `Sub Osc` — Sub oscillator (-2 to 0 octaves, sine/triangle)
+- `Filter Type` — LP/HP/BP with various slopes
+- `Filter Freq` — Cutoff
+- `Filter Res` — Resonance
+- `Mod Matrix` — Map any source (LFO, envelope, velocity, etc.) to any parameter
+- `Unison Voices` — 1-8 voices for supersaw/thick sounds
+- `Unison Amount` — Detune spread between voices
+
+### Operator (FM Synth)
+Four oscillators (operators) that can modulate each other's frequency. 11 algorithms define the routing.
+
+**Key parameters:**
+- `Algorithm` — Routing topology (1-11). Algorithm 1 = all serial (most harmonics). Algorithm 11 = all parallel (additive).
+- `Osc A-D Coarse` — Frequency ratio (0.5, 1, 2, 3... harmonic ratios)
+- `Osc A-D Level` — Output level / modulation amount
+- `Osc A-D Waveform` — Sine, Saw, Square, Triangle, Noise
+- `Filter Freq` / `Res` — Global filter
+- `LFO Rate` / `Amount` — Vibrato, tremolo
+- `ADSR per operator` — Each operator has its own envelope
+
+### Drift (Analog-Modeled)
+Simple, characterful analog synth with built-in instability and warmth.
+
+**Key parameters:**
+- `Shape` — Oscillator shape (continuous morph)
+- `Drift` — Amount of analog-style instability
+- `Filter` — Low-pass filter with resonance
+- `Envelope` — Attack/Decay/Sustain/Release
+- `Voice Mode` — Mono, Poly, Unison
+- `Modulation` — Built-in LFO and envelope routing
+
+### Simpler (Sample Player)
+One-shot or looped sample playback with filter, envelope, LFO, and warp modes.
+
+**Key parameters:**
+- `Mode` — Classic (one-shot), One-Shot, Slicing
+- `Start` / `End` — Sample region
+- `Loop` — On/off, loop start/length
+- `Filter Type` / `Freq` / `Res` — Sample filtering
+- `Amp Envelope` — ADSR for amplitude
+- `Warp` — Time-stretch sample to tempo
+- `Voices` — Polyphony count
+- `Spread` — Stereo spread for polyphonic voices
+
+### Drum Rack
+Container that maps samples/instruments to MIDI notes (pads). Each pad is a chain.
+
+**Key concepts:**
+- 128 pads (MIDI 0-127), typically using 36-51 (C1-D#2)
+- **Choke groups**: Assign pads to same group — triggering one silences others (e.g., open/closed hi-hat)
+- Each pad has its own chain: sample player + effects
+- **Macro knobs**: 8 knobs that can control parameters across multiple chains
+- Sends A/B per pad for internal effects routing
+
+### Other Instruments
+- **Sampler** — Advanced multi-sample instrument with zones, layers, modulation matrix
+- **Tension** — Physical modeling of strings (pluck, bow, hammer)
+- **Collision** — Physical modeling of mallet instruments (bars, membranes, plates)
+- **Electric** — Electric piano modeling (tine, reed, pickup, damper)
+- **Meld** — MPE-capable synth with two engines and a mixer
+
+## Stock Audio Effects
+
+### Dynamics
+
+**Compressor**
+- `Threshold` — Level where compression starts (dB)
+- `Ratio` — Compression ratio (1:1 to inf:1)
+- `Attack` — How fast compression engages (0.01-300ms)
+- `Release` — How fast compression releases (1-3000ms)
+- `Knee` — Soft/hard knee transition
+- `Makeup` / `Output Gain` — Compensate for gain reduction
+- `Sidechain` — External input for ducking (key for pumping effects)
+- **Modes**: Peak, RMS, Expand, OTT-style multiband (Compressor modes)
+
+**Glue Compressor**
+Bus-style compressor modeled on classic mix bus compressors.
+- `Threshold`, `Ratio` (2, 4, 10), `Attack`, `Release`
+- `Range` — Limits maximum compression
+- `Dry/Wet` — Parallel compression in one device
+- **Best for**: Drum bus, mix bus, gluing groups together
+
+**Limiter**
+- `Gain` — Input gain before limiting
+- `Ceiling` — Maximum output level
+- `Release` — Auto or manual
+- **Use for**: Final output protection, loudness maximizing
+
+**Gate**
+- `Threshold` — Level below which audio is muted
+- `Attack` / `Hold` / `Release` — Gate timing
+- `Return` — Hysteresis (how far below threshold to close)
+- **Use for**: Removing bleed, tightening drums, creative gating
+
+**Multiband Dynamics**
+Three frequency bands, each with its own compressor/expander.
+- `Low` / `Mid` / `High` — Frequency crossover points
+- Per-band: `Threshold Above/Below`, `Ratio`, `Attack`, `Release`
+- **Use for**: Mastering, de-essing, frequency-specific dynamics
+
+### EQ & Filters
+
+**EQ Eight**
+8-band parametric EQ — the workhorse.
+- Per band: `Frequency`, `Gain` (dB), `Q` (bandwidth)
+- Filter types: LP, HP, Bell, Notch, Low Shelf, High Shelf
+- Various slopes: 12dB, 24dB, 48dB per octave
+- `Oversampling` — Reduce aliasing at high frequencies
+
+**Auto Filter**
+Resonant filter with LFO, envelope follower, and sidechain.
+- `Filter Type` — LP/HP/BP/Notch, various slopes
+- `Frequency` — Cutoff
+- `Resonance` — Q factor
+- `LFO Amount` / `Rate` / `Shape` — Filter movement
+- `Envelope Amount` / `Attack` / `Release` — Envelope follower
+- **Use for**: Sweeps, wobbles, auto-wah, rhythmic filtering
+
+**Channel EQ**
+Simple 3-band EQ for quick tonal shaping.
+- `Low`, `Mid`, `High` — Gain knobs
+- `Mid Freq` — Sweepable mid frequency
+
+### Time-Based
+
+**Reverb**
+- `Decay Time` — Reverb tail length (0.2-60s)
+- `Pre Delay` — Delay before reverb starts (0-500ms)
+- `Room Size` — Early reflection size
+- `Diffusion` — Density of reflections
+- `High/Low Cut` — EQ the reverb tail
+- `Dry/Wet` — Mix (100% wet on return tracks)
+- `Freeze` — Infinite sustain of current reverb
+- **Types**: Room (short, 0.5-1.5s), Hall (medium, 1.5-4s), Cathedral (long, 4-10s+)
+
+**Delay**
+- `Time Left/Right` — Delay time (sync or ms)
+- `Feedback` — How much repeats (0-100%)
+- `Filter` — LP/HP on feedback path
+- `Dry/Wet` — Mix
+- `Ping Pong` — Alternates between L/R
+- **Common sync values**: 1/4, 1/8, 3/16 (dotted eighth), 1/4T (triplet)
+
+**Echo** (combines delay + reverb + modulation)
+- `Left/Right Time` — Delay times
+- `Feedback` — Repeat amount
+- `Reverb Level` — Built-in reverb
+- `Modulation` — Chorus-like movement in delay
+- `Ducking` — Delays get quieter when input is playing
+- `Gate` — Rhythmic gating of the echo tail
+
+### Distortion & Saturation
+
+**Saturator**
+- `Drive` — Amount of saturation
+- `Curve Type` — Analog Clip, Soft Sine, Medium Curve, Hard Curve, Sinoid Fold, Digital Clip
+- `Output` — Compensate volume
+- `Dry/Wet` — Parallel blend
+- **Soft Sine**: Warm, subtle. **Sinoid Fold**: Aggressive harmonics. **Analog Clip**: Tape-like.
+
+**Overdrive**
+- `Drive` — Distortion amount
+- `Tone` — Brightness
+- `Dynamics` — Preserves or compresses dynamics
+- **Use for**: Guitar-amp style warmth, bass grit
+
+**Erosion**
+- Adds digital artifacts: noise, sine wave modulation
+- `Amount`, `Frequency`, `Width`
+- **Use for**: Lo-fi, bitcrushed textures, digital degradation
+
+**Redux**
+- `Downsample` — Reduces sample rate (aliasing)
+- `Bit Reduction` — Reduces bit depth (quantization noise)
+- **Use for**: 8-bit sounds, lo-fi, retro textures
+
+### Modulation
+
+**Chorus-Ensemble**
+- `Rate 1/2` — LFO speeds
+- `Amount 1/2` — Modulation depths
+- `Feedback` — Flanging intensity
+- `Dry/Wet` — Mix
+- **Use for**: Thickening, stereo width, classic chorus
+
+**Phaser-Flanger**
+- `Rate` — LFO speed
+- `Amount` — Modulation depth
+- `Feedback` — Intensity/resonance
+- **Phaser**: Sweeping notches. **Flanger**: Jet/whoosh effect.
+
+**Frequency Shifter**
+- `Frequency` — Shift amount in Hz (not semitones — inharmonic)
+- `Drive` — Input gain
+- `Dry/Wet` — Mix
+- **Use for**: Metallic textures, detuned unease, ring-mod effects
+
+### Utility
+
+**Utility**
+Essential for mixing — should be on every track during mix.
+- `Gain` — Volume trim (-inf to +35dB)
+- `Width` — Stereo width (0=mono, 100=normal, 200=wide)
+- `Bass Mono` — Make frequencies below X Hz mono
+- `Bass Mono Freq` — Cutoff for mono bass (typically 120-200 Hz)
+- `Mute` — Kill switch
+- `Phase Invert L/R` — Flip phase
+- `Channel Mode` — Left, Right, Both, Swap
+
+## Sound Design Recipes
+
+These are starting points — load the instrument with `find_and_load_device`, then use `batch_set_parameters` to set values. Always `get_device_parameters` first to see exact parameter names.
+
+### Sub Bass (Analog)
+Deep, clean low-end foundation.
+```
+Oscillator 1: Sine wave
+Oscillator 2: Off
+Filter: LP24, cutoff ~200 Hz, no resonance
+Amp Envelope: Attack 0ms, Decay 0ms, Sustain 100%, Release 100ms
+Note range: C0-C2 (MIDI 24-48)
+```
+- Mono mode (one voice)
+- Velocity sensitivity low/off for consistent level
+
+### Reese Bass (Analog or Wavetable)
+Thick, detuned, evolving bass for DnB/dubstep.
+```
+Oscillator 1: Saw wave
+Oscillator 2: Saw wave, detune +5-15 cents
+Filter: LP24, cutoff ~500 Hz, resonance 20%
+Filter Envelope: moderate amount, medium attack (50-200ms)
+Unison: 2-4 voices, moderate spread
+```
+- Automate filter cutoff for movement
+- Layer with clean sub (separate track) for low-end clarity
+
+### Pad (Wavetable or Analog)
+Warm, evolving background texture.
+```
+Oscillator: Soft wavetable or saw + triangle
+Unison: 4-8 voices, wide spread
+Filter: LP, cutoff ~2 kHz, low resonance
+Amp Envelope: Attack 200-800ms, Decay 0, Sustain 100%, Release 500-2000ms
+LFO → Filter Cutoff: slow rate (0.1-0.5 Hz), subtle amount
+```
+- Add Chorus-Ensemble for extra width
+- Add Reverb (hall, 3-5s decay, 30-50% wet)
+- Velocity → filter cutoff for expressiveness
+
+### Pluck (Analog or Wavetable)
+Short, percussive melodic sound.
+```
+Oscillator: Saw or square
+Filter: LP24, cutoff ~1 kHz, moderate resonance (30-50%)
+Filter Envelope: Amount high, Attack 0, Decay 100-300ms, Sustain 0%, Release 50ms
+Amp Envelope: Attack 0, Decay 200-400ms, Sustain 0%, Release 100ms
+```
+- Short decay = harp-like. Longer decay = guitar-like.
+- Add short reverb (room, 0.5-1s) for space
+
+### Lead (Analog or Operator)
+Cutting melodic line that sits on top of the mix.
+```
+Oscillator: Square or saw
+Filter: LP or BP, cutoff ~3 kHz, moderate resonance
+Amp Envelope: Attack 5-20ms, Decay 200ms, Sustain 70%, Release 200ms
+Portamento/Glide: On (50-100ms) for mono mode
+```
+- Add Delay (1/8 or dotted 1/8, 30% feedback, 20% wet)
+- Add subtle Reverb (plate, 1-2s)
+- Use Saturator lightly for presence
+
+### Supersaw (Wavetable)
+Classic trance/EDM lead/pad.
+```
+Oscillator: Saw wavetable
+Unison: 7-8 voices
+Unison Amount: High (wide detune)
+Filter: LP, cutoff ~5 kHz, low resonance
+Amp Envelope: Attack 2ms, Sustain 100%, Release 300ms
+```
+- Layer with sub sine one octave below
+- Chorus or Ensemble for extra width
+- Stereo Delay (1/8 L, dotted 1/8 R)
+
+### Texture / Ambient (Wavetable + Effects)
+Evolving atmospheric sound.
+```
+Oscillator: Complex wavetable, automate position slowly
+Filter: BP, slowly sweeping frequency
+Amp Envelope: Slow attack (500ms-2s), long release (3-5s)
+LFO: Multiple slow LFOs mapped to position, filter, pitch (subtle)
+```
+- Heavy Reverb (5-10s decay, high diffusion, 80-100% wet)
+- Delay with high feedback (60-80%), filtered
+- Frequency Shifter at very small values (+/- 1-5 Hz) for movement
+- Grain Delay for granular textures
+
+### 808 Bass (Simpler or Drum Rack)
+Pitched sub with distortion for trap/hip-hop.
+```
+Sample: 808 kick or sine with fast pitch envelope
+Amp Envelope: Attack 0, Decay 1-3s (long tail), Sustain 0%
+Tuning: Tune to song key
+```
+- Add Saturator (soft sine or analog clip) for upper harmonics
+- Set Simpler to mono
+- Duration determines how long the 808 rings
+
+## Device Chain Patterns
+
+### Standard Insert Chain (on a track)
+```
+EQ Eight (surgical cuts) → Compressor → Saturator (subtle) → EQ Eight (tonal shaping) → Utility (final trim)
+```
+
+### Vocal Chain
+```
+EQ Eight (HP at 80 Hz, cut mud at 300 Hz) → Compressor (4:1, medium attack) → De-esser (Multiband Dynamics, high band) → EQ Eight (presence boost at 3-5 kHz) → Reverb (20-30% wet, plate)
+```
+
+### Drum Bus Chain
+```
+EQ Eight (HP at 30 Hz) → Glue Compressor (4:1, 10ms attack, 100ms release) → Saturator (subtle drive for warmth) → Utility (trim)
+```
+
+### Parallel Compression Setup
+Using Audio Effect Rack:
+- Chain A: Dry (no processing)
+- Chain B: Compressor (heavy — 10:1, fast attack, fast release, low threshold) → balance chain volume
+
+Or using Return track:
+1. `create_return_track` for parallel compression
+2. Add Compressor with extreme settings on the return
+3. Use `set_track_send` to feed signal to the return
+4. Blend return level to taste
+
+### Sidechain Ducking Setup
+1. Load Compressor on the track to be ducked (bass, pads)
+2. Enable Sidechain in Compressor
+3. Route kick track to sidechain input
+4. Settings: Ratio 4:1-inf:1, Attack 0.1ms, Release 50-200ms, Threshold low
+5. Adjust release to match tempo (longer for slower tempos)
+
+## Creative Effects Techniques
+
+### Reverb Freeze
+Set Reverb's Freeze parameter to capture and infinitely sustain the current sound. Automate on/off for dramatic transitions.
+
+### Delay Feedback Washes
+Automate Delay feedback above 100% briefly — the delay builds and self-oscillates. Pull back before it gets out of control. Great for transitions.
+
+### Beat Repeat (Stock Effect)
+Repeats/stutters incoming audio rhythmically.
+- `Grid` — Repeat size (1/4 to 1/32)
+- `Chance` — Probability of repeating
+- `Gate` — How long the repeat runs
+- Great for glitch, fills, and transitions
+
+### Grain Delay
+Granular delay that can pitch-shift and scatter audio.
+- `Pitch` — Transpose the grains
+- `Spray` — Randomize grain position
+- `Frequency` — Grain rate
+- Great for ambient textures and otherworldly effects

package/remote_script/LivePilot/__init__.py

@@ -0,0 +1,42 @@
+"""
+LivePilot - Ableton Live 12 AI Copilot Remote Script.
+
+Entry point for the ControlSurface. Ableton calls create_instance(c_instance)
+when this script is selected in Preferences > Link, Tempo & MIDI.
+"""
+
+from _Framework.ControlSurface import ControlSurface
+from .server import LivePilotServer
+from . import transport    # noqa: F401  — registers transport handlers
+from . import tracks       # noqa: F401  — registers track handlers
+from . import clips        # noqa: F401  — registers clip handlers
+from . import notes        # noqa: F401  — registers note handlers
+from . import devices      # noqa: F401  — registers device handlers
+from . import scenes       # noqa: F401  — registers scene handlers
+from . import mixing       # noqa: F401  — registers mixing handlers
+from . import browser      # noqa: F401  — registers browser handlers
+from . import arrangement  # noqa: F401  — registers arrangement handlers
+from . import diagnostics  # noqa: F401  — registers diagnostics handler
+
+
+def create_instance(c_instance):
+    """Factory function called by Ableton Live."""
+    return LivePilot(c_instance)
+
+
+class LivePilot(ControlSurface):
+    """Main ControlSurface that starts the LivePilot TCP server."""
+
+    def __init__(self, c_instance):
+        ControlSurface.__init__(self, c_instance)
+        self._server = LivePilotServer(self)
+        self._server.start()
+        self.log_message("LivePilot v1.0.0 initialized")
+        self.show_message("LivePilot: Listening on port 9878")
+
+    def disconnect(self):
+        """Called by Ableton when the script is unloaded."""
+        if self._server:
+            self._server.stop()
+        self.log_message("LivePilot disconnected")
+        ControlSurface.disconnect(self)