Arquitectura del Sistema CORE - AudioLab¶

Sistema de Audio Real-Time | Diseño en Capas

🎯 Visión General¶

El sistema 04_CORE es el motor fundamental de AudioLab, diseñado para procesamiento de audio de latencia ultra-baja con garantías de real-time safety.

Principios de Diseño¶

Real-Time First - Cero allocations en audio thread
Type Safety - Strong typing, compile-time validation
Performance - SIMD optimization, fast-math approximations
Modularity - 16 subsistemas independientes pero cohesivos
Platform Agnostic - Windows, macOS, Linux support

🏗️ Arquitectura en 5 Capas¶

┌─────────────────────────────────────────────────────┐
│           LAYER 5: Cross-Cutting Concerns           │
│  Error Recovery | Platform Abstraction | Test Utils │
│              04_12 | 04_13 | 04_14 | 04_15          │
└─────────────────────────────────────────────────────┘
                            ▲
┌─────────────────────────────────────────────────────┐
│          LAYER 4: Plugin Infrastructure             │
│  Parameters | Lifecycle | Processor | Serialization │
│           04_08 | 04_09 | 04_10 | 04_11              │
└─────────────────────────────────────────────────────┘
                            ▲
┌─────────────────────────────────────────────────────┐
│          LAYER 3: Audio Processing Core             │
│   Buffer Mgmt | Threading | Event Dispatcher        │
│          04_05 | 04_06 | 04_07                      │
└─────────────────────────────────────────────────────┘
                            ▲
┌─────────────────────────────────────────────────────┐
│         LAYER 2: Memory & Safety                    │
│      Memory Management | Realtime Safety            │
│             04_03 | 04_04                           │
└─────────────────────────────────────────────────────┘
                            ▲
┌─────────────────────────────────────────────────────┐
│            LAYER 1: Foundation                      │
│    Type System | Interfaces | Math Primitives       │
│          04_00 | 04_01 | 04_02                      │
└─────────────────────────────────────────────────────┘

📦 Detalle de Capas¶

LAYER 1: Foundation (Base Fundacional)¶

Propósito: Tipos fundamentales, interfaces base, y primitivas matemáticas.

04_00 - Type System ⭐¶

Responsibilities:
├── Sample types (float, double, int32)
├── SIMD vectors (AVX2, NEON, scalar fallback)
├── Buffer abstractions (AudioBuffer, CircularBuffer)
├── Parameter types (RangedParameter, NormalizedParam)
└── Conversion traits

Key Features: - Header-only, zero runtime overhead - Constexpr where possible - Platform-agnostic SIMD

Dependencies: None (foundational)

04_01 - Core Interfaces ⭐¶

Responsibilities:
├── Processing interfaces (IProcessor, IEffect)
├── Lifecycle interfaces (IInitializable, IDisposable)
├── State interfaces (IStateful, ISerializable)
├── Communication interfaces (IParameterListener)
└── Factory interfaces (IFactory, IBuilder)

Key Features: - Abstract interfaces for extensibility - Plugin architecture foundation - Decoupling mechanism

Dependencies: 04_00 (types)

04_02 - Math Primitives ⭐¶

Responsibilities:
├── Fast math (sin, exp, log, sqrt, pow)
├── Interpolation (linear, cubic, hermite)
├── DSP conversions (dB, MIDI, pan)
└── Utility functions

Key Features: - ~1000x speedup vs std::sin - Error < 0.005 for approximations - Constexpr-friendly

Dependencies: 04_00 (types)

LAYER 2: Memory & Safety (Gestión Segura)¶

Propósito: Gestión de memoria y garantías de real-time safety.

04_03 - Memory Management¶

Responsibilities:
├── Custom allocators (RT-safe, pooled)
├── Alignment utilities (SIMD, cache-line)
├── Memory pools (pre-allocated buffers)
└── Smart pointers (RT-safe wrappers)

Key Features: - Zero allocation en RT thread - 64-byte alignment para cache efficiency - Pool-based allocation

Dependencies: 04_00, 04_01

04_04 - Realtime Safety¶

Responsibilities:
├── Lock-free primitives (SPSC queue, atomics)
├── RT patterns (wait-free algorithms)
├── Thread communication (RT-safe messaging)
└── Safety validators

Key Features: - Lock-free data structures - Guaranteed latency bounds - Wait-free operations

Dependencies: 04_00, 04_01, 04_03

LAYER 3: Audio Processing Core (Motor de Audio)¶

Propósito: Gestión de buffers, threading, y despacho de eventos.

04_05 - Buffer Management¶

Responsibilities:
├── Buffer pooling (pre-allocated pools)
├── Buffer operations (copy, clear, mix)
├── Channel interleaving/deinterleaving
└── Buffer resizing (RT-safe)

Key Features: - Pool-based buffer allocation - SIMD-optimized operations - Zero-copy where possible

Dependencies: 04_00, 04_03, 04_04

04_06 - Threading Architecture¶

Responsibilities:
├── Thread management (RT audio thread)
├── Thread-local storage
├── Priority scheduling
└── CPU affinity control

