livepilot 1.9.16 → 1.9.18

package/livepilot/skills/livepilot-performance-engine/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: livepilot-performance-engine
+description: This skill should be used when the user asks to "perform live", "what's safe to do during a show", "scene handoff", "energy flow", "performance mode", "safe moves", or wants live performance support with safety constraints.
+---
+
+# Performance Engine — Safety-First Live Performance
+
+The performance engine enforces a strict safety model for live performance. Every action is classified before execution. Destructive operations are blocked. Risky operations require user confirmation. Only safe operations execute freely.
+
+## Safety Classification
+
+Every performance action falls into one of four tiers.
+
+### Safe — Execute Freely
+
+These actions are non-destructive and audience-invisible if they fail. Execute without asking.
+
+- `fire_scene` / `fire_clip` — launch scenes or clips (the core of live performance)
+- `set_track_send` with small delta — nudge send levels (reverb/delay throws)
+- `set_device_parameter` on mapped macros — macro knob adjustments
+- `set_track_mute` / `set_track_solo` — mute/solo toggles
+- `set_track_volume` with delta <= 3 dB — volume nudges
+- `set_track_pan` with delta <= 0.2 — subtle pan shifts
+- Filter sweeps via `set_device_parameter` on Auto Filter — smooth frequency movement
+
+### Caution — Require User Confirmation
+
+These actions are audible and may cause a noticeable glitch if wrong. Always ask before executing.
+
+- `set_tempo` with delta <= 5 BPM — tempo nudge (can destabilize synced elements)
+- `toggle_device` — enable/disable effects (may cause pops or silence)
+- `set_track_pan` with delta > 0.2 — large pan moves are disorienting live
+- `set_track_volume` with delta > 3 dB — large volume jumps
+
+Present the action to the user: "I will [action]. This may [risk]. Confirm?"
+
+### Blocked — Never Execute During Performance
+
+These actions risk audible disasters, data loss, or session corruption during a live show.
+
+- `delete_device` / `find_and_load_device` — device chain surgery causes audio interruption
+- `create_arrangement_clip` / `create_clip` / `delete_clip` — clip creation/deletion
+- `create_midi_track` / `create_audio_track` / `delete_track` — track structure changes
+- `add_notes` / `modify_notes` / `remove_notes` — note editing while playing
+- `set_clip_loop` / `set_clip_warp_mode` — clip property changes while playing
+- `flatten_track` / `freeze_track` — CPU-intensive operations
+- Any arrangement-view editing tools
+
+If the user requests a blocked action during performance mode, explain why it is blocked and suggest a safe alternative: "That requires editing the device chain, which can cause audio dropouts during a live show. Instead, try [safe alternative]."
+
+### Unknown — Treat as Blocked
+
+Any action not explicitly classified above defaults to blocked. Do not experiment with unclassified actions during a live performance.
+
+## Performance Loop
+
+### Step 1 — Get State
+
+Call `get_performance_state` to read the current session state:
+- Playing status, current tempo, time signature
+- Which scenes and clips are currently playing
+- Track arm states, solo/mute states
+- Current energy level estimate
+
+### Step 2 — Get Safe Moves
+
+Call `get_performance_safe_moves` to get a list of contextually appropriate safe actions based on the current state. The response is filtered by what makes musical sense right now — not just what is technically safe.
+
+### Step 3 — Check Safety
+
+Before executing any user request, call `check_safety(move_type)` to verify the classification. The response confirms: `safe`, `caution`, or `blocked` with an explanation.
+
+### Step 4 — Execute Safe/Caution Only
+
+- Safe: execute immediately
+- Caution: present to user, wait for confirmation, then execute
+- Blocked: refuse with explanation and alternative
+
+### Step 5 — Scene Handoff
+
+For transitioning between scenes (the primary live performance action), call `plan_scene_handoff(from_scene, to_scene)` to get a transition plan:
+
+- Which clips change between the scenes
+- Recommended launch timing (quantization)
+- Volume/send adjustments to smooth the handoff
+- Any tempo changes between scenes
+
+Execute the handoff plan using safe actions only.
+
+## Energy Flow
+
+During a live set, track the energy trajectory:
+
+1. `get_performance_state` includes an `energy_estimate` (0.0-1.0)
+2. Use scene ordering to build energy arcs: low-energy scenes for intros/breakdowns, high-energy for drops/peaks
+3. `plan_scene_handoff` accounts for energy delta — large energy jumps get transition suggestions
+
+## Performance Mode Entry
+
+When the user says "performance mode", "going live", or "starting the show":
+
+1. Call `get_performance_state` to verify the session is ready
+2. Confirm the safety model with the user: "Performance mode active. I will only execute safe actions freely and ask before caution-level moves. Destructive edits are blocked."
+3. Switch to a response style optimized for speed: short confirmations, no lengthy explanations mid-performance
+4. Prioritize scene launches and safe parameter nudges
+
+## Performance Mode Exit
+
+When the user says "done performing", "show's over", or "exit performance mode":
+
+1. Confirm: "Performance mode ended. Full editing capabilities restored."
+2. Resume normal operation with all tools available
+
+## Emergency Actions
+
+If something goes wrong during a live show:
+
+- `stop_all_clips` — emergency silence (use only if requested)
+- `set_master_volume(0.0)` — fade to silence
+- `set_track_mute` on the problem track — isolate the issue
+
+Never call `undo` during a live performance — it may revert a scene launch or clip state in unpredictable ways.

