livepilot 1.10.7 → 1.10.9

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

@@ -1,123 +0,0 @@
----
-name: livepilot-mix-engine
-description: This skill should be used when the user asks to "analyze my mix", "find mix issues", "fix masking", "check frequency clashes", "improve dynamics", "check stereo width", "check headroom", or wants critic-driven mix analysis and evaluation. Provides the mix critic loop for iterative mix improvement.
----
-
-# Mix Engine — Critic-Driven Mix Improvement
-
-The mix engine runs an iterative critic loop: analyze, plan, execute, measure, evaluate, keep or undo. Every mix change is measured before and after. Nothing stays unless it scores better than the original.
-
-## The Mix Critic Loop
-
-Follow these steps in order. Do not skip the evaluation step.
-
-### Step 1 — Analyze
-
-Call `analyze_mix` or `get_mix_issues` to build a MixState and run all critics against the current session. The response contains an `issues` array, each with a `critic`, `severity`, `track_index`, and `evidence` dict.
-
-If the M4L analyzer bridge is absent, critics fall back to role-based heuristics only (track names, device chains, volume/pan positions). Inform the user that spectral analysis is unavailable and recommendations are less precise.
-
-For detailed frequency collision data, call `get_masking_report`. For a quick status overview without the full critic pass, call `get_mix_summary`.
-
-### Step 2 — Plan
-
-Pick the highest-severity issue from the `issues` array. Call `plan_mix_move` with the issue data. The planner returns the smallest intervention that addresses the problem — a single parameter change, not a chain of edits.
-
-Read the `move` object: it contains `move_type`, `target_track`, `target_device`, `target_parameter`, `target_value`, and `rationale`. Consult the move vocabulary in `references/mix-moves.md` for parameter ranges.
-
-### Step 3 — Capture Before
-
-Take a measurement snapshot before executing anything:
-
-1. Call `get_master_spectrum` — save the 8-band spectral data
-2. Call `get_master_rms` — save the RMS and peak values
-
-Optionally call `get_mix_snapshot` if you need per-track volume/pan/send state for the evaluation.
-
-### Step 4 — Execute
-
-Execute the planned move. Use the appropriate tool for the move type:
-
-- `set_device_parameter` for EQ cuts/boosts, compressor thresholds, saturation drives
-- `set_track_volume` for gain staging
-- `set_track_pan` for stereo placement
-- `set_track_send` for bus routing levels
-- `toggle_device` for bypassing/enabling processors
-- `batch_set_parameters` when the move requires multiple related parameter changes on the same device
-
-Execute exactly one move. Do not chain multiple interventions before measuring.
-
-### Step 5 — Capture After
-
-Repeat the same measurements from Step 3:
-
-1. Call `get_master_spectrum` — save the post-change spectral data
-2. Call `get_master_rms` — save the post-change RMS and peak values
-
-### Step 6 — Evaluate
-
-Call `evaluate_mix_move` with the before and after snapshots:
-
-```
-evaluate_mix_move(
-  before_snapshot: { spectrum: [...], rms: float, peak: float },
-  after_snapshot:  { spectrum: [...], rms: float, peak: float },
-  targets: { ... },     # what the move aimed to improve
-  protect: { ... }      # what must not get worse
-)
-```
-
-Read the response: `keep_change` (bool), `score` (0.0-1.0), `improvements` (list), `regressions` (list), `explanation` (string).
-
-### Step 7 — Keep or Undo
-
-If `keep_change` is `false`, call `undo()` immediately. Tell the user what was tried and why it was reverted, citing the `regressions` list.
-
-If `keep_change` is `true`, report the improvement to the user with the score and explanation.
-
-### Step 8 — Learn (Optional)
-
-If the move scored above 0.7 and the user confirms satisfaction, call `memory_learn(name="...", type="mix_template", qualities={"summary": "..."}, payload={...})` to save the technique for future recall.
-
-### Step 9 — Repeat
-
-Return to Step 1 and re-analyze. The critic list updates after each change. Continue until no high-severity issues remain or the user says to stop.
-
-## Quick Mix Checks
-
-Not every request needs the full loop:
-
-- **"How's my mix?"** — Call `get_mix_summary` for a one-shot status report with no changes
-- **"What's clashing?"** — Call `get_masking_report` for detailed per-pair frequency collision data
-- **"What are the issues?"** — Call `get_mix_issues` for the critic list without executing any fixes
-
-## Critic Types
-
-Six critics run during analysis. See `references/mix-critics.md` for thresholds and evidence format:
-
-- **masking** — frequency collisions between overlapping tracks
-- **over_compressed** — excessive compression reducing dynamic range
-- **flat_dynamics** — insufficient volume variation across sections
-- **low_headroom** — master peak too close to 0 dBFS
-- **stereo_width** — mono collapse or excessive width on specific elements
-- **spectral_balance** — overall tonal balance skew (too bright, too dark, mid-heavy)
-
-## Move Vocabulary
-
-The planner draws from six move types. See `references/mix-moves.md` for parameter ranges:
-
-- **gain_staging** — volume adjustments to establish proper level hierarchy
-- **bus_compression** — glue compression on groups or master
-- **transient_shaping** — attack/sustain manipulation for punch or smoothness
-- **eq_cut** — subtractive EQ to clear masking or remove resonances
-- **eq_boost** — additive EQ to bring out character (use sparingly)
-- **pan_spread** — stereo placement adjustments for width and separation
-
-## Analyzer Dependency
-
-The mix engine works in two modes:
-
-- **Full mode** (M4L analyzer connected): spectral data, RMS, key detection available. Critics use measured evidence.
-- **Heuristic mode** (no analyzer): critics infer from track names, device chains, and parameter positions. Always inform the user: "Spectral analysis unavailable — recommendations are based on track structure and device settings only."
-
-Call `get_capability_state` to check which mode is active before starting the loop.

