# FX Automation Applied (T146-T160)

## Overview

This document describes the FX automation and transition tools implemented as part of GRANULAR SPRINT PART2 (T146-T160).

## Implemented Tools

### T146: Filter Sweep Automation (`apply_filter_sweep`)

**Location:** `server.py` line ~16622

**Description:** Applies filter sweep automation for transitions.

**Parameters:**
- `track_index`: Target track (usually bass or music)
- `section_start_bar`: Start of transition
- `section_end_bar`: End of transition (drop)
- `sweep_type`: 'highpass_up' or 'lowpass_down'

**Example Usage:**
```python
# High-pass filter rising before drop
apply_filter_sweep(track_index=3, section_start_bar=32, section_end_bar=64, sweep_type="highpass_up")
```

**Automation Pattern:**
- `highpass_up`: 20Hz → 800Hz (energy build)
- `lowpass_down`: 20kHz → 800Hz (energy reduction)

---

### T147: Crash at Drop (`place_crash_at_drop`)

**Location:** `arrangement_intelligence.py` + `server.py`

**Description:** Places crash cymbal impact at drop position.

**Parameters:**
- `drop_position_bar`: Position where drop occurs
- `fx_track_index`: Track index for FX (default 10)

**Returns:**
```json
{
    "fx_type": "crash",
    "position_beats": drop_position - 0.5,
    "timing": "half_beat_before_drop",
    "automation": {
        "envelope": "fast_attack_medium_decay",
        "volume_start": 0.9,
        "volume_end": 0.1,
        "fade_time_beats": 1.5
    }
}
```

---

### T148: Snare Roll (`place_snare_roll`)

**Location:** `arrangement_intelligence.py` + `server.py`

**Description:** Creates velocity-ramped snare roll during builds.

**Parameters:**
- `build_start_bar`: Start of build section
- `build_end_bar`: End of build (drop position)
- `fx_track_index`: Track for FX
- `density`: 'sparse', 'medium', or 'heavy'

**Density Patterns:**
| Density | Subdivisions | Hit Pattern | Velocity Curve |
|---------|-------------|--------------|----------------|
| sparse | 4 | [1,0,0,0] | linear |
| medium | 8 | [1,0,1,0,1,0,1,0] | exponential |
| heavy | 16 | all hits | exponential_aggressive |

---

### T149: Riser Effect (`place_riser`)

**Location:** `arrangement_intelligence.py` + `server.py`

**Description:** Creates rising tension before drop.

**Parameters:**
- `start_bar`: Start position
- `end_bar`: End position (drop)
- `fx_track_index`: Track for FX
- `riser_type`: 'noise', 'synth', or 'pitch'

**Automation Types:**
| Type | Automation | Range |
|------|------------|-------|
| noise | filter_sweep | 80Hz → 12000Hz |
| synth | pitch_rise | 0 → +12 semitones |
| pitch | pitch_rise | 0 → +24 semitones |

---

### T150: Downlifter Effect (`place_downlifter`)

**Location:** `arrangement_intelligence.py` + `server.py`

**Description:** Creates falling/decelerating effect after drop.

**Parameters:**
- `start_bar`: Start position (at drop)
- `end_bar`: End position
- `fx_track_index`: Track for FX
- `downlifter_type`: 'noise', 'reverse_crash', or 'pitch'

**Automation Types:**
| Type | Automation | Character |
|------|------------|-----------|
| noise | filter_fall | 12kHz → 80Hz |
| reverse_crash | reverse_swell | volume swell |
| pitch | pitch_fall | +12 → -12 semitones |

---

### T151: Apply Transition FX (`apply_transition_fx`)

**Location:** `server.py`

**Description:** Applies comprehensive transition FX for a section.

**Parameters:**
- `track_index`: Target track
- `section`: 'intro', 'build', 'drop', 'break', 'outro'
- `fx_types`: 'all' or specific type

**Section-FX Mapping:**
- `intro`: ["downlifter"]
- `build`: ["riser", "snare_roll"]
- `drop`: ["crash"]
- `break`: ["downlifter"]
- `outro`: ["downlifter"]

---

### T152-T154: Send Automation in Builds (`automate_sends_in_build`)

**Location:** `server.py` + `abletonmcp_init.py`

**Description:** Automates send levels during build sections.

**Parameters:**
- `track_index`: Target track
- `build_start_bar`: Start of build
- `build_end_bar`: End of build (drop)
- `send_type`: 'reverb', 'delay', or 'both'

**Automation Pattern:**
```
0% ────────────────> 40% ──> snap to 0%
     70% of build      final 30%
```

**Runtime Handler:** `_write_track_automation()` in `abletonmcp_init.py`

---

### T155: Create Send Automation (`_create_send_automation`)

**Location:** `abletonmcp_init.py` (runtime handler)

**Description:** Low-level automation writer for sends.

**Internal Command:** `write_track_automation`

---

## Command Handlers Added (abletonmcp_init.py)

### New Command Types:
1. `write_filter_automation` - Filter automation on tracks
2. `write_reverb_automation` - Reverb send automation
3. `write_pitch_automation` - Pitch automation for instruments
4. `write_track_automation` - Generic track automation
5. `create_fx_clip` - Create FX clips
6. `apply_track_delay` - Micro-timing delays
7. `apply_groove_to_section` - Apply groove templates
8. `setup_sidechain` - Setup sidechain compression
9. `inject_pattern_fills` - Pattern fills for drums

---

## Files Modified

| File | Changes |
|------|---------|
| `server.py` | Added MCP tools: `place_crash_at_drop`, `place_snare_roll`, `place_riser`, `place_downlifter`, `apply_transition_fx`, `automate_sends_in_build` |
| `arrangement_intelligence.py` | Added functions: `place_crash_at_drop()`, `place_snare_roll()`, `place_riser()`, `place_downlifter()` |
| `abletonmcp_init.py` | Added command handlers: `_write_filter_automation`, `_write_reverb_automation`, `_write_pitch_automation`, `_write_track_automation`, `_create_fx_clip`, `_apply_track_delay`, `_apply_groove_to_section`, `_setup_sidechain`, `_inject_pattern_fills` |

---

## Integration Notes

### RPC Flow
1. **MCP Tool Call** (server.py)
2. **Command Send** → Ableton Runtime
3. **Runtime Handler** (abletonmcp_init.py)
4. **Result Return** → JSON Response

### Timing Considerations
- All automation uses bar-relative positioning
- Builds typically 8-32 bars
- Drops at predictable positions (64, 128, 192 beats)

### Best Practices
1. Use `apply_transition_fx` for automatic section-aware FX
2. Use individual tools for precise control
3. Combine with `apply_filter_sweep` for hybrid transitions
4. Pair risers with snare rolls for maximum impact

---

## Testing Commands

```python
# Test crash at drop
place_crash_at_drop(drop_position_bar=64, fx_track_index=10)

# Test snare roll in build
place_snare_roll(build_start_bar=32, build_end_bar=64, density="heavy")

# Test riser before drop
place_riser(start_bar=48, end_bar=64, riser_type="noise")

# Test send automation
automate_sends_in_build(track_index=3, build_start_bar=32, build_end_bar=64, send_type="reverb")

# Test full transition FX
apply_transition_fx(track_index=10, section="build", fx_types="all")
```

---

## Version History

- **v0.1.40**: Initial implementation (T146-T160)
- **Sprint**: GRANULAR SPRINT PART2
- **Date**: 2026-04-05