package/livepilot/skills/livepilot-performance-engine/references/performance-safety.md

@@ -0,0 +1,98 @@
+# Performance Safety Reference
+
+Complete classification of every LivePilot action for live performance contexts.
+
+## Safe Actions (No Confirmation Needed)
+
+| Action | Tool | Notes |
+|--------|------|-------|
+| Launch scene | `fire_scene` | Core performance action |
+| Launch clip | `fire_clip` | Individual clip triggering |
+| Stop clip | `stop_clip` | Individual clip stop |
+| Stop track clips | `stop_track_clips` | Clear a track |
+| Volume nudge (small) | `set_track_volume` | Delta <= 3 dB only |
+| Send nudge | `set_track_send` | Small adjustments to reverb/delay throws |
+| Macro nudge | `set_device_parameter` | On mapped macro controls only |
+| Filter sweep | `set_device_parameter` | On Auto Filter frequency parameter |
+| Mute toggle | `set_track_mute` | Non-destructive, reversible |
+| Solo toggle | `set_track_solo` | Non-destructive, reversible |
+| Pan nudge (small) | `set_track_pan` | Delta <= 0.2 only |
+| Master volume | `set_master_volume` | For overall level control |
+| Continue playback | `continue_playback` | Resume from pause |
+| Jump to cue | `jump_to_cue` | Navigate arrangement cue points |
+| Get state | `get_performance_state` | Read-only, always safe |
+| Get playing clips | `get_playing_clips` | Read-only |
+| Get scene matrix | `get_scene_matrix` | Read-only |
+| Any get_* tool | various | All read-only tools are safe |
+
+## Caution Actions (Require Confirmation)
+
+| Action | Tool | Risk |
+|--------|------|------|
+| Tempo nudge | `set_tempo` | May destabilize warped audio, synced plugins |
+| Device toggle | `toggle_device` | May cause audio pop, click, or silence |
+| Large pan move | `set_track_pan` | Disorienting for audience if sudden |
+| Large volume jump | `set_track_volume` | Jarring if delta > 3 dB |
+| Fire scene clips | `fire_scene_clips` | Selective scene launch, less predictable |
+| Set scene tempo | `set_scene_tempo` | Changes tempo on next scene fire |
+
+### Confirmation Protocol
+
+Present as: "[Action description]. Risk: [what could go wrong]. Confirm?"
+
+Keep confirmations short during performance. One line maximum.
+
+## Blocked Actions (Never During Performance)
+
+### Device Chain Surgery
+- `find_and_load_device` — loading causes audio thread hiccup
+- `delete_device` — removing active device causes dropout
+- `load_device_by_uri` — same as find_and_load
+- `load_browser_item` — browser loading is unpredictable latency
+
+### Track Structure
+- `create_midi_track` / `create_audio_track` / `create_return_track` — track creation pauses audio engine momentarily
+- `delete_track` — data loss, audio interruption
+- `duplicate_track` — CPU spike
+- `set_track_routing` — routing changes can cause feedback or silence
+
+### Clip Editing
+- `create_clip` / `delete_clip` / `duplicate_clip` — structural changes while playing
+- `set_clip_loop` / `set_clip_warp_mode` / `quantize_clip` — property changes on playing clips
+- `add_notes` / `modify_notes` / `remove_notes` — note editing mid-playback
+
+### Arrangement Editing
+- All `*_arrangement_*` tools — arrangement view editing during performance
+- `set_arrangement_automation` — automation lane changes
+
+### Heavy Operations
+- `freeze_track` / `flatten_track` — CPU-intensive, blocks audio thread
+- `start_recording` — may cause unexpected monitoring behavior
+- `capture_audio` / `capture_midi` — resource-intensive
+
+### Data Operations
+- `undo` / `redo` — unpredictable state reversion during live playback
+- `memory_learn` / `memory_delete` — non-urgent, save for after the show
+- `import_midi_to_clip` — file I/O during performance
+
+## Emergency Procedures
+
+### Audio Problem
+1. `set_track_mute(track_index, true)` on the problem track
+2. If problem persists: `set_master_volume(0.0)` for fade to silence
+3. Last resort: `stop_all_clips` for emergency silence
+
+### Feedback Loop
+1. `set_track_mute` on the suspected track immediately
+2. `set_track_send` to zero on all sends for that track
+3. Gradually unmute after identifying the routing issue
+
+### Wrong Scene Launched
+1. Immediately `fire_scene` on the correct scene
+2. Or `stop_all_clips` and restart from the correct point
+3. Do not use `undo` — it may revert more than intended
+
+### CPU Spike
+1. `set_track_mute` on the most CPU-heavy tracks (check `get_session_info` for device counts)
+2. `toggle_device` to bypass heavy effects (with caution confirmation skipped in emergency)
+3. If critical: `stop_all_clips` and restart with fewer active tracks