package/livepilot/skills/livepilot-mix-engine/references/mix-critics.md

@@ -1,143 +0,0 @@
-# Mix Critics Reference
-
-Each critic runs during `analyze_mix` or `get_mix_issues` and produces an issue object with `critic`, `severity` (0.0-1.0), `track_index`, and `evidence`.
-
-## masking
-
-Detects frequency collisions between tracks that occupy the same spectral range.
-
-**Thresholds:**
-- severity >= 0.7: Two tracks share > 60% spectral overlap in the same frequency band with both > -12 dB in that range
-- severity >= 0.4: Partial overlap (30-60%) or one track is significantly quieter
-- severity < 0.4: Minor overlap, likely intentional layering
-
-**Evidence format:**
-```json
-{
-  "track_a": 0,
-  "track_b": 2,
-  "collision_band": "low_mid",
-  "frequency_range": [200, 500],
-  "overlap_percent": 72.5,
-  "a_level_db": -8.2,
-  "b_level_db": -10.1
-}
-```
-
-**Typical fix:** eq_cut on the less important track in the collision band, or pan_spread to separate spatially.
-
-## over_compressed
-
-Detects tracks or the master bus with excessive compression, indicated by very low crest factor (peak-to-RMS ratio).
-
-**Thresholds:**
-- severity >= 0.7: Crest factor < 3 dB on a dynamic source (vocals, drums, full mix)
-- severity >= 0.4: Crest factor 3-6 dB on sources that should be more dynamic
-- severity < 0.4: Mild compression, may be intentional for genre
-
-**Evidence format:**
-```json
-{
-  "track_index": 1,
-  "crest_factor_db": 2.4,
-  "rms_db": -12.3,
-  "peak_db": -9.9,
-  "compressor_device": "Compressor",
-  "compressor_ratio": 8.0,
-  "compressor_threshold_db": -20.0
-}
-```
-
-**Typical fix:** Raise compressor threshold, reduce ratio, or increase attack time.
-
-## flat_dynamics
-
-Detects tracks or sections with insufficient volume variation, making the mix feel static across song sections.
-
-**Thresholds:**
-- severity >= 0.7: Volume variation < 2 dB across all sections
-- severity >= 0.4: Volume variation 2-4 dB where genre expects more contrast
-- severity < 0.4: Minimal variation but may suit the genre (EDM drops, ambient)
-
-**Evidence format:**
-```json
-{
-  "track_index": 3,
-  "section_volumes_db": [-10.2, -10.5, -10.1, -10.4],
-  "volume_range_db": 0.4,
-  "expected_range_db": 6.0
-}
-```
-
-**Typical fix:** Automation on track volume or device parameters between sections.
-
-## low_headroom
-
-Detects when the master bus peak is dangerously close to 0 dBFS, risking clipping.
-
-**Thresholds:**
-- severity >= 0.7: Master peak > -1 dBFS
-- severity >= 0.4: Master peak between -3 and -1 dBFS
-- severity < 0.4: Master peak between -6 and -3 dBFS (acceptable for mastered content)
-
-**Evidence format:**
-```json
-{
-  "master_peak_db": -0.3,
-  "master_rms_db": -8.2,
-  "headroom_db": 0.3,
-  "clipping": false
-}
-```
-
-**Typical fix:** gain_staging — reduce the loudest tracks by 1-3 dB, or apply a limiter on the master.
-
-## stereo_width
-
-Detects stereo problems: mono collapse (too narrow), excessive width (phase issues), or elements placed inappropriately in the stereo field.
-
-**Thresholds:**
-- severity >= 0.7: Correlation coefficient < 0.1 (phase issues) or > 0.95 (essentially mono)
-- severity >= 0.4: Bass content with significant stereo width, or lead vocal panned away from center
-- severity < 0.4: Minor width imbalance
-
-**Evidence format:**
-```json
-{
-  "track_index": 5,
-  "correlation": 0.05,
-  "width_estimate": 0.95,
-  "issue_type": "phase_cancellation",
-  "frequency_range": [100, 300]
-}
-```
-
-**Typical fix:** Narrow bass to mono below 150 Hz (Utility mid/side), widen or narrow specific elements with pan_spread.
-
-## spectral_balance
-
-Detects overall tonal balance skew across the full mix — too bright, too dark, or mid-heavy compared to reference targets.
-
-**Thresholds:**
-- severity >= 0.7: Any band deviates > 6 dB from genre target curve
-- severity >= 0.4: Deviation 3-6 dB in one or more bands
-- severity < 0.4: Minor skew, within normal range
-
-**Evidence format:**
-```json
-{
-  "balance_type": "too_bright",
-  "band_deviations_db": {
-    "sub": -1.2,
-    "low": 0.5,
-    "low_mid": -0.8,
-    "mid": -2.1,
-    "high_mid": 4.2,
-    "high": 7.1,
-    "air": 5.8
-  },
-  "reference_curve": "electronic_modern"
-}
-```
-
-**Typical fix:** eq_cut on the protruding bands, or eq_boost on deficient bands. Prefer cuts over boosts.

