---
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.

## Default Value Filter

For broad musical requests, do not spend the turn on manual-feeling volume balancing. Levels, pan, and sends are useful when the user asks for them, when clipping/headroom/translation is objectively unsafe, or when a routing architecture is part of the style. Otherwise, treat meters as context and use analyzer character to make higher-value choices: source selection, filter/envelope shape, saturation, modulation, transient design, or a better device/preset.

When a request says "more punch", "more warmth", "more character", "less flat", "more alive", or similar, route through sound-design/creative-director first and use mix tools only as safety checks.

## 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` — 9-band frequency analysis: sub_low (20-60 Hz), sub (60-120 Hz), low (120-250 Hz), low_mid (250-500 Hz), mid (500-1k Hz), high_mid (1-2k Hz), high (2-4k Hz), presence (4-8k Hz), air (8-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. When FluCoMa streams are active, prefer `get_spectral_shape`, `get_mel_spectrum`, `get_onsets`, and `get_novelty` for character decisions; those descriptors tell you whether the sound is bright/dark, flat/peaked, static/moving, or transient/soft in a way simple level meters cannot.

## 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 + safety context.
2. **Fast character:** `get_spectral_shape` + `get_novelty` + `get_onsets` when available — decide whether the next move belongs to sound design, arrangement, or mix.
3. **Fast mix (1-5s):** `analyze_loudness` + `analyze_mix` — LUFS, true peak, and full mix analysis. For mastering prep or explicit mix critique.
4. **Slow (5-15s):** `compare_to_reference` + `analyze_spectrum_offline` — reference matching, offline spectral analysis. Ask the user first.
5. **Ground-truth A/B (significant moves):** `capture_audio` before and after the move, then `listen_ab` — WAV-grounded before/after with stereo width, groove tightness, and technical-polish evidence the live spectrum snapshot can't give; its `before_snapshot`/`after_snapshot` feed `evaluate_move`/`evaluate_mix_move` directly. Reserve for a move worth reporting as kept, not routine level nudges.

Never skip safety context. Do not let safety context become a long volume-tweaking session unless the user asked for that.

## 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