package/livepilot/skills/livepilot-release/SKILL.md

@@ -28,21 +28,21 @@ Run this checklist EVERY time the user says "update everything", "push", "releas
 
 ## 2. Tool Count (must ALL match)
 
-Current: **236 tools across 32 domains**.
+Current: **236 tools across 31 domains**.
 Core (no M4L): **149**. Analyzer (M4L): **29**. Perception (offline): **4**.
 
 Verify: `grep -rc "@mcp.tool" mcp_server/tools/ | grep -v ":0" | awk -F: '{sum+=$2} END{print sum}'`
 
 Files that reference tool count:
 - [ ] `README.md` — header, PERCEPTION section ("207 core...29 analyzer"), Analyzer table header "(29)", Perception table header "(4)"
-- [ ] `package.json` → `"description"` (236 tools, 32 domains)
+- [ ] `package.json` → `"description"` (236 tools, 31 domains)
 - [ ] `server.json` → `"description"`
 - [ ] `livepilot/.Codex-plugin/plugin.json` → `"description"` (primary Codex manifest)
 - [ ] `livepilot/.claude-plugin/plugin.json` → `"description"` (must match Codex plugin)
 - [ ] `.claude-plugin/marketplace.json` → `"description"`
-- [ ] `CLAUDE.md` → "236 tools across 32 domains"
-- [ ] `livepilot/skills/livepilot-core/SKILL.md` — "236 tools across 32 domains", Analyzer (29), Perception (4)
-- [ ] `livepilot/skills/livepilot-core/references/overview.md` — "236 tools across 32 domains"
+- [ ] `CLAUDE.md` → "236 tools across 31 domains"
+- [ ] `livepilot/skills/livepilot-core/SKILL.md` — "236 tools across 31 domains", Analyzer (29), Perception (4)
+- [ ] `livepilot/skills/livepilot-core/references/overview.md` — "236 tools across 31 domains"
 - [ ] `docs/manual/index.md` — domain table: Analyzer (29), Perception (4)
 - [ ] `docs/manual/getting-started.md` — "207 core tools...29 analyzer"
 - [ ] `docs/manual/tool-reference.md` — all domains present with correct counts
@@ -56,10 +56,10 @@ Files that reference tool count:
 
 ## 3. Domain Count
 
-Current: **32 domains**: transport, tracks, clips, notes, devices, scenes, mixing, browser, arrangement, memory, analyzer, automation, theory, generative, harmony, midi_io, perception, agent_os, composition, research, planner, project_brain, runtime, evaluation, memory_fabric, mix_engine, sound_design, transition_engine, reference_engine, translation_engine, performance_engine.
+Current: **31 domains**: transport, tracks, clips, notes, devices, scenes, mixing, browser, arrangement, memory, analyzer, automation, theory, generative, harmony, midi_io, perception, agent_os, composition, motif, research, planner, project_brain, runtime, evaluation, mix_engine, sound_design, transition_engine, reference_engine, translation_engine, performance_engine.
 