package/livepilot/skills/livepilot-mix-engine/references/mix-moves.md

@@ -1,105 +0,0 @@
-# Mix Moves Reference
-
-The move vocabulary used by `plan_mix_move`. Each move type has defined parameter ranges and constraints.
-
-## gain_staging
-
-Adjust track or bus volume to establish proper level hierarchy.
-
-**Parameters:**
-- `target_track`: track index (0-based)
-- `target_value`: normalized volume 0.0-1.0 (0.85 = unity / 0 dB)
-- `delta_db`: typical adjustment range -6 to +3 dB per move
-
-**Constraints:**
-- Never boost more than +3 dB in a single move
-- Prefer cutting the louder track over boosting the quieter one
-- Check master headroom after any gain change
-- Group tracks (drums, synths, vocals) should be staged relative to each other first
-
-**Tools:** `set_track_volume`, `set_master_volume`
-
-## bus_compression
-
-Apply or adjust glue compression on groups, return tracks, or master bus.
-
-**Parameters:**
-- `threshold_db`: -30 to 0 dB (start conservative at -15)
-- `ratio`: 1.5:1 to 4:1 for glue, up to 8:1 for limiting
-- `attack_ms`: 0.1 to 100 ms (10-30 ms for glue, <1 ms for limiting)
-- `release_ms`: 50 to 500 ms (auto release preferred for master bus)
-- `makeup_gain_db`: 0 to +6 dB
-
-**Constraints:**
-- Gain reduction should stay under 3-4 dB for glue compression
-- Always capture before/after RMS to verify loudness is maintained
-- On master bus, prefer ratio <= 2:1 and attack >= 10 ms
-
-**Tools:** `set_device_parameter`, `find_and_load_device(track_index, "Compressor")`
-
-## transient_shaping
-
-Adjust attack and sustain characteristics to control punch and body.
-
-**Parameters:**
-- `attack`: -100% to +100% (negative softens, positive sharpens)
-- `sustain`: -100% to +100% (negative tightens, positive lengthens)
-
-**Constraints:**
-- Apply to individual drum hits or drum bus, not full mix
-- Check that transient shaping doesn't push peaks above headroom
-- Often more effective than compression for punch problems
-
-**Tools:** `set_device_parameter` on a transient shaper device
-
-## eq_cut
-
-Subtractive EQ to clear masking, remove resonances, or fix spectral balance.
-
-**Parameters:**
-- `frequency_hz`: 20 to 20000 Hz
-- `gain_db`: -12 to 0 dB (never cut more than 12 dB in one move)
-- `q`: 0.5 to 8.0 (narrow cuts 4-8 for resonances, wide cuts 0.5-2 for balance)
-- `filter_type`: low_cut, high_cut, bell, notch
-
-**Constraints:**
-- Prefer EQ Eight for surgical work (8 bands available)
-- For low cuts on non-bass tracks, use 18 or 24 dB/oct high-pass
-- Cut on the less important track in a masking pair
-- Verify after cut that the track still sounds full — over-cutting kills body
-
-**Tools:** `set_device_parameter`, `find_and_load_device(track_index, "EQ Eight")`
-
-## eq_boost
-
-Additive EQ to bring out character frequencies. Use sparingly.
-
-**Parameters:**
-- `frequency_hz`: 20 to 20000 Hz
-- `gain_db`: 0 to +4 dB (never boost more than 4 dB in one move)
-- `q`: 0.5 to 4.0 (wide boosts sound more natural)
-
-**Constraints:**
-- Always try a cut on competing tracks before boosting
-- Boosts above +4 dB usually indicate a source problem, not a mix problem
-- Check master headroom after any boost — boosts add energy
-- Wide Q (0.5-1.5) for tonal shaping, narrow Q (2-4) for emphasis
-
-**Tools:** `set_device_parameter` on EQ device
-
-## pan_spread
-
-Stereo placement adjustments for width and separation.
-
-**Parameters:**
-- `pan`: -1.0 (full left) to 1.0 (full right), 0.0 = center
-- `width`: 0.0 (mono) to 2.0 (extra wide) on Utility device
-
-**Constraints:**
-- Bass and kick stay centered (pan 0.0)
-- Lead vocal stays centered or very slightly off-center (within -0.1 to 0.1)
-- Stereo pairs (L/R guitars, synth layers) mirror symmetrically
-- Check mono compatibility after spreading — call `check_translation` if available
-- Never pan return tracks (reverb/delay should remain stereo)
-
-**Tools:** `set_track_pan`, `set_device_parameter` on Utility for mid/side width

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