Key Features: - RT thread with priority boost - Thread isolation - Platform-specific optimizations

Dependencies: 04_00, 04_03, 04_04

04_07 - Event Dispatcher¶

Responsibilities:
├── UI ↔ DSP communication
├── Event queuing (lock-free)
├── Command pattern implementation
└── Async message passing

Key Features: - Lock-free event queue - Type-safe event system - Bidirectional communication

Dependencies: 04_00, 04_04, 04_06

LAYER 4: Plugin Infrastructure (Framework de Plugins)¶

Propósito: Sistema completo para crear plugins de audio.

04_08 - Parameter System¶

Responsibilities:
├── Parameter definitions (ranges, units)
├── Parameter smoothing (anti-aliasing)
├── Automation handling
└── Preset management

Key Features: - Automatic smoothing - MIDI learn support - Preset versioning

Dependencies: 04_00, 04_04, 04_07

04_09 - Plugin Lifecycle¶

Responsibilities:
├── Initialization sequence
├── Configuration management
├── Resource allocation/deallocation
└── Shutdown procedures

Key Features: - Deterministic initialization - Graceful shutdown - State restoration

Dependencies: 04_01, 04_03, 04_08

04_10 - Audio Processor¶

Responsibilities:
├── Main processing loop
├── Buffer management
├── Parameter updates
└── Performance monitoring

Key Features: - Template-based processor - Zero-overhead abstraction - Built-in profiling

Dependencies: 04_00, 04_05, 04_08, 04_09

04_11 - State Serialization¶

Responsibilities:
├── State save/load
├── Preset serialization (JSON, XML, binary)
├── Version migration
└── DAW integration

Key Features: - Version-aware serialization - Binary and text formats - Backward compatibility

Dependencies: 04_08, 04_09, 04_10

LAYER 5: Cross-Cutting Concerns (Servicios Transversales)¶

Propósito: Funcionalidades que atraviesan todo el sistema.

04_12 - Error Recovery¶

Responsibilities:
├── Error detection
├── Recovery strategies
├── Fallback mechanisms
└── Error reporting

Key Features: - RT-safe error handling - Graceful degradation - Diagnostic logging

Dependencies: Todas las capas

04_13 - Platform Abstraction¶

Responsibilities:
├── OS-specific APIs (Windows, macOS, Linux)
├── Filesystem abstraction
├── Thread primitives
└── Performance counters

Key Features: - Single API, multiple platforms - Compile-time platform detection - Minimal overhead

Dependencies: Foundation layer

04_14 - Audio Test Utilities¶

Responsibilities:
├── Test signal generators (sine, noise, sweep)
├── Audio file I/O (WAV, AIFF)
├── Golden file comparison
└── Performance benchmarks

Key Features: - Comprehensive test signals - Bit-exact comparison - Automated testing support

Dependencies: 04_00, 04_02

04_15 - Core Config¶

Responsibilities:
├── Build configuration
├── Feature flags
├── Optimization settings
└── Platform defaults

Key Features: - Centralized configuration - CMake integration - Debug/Release profiles

Dependencies: None (configuration only)

🔄 Flujo de Datos¶

Procesamiento de Audio (RT Thread)¶

┌──────────────┐
│   DAW Host   │
└──────┬───────┘
       │ processBlock()
       ▼
┌──────────────────────────────────┐
│    04_10 Audio Processor         │
│  ┌────────────────────────────┐  │
│  │ 1. Read Parameters         │  │ ◄── 04_08 Parameter System
│  │ 2. Smooth Values           │  │
│  │ 3. Process DSP             │  │ ◄── 04_02 Math Primitives
│  │ 4. Write Output            │  │
│  └────────────────────────────┘  │
└────────┬─────────────────────────┘
         │
         ▼
┌──────────────────────────────────┐
│    04_05 Buffer Management       │
│  ┌────────────────────────────┐  │
│  │ - Get buffer from pool     │  │
│  │ - SIMD operations          │  │ ◄── 04_00 SIMD Types
│  │ - Return to pool           │  │
│  └────────────────────────────┘  │
└──────────────────────────────────┘

Comunicación UI ↔ DSP¶

┌─────────────┐                    ┌──────────────┐
│  UI Thread  │                    │  Audio Thread│
└──────┬──────┘                    └──────▲───────┘
       │                                  │
       │ Parameter Change                 │
       ▼                                  │
┌──────────────────────┐                 │
│ 04_07 Event          │                 │
│    Dispatcher        │                 │
│                      │                 │
│ [Lock-Free Queue]    │─────────────────┘
│                      │  RT-safe delivery
└──────────────────────┘

Inicialización de Plugin¶

1. DAW carga plugin
        ▼
2. 04_09 Plugin Lifecycle
   - Allocate resources
   - Initialize state
        ▼
3. 04_10 Audio Processor
   - Setup processing chain
   - Connect to DAW
        ▼
4. 04_08 Parameter System
   - Register parameters
   - Load preset
        ▼
5. Ready to process

🎨 Patrones de Diseño¶

1. Template Method Pattern¶