-- [ ] All files that mention domain count say "32 domains"
-- [ ] Domain lists include ALL 32 (especially newer domains — they're the most often omitted)
+- [ ] All files that mention domain count say "31 domains"
+- [ ] Domain lists include ALL 31 (especially newer domains — they're the most often omitted)
 
 ## 4. npm Registry
 
@@ -89,8 +89,8 @@ Current: **32 domains**: transport, tracks, clips, notes, devices, scenes, mixin
 
 - [ ] `README.md` — features match current capabilities, "Coming" section is accurate
 - [ ] `docs/manual/getting-started.md` — install instructions current
-- [ ] `docs/manual/tool-reference.md` — all 32 domains listed, all 236 tools present
-- [ ] `docs/TOOL_REFERENCE.md` — all 32 domains present
+- [ ] `docs/manual/tool-reference.md` — all 31 domains listed, all 236 tools present
+- [ ] `docs/TOOL_REFERENCE.md` — all 31 domains present
 - [ ] `docs/M4L_BRIDGE.md` — architecture accurate, core tool count correct
 
 ## 9. Derived Artifacts

package/livepilot/skills/livepilot-sound-design-engine/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: livepilot-sound-design-engine
+description: This skill should be used when the user asks to "design a sound", "analyze a patch", "fix a static sound", "add modulation", "check my timbre", "improve a synth patch", or wants critic-driven sound design feedback and iterative patch refinement.
+---
+
+# Sound Design Engine — Critic-Driven Patch Refinement
+
+The sound design engine analyzes synth patches, identifies timbral weaknesses, and iteratively refines them through a measured critic loop. Every change is evaluated against the before state.
+
+## The Sound Design Critic Loop
+
+### Step 1 — Build Patch Model
+
+Call `get_patch_model(track_index)` to build a PatchModel for the target track. The PatchModel maps every device on the track into typed blocks (oscillator, filter, envelope, lfo, saturation, spatial, effect) and classifies each as `controllable` or `opaque`.
+
+Read the response carefully:
+- `blocks`: ordered list of processing blocks with types and parameter names
+- `controllable_params`: parameters you can modify via `set_device_parameter`
+- `opaque_blocks`: third-party plugins where parameters may not map cleanly
+- `modulation_sources`: detected LFOs, envelopes, and macro mappings
+- `signal_flow`: how blocks connect (serial, parallel, or rack chains)
+
+See `references/patch-model.md` for the full PatchModel structure and native device block map.
+
+### Step 2 — Analyze
+
+Call `analyze_sound_design(track_index)` to run all sound design critics against the patch. The response contains an `issues` array with `critic`, `severity`, `block`, and `evidence`.
+
+Five critics run during analysis. See `references/sound-design-critics.md` for thresholds:
+
+- **static_timbre** — sound does not evolve over time, no movement
+- **no_modulation_sources** — no LFOs, envelopes, or automation detected
+- **modulation_flatness** — modulation exists but ranges are too narrow to hear
+- **missing_filter** — raw oscillator output with no spectral shaping
+- **spectral_imbalance** — too much energy in one frequency region, or gaps
+
+### Step 3 — Plan
+
+Pick the highest-severity issue. Call `plan_sound_design_move(track_index)` with the issue. The planner returns a single intervention:
+
+- `move_type`: one of the move vocabulary entries
+- `target_device`: device index on the track
+- `target_parameter`: parameter name or index
+- `target_value`: the new value
+- `rationale`: why this move addresses the issue
+
+Move vocabulary:
+- **modulation_injection** — add or increase LFO/envelope depth on a parameter
+- **filter_shaping** — adjust cutoff, resonance, or filter type
+- **parameter_automation** — create clip automation for time-varying timbral change
+- **oscillator_tuning** — adjust pitch, detune, waveform, or unison settings
+
+### Step 4 — Capture Before
+
+1. Call `get_device_parameters(track_index, device_index)` — save current parameter state
+2. Call `get_master_spectrum` — save spectral snapshot (if analyzer available)
+
+### Step 5 — Execute
+
+Apply the planned move using the appropriate tool:
+
+- `set_device_parameter` for direct parameter changes (filter cutoff, LFO rate, oscillator shape)
+- `toggle_device` for enabling/disabling processing blocks
+- `batch_set_parameters` when the move requires coordinated changes (e.g., LFO depth + rate together)
+- `set_clip_automation` for parameter automation moves
+- `find_and_load_device` when the fix requires adding a new device (e.g., adding an Auto Filter)
+
+Execute one move at a time. Verify before continuing.
+
+### Step 6 — Capture After
+
+Repeat the same measurements:
+
+1. Call `get_device_parameters(track_index, device_index)` — confirm the change took effect
+2. Call `get_master_spectrum` — save post-change spectral snapshot
+
+### Step 7 — Evaluate
+
+Call `evaluate_move(engine="sound_design")` with the before and after snapshots. Read:
+
+- `keep_change` (bool): whether the change improved the sound
+- `score` (0.0-1.0): quality improvement magnitude
+- `timbral_delta`: what changed spectrally
+- `explanation`: human-readable summary
+
+### Step 8 — Keep or Undo
+
+If `keep_change` is `false`, call `undo()`. Explain what was tried and why it did not improve the sound.
+
+If `keep_change` is `true`, report the improvement. If score > 0.7, consider calling `memory_learn(type="sound_design")` to save the technique.
+
+### Step 9 — Repeat
+
+Return to Step 2. Re-analyze after each kept change. The critic list updates as issues are resolved. Continue until the user is satisfied or no high-severity issues remain.
+
+## Working with Opaque Plugins
+
+Third-party AU/VST plugins may report as `opaque` in the PatchModel:
+
+1. Check `get_plugin_parameters(track_index, device_index)` — some plugins expose parameters through the host
+2. If `parameter_count <= 1`, the plugin is dead or unresponsive. Call `delete_device` and suggest a native alternative
+3. If parameters are available but unnamed (Parameter 1, Parameter 2...), try `map_plugin_parameter` to identify them by ear
+4. Report opaque status to the user — sound design critics cannot fully analyze what they cannot inspect
+
+## Quick Sound Design Checks
+
+- **"What's wrong with this sound?"** — Call `get_sound_design_issues(track_index)` for a diagnostic without executing fixes
+- **"Show me the patch"** — Call `get_patch_model(track_index)` then `walk_device_tree(track_index)` for full device chain visibility
+- **"What can I automate?"** — Read the `controllable_params` list from the PatchModel response
+
+## Native Device Strengths
+
+When adding processing blocks, prefer native Ableton devices for controllability:
+
+- **Wavetable** — complex oscillator section with built-in modulation matrix
+- **Operator** — FM synthesis with per-operator envelopes and LFO
+- **Analog** — subtractive with two filters and two LFOs
+- **Auto Filter** — standalone filter with envelope follower and LFO
+- **Corpus** — resonant body modeling for physical character
+- **Erosion** — high-frequency noise and distortion artifacts
+- **Saturator** — waveshaping with multiple curve types
+
+Always `search_browser` before loading — never guess device names.

package/livepilot/skills/livepilot-sound-design-engine/references/patch-model.md

@@ -0,0 +1,119 @@
+# Patch Model Reference
+
+The PatchModel is returned by `get_patch_model(track_index)` and represents the complete signal processing structure of a track's device chain.
+
+## PatchModel Structure
+
+```json
+{
+  "track_index": 0,
+  "track_name": "Lead Synth",
+  "blocks": [
+    {
+      "device_index": 0,
+      "device_name": "Wavetable",
+      "block_type": "oscillator",
+      "controllable": true,
+      "parameters": ["Osc 1 Pos", "Osc 1 Gain", "Sub Gain", ...],
+      "sub_blocks": [
+        { "block_type": "filter", "parameters": ["Filter Freq", "Filter Res", ...] },
+        { "block_type": "lfo", "parameters": ["LFO 1 Rate", "LFO 1 Amount", ...] },
+        { "block_type": "envelope", "parameters": ["Amp Attack", "Amp Decay", ...] }
+      ]
+    },
+    {
+      "device_index": 1,
+      "device_name": "Auto Filter",
+      "block_type": "filter",
+      "controllable": true,
+      "parameters": ["Frequency", "Resonance", "Env. Modulation", ...]
+    }
+  ],
+  "controllable_params": [...],
+  "opaque_blocks": [],
+  "modulation_sources": [
+    { "type": "lfo", "device_index": 0, "rate": "0.5 Hz", "targets": ["Filter Freq"] }
+  ],
+  "signal_flow": "serial"
+}
+```
+
+## Block Types
+
+### oscillator
+Sound source generators. Found in synth instruments (Wavetable, Operator, Analog, Drift, Simpler, Sampler).
+
+Key parameters: waveform/position, pitch/tune/detune, unison voices/spread, sub oscillator level, FM amount/ratio.
+
+### filter
+Spectral shaping. Found as sub-blocks inside instruments or as standalone devices (Auto Filter, EQ Eight).
+
+Key parameters: cutoff frequency, resonance, filter type (LP/HP/BP/Notch), slope (12/24 dB), envelope modulation amount, drive.
+
+### envelope
+Time-shaping contour generators. Usually ADSR controlling amplitude or filter cutoff.
+
+Key parameters: attack, decay, sustain, release. Some instruments offer additional envelopes with arbitrary targets.
+
+### lfo
+Low-frequency oscillators for cyclic modulation.
+
+Key parameters: rate (Hz or synced), waveform (sine, triangle, square, saw, random), amount/depth, target parameter, phase, offset.
+
+### saturation
+Waveshaping, distortion, and harmonic generation.
+
+Devices: Saturator, Overdrive, Pedal, Amp, Erosion, Dynamic Tube. Key parameters: drive, tone, type/curve, dry/wet.
+
+### spatial
+Stereo field and space processing.
+
+Devices: Reverb, Delay, Chorus, Phaser, Flanger, Echo, Hybrid Reverb. Key parameters: decay/time, pre-delay, size, damping, dry/wet, feedback.
+
+### effect
+Catch-all for utility and dynamics processing.
+
+Devices: Compressor, Glue Compressor, Limiter, Gate, Utility, Tuner, Spectrum. Key parameters vary by device.
+
+## Controllable vs Opaque
+
+- **Controllable**: native Ableton devices and well-behaved plugins where `get_device_parameters` returns named, ranged parameters. All LivePilot set/get parameter tools work reliably.
+- **Opaque**: third-party AU/VST plugins where parameter inspection fails or returns generic names (Parameter 1, Parameter 2). The sound design engine can detect the block exists but cannot reason about individual parameters.
+
+Check `parameter_count` on opaque blocks. If <= 1, the plugin failed to load — delete it and replace with a native alternative.
+
+## Native Device Block Map
+
+Quick reference for which block types each native device provides:
+
+| Device | Primary Block | Sub-blocks |
+|--------|--------------|------------|
+| Wavetable | oscillator | filter, lfo, envelope |
+| Operator | oscillator | filter, lfo, envelope |
+| Analog | oscillator | filter, lfo, envelope |
+| Drift | oscillator | filter, lfo, envelope |
+| Simpler | oscillator | filter, lfo, envelope |
+| Sampler | oscillator | filter, lfo, envelope |
+| Auto Filter | filter | lfo, envelope |
+| EQ Eight | filter | — |
+| Compressor | effect | envelope (sidechain) |
+| Glue Compressor | effect | — |
+| Saturator | saturation | — |
+| Overdrive | saturation | — |
+| Pedal | saturation | — |
+| Reverb | spatial | — |
+| Delay | spatial | filter |
+| Echo | spatial | filter, lfo |
+| Chorus-Ensemble | spatial | — |
+| Phaser-Flanger | spatial | lfo |
+| Hybrid Reverb | spatial | — |
+| Corpus | spatial | — |
+| Utility | effect | — |
+
+## Rack Detection
+
+If a track contains an Instrument Rack or Audio Effect Rack, the PatchModel reports:
+
+- `signal_flow`: "parallel" (rack chains run in parallel)
+- Each chain appears as a nested block list
+- Use `get_rack_chains(track_index, device_index)` for per-chain detail

package/livepilot/skills/livepilot-sound-design-engine/references/sound-design-critics.md

@@ -0,0 +1,118 @@
+# Sound Design Critics Reference
+
+Each critic runs during `analyze_sound_design(track_index)` and produces an issue object with `critic`, `severity` (0.0-1.0), `block`, and `evidence`.
+
+## static_timbre
+
+Detects sounds that do not evolve over time. A static timbre lacks movement, making it sound flat and lifeless in a mix.
+
+**Thresholds:**
+- severity >= 0.7: No detectable spectral change over a 4-bar window. Crest factor of spectral flux < 0.5 dB
+- severity >= 0.4: Minimal change (spectral flux < 1.5 dB). Some subtle movement present
+- severity < 0.4: Adequate movement detected, likely intentional sustain character
+
+**Evidence format:**
+```json
+{
+  "spectral_flux_db": 0.3,
+  "analysis_window_bars": 4,
+  "brightest_moment_db": -8.2,
+  "dullest_moment_db": -8.5
+}
+```
+
+**Typical fix:** modulation_injection — add LFO to filter cutoff (rate 0.1-2 Hz, depth 20-40%).
+
+## no_modulation_sources
+
+Detects patches with zero modulation sources: no LFOs, no envelopes beyond amp/filter ADSR, no automation, no macro mappings.
+
+**Thresholds:**
+- severity >= 0.7: Zero modulation sources on a melodic/pad/lead instrument
+- severity >= 0.4: No modulation on a bass or rhythmic element (some genres keep bass static intentionally)
+- severity < 0.4: Drum hits and one-shots (modulation not expected)
+
+**Evidence format:**
+```json
+{
+  "lfo_count": 0,
+  "envelope_count": 1,
+  "automation_lanes": 0,
+  "macro_mappings": 0,
+  "instrument_type": "pad"
+}
+```
+
+**Typical fix:** modulation_injection — enable device LFO if available, or add Auto Filter with LFO. For pads, map LFO to filter cutoff and/or oscillator pitch (subtle detune).
+
+## modulation_flatness
+
+Detects modulation sources that exist but operate with such narrow ranges they produce no audible effect.
+
+**Thresholds:**
+- severity >= 0.7: Modulation depth < 5% of parameter range on all targets
+- severity >= 0.4: Modulation depth 5-15% — present but barely perceptible
+- severity < 0.4: Depth > 15%, audible modulation
+
+**Evidence format:**
+```json
+{
+  "modulation_source": "LFO 1",
+  "target_parameter": "Filter Cutoff",
+  "depth_percent": 3.2,
+  "parameter_range": [20, 20000],
+  "effective_range": [850, 920]
+}
+```
+
+**Typical fix:** Increase modulation depth to 20-40% for filter targets, 5-15% for pitch targets, 10-30% for amplitude targets.
+
+## missing_filter
+
+Detects raw oscillator output with no filter or spectral shaping in the signal path. Unfiltered signals often sound harsh and sit poorly in a mix.
+
+**Thresholds:**
+- severity >= 0.7: No filter device in the signal chain, and the source is a harmonically rich waveform (saw, square, FM)
+- severity >= 0.4: Filter present but fully open (cutoff at maximum, no resonance)
+- severity < 0.4: Filter active and shaping the spectrum
+
+**Evidence format:**
+```json
+{
+  "has_filter": false,
+  "source_waveform": "sawtooth",
+  "harmonic_content": "rich",
+  "device_chain": ["Wavetable"]
+}
+```
+
+**Typical fix:** filter_shaping — add Auto Filter (low-pass, cutoff around 2-5 kHz, resonance 20-40%) or enable the instrument's built-in filter.
+
+## spectral_imbalance
+
+Detects patches with too much energy concentrated in one frequency region, or significant spectral gaps.
+
+**Thresholds:**
+- severity >= 0.7: Single band > 12 dB above the mean, or a gap > 12 dB below
+- severity >= 0.4: Imbalance 6-12 dB in one or more regions
+- severity < 0.4: Balanced spectrum appropriate for the instrument role
+
+**Evidence format:**
+```json
+{
+  "peak_band": "high_mid",
+  "peak_deviation_db": 14.2,
+  "gap_band": "low_mid",
+  "gap_deviation_db": -8.5,
+  "band_levels_db": {
+    "sub": -22.0,
+    "low": -14.5,
+    "low_mid": -20.1,
+    "mid": -11.6,
+    "high_mid": -2.4,
+    "high": -8.9
+  }
+}
+```
+
+**Typical fix:** filter_shaping to tame the peak (EQ cut or filter sweep), or oscillator_tuning to fill the gap (add sub oscillator, adjust waveform).

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.16"});
+            send_response({"ok": true, "version": "1.9.18"});
             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.16"
+__version__ = "1.9.18"