@@ -1,157 +0,0 @@
----
-name: livepilot-mixing
-description: This skill should be used when the user asks to "mix", "balance levels", "set volume", "pan a track", "EQ", "compress", "sends", "routing", "master volume", "gain staging", "sidechain", or wants to perform mixing operations in Ableton Live.
----
-
-# Mixing — Levels, Panning, Routing, and Analysis
-
-Balance track levels, configure routing, apply mix effects, and analyze frequency content in Ableton Live.
-
-## Read Before Write
-
-Always understand the current state before changing anything:
-
-1. `get_session_info` — see all tracks, their types, and current configuration
-2. `get_track_info(track_index)` — detailed info on a single track: devices, clips, mixer state
-3. `get_mix_snapshot` — one-call overview of all levels, panning, routing, mute/solo state across the entire session
-4. `get_device_parameters(track_index, device_index)` — read current parameter values before tweaking
-
-Never set levels blindly. Read the current state, make informed adjustments, then verify the result.
-
-## Volume and Pan
-
-- `set_track_volume(track_index, value)` — value is normalized 0.0 to 1.0 (not dB). 0.85 is roughly unity gain. 0.0 is silence, 1.0 is max.
-- `set_track_pan(track_index, value)` — value is -1.0 (hard left) to 1.0 (hard right). 0.0 is center.
-- `set_master_volume(value)` — master output level, same 0.0-1.0 range.
-
-Gain staging principle: keep individual tracks at moderate levels (0.5-0.85) and use the master for final output. Avoid pushing tracks to 1.0 — it leaves no headroom for summing.
-
-## Sends and Return Tracks
-
-Sends route signal from any track to a return track for shared processing (reverb bus, delay bus, parallel compression).
-
-- `set_track_send(track_index, send_index, value)` — set send level (0.0-1.0). Send index 0 = Send A, 1 = Send B, etc.
-- `get_return_tracks` — list all return tracks with their names, devices, and routing
-- `create_return_track` — add a new return track to the session
-- `get_master_track` — inspect the master track configuration
-
-Return track workflow:
-1. `create_return_track` — creates a new return (automatically assigned next letter: A, B, C...)
-2. Load an effect on the return track (e.g., Reverb with Dry/Wet at 100%)
-3. `set_track_send(track_index, send_index, value)` on each track that needs the effect
-4. Adjust send levels per track for different amounts of the shared effect
-
-## Routing
-
-- `get_track_routing(track_index)` — see current input/output routing for a track
-- `set_track_routing(track_index, input_routing, output_routing)` — configure where audio comes from and goes to
-
-Common routing patterns:
-- **Resampling:** set input routing to "Resampling" on an audio track to capture the master output
-- **Sidechain:** route a track's output to another track's sidechain input for ducking compression
-- **Sub-groups:** route multiple tracks to a group track for bus processing
-
-## Metering
-
-- `get_track_meters(track_index)` — read real-time output level of a specific track (left/right channels)
-- `get_master_meters` — read the master output level in real-time
-
-Use metering to verify your level adjustments. After setting volumes, check meters to confirm nothing is clipping and the balance sounds right.
-
-## Mix Snapshot
-
-`get_mix_snapshot` returns a complete picture of the session mix in one call:
-- All track volumes and pan positions
-- Mute and solo states
-- Send levels
-- Routing configuration
-- Return track setup
-
-Use this as your starting point for any mixing task. It shows the full picture without needing to query each track individually.
-
-## Automation
-
-### Clip Automation
-
-- `get_clip_automation(track_index, clip_index, parameter_name)` — read existing automation for a parameter
-- `set_clip_automation(track_index, clip_index, parameter_name, points)` — write automation points as `[{time, value}, ...]`
-- `clear_clip_automation(track_index, clip_index, parameter_name)` — remove automation before rewriting
-
-### Intelligent Curves
-
-- `generate_automation_curve(shape, start_value, end_value, num_points)` — generate automation points using 16 curve types: linear, exponential, logarithmic, sine, cosine, s_curve, ease_in, ease_out, bounce, random_walk, step, triangle, sawtooth, reverse_sawtooth, pulse, and smooth_random
-- `apply_automation_shape(track_index, clip_index, parameter_name, shape, start_value, end_value)` — generate and apply a curve in one call
-
-### Recipes
-
-`apply_automation_recipe(track_index, clip_index, recipe_name)` — apply a pre-built automation pattern. Available recipes:
-
-- `filter_sweep_up` — low-pass filter opens over time, classic build
-- `filter_sweep_down` — filter closes, darkening effect
-- `sidechain_pump` — rhythmic volume ducking on each beat
-- `dub_throw` — delay feedback spikes on specific beats
-- `tremolo` — rhythmic volume oscillation
-- `autopan` — stereo movement back and forth
-- `fade_in` / `fade_out` — gradual volume transitions
-- `stutter` — rapid volume gates for glitch effects
-- `vinyl_crackle` — subtle noise modulation
-- `tape_wow` — pitch/speed micro-variations
-- `bit_crush_sweep` — sample rate reduction over time
-- `resonance_peak` — filter resonance spike for emphasis
-- `stereo_width_grow` — mono to wide stereo expansion
-- `grain_scatter` — granular parameter randomization
-
-### Automation Feedback Loop
-
-Follow this cycle for all automation work:
-
-1. **Perceive:** `get_master_spectrum` + `get_track_meters` to understand current state
-2. **Diagnose:** identify what needs to change based on spectral data
-3. **Act:** `apply_automation_shape` or `apply_automation_recipe`
-4. **Verify:** `get_master_spectrum` again to confirm the change worked
-5. **Adjust:** if not right, `clear_clip_automation` and try different parameters
-
-Never write automation without reading spectrum before and after.
-
-## Spectrum Analysis (Requires M4L Bridge)
-
-When the LivePilot Analyzer M4L device is on the master track:
-
-- `get_master_spectrum` — 8-band frequency analysis: sub (20-60 Hz), bass (60-200 Hz), low_mid (200-500 Hz), mid (500-2k Hz), high_mid (2k-4k Hz), presence (4k-6k Hz), brilliance (6k-12k Hz), air (12k-20k Hz)
-- `get_master_rms` — true RMS and peak levels for loudness assessment
-- `get_detected_key` — detect musical key from audio content
-
-Use spectrum data to make informed EQ decisions. If the low_mid band is 6 dB hotter than everything else, there is mud to clean up. If the air band is absent, the mix may sound dull.
-
-## Mix Engine — Critic-Driven Analysis
-
-For deeper mix analysis beyond basic levels and spectrum:
-
-- `analyze_mix` — full spectral mix analysis with per-track breakdown
-- `get_mix_issues` — identify specific problems (masking, imbalance, phase)
-- `plan_mix_move` — get a suggested action to fix a detected issue
-- `evaluate_mix_move` — score a proposed change before applying it
-- `get_masking_report` — detect frequency masking between tracks
-- `get_mix_summary` — quick overall mix health status
-
-Use the mix engine when the user wants a critical evaluation of their mix, not just level adjustments. Start with `get_mix_summary` for a quick overview, escalate to `analyze_mix` for full detail.
-
-## Quick Mix Status
-
-`get_mix_summary` from the mix engine provides an overall health score, top issues, and priority recommendations in a single call. Use it as a fast check before diving into detailed analysis.
-
-## Escalation Ladder
-
-Follow this progression — start fast, go deeper only when needed:
-
-1. **Instant:** `get_master_spectrum` + `get_track_meters` — frequency balance + levels. Answers 80% of mix questions.
-2. **Fast (1-5s):** `analyze_loudness` + `analyze_mix` — LUFS, true peak, and full mix analysis. For mastering prep.
-3. **Slow (5-15s):** `compare_to_reference` + `analyze_spectrum_offline` — reference matching, offline spectral analysis. Ask the user first.
-
-Never skip levels. Start at the lowest appropriate level and offer to go deeper.
-
-## Reference
-
-Supporting references live in the `livepilot-core` skill's `references/` directory:
-- `livepilot-core/references/mixing-patterns.md` — gain staging, parallel compression, sidechain, EQ by instrument, bus processing, stereo width
-- `livepilot-core/references/automation-atlas.md` — curve theory, genre-specific recipes, diagnostic filter, cross-track spectral mapping

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

