Sync: Complete project state with all MEGA SPRINT V1-V3 features and Codex stubs
This commit is contained in:
renato97
445
AbletonMCP_AI/docs/HARDWARE_MAPEO.md
Normal file
445
AbletonMCP_AI/docs/HARDWARE_MAPEO.md
Normal file
@@ -0,0 +1,445 @@
|
||||
# BLOQUE 3: Mapeo de Hardware MIDI & Sensores (T166-T180)
|
||||
|
||||
## Resumen Ejecutivo
|
||||
|
||||
Módulo completo de integración de hardware MIDI para control en vivo, incluyendo:
|
||||
- Mapeo de controladores (Xone:K2, APC40, Pioneer DDJ)
|
||||
- Callbacks asíncronos para filtros
|
||||
- Sincronización MIDI Clock
|
||||
- Feedback luminoso
|
||||
- Modo Performance
|
||||
- Detección de silencio
|
||||
- Y más...
|
||||
|
||||
---
|
||||
|
||||
## T166: Mapeo de Hardware
|
||||
|
||||
### Controladores Soportados
|
||||
|
||||
#### 1. Allen & Heath Xone:K2
|
||||
|
||||
| Control | CC | Canal | Función Asignada |
|
||||
|---------|-----|-------|------------------|
|
||||
| Knob 1 (Filter High) | 1 | 0 | Filter High para Music Bus |
|
||||
| Knob 2 (Filter Mid) | 2 | 0 | Filter Mid para Music Bus |
|
||||
| Knob 3 (Filter Low) | 3 | 0 | Filter Low para Music Bus |
|
||||
| Knob 4 | 4 | 0 | Gain Staging |
|
||||
| Knob 5 | 5 | 0 | Humanize Amount |
|
||||
| Knob 6 | 6 | 0 | Sidechain Amount (Bass Bus) |
|
||||
| Knob 7 | 7 | 0 | Reverb Send |
|
||||
| Knob 8 | 8 | 0 | Delay Send |
|
||||
| Fader 1 | 11 | 0 | Drums Bus Volume |
|
||||
| Fader 2 | 12 | 0 | Bass Bus Volume |
|
||||
| Fader 3 | 13 | 0 | Music Bus Volume |
|
||||
| Fader 4 | 14 | 0 | FX Bus Volume |
|
||||
| Master Fader | 15 | 0 | Master Volume |
|
||||
|
||||
**Pads (Notas MIDI):**
|
||||
|
||||
| Pad | Nota | Canal | Función |
|
||||
|-----|------|-------|---------|
|
||||
| Scene 1 | 32 | 0 | Fire Scene 1 |
|
||||
| Scene 2 | 33 | 0 | Fire Scene 2 |
|
||||
| Scene 3 | 34 | 0 | Fire Scene 3 |
|
||||
| Scene 4 | 35 | 0 | Fire Scene 4 |
|
||||
| Panic | 36 | 0 | Botón de Pánico |
|
||||
| Fill Trigger | 37 | 0 | Disparar Fill |
|
||||
| Backup Track | 38 | 0 | Toggle Track Backup |
|
||||
| Performance Mode | 39 | 0 | Toggle Performance Mode |
|
||||
| Pads 1-8 | 40-47 | 1 | Drum Pads (Fills) |
|
||||
|
||||
#### 2. AKAI APC40 MKII
|
||||
|
||||
| Control | CC | Canal | Función |
|
||||
|---------|-----|-------|---------|
|
||||
| Master Fader | 14 | 0 | Master Volume |
|
||||
| Fader 1-4 | 48-51 | 0 | Bus Volumes |
|
||||
| Knob 1-4 (Device) | 16-19 | 0 | Device Macros |
|
||||
| Knob 5-8 (Send) | 20-23 | 0 | Humanize/Sidechain/Reverb/Delay |
|
||||
|
||||
**Pads de Clip (5x8 matrix):**
|
||||
- Notas 53-89 en canales 0-7
|
||||
- Cada pad puede disparar clips o funciones especiales
|
||||
|
||||
**Botones de Scene:**
|
||||
- Notas 82-85 para lanzar scenes 1-4
|
||||
|
||||
#### 3. Pioneer DDJ (Mapeo Estándar)
|
||||
|
||||
| Control | CC | Canal | Función |
|
||||
|---------|-----|-------|---------|
|
||||
| CH1 Fader | 2 | 0 | Drums Bus |
|
||||
| CH2 Fader | 3 | 0 | Bass Bus |
|
||||
| CH3 Fader | 4 | 0 | Music Bus |
|
||||
| CH4 Fader | 5 | 0 | Vocals/FX Bus |
|
||||
| Master | 6 | 0 | Master Volume |
|
||||
| Crossfader | 8 | 0 | Crossfade entre A/B |
|
||||
| EQ High/Mid/Low CH1 | 10-12 | 0 | EQ Drums Bus |
|
||||
| EQ High/Mid/Low CH2 | 13-15 | 0 | EQ Bass Bus |
|
||||
| Filter CH1 | 20 | 0 | Filter Drums |
|
||||
| Filter CH2 | 21 | 0 | Filter Bass |
|
||||
|
||||
---
|
||||
|
||||
## T167: Ligadura Asíncrona de Filtros
|
||||
|
||||
```python
|
||||
# Ejemplo de uso
|
||||
bind_filter_to_bus_async(
|
||||
filter_cc=1, # CC del knob de filtro
|
||||
bus_name="music_bus", # Bus objetivo
|
||||
hardware_type="xone_k2"
|
||||
)
|
||||
```
|
||||
|
||||
**Parámetros de Smoothing:**
|
||||
- Smoothing: 0.1 (10% por paso)
|
||||
- Respuesta: Suave para evitar saltos bruscos
|
||||
|
||||
---
|
||||
|
||||
## T168: Monitor de Pista
|
||||
|
||||
```python
|
||||
toggle_track_monitor(track_index=0) # Toggle monitor track 0
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## T169: MIDI Clock Sync
|
||||
|
||||
**Configuración:**
|
||||
- PPQN: 24 pulsos por negra
|
||||
- Rango BPM: 60-200
|
||||
- Smoothing: 0.3 (suavizado de tempo)
|
||||
|
||||
```python
|
||||
start_midi_clock_sync() # Inicia sync
|
||||
stop_midi_clock_sync() # Detiene sync
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## T170: Gain Staging desde Fader
|
||||
|
||||
**Mapeo CC a LUFS:**
|
||||
|
||||
| CC Value | LUFS Target | Rango |
|
||||
|----------|-------------|-------|
|
||||
| 0-63 | -23 a -14 | Streaming |
|
||||
| 64-127 | -14 a -8 | Club |
|
||||
|
||||
```python
|
||||
update_gain_staging_from_fader(cc_value=100) # Target: ~-10.6 LUFS
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## T171: Fills desde Pads
|
||||
|
||||
**Mapeo de Pads a Fills:**
|
||||
|
||||
| Pad | Fill Type | Density | Section |
|
||||
|-----|-----------|---------|---------|
|
||||
| 1 | fill_1 | sparse | drop |
|
||||
| 2 | fill_2 | medium | build |
|
||||
| 3 | fill_3 | heavy | drop |
|
||||
| 4 | fill_4 | sparse | break |
|
||||
|
||||
```python
|
||||
trigger_fill_from_pad(pad_number=1) # Dispara fill tipo sparse
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## T172: Botón de Pánico
|
||||
|
||||
**Efectos Afectados:**
|
||||
- music_bus: Reverb send -> 0%
|
||||
- vocal_bus: Delay send -> 0%
|
||||
- atmos_bus: Todos los sends -> 0%
|
||||
|
||||
```python
|
||||
trigger_panic_button() # Activa pánico
|
||||
release_panic_button() # Restaura gradualmente
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## T173: Feedback Luminoso
|
||||
|
||||
**Colores LED (APC40):**
|
||||
- 0: Off
|
||||
- 1: Green
|
||||
- 2: Green Blink
|
||||
- 3: Red
|
||||
- 4: Red Blink
|
||||
- 5: Yellow
|
||||
- 6: Yellow Blink
|
||||
- 7: Orange
|
||||
|
||||
**Patrones:**
|
||||
- Export Active: Secuencial blink 2 segundos
|
||||
- Scene Active: Verde fijo
|
||||
- Panic: Rojo blink
|
||||
|
||||
---
|
||||
|
||||
## T174: CPU Monitoring
|
||||
|
||||
**Configuración:**
|
||||
- Intervalo: 500ms (default)
|
||||
- Display: LED ring del knob master
|
||||
- Escala: 0-100% -> CC 0-127
|
||||
|
||||
```python
|
||||
start_cpu_monitoring(interval_ms=500)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## T175: Scene Trigger con Quantización
|
||||
|
||||
**Modos de Quantización:**
|
||||
|
||||
| Modo | Beats | Uso |
|
||||
|------|-------|-----|
|
||||
| none | 0 | Inmediato |
|
||||
| 8th | 0.5 | Rápido |
|
||||
| 4th | 1.0 | Precisión |
|
||||
| 2nd | 2.0 | Medio compás |
|
||||
| 1bar | 4.0 | Standard |
|
||||
| 2bar | 8.0 | Largo |
|
||||
|
||||
```python
|
||||
trigger_scene_from_hardware(scene_index=0, quantization="1bar")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## T176: Performance Mode
|
||||
|
||||
**Layouts Disponibles:**
|
||||
|
||||
### Default
|
||||
- Fader 1: Drums Bus
|
||||
- Fader 2: Bass Bus
|
||||
- Fader 3: Music Bus
|
||||
- Fader 4: Master
|
||||
|
||||
### DJ
|
||||
- Fader 1: Deck A
|
||||
- Fader 2: Deck B
|
||||
- Fader 3: FX Bus
|
||||
- Fader 4: Master
|
||||
|
||||
### Live
|
||||
- Fader 1: Kick
|
||||
- Fader 2: Snare
|
||||
- Fader 3: Synth
|
||||
- Fader 4: Vocals
|
||||
|
||||
```python
|
||||
activate_performance_mode(layout="default")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## T177: Humanize Macro
|
||||
|
||||
**Mapeo Intensidad:**
|
||||
|
||||
| CC | Intensidad | Nivel |
|
||||
|----|-----------|-------|
|
||||
| 0-38 | 0.0-0.3 | Subtle |
|
||||
| 39-76 | 0.3-0.6 | Medium |
|
||||
| 77-127 | 0.6-1.0 | Extreme |
|
||||
|
||||
```python
|
||||
update_humanize_from_knob(cc_value=64) # ~50% intensity
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## T178: Detección de Silencio
|
||||
|
||||
**Parámetros:**
|
||||
- Threshold: -60 dB (default)
|
||||
- Duration: 3000 ms (default)
|
||||
- Action: Auto-trigger backup track
|
||||
|
||||
```python
|
||||
start_silence_detection(threshold_db=-60.0, duration_ms=3000)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## T179: Nudging Asíncrono
|
||||
|
||||
**Precisión:**
|
||||
- 1 ms = 48 samples @ 48kHz
|
||||
- 5 ms = 240 samples
|
||||
|
||||
```python
|
||||
apply_nudge_forward(ms=5.0) # Acelera 5ms
|
||||
apply_nudge_backward(ms=3.0) # Atrasa 3ms
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## T180: Macros de Visualización
|
||||
|
||||
**Disponibles:**
|
||||
|
||||
| Macro | Descripción |
|
||||
|-------|-------------|
|
||||
| strobe_beat | Strobe rojo sync con beat |
|
||||
| level_meter | Medidor de nivel en LEDs |
|
||||
| peak_indicator | Parpadeo rojo rápido |
|
||||
| recording_active | LED lento parpadeante |
|
||||
| midi_clock_sync | LED verde fijo |
|
||||
|
||||
```python
|
||||
trigger_visualization_macro("strobe_beat")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## API MCP Disponible
|
||||
|
||||
### Herramientas Exports
|
||||
|
||||
```python
|
||||
# T166
|
||||
ableton_mcp_ai_get_hardware_mapping(hardware_type: str)
|
||||
|
||||
# T167
|
||||
ableton_mcp_ai_bind_filter_to_bus(filter_cc: int, bus_name: str, hardware_type: str)
|
||||
|
||||
# T168
|
||||
ableton_mcp_ai_toggle_track_monitor(track_index: int)
|
||||
|
||||
# T169
|
||||
ableton_mcp_ai_start_midi_clock_sync()
|
||||
ableton_mcp_ai_stop_midi_clock_sync()
|
||||
|
||||
# T170
|
||||
ableton_mcp_ai_update_gain_staging(cc_value: int)
|
||||
|
||||
# T171
|
||||
ableton_mcp_ai_trigger_fill_from_pad(pad_number: int)
|
||||
|
||||
# T172
|
||||
ableton_mcp_ai_trigger_panic()
|
||||
ableton_mcp_ai_release_panic()
|
||||
|
||||
# T173
|
||||
ableton_mcp_ai_indicate_export()
|
||||
|
||||
# T174
|
||||
ableton_mcp_ai_start_cpu_monitoring(interval_ms: int)
|
||||
ableton_mcp_ai_stop_cpu_monitoring()
|
||||
|
||||
# T175
|
||||
ableton_mcp_ai_trigger_scene_hardware(scene_index: int, quantization: str)
|
||||
ableton_mcp_ai_set_scene_quantization(mode: str)
|
||||
|
||||
# T176
|
||||
ableton_mcp_ai_activate_performance_mode(layout: str)
|
||||
ableton_mcp_ai_deactivate_performance_mode()
|
||||
|
||||
# T177
|
||||
ableton_mcp_ai_update_humanize_macro(cc_value: int)
|
||||
|
||||
# T178
|
||||
ableton_mcp_ai_start_silence_detection(threshold_db: float, duration_ms: int)
|
||||
ableton_mcp_ai_stop_silence_detection()
|
||||
|
||||
# T179
|
||||
ableton_mcp_ai_apply_nudge_forward(ms: float)
|
||||
ableton_mcp_ai_apply_nudge_backward(ms: float)
|
||||
|
||||
# T180
|
||||
ableton_mcp_ai_trigger_visualization_macro(macro_name: str)
|
||||
|
||||
# Status completo
|
||||
ableton_mcp_ai_get_hardware_status()
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Archivos del Bloque 3
|
||||
|
||||
| Archivo | Descripción |
|
||||
|---------|-------------|
|
||||
| `hardware_integration.py` | Módulo principal (1100+ líneas) |
|
||||
| `tests/test_hardware_integration.py` | Test suite completo |
|
||||
| `docs/HARDWARE_MAPEO.md` | Esta documentación |
|
||||
|
||||
---
|
||||
|
||||
## Estado de Implementación
|
||||
|
||||
| Tarea | Estado | Cobertura |
|
||||
|-------|--------|-----------|
|
||||
| T166 | ✅ Completado | 3 controladores mapeados |
|
||||
| T167 | ✅ Completado | Async filter bindings |
|
||||
| T168 | ✅ Completado | Track monitor toggle |
|
||||
| T169 | ✅ Completado | MIDI Clock sync |
|
||||
| T170 | ✅ Completado | Gain staging fader |
|
||||
| T171 | ✅ Completado | Drum pad fills |
|
||||
| T172 | ✅ Completado | Panic button |
|
||||
| T173 | ✅ Completado | LED feedback |
|
||||
| T174 | ✅ Completado | CPU monitoring |
|
||||
| T175 | ✅ Completado | Scene quantization |
|
||||
| T176 | ✅ Completado | Performance mode |
|
||||
| T177 | ✅ Completado | Humanize macro |
|
||||
| T178 | ✅ Completado | Silence detection |
|
||||
| T179 | ✅ Completado | Async nudging |
|
||||
| T180 | ✅ Completado | Visualization macros |
|
||||
|
||||
**Total: 15/15 tareas completadas**
|
||||
|
||||
---
|
||||
|
||||
## Uso Ejemplo
|
||||
|
||||
```python
|
||||
# 1. Inicializar hardware
|
||||
ableton_mcp_ai_get_hardware_mapping("xone_k2")
|
||||
|
||||
# 2. Activar performance mode
|
||||
ableton_mcp_ai_activate_performance_mode("default")
|
||||
|
||||
# 3. Configurar sync MIDI
|
||||
ableton_mcp_ai_start_midi_clock_sync()
|
||||
|
||||
# 4. Monitorear CPU
|
||||
ableton_mcp_ai_start_cpu_monitoring(500)
|
||||
|
||||
# 5. Listo para live performance!
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Notas Técnicas
|
||||
|
||||
### Dependencias
|
||||
- `mido`: Opcional, para I/O MIDI real
|
||||
- Sin dependencias obligatorias para funcionamiento simulado
|
||||
|
||||
### Thread Safety
|
||||
- Todos los controladores usan locks (threading/asyncio)
|
||||
- Callbacks asíncronos para operaciones en tiempo real
|
||||
- No bloquea el hilo principal
|
||||
|
||||
### Integración Live
|
||||
- Los callbacks están preparados para conectar con Ableton Live API
|
||||
- Señales MIDI se pueden mapear a funciones de Live vía Remote Script
|
||||
|
||||
---
|
||||
|
||||
**Documentación generada: 2026-04-08**
|
||||
**Versión: 1.0.0**
|
||||
**Módulo: AbletonMCP-AI Hardware Integration**
|
||||
Reference in New Issue
Block a user