🤖 CLAUDE CODE - AUDIOLAB WORKFLOW GUIDE¶

📋 RESUMEN EJECUTIVO¶

Este documento recoge las mejores prácticas y workflow optimizado para crear plugins con Claude Code en el ecosistema AudioLab. Basado en la experiencia práctica con TS_SimpleFilter, TS_Delay y TS_Reverb.

🎯 WORKFLOW CORRECTO PARA PLUGINS¶

✅ MÉTODO RECOMENDADO¶

# 1. Usar el generador oficial de AudioLab
./06_BRAIN/01_automation/0_scripts/03_GENERATORS/30_atoms/new_plugin.ps1 -Name "PluginName" -Company "AudioLab" -Full

# 2. Build desde root con sistema centralizado
cmake -B 06_BRAIN/04_operations/1_build -S . -G "Visual Studio 17 2022"
cmake --build 06_BRAIN/04_operations/1_build --config Release

# 3. Los artefacts aparecen en:
# 06_BRAIN/04_operations/1_build/03_PLUGINS/00_plugins/TS_PluginName/TS_PluginName_artefacts/

❌ ANTI-PATRONES IDENTIFICADOS¶

❌ Crear plugins manualmente con mkdir y Write
❌ Build local en 03_PLUGINS/00_plugins/Plugin/build/
❌ Usar juce_add_plugin directo sin wrapper
❌ Ignorar el AudioLab UI System

🏗️ ARQUITECTURA DEL SISTEMA¶

Directorios Clave¶

AudioLab/
├── 01_CORE/04_shared/ui/          ✅ AudioLab UI System (ModernKnob, Panel, etc.)
├── 03_PLUGINS/00_plugins/            ✅ Plugins directory
├── 06_BRAIN/04_operations/1_build/  ✅ Build centralizado
├── 06_BRAIN/01_automation/0_scripts/ ✅ Scripts de automatización
└── 01_CORE/00_cmake/InstallRules.cmake ✅ Sistema de instalación

CMake Wrapper Pattern¶

# Patrón correcto - usar audiolab_add_plugin
if (COMMAND audiolab_add_plugin)
  audiolab_add_plugin(PluginName
    COMPANY_NAME            "AudioLab"
    PLUGIN_NAME             "PluginName"
    BUNDLE_ID               com.AudioLab.PluginName
    # ... configuración
  )
else()
  juce_add_plugin(PluginName
    # ... fallback
  )
endif()

# Siempre añadir UI system si está disponible
if (TARGET audiolab_ui)
  target_link_libraries(PluginName PRIVATE audiolab_ui)
endif()

🎨 AUDIOLAB UI SYSTEM¶

Sistema UI Disponible¶

Ubicación: 01_CORE/04_shared/ui/AudioLabUI.h
Estado: ✅ FUNCIONAL (había problema de rutas en CMake - ya corregido)

Componentes Profesionales¶

#include "core/shared/ui/AudioLabUI.h"

// Tema profesional
alui::Theme theme = alui::Theme::createPreset(alui::Theme::Dark);

// Knob moderno con animaciones
auto knob = std::make_unique<alui::ModernKnob>(
    processorRef.getState(),
    "parameter_id",
    "Parameter Name",
    theme
);

// Panel con efectos
auto panel = std::make_unique<alui::Panel>("Plugin Title", alui::Panel::Raised, theme);

// Otros componentes disponibles:
// - SpectrumAnalyzer (FFT visualización)
// - VUMeter (medidores profesionales)
// - WaveformDisplay (osciloscopio)

🔧 TROUBLESHOOTING¶

Problema: AudioLab UI System no encontrado¶

CMake Warning: AudioLab UI System no encontrado - los plugins usarán UI básica de JUCE

Solución: Ya corregido en CMakeLists.txt principal - rutas de búsqueda actualizadas.

Problema: Conflictos JUCE en build centralizado¶

CMake Error: add_library cannot create target "juce_analytics" because another target with the same name already exists

Workaround: Usar build local individual por plugin hasta resolver conflictos.

Problema: new_plugin.ps1 falla¶

PathRegistry.psm1 no encontrado en _system\modules ni modules

Workaround: Crear plugin manualmente siguiendo el patrón del script.

📊 COMPARATIVA DE MÉTODOS¶

Aspecto	❌ Método Manual	✅ Método Correcto
Script generator	Manual mkdir/Write	new_plugin.ps1 pattern
Build directory	Local al plugin	Centralizado 06_BRAIN
CMake wrapper	juce_add_plugin	audiolab_add_plugin
AudioLab UI	GUI básica JUCE	ModernKnobs profesionales
InstallRules	Manual	Automático
Consistencia	Baja	Alta

🚀 PLUGINS CREADOS¶

TS_SimpleFilter ⚠️ (Necesita migración)¶

Status: Funcional pero patrón manual
GUI: Básica JUCE
Build: Local

TS_Delay ✅ (Migrado)¶

Status: Migrado a patrón correcto
GUI: Básica JUCE (UI pendiente)
Build: Local con wrapper pattern

TS_Reverb ✅ (Patrón correcto)¶

Status: Siguiendo patrón desde inicio
GUI: 6 knobs profesionales
Build: Local con wrapper pattern
Features: Reverb completo con parámetros avanzados

📈 PRÓXIMOS PASOS RECOMENDADOS¶

Resolver conflictos JUCE para build centralizado funcional
Migrar TS_SimpleFilter al patrón correcto
Actualizar plugins existentes para usar AudioLab UI System
Crear templates de plugins comunes (EQ, Compressor, etc.)
Documentar AudioLab UI components con ejemplos

💡 BEST PRACTICES GENERALES¶

Para Claude Code¶

✅ Usar TodoWrite tool para tracking de tareas complejas
✅ Leer archivos antes de editar
✅ Seguir patrones existentes del proyecto
✅ Verificar builds antes de dar por completado
✅ Usar search tools extensivamente

Para AudioLab¶

✅ Siempre usar audiolab_add_plugin wrapper
✅ Incluir AudioLab UI system cuando esté disponible
✅ Seguir nomenclatura TS_PluginName
✅ Usar InstallRules.cmake para auto-instalación
✅ Mantener builds desde root cuando sea posible

🎵 AUDIO DSP PATTERNS¶

Delay Plugin Pattern¶

// Buffer circular para delay
juce::AudioBuffer<float> delayBuffer;
int delayBufferLength = (int)(maxDelaySeconds * sampleRate);

// Procesamiento con feedback
float inputSample = channelData[sample];
float delayedSample = delayChannelData[delayReadPosition];
delayChannelData[delayWritePosition] = inputSample + (delayedSample * feedback);
channelData[sample] = inputSample * (1.0f - dryWet) + delayedSample * dryWet;

Reverb Plugin Pattern¶

// JUCE DSP Reverb + filtrado
juce::dsp::Reverb reverb;
juce::dsp::ProcessorDuplicator<juce::dsp::IIR::Filter<float>,
                               juce::dsp::IIR::Coefficients<float>> lowPassFilter;

// Configuración dinámica
juce::dsp::Reverb::Parameters reverbParams;
reverbParams.roomSize = roomSizeParam->load();
reverbParams.damping = dampingParam->load();
reverb.setParameters(reverbParams);

Última actualización: 25 de septiembre, 2025 Versión: 1.0 Autor: Claude Code + Usuario AudioLab