livepilot 1.9.21 → 1.9.22

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
     {
       "name": "livepilot",
       "description": "Agentic production system for Ableton Live 12 — 237 tools, 32 domains, device atlas, spectral perception, technique memory, neo-Riemannian harmony, Euclidean rhythm, species counterpoint, MIDI I/O",
-      "version": "1.9.21",
+      "version": "1.9.22",
       "author": {
         "name": "Pilot Studio"
       },

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 1.9.22 — Skill & Command Overhaul (April 2026)
+
+### Skill Updates
+- **feat(beat):** Added Step 0 "Session Prep" — for fresh projects, deletes all tracks and loads M4L Analyzer on master before starting. Includes perception check (Step 11) with spectral balance verification.
+- **feat(mix):** Added analyzer auto-load (Step 2), spectral targets by genre (Step 6), mandatory meter verification after every change (Step 8), capture+analyze loop (Step 11)
+- **feat(sounddesign):** Added mandatory `value_string` verification (Step 5), perception check (Step 11), organic movement with perlin curves (Step 8)
+- **feat(arrange):** Added motif detection (Step 3), gesture template execution (Step 7), perlin organic movement (Step 8), emotional arc verification (Step 9), LRA check for dynamic range (Step 10)
+- **feat(evaluate):** Added analyzer auto-load (Step 2), full perception snapshot with track meters (Step 6), capture+analyze offline as ground truth option
+
 ## 1.9.21 — Verification Discipline Pass (April 2026)
 
 ### Systemic Fixes

package/livepilot/.Codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "livepilot",
-  "version": "1.9.21",
+  "version": "1.9.22",
   "description": "Agentic production system for Ableton Live 12 — 237 tools, 32 domains, device atlas, spectral perception, technique memory, neo-Riemannian harmony, Euclidean rhythm, species counterpoint, MIDI I/O",
   "author": {
     "name": "Pilot Studio"

package/livepilot/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "livepilot",
-  "version": "1.9.21",
+  "version": "1.9.22",
   "description": "Agentic production system for Ableton Live 12 — 237 tools, 32 domains, device atlas, spectral perception, technique memory, neo-Riemannian harmony, Euclidean rhythm, species counterpoint, MIDI I/O",
   "author": {
     "name": "Pilot Studio"

package/livepilot/commands/arrange.md

@@ -5,15 +5,24 @@ description: Guided arrangement — build song structure with sections, transiti
 
 Guide the user through arranging their session into a full song structure.
 
-1. **Read the session** — `get_session_info` to see all tracks and clips
-2. **Analyze current structure** — `get_section_graph` to see inferred sections from scene names. If no sections, `get_scenes_info` for raw scene data.
-3. **Ask about the target structure** — what form? (verse-chorus, AABA, build-drop, through-composed). What energy arc? (gradual build, peaks and valleys, flat)
-4. **Plan the arrangement** — `plan_arrangement` with the target structure. Review the proposed section order and transitions.
-5. **Build sections** — for each section, create or duplicate scenes, set scene names and colors. Use `duplicate_scene` for variations.
-6. **Check transitions** — `analyze_transition(from_section, to_section)` for each adjacent pair. `score_transition` to evaluate quality.
-7. **Plan weak transitions** — `plan_transition` for any scored below 0.6. Execute the suggested gestures (filter sweeps, energy ramps, rhythmic fills).
-8. **Check emotional arc** — `get_emotional_arc` to verify the energy flow matches the target.
-9. **Translation check** — `check_translation` to verify mono compatibility and spectral consistency across sections.
-10. **Record to arrangement** — when the user is happy, guide them through `back_to_arranger` and recording the session performance to the timeline.
+1. **Read the session** — `get_session_info` to see all tracks and clips. `get_scene_matrix` for the full clip grid.
+2. **Analyze current structure** — `get_section_graph` to see inferred sections from scene names. `get_emotional_arc` to understand current energy flow.
+3. **Detect motifs** — `get_motif_graph` to find recurring patterns, fatigue risk, and suggested developments (inversion, augmentation, fragmentation).
+4. **Ask about the target structure** — what form? (verse-chorus, AABA, build-drop, through-composed). What energy arc? (gradual build, peaks and valleys, flat)
+5. **Plan the arrangement** — `plan_arrangement` with the target bar count and style. Review the proposed section order, transitions, and gesture templates.
+6. **Build sections** — for each section, create or duplicate scenes, set scene names and colors. Use `duplicate_scene` for variations. Use `transform_motif` for melodic development (inversion, retrograde, diminution, augmentation).
+7. **Apply gesture templates** — for each transition, use `apply_gesture_template` with the planned template:
+   - `pre_arrival_vacuum` — pull energy back before a drop
+   - `harmonic_tint_rise` — gradually open filters for intro/build sections
+   - `re_entry_spotlight` — darken then snap back to highlight returning elements
+   - `tension_ratchet` — stepped build in 4-bar stages
+   - `outro_decay_dissolve` — gradual dissolution for endings
+   - `phrase_end_throw` — reverb/delay throw at section boundaries
+   Then execute each gesture plan using `apply_automation_shape` with the suggested curve_family.
+8. **Add organic movement** — use `apply_automation_shape` with `curve_type="perlin"` on filter/send/effect parameters so nothing repeats exactly the same each cycle.
+9. **Check emotional arc** — `get_emotional_arc` to verify the energy flow matches the target. Address any issues flagged (no_clear_build, peak_too_early, no_resolution).
+10. **Verify with perception** — `get_master_spectrum` during each section to confirm spectral differentiation. `capture_audio` + `analyze_loudness` to check LRA (should be >2 LU for dynamic arrangements).
+11. **Translation check** — `check_translation` to verify mono compatibility and spectral consistency across sections.
+12. **Record to arrangement** — when satisfied, use `create_arrangement_clip` to lay out clips on the timeline, or guide the user through `back_to_arranger` and recording the session performance.
 
 Use the livepilot-composition-engine skill for section analysis and transition planning. Present the arrangement as a visual timeline to the user.

package/livepilot/commands/beat.md

@@ -5,26 +5,73 @@ description: Guided beat creation — create a beat from scratch with genre, tem
 
 Guide the user through creating a beat from scratch. Follow these steps:
 
-1. **Ask about the vibe** — genre, tempo range, mood, reference tracks
-2. **Set up the session** — `set_tempo`, create tracks for drums/bass/harmony/melody with `create_midi_track`, name and color them
-3. **Load instruments** — use `find_and_load_device` for appropriate instruments per track
-4. **Verify device health** — after loading, run `get_device_info` on each loaded device. A `parameter_count` of 0 or 1 on AU/VST plugins means the plugin failed to initialize (dead plugin). If detected:
-   - Delete the dead plugin with `delete_device`
-   - Replace with a native Ableton alternative (e.g., Saturator instead of tape plugins, Operator instead of failed FM synths)
-   - Run `get_session_diagnostics` for any other issues (armed tracks, missing instruments)
-   - Inform the user which plugin failed and what replacement was used
-5. **Program drums first** — create a clip, add kick/snare/hat patterns with `add_notes`
-6. **Add bass** — create clip, program a bassline that locks with the kick
-7. **Add harmony** — chords or pads that set the mood
-8. **Add melody** — top-line or lead element
-9. **Mix** — balance levels with `set_track_volume` and `set_track_pan`
-10. **Pitch & tuning audit** — MANDATORY before firing. Run on every melodic track (skip drums):
-    - `identify_scale` on each track — verify all tracks agree on the same tonal center
-    - `analyze_harmony` on chordal tracks (pads, keys) — verify chord quality (no accidental augmented/diminished chords unless intentional)
-    - `detect_theory_issues` with `strict=true` on each track — check for out-of-key notes, parallel fifths, voice crossing
-    - **Interpret results against the intended scale**, not just C major. The analyzer only knows 7 standard modes — exotic scales (Hijaz, Hungarian minor, whole tone, etc.) will produce false "out of key" warnings. Cross-reference flagged notes against the intended scale manually.
-    - Report a clear tuning table to the user: which tracks are clean, which have issues, what the issues are
-    - Fix wrong notes with `modify_notes` before proceeding
-11. **Fire the scene** to listen, iterate based on feedback
+## Step 0: Session Prep (fresh projects only)
+
+If the user asks for a **fresh start** (new track, clean slate, start from scratch):
+
+1. **Read the session** — `get_session_info` to see what exists
+2. **Delete all existing tracks** — loop through all tracks with `delete_track`, starting from the highest index down to 0 (deleting from the top prevents index shifts)
+3. **Load the M4L Analyzer on master** — `find_and_load_device(track_index=-1000, device_name="LivePilot_Analyzer")`. This enables real-time spectral analysis, RMS metering, and key detection for the entire session. If it fails, try `search_browser(path="max_for_live", name_filter="LivePilot")` to find the URI and load manually.
+4. **Set up master chain** — load Glue Compressor + EQ Eight + Utility on master for bus processing
+5. **Verify analyzer** — wait 2 seconds, then call `get_master_spectrum`. If it returns data, the bridge is connected. If it errors with "UDP bridge not connected", call `reconnect_bridge` to rebind.
+
+If the user is adding to an **existing project**, skip step 0 — just call `get_session_info` and work with what's there.
+
+## Step 1: Ask about the vibe
+Genre, tempo range, mood, reference tracks.
+
+## Step 2: Set up the session
+`set_tempo`, create tracks for drums/bass/harmony/melody with `create_midi_track`, name and color them.
+
+## Step 3: Load instruments
+Use `search_browser` to find devices by name, `load_browser_item` or `find_and_load_device` to load them.
+
+## Step 4: Verify device health
+After loading, run `get_device_info` on each loaded device. A `parameter_count` of 0 or 1 on AU/VST plugins means the plugin failed to initialize (dead plugin). If detected:
+- Delete the dead plugin with `delete_device`
+- Replace with a native Ableton alternative (e.g., Saturator instead of tape plugins, Operator instead of failed FM synths)
+- Run `get_session_diagnostics` for any other issues (armed tracks, missing instruments)
+- Inform the user which plugin failed and what replacement was used
+
+## Step 5: Program drums first
+Create a clip, add kick/snare/hat patterns with `add_notes`.
+
+## Step 6: Add bass
+Create clip, program a bassline that locks with the kick.
+
+## Step 7: Add harmony
+Chords or pads that set the mood.
+
+## Step 8: Add melody
+Top-line or lead element.
+
+## Step 9: Mix + VERIFY
+Balance levels with `set_track_volume` and `set_track_pan`.
+
+**MANDATORY after every parameter change:**
+- Read `value_string` in the response to confirm the actual Hz/dB/% value makes sense
+- Call `get_track_meters(include_stereo=true)` and verify each track has non-zero output
+- If a track's stereo output drops to 0, the effect is killing the signal — check `get_device_parameters` for `value_string`, fix, re-verify
+- Parameter ranges are NOT always 0-1. Always read `value_string`.
+
+## Step 10: Pitch & tuning audit
+MANDATORY before firing. Run on every melodic track (skip drums):
+- `identify_scale` on each track — verify all tracks agree on the same tonal center
+- `analyze_harmony` on chordal tracks — verify chord quality
+- `detect_theory_issues` with `strict=true` on each track — check for out-of-key notes, parallel fifths, voice crossing
+- **Interpret results against the intended scale**, not just C major
+- Report a clear tuning table to the user: which tracks are clean, which have issues
+- Fix wrong notes with `modify_notes` before proceeding
+
+## Step 11: Perception check
+If the M4L Analyzer is connected:
+- `get_master_spectrum` — check spectral balance (sub should be present but not >60% for most genres)
+- `get_master_rms` — check levels aren't clipping
+- `get_detected_key` — verify the analyzer agrees with the intended key
+
+If not connected, use `capture_audio` + `analyze_loudness` + `analyze_spectrum_offline` for offline analysis.
+
+## Step 12: Fire the scene
+Fire to listen, iterate based on feedback.
 
 Use the livepilot-core skill for all tool calls. Verify after each step. Keep the user informed of what you're doing and why.

package/livepilot/commands/evaluate.md

@@ -11,28 +11,38 @@ Run the universal evaluation loop on recent production changes.
    - `judgment_only` — no analyzer, parameter-level heuristics only
    - `read_only` — session disconnected
 
-2. **Get the last move** — `get_last_move` to understand what was changed. If no recent move, `get_recent_actions` for history.
+2. **Ensure analyzer** — if mode is `judgment_only`, try to get full perception:
+   - `find_and_load_device(track_index=-1000, device_name="LivePilot_Analyzer")`
+   - Wait 2s, then `get_master_spectrum` to test the bridge
+   - If bridge disconnected: `reconnect_bridge`
+   - If still unavailable: proceed with `judgment_only` but tell the user
 
-3. **Ask what the goal was** — what were they trying to achieve? More clarity? Wider stereo? Punchier drums?
+3. **Get the last move** — `get_last_move` to understand what was changed. If no recent move, `get_recent_actions` for history.
 
-4. **Compile the goal** — `compile_goal_vector(goal_description, mode="improve")`
+4. **Ask what the goal was** — what were they trying to achieve? More clarity? Wider stereo? Punchier drums?
 
-5. **Capture current state** — `get_master_spectrum` + `get_master_rms` + `get_mix_snapshot`
+5. **Compile the goal** — `compile_goal_vector(goal_description, mode="improve")`
 
-6. **Undo the change** — `undo()` to restore the before state
+6. **Capture current state** — full perception snapshot:
+   - `get_master_spectrum` + `get_master_rms` (if analyzer available)
+   - `get_track_meters(include_stereo=true)` — verify all tracks producing audio
+   - `get_mix_snapshot` — full volume/pan/send state
+   - Optionally: `capture_audio` + `analyze_loudness` + `analyze_spectrum_offline` for ground truth
 
-7. **Capture before state** — same reads as step 5
+7. **Undo the change** — `undo()` to restore the before state
 
-8. **Redo the change** — `redo()` to restore the after state
+8. **Capture before state** — same reads as step 6
 
-9. **Evaluate** — `evaluate_move(before_snapshot, after_snapshot, goal)` or use engine-specific:
-   - Mix changes: `evaluate_mix_move`
-   - Composition changes: `evaluate_composition_move`
-   - Multi-dimensional: `evaluate_with_fabric`
+9. **Redo the change** — `redo()` to restore the after state
 
-10. **Report results** — show: score (0-1), keep_change recommendation, goal_progress, collateral_damage, dimension changes
+10. **Evaluate** — `evaluate_move(before_snapshot, after_snapshot, goal)` or use engine-specific:
+    - Mix changes: `evaluate_mix_move`
+    - Composition changes: `evaluate_composition_move`
+    - Multi-dimensional: `evaluate_with_fabric`
 
-11. **Act on recommendation:**
+11. **Report results** — show: score (0-1), keep_change recommendation, goal_progress, collateral_damage, dimension changes
+
+12. **Act on recommendation:**
     - If `keep_change=true` — keep, suggest `memory_learn` if score > 0.7
     - If `keep_change=false` — `undo()`, explain why (collateral damage, goal regression)
 

package/livepilot/commands/mix.md

@@ -6,14 +6,23 @@ description: Mixing assistant — analyze and balance track levels, panning, and
 Help the user mix their session. Follow these steps:
 
 1. **Read the session** — `get_session_info` to see all tracks
-2. **Analyze each track** — `get_track_info` for clip and device details, check current volume/pan
-3. **Quick mix status** — `get_mix_summary` for a fast overview (track count, dynamics, stereo, issues)
-4. **Run critics** — `get_mix_issues` to detect problems (masking, dynamics, stereo width, headroom)
-5. **Suggest a mix** — propose volume levels, panning positions, and send amounts based on the track types, instruments, and detected issues
-6. **Apply with confirmation** — only change levels after the user approves each suggestion
-7. **Check return tracks** — `get_return_tracks` to see shared effects
-8. **Master chain** — `get_master_track` to review the master
-9. **Evaluate** — after changes, `evaluate_mix_move` with before/after snapshots to verify improvement
+2. **Ensure analyzer** — check if M4L Analyzer is on master. If `get_master_spectrum` errors, load it: `find_and_load_device(track_index=-1000, device_name="LivePilot_Analyzer")`. If bridge disconnected, try `reconnect_bridge`.
+3. **Analyze each track** — `get_track_info` for clip and device details, `get_track_meters(include_stereo=true)` for actual output levels
+4. **Quick mix status** — `get_mix_summary` for a fast overview (track count, dynamics, stereo, issues)
+5. **Run critics** — `get_mix_issues` to detect problems (masking, dynamics, stereo width, headroom). For frequency collisions: `get_masking_report`
+6. **Spectral check** — `get_master_spectrum` for 8-band frequency balance. Typical targets:
+   - Hip-hop: sub dominant, centroid 400-800 Hz
+   - Electronic: balanced, centroid 800-1500 Hz
+   - Ambient: mid-focused, low sub, centroid 500-1000 Hz
+7. **Suggest a mix** — propose volume levels, panning positions, and send amounts based on the track types, instruments, and detected issues
+8. **Apply with verification** — after EVERY volume/pan/send change:
+   - Read `value_string` in the response
+   - Call `get_track_meters(include_stereo=true)` to verify no track went silent
+   - Check master spectrum to verify the balance improved
+9. **Check return tracks** — `get_return_tracks` to see shared effects
+10. **Master chain** — `get_master_track` to review the master. Typical chain: Glue Compressor → EQ Eight → Utility → LivePilot_Analyzer
+11. **Capture + analyze** — `capture_audio` then `analyze_loudness` for LUFS/peak/LRA, `analyze_spectrum_offline` for centroid/rolloff/balance
+12. **Evaluate** — `evaluate_mix_move` with before/after snapshots to verify improvement. If `keep_change` is false, `undo` immediately.
 
 Present suggestions in a clear table format. Always explain the reasoning (e.g., "panning the hi-hats slightly right to create stereo width"). Use `undo` if the user doesn't like a change.
 

package/livepilot/commands/sounddesign.md

@@ -8,14 +8,22 @@ Guide the user through designing a sound. Follow these steps:
 1. **Ask about the target sound** — what character? (warm pad, aggressive bass, shimmering lead, atmospheric texture, etc.)
 2. **Choose an instrument** — pick the right synth for the job, load it with `search_browser` → `load_browser_item`
 3. **Verify device loaded** — `get_device_info` to confirm plugin initialized (AU/VST with `parameter_count` <= 1 = dead plugin — delete and replace with native alternative)
-4. **Get parameters** — `get_device_parameters` to see what's available
+4. **Get parameters** — `get_device_parameters` to see what's available. **Read `value_string`** to understand actual units (Hz, dB, %, ms) — raw values are often NOT in human units.
 5. **Shape the sound** — `set_device_parameter` or `batch_set_parameters` to dial in the character
+   - **ALWAYS read `value_string` in the response** to confirm the actual value makes sense
+   - **ALWAYS call `get_track_meters(include_stereo=true)` after filter/effect changes** — verify the track still produces audio
+   - If stereo output drops to 0, the effect is killing the signal. Check `value_string`, fix, re-verify.
 6. **Run critics** — `analyze_sound_design(track_index)` to check for static timbre, missing modulation, spectral imbalance
-7. **Address issues** — `plan_sound_design_move(track_index)` for suggested improvements
-8. **Add effects** — load effects (reverb, delay, chorus, distortion, etc.) and tweak their parameters
+7. **Address issues** — `plan_sound_design_move(track_index)` for suggested improvements, `get_patch_model` to see chain structure
+8. **Add effects** — load effects and tweak. For automation, use `apply_automation_shape` with musically appropriate curve types:
+   - Filter sweeps → exponential (perceptually even)
+   - Volume fades → logarithmic (matches ear's response)
+   - Organic movement → perlin (never repeats exactly)
+   - If using `apply_automation_recipe`, verify the recipe didn't push parameters to extremes
 9. **Create a test pattern** — `create_clip` + `add_notes` with a simple pattern to audition
 10. **Fire the clip** to listen, iterate based on feedback
-11. **Evaluate** — `evaluate_move(engine="sound_design")` with before/after to verify improvement
+11. **Perception check** — `get_master_spectrum` or `capture_audio` + `analyze_spectrum_offline` to verify the sound sits correctly in the frequency spectrum
+12. **Evaluate** — `evaluate_move` with before/after snapshots to verify improvement
 
 Explain what each parameter does as you adjust it. Use `undo` liberally if something sounds wrong.
 

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

@@ -1,4 +1,4 @@
-# LivePilot v1.9.21 — Architecture & Tool Reference
+# LivePilot v1.9.22 — Architecture & Tool Reference
 
 Agentic production system for Ableton Live 12. 237 tools across 32 domains. Device atlas (280+ devices), spectral perception (M4L analyzer), technique memory, automation intelligence (16 curve types, 15 recipes), music theory (Krumhansl-Schmuckler, species counterpoint), generative algorithms (Euclidean rhythm, tintinnabuli, phase shift, additive process), neo-Riemannian harmony (PRL transforms, Tonnetz), MIDI file I/O.
 

package/m4l_device/livepilot_bridge.js

@@ -84,7 +84,7 @@ function anything() {
 function dispatch(cmd, args) {
     switch(cmd) {
         case "ping":
-            send_response({"ok": true, "version": "1.9.21"});
+            send_response({"ok": true, "version": "1.9.22"});
             break;
         case "get_params":
             cmd_get_params(args);

package/mcp_server/__init__.py

@@ -1,2 +1,2 @@
 """LivePilot MCP Server — bridges MCP protocol to Ableton Live."""
-__version__ = "1.9.21"
+__version__ = "1.9.22"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "livepilot",
-  "version": "1.9.21",
+  "version": "1.9.22",
   "mcpName": "io.github.dreamrec/livepilot",
   "description": "Agentic production system for Ableton Live 12 — 237 tools, 32 domains, device atlas, spectral perception, technique memory, neo-Riemannian harmony, Euclidean rhythm, species counterpoint, MIDI I/O",
   "author": "Pilot Studio",

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.9.21"
+__version__ = "1.9.22"
 
 from _Framework.ControlSurface import ControlSurface
 from .server import LivePilotServer