// 04_10 Audio Processor
template<typename DSPImpl>
class AudioProcessor {
    void processBlock(AudioBuffer& buffer) {
        static_cast<DSPImpl*>(this)->preProcess();
        static_cast<DSPImpl*>(this)->process(buffer);
        static_cast<DSPImpl*>(this)->postProcess();
    }
};

2. Strategy Pattern¶

// 04_08 Parameter Smoothing
class ParameterSmoother {
    std::unique_ptr<ISmoothingStrategy> strategy_;
    // Linear, Exponential, S-curve...
};

3. Command Pattern¶

// 04_07 Event Dispatcher
struct ParameterChangeCommand : ICommand {
    void execute() override;
};

4. Object Pool Pattern¶

// 04_05 Buffer Management
class BufferPool {
    std::vector<Buffer> pool_;
    Buffer* acquire();
    void release(Buffer*);
};

5. RAII Pattern¶

// 04_03 Memory Management
class ScopedBuffer {
    ~ScopedBuffer() { pool_.release(buffer_); }
};

⚡ Consideraciones de Performance¶

SIMD Optimization (04_00)¶

// Auto-vectorization
for (size_t i = 0; i < N; i += 8) {
    SimdFloat8::load(&in[i])
        .multiply(gain)
        .store(&out[i]);
}
// ~8x speedup vs scalar

Fast Math (04_02)¶

// Approximation vs precision trade-off
float angle = computePhase();
float sine = fast_sin(angle);  // ~1000x faster, error < 0.005

Lock-Free Communication (04_07)¶

// SPSC queue for UI ↔ DSP
SPSCQueue<Event> queue_;
queue_.push(event);  // Lock-free, wait-free

Memory Pooling (04_05)¶

// Pre-allocated buffers
BufferPool pool(1024, 512);  // 1024 buffers of 512 samples
auto buf = pool.acquire();   // O(1), no allocation

🧪 Testing Strategy¶

Unit Tests (Todos los subsistemas)¶

ctest -R 04_00  # Type system tests
ctest -R 04_02  # Math primitives tests

Integration Tests¶

ctest -R integration_  # Cross-subsystem tests

Performance Tests (04_02, 04_05)¶

./bench_fast_math      # Benchmark math functions
./bench_buffer_ops     # Benchmark buffer operations

Regression Tests¶

./test_golden_files    # Bit-exact comparison

🔗 Dependencias¶

Dependency Graph¶

04_15 (Config) ──────────────────────────────┐
                                             │
04_00 (Types) ◄──────────────────────────────┘
  │
  ├─► 04_01 (Interfaces)
  ├─► 04_02 (Math)
  │
  ▼
04_03 (Memory) ◄── 04_01
  │
  ▼
04_04 (RT Safety) ◄── 04_03
  │
  ├─► 04_05 (Buffers)
  ├─► 04_06 (Threading)
  ├─► 04_07 (Events)
  │
  ▼
04_08 (Parameters) ◄── 04_04, 04_07
  │
  ├─► 04_09 (Lifecycle)
  ├─► 04_10 (Processor)
  ├─► 04_11 (Serialization)
  │
  ▼
04_12 (Error Recovery) ◄── Todas
04_13 (Platform) ◄── Foundation
04_14 (Test Utils) ◄── 04_00, 04_02

External Dependencies¶

C++17 Standard Library - Única dependencia externa
CMake 3.15+ - Build system
Platform SDKs - Windows SDK, macOS SDK, Linux headers

📊 Métricas de Arquitectura¶

Acoplamiento¶

Foundation Layer: Acoplamiento = 0 (no dependencies)
Processing Layer: Acoplamiento < 3 (well isolated)
Plugin Layer: Acoplamiento < 5 (acceptable)

Cohesión¶

Intra-module: Alta (single responsibility)
Inter-module: Media (clear interfaces)

Complejidad¶

Ciclomática: Baja en interfaces, controlada en implementaciones
Cognitive: Mitigada con documentación y ejemplos

🚀 Extensibilidad¶

Añadir Nuevo Efecto DSP¶

// 1. Heredar de AudioProcessor
class MyEffect : public AudioProcessor<MyEffect> {
    void process(AudioBuffer& buffer);
};

// 2. Usar primitivas existentes
void MyEffect::process(AudioBuffer& buffer) {
    for (auto& sample : buffer) {
        sample = fast_tanh(sample * gain_);  // 04_02
    }
}

Añadir Nuevo Tipo de Parámetro¶

// 1. Definir en 04_00
template<typename T>
struct LogParameter {
    T value;
    static constexpr T toLinear(T log);
};

// 2. Integrar con 04_08
ParameterManager::registerLogParam(...);

📚 Recursos Adicionales¶

Documentación de Referencia¶

Guías de Desarrollo¶

Getting Started (próximamente)
Best Practices (próximamente)
API Reference (próximamente)

Análisis y Reportes¶

System Audit 2024-10-16
Performance Metrics (próximamente)

🔄 Versionado¶

Versión actual: 0.1.0-alpha Última actualización: 2024-10-16 Próxima milestone: 0.2.0-beta (Q1 2025)

AudioLab CORE System Architecture - Foundation for Professional Audio Processing