# Sends Routing Guide

## Guia de Routing de Sends y Buses

**Sprint:** Granular v0.1.40  
**Tareas:** T101-T106  
**Modulos:** `server.py`, `bus_routing_fix.py`

---

## Resumen Ejecutivo

El sistema de routing RCA (Return Channel Architecture) organiza los tracks en buses logicos para mezcla profesional. Esta guia describe la configuracion de sends, buses y routing implementado.

---

## Arquitectura RCA

### Buses Principales

| Bus | Indice | Color | LUFS Target | Funcion |
|-----|--------|-------|--------------|---------|
| Drums | 1 | 10 (Rojo) | -8 dB | Kick, clap, hats, percussion |
| Bass | 2 | 30 (Azul) | -10 dB | Bass y sub-bass |
| Music | 3 | 45 (Verde) | -12 dB | Synth, pads, leads |
| Vocal | 4 | 60 (Amarillo) | -12 dB | Vocals, vocal shots |
| FX | 5 | 75 (Morado) | -14 dB | Atmos, FX, risers |

### Master Bus

| Master | Indice | Color | LUFS Target |
|--------|--------|-------|-------------|
| Master | 0 | 0 | -8 (club) / -14 (streaming) |

---

## Configuracion de Sends

### Cada Send Tiene:

```python
SEND_CONFIG = {
    "drums_send": {
        "index": 0,
        "devices": ["Heat", "Glue Compressor"],
        "dry_wet": {"heat": 1.0, "glue": 0.3}
    },
    "music_send": {
        "index": 1,
        "devices": ["Hybrid Reverb", "Echo"],
        "dry_wet": {"reverb": 0.5, "echo": 0.4}
    }
}
```

### Sends por Defecto

| Send | Dispositivos | Funcion |
|------|--------------|---------|
| Drums Send | Heat, Glue Compressor | Saturacion y glue |
| Music Send | Hybrid Reverb, Echo | Space y delay |
| Vocal Send | Hybrid Reverb, Echo | Space y delay |
| FX Send | Hybrid Reverb | Space atmosferico |

---

## Routing por Rol

### Rol -> Bus Mapping

```python
ROLE_TO_BUS_MAP = {
    # Drums bus (index 1)
    "kick": 1,
    "clap": 1,"hat": 1,
    "hat_open": 1,
    "snare": 1,
    "perc_main": 1,
    "perc_alt": 1,"top_loop": 1,
    
    # Bass bus (index 2)
    "bass": 2,
    "sub_bass": 2,
    
    # Music bus (index 3)
    "synth": 3,
    "pad": 3,
    "lead": 3,"atmos": 3,
    
    # Vocal bus (index 4)
    "vocal": 4,
    "vocal_shot": 4,
    
    # FX bus (index 5)
    "fx": 5,
    "riser": 5,
    "atmos_fx": 5,"fill_fx": 5
}
```

---

## Configuracion de Gain Staging

### Targets por Bus

```python
BUS_GAIN_TARGETS = {
    "drums": {"gain_db": 0.0, "pan": 0.0},
    "bass": {"gain_db": -0.5, "pan": 0.0},
    "music": {"gain_db": -2.0, "pan": 0.0},
    "vocal": {"gain_db": -3.0, "pan": 0.0},
    "fx": {"gain_db": -4.0, "pan": 0.0}
}
```

### LUFS Targets

| Target | LUFS | Uso |
|---------|------|-----|
| Club | -8 dB | Reproduccion en vivo |
| Streaming | -14 dB | Spotify, Apple Music |
| Demo | -12 dB | Preview separado |

---

## Sidechain Configuration

### Sidechain por Defecto

```python
SIDECHAIN_CONFIG = {
    "destination": "kick",
    "threshold_db": -30,
    "attack_ms": 3,
    "release_ms": 50,
    "ratio": "4:1"
}
```

### Tracks con Sidechain

- Bass: sidechain al kick
- Synth: sidechain al kick (opcional)
- Music: sidechain al kick (opcional)---

## Validacion de Routing

### T102: Diagnostico de Problemas

```python
defdiagnose_bus_routing() -> Dict[str, Any]:
    """
    Detecta:
    - Tracks en bus incorrecto
    - Sends excesivos en kicks/bass
    - FX bypassing master
    """
```

### Problemas Comunes

| Problema | Sintoma | Solucion |
|----------|---------|----------|
| Track en bus incorrecto | Balance roto | Reasignar rol |
| Sin sidechain en bass | Kick ahogado | Configurar sidechain |
| Send excesivo | Mezcla sucia | Reducir send level |
| FX sin master | Niveles inconsistentes | Enrutar a master |

---

## Ejemplos de Uso

### Configurar Bus Routing

```python
# Obtener bus para un rol
bus_index = get_bus_for_role("bass")# Retorna 2

# Configurar send
set_track_send(
    track_index=3,
    send_index=0,
    value=0.7
)
```

### Validar Routing

```python
# Diagnostico completo
issues = diagnose_bus_routing()

# Validacion por track
validate_set_detailed(
    check_routing=True,
    check_gain=True,
    check_clips=True
)
```

---

## Flujo de Señal

```
Track Individual
      |
      v
   [Gain Staging]
      |
      v
  [Bus Routing] --> Drums Bus --> [Heat + Glue]
      |                               |
      v                               v
   [Sends] --> Music Bus --> [Reverb + Echo]
      |                               |
      v                               v
   [Master] <-------------------------+
      |
      v
[Master Processing]
      |
      v
   [Output]
```

---

## Limitaciones

1. **Solo returns configurados**: No se crean grupos adicionales
2. **Sidechain manual**: El sidechain debe configurarse por track
3. **Sends limitados**: Maximo 8 sends disponibles

---

## Troubleshooting

### Sin Sonido en Bus

1. Verificar que el bus existe
2. Comprobar que el send no esta en 0
3. Validar que eltrack esta ruteado al bus

### Niveles Muy Bajos

1. Revisar gain staging por bus
2. Comprobar LUFS del master
3. Verificar que no hay compresores excesivos

### Niveles Muy Altos

1. Reducir gain del bus
2. Comprobar sidechain threshold
3. Verificar true peak del master

---

## Tests

```powershell
python -m pytest "tests/test_bus_routing.py" -v
```

---

##Roadmap

- [ ] T107: Automatic sidechain setup
- [ ] T108: Dynamic EQ routing
- [ ] T109: Parallel compression sends

---

*Maintained by: AbletonMCP-AI Team*  
*Last updated: 2026-04-05*