@@ -1,130 +0,0 @@
----
-name: livepilot-notes
-description: This skill should be used when the user asks to "write notes", "add a melody", "chord progression", "rhythm pattern", "MIDI notes", "transpose", "quantize", "Euclidean rhythm", "counterpoint", "scale", "key detection", "harmony", or wants to create, edit, or analyze MIDI content in Ableton Live.
----
-
-# MIDI Notes — Create, Edit, and Analyze
-
-Write melodies, chords, rhythms, and generative patterns in Ableton Live clips. Every note operation follows the Live 12 API.
-
-## Note API Cycle
-
-Four operations form the core CRUD cycle for MIDI notes:
-
-1. **Create:** `add_notes(track_index, clip_index, notes)` — write new notes into a clip
-2. **Read:** `get_notes(track_index, clip_index)` — retrieve all notes with IDs, pitches, timings
-3. **Update:** `modify_notes(track_index, clip_index, modifications)` — change existing notes by `note_id`
-4. **Delete:** `remove_notes(track_index, clip_index, start_time, duration, pitch_start, pitch_end)` — clear a region, or `remove_notes_by_id(track_index, clip_index, note_ids)` — surgical deletion by ID
-
-Always create a clip first with `create_clip(track_index, clip_index, length)` before adding notes to it.
-
-## Note Format
-
-When calling `add_notes`, each note requires:
-
-```json
-{
-  "pitch": 60,
-  "start_time": 0.0,
-  "duration": 0.5,
-  "velocity": 100,
-  "mute": false
-}
-```
-
-When reading with `get_notes`, each note also returns Live 12 extended fields:
-- `note_id` — unique identifier for modify/remove operations
-- `probability` — 0.0 to 1.0, per-note trigger probability (Live 12 feature)
-- `velocity_deviation` — -127.0 to 127.0, randomizes velocity on each trigger
-- `release_velocity` — 0.0 to 127.0, note-off velocity
-
-Use `modify_notes` with `note_id` to update any field on existing notes — pitch, velocity, timing, probability, mute state.
-
-## Duplication and Transposition
-
-- `duplicate_notes(track_index, clip_index, time_offset)` — copy all notes forward by `time_offset` beats. Use for pattern repetition: a 4-beat pattern duplicated at offset 4.0 creates an 8-beat loop.
-- `transpose_notes(track_index, clip_index, semitones, start_time, duration)` — shift pitches in a region by semitones. Positive = up, negative = down.
-- `transpose_smart(track_index, clip_index, semitones, key)` — transpose with scale awareness. Notes stay within the target key, avoiding chromatic collisions.
-
-## Quantization
-
-`quantize_clip(track_index, clip_index, grid, amount)` snaps note start times to a rhythmic grid.
-
-Grid enum values:
-- 0 = None (no quantize)
-- 1 = 1/4 notes
-- 2 = 1/8 notes
-- 3 = 1/8 triplets
-- 4 = 1/8 + triplets (combined grid)
-- 5 = 1/16 notes
-- 6 = 1/16 triplets
-- 7 = 1/16 + triplets (combined grid)
-- 8 = 1/32 notes
-
-The `amount` parameter (0.0-1.0) controls how far notes move toward the grid. Use 1.0 for rigid quantize, 0.5-0.7 for humanized feel.
-
-## Theory Integration
-
-Run these checks before firing any clip with melodic content:
-
-1. `identify_scale(track_index, clip_index)` — detect the scale from existing notes (Krumhansl-Schmuckler algorithm). Returns key, mode, and confidence.
-2. `detect_theory_issues(track_index, clip_index, strict=true)` — check for out-of-key notes, parallel fifths, voice crossing, augmented/diminished accidents. The `strict` flag enables all checks.
-3. Fix problems with `modify_notes` — adjust offending pitches before the user hears them.
-
-The theory engine knows 7 standard modes. Exotic scales (Hijaz, Hungarian minor, whole tone) produce false "out of key" warnings. Cross-reference flagged pitches against the intended scale manually. Use `key="C hijaz"` for Hijaz/Phrygian Dominant keys.
-
-## Harmony Analysis and Suggestions
-
-- `analyze_harmony(track_index, clip_index)` — identify chords in a clip, returns chord names, qualities, root notes, and progression analysis
-- `suggest_next_chord(track_index, clip_index, key)` — given the current harmonic context, suggest the next chord with voice leading and functional reasoning
-- `harmonize_melody(track_index, clip_index, key, style)` — generate harmony notes for an existing melody. Returns a note array ready for `add_notes` on a separate track.
-- `generate_countermelody(track_index, clip_index, key, species)` — generate a counterpoint line against existing notes. Species 1-5 follow classical counterpoint rules. Returns notes for `add_notes`.
-
-Both `harmonize_melody` and `generate_countermelody` return note arrays — do not call them and discard the output. Place the results into a clip with `add_notes`.
-
-## Generative Algorithms
-
-### Euclidean Rhythms
-
-`generate_euclidean_rhythm(pulses, steps, pitch, velocity, duration)` — distribute `pulses` as evenly as possible across `steps` using the Bjorklund algorithm. Returns a note array. The tool identifies named rhythms automatically (e.g., 3 pulses in 8 steps = "tresillo", 5 in 8 = "cinquillo").
-
-`layer_euclidean_rhythms(layers)` — stack multiple Euclidean patterns for polyrhythmic textures. Each layer specifies pulses, steps, pitch, and velocity. Returns a combined note array spanning all layers, ready for a single `add_notes` call or split across tracks.
-
-### Minimalist Techniques
-
-`generate_tintinnabuli(melody_pitches, key, mode, position)` — implement Arvo Part's technique: a T-voice (triad arpeggio) against a M-voice (stepwise melody). Returns two-voice note data.
-
-`generate_phase_shift(pattern, shift_amount, repetitions)` — implement Steve Reich's phasing: two identical patterns drifting apart over time. One voice holds steady while the other shifts by `shift_amount` per repetition.
-
-`generate_additive_process(melody_pitches, iterations)` — implement Philip Glass's additive technique: melody expanded by adding one note per iteration, building complexity gradually.
-
-All generative tools return note arrays. Place them in clips with `add_notes`.
-
-## Neo-Riemannian Harmony
-
-- `navigate_tonnetz(chord, transform)` — apply PRL (Parallel, Relative, Leading-tone) transforms to a chord. Returns the neighbor chord and its relationship.
-- `find_voice_leading_path(start_chord, end_chord)` — find the shortest harmonic path between two chords through Tonnetz space. Returns intermediate chords.
-- `classify_progression(chords)` — identify the neo-Riemannian transform pattern in a chord sequence (e.g., PRL cycle, hexatonic, octatonic).
-- `suggest_chromatic_mediants(chord)` — return all chromatic mediant relations with film score usage notes. Useful for dramatic harmonic shifts.
-
-## MIDI File I/O
-
-- `export_clip_midi(track_index, clip_index, file_path)` — export a session clip's notes to a .mid file
-- `import_midi_to_clip(track_index, clip_index, file_path)` — load a .mid file into a clip, replacing existing notes
-- `analyze_midi_file(file_path)` — offline analysis of any .mid file (tempo, note count, structure). No Ableton connection needed.
-- `extract_piano_roll(file_path)` — return a 2D velocity matrix (pitch x time) from a .mid file for visualization
-
-## Pitch Audit — Mandatory Before Firing
-
-Before playing any clip with melodic or harmonic content:
-
-1. `identify_scale` on every melodic track — verify all tracks share the same tonal center
-2. `analyze_harmony` on chordal tracks — verify chord quality (no accidental augmented/diminished)
-3. `detect_theory_issues(strict=true)` — check all theory rules
-4. Report a clear tuning summary to the user before proceeding
-5. Fix wrong notes with `modify_notes` before firing
-
-## Reference
-
-Supporting references live in the `livepilot-core` skill's `references/` directory:
-- `livepilot-core/references/midi-recipes.md` — drum patterns by genre, chord voicings, scale tables, hi-hat articulations, humanization, polymetric layering