05_07_ATOMS_L1 - Plan de Desarrollo Detallado¶

INFORMACIÓN GENERAL¶

Subsistema: 05_07_ATOMS_L1 - L1 Atoms (Componentes DSP Básicos) Criticidad: ⭐⭐⭐⭐⭐ (Máxima - bloque fundamental de construcción) Equipo sugerido: 3 desarrolladores en paralelo Duración estimada: 14 semanas (paralelo) / 28 semanas (secuencial) Líneas de código estimadas: ~30,000 LOC (C++ core + tests + bindings)

CONTEXTO Y ARQUITECTURA¶

Los L1 Atoms son componentes DSP modulares y autocontenidos que encapsulan kernels L0 en unidades funcionales completas. Cada átomo es un procesador mínimo viable con interface estandarizada, estado interno gestionado, y comportamiento RT-safe.

Jerarquía:

L0 Kernels (primitivas matemáticas)
    ↓
L1 Atoms (componentes funcionales completos)
    ↓
L2 Cells (combinaciones de atoms)
    ↓
L3 Engines (sistemas completos)

Átomos a implementar: 1. Filter Atom - Biquad, SVF, Ladder (4-pole Moog) 2. Oscillator Atom - Sin, Saw, Square, Triangle, Wavetable 3. Envelope Atom - ADSR, AR, Multi-stage 4. LFO Atom - Low-frequency oscillator con sync 5. Delay Atom - Simple delay con feedback y modulación 6. Saturator Atom - Soft/hard clip, waveshaper, tube emulation 7. Gain Atom - Linear/dB gain con smoothing 8. Pan Atom - Stereo panning con leyes (-3dB, -4.5dB, -6dB)

Principios de diseño: - Interface uniforme (Processor base class) - RT-safe (sin allocations, sin locks) - Estado mínimo y eficiente - Parámetros modulables a tasa de audio - SIMD-ready desde el inicio - Zero-latency cuando sea posible

ORGANIZACIÓN EN TIERS¶

TIER 1 - Fundamentos de Interface (Semanas 1-2)¶

TAREA 1: Base Infrastructure & Processor Interface

TIER 2 - Átomos Generadores (Semanas 3-5)¶

TAREA 2: Oscillator Atom
TAREA 3: Envelope Atom
TAREA 4: LFO Atom

TIER 3 - Átomos Procesadores (Semanas 6-8)¶

TAREA 5: Filter Atom
TAREA 6: Saturator Atom
TAREA 7: Gain Atom

TIER 4 - Átomos de Tiempo/Espacio (Semanas 9-10)¶

TAREA 8: Delay Atom
TAREA 9: Pan Atom

TIER 5 - Presets y Factorías (Semanas 11-12)¶

TAREA 10: Preset System & Factory Pattern

TIER 6 - Testing y Validación (Semanas 13)¶

TAREA 11: Integration Testing & Quality Validation

TIER 7 - Documentación y Conexiones (Semana 14)¶

TAREA 12: Documentation & External Interfaces

TAREAS DETALLADAS¶

TAREA 1: Base Infrastructure & Processor Interface¶

Tier: 1 Archivos: 05_07_00_base_infrastructure/

Core Implementation:¶

Processor Base Class (processor.hpp)

namespace audiolab::atoms {

struct ProcessContext {
    float sample_rate;
    int block_size;
    uint64_t timestamp;
    float* modulation_inputs[16];  // Para modulación externa
};

class Processor {
public:
    virtual ~Processor() = default;

    // Lifecycle
    virtual void reset() = 0;
    virtual void set_sample_rate(float sr) = 0;

    // Processing
    virtual void process(AudioBuffer& buffer, const ProcessContext& ctx) = 0;

    // Parameters
    virtual void set_parameter(int id, float value) = 0;
    virtual float get_parameter(int id) const = 0;

    // Introspection
    virtual const char* get_name() const = 0;
    virtual int get_latency_samples() const { return 0; }

    // RT-safety check
    bool is_rt_safe() const { return rt_safe_flag_; }

protected:
    bool rt_safe_flag_ = true;
};

} // namespace

Parameter System (parameter.hpp)

struct ParameterDescriptor {
    int id;
    const char* name;
    float min_value;
    float max_value;
    float default_value;
    float skew_factor;  // Para mapeos logarítmicos
    const char* unit;   // "Hz", "dB", "%", etc.
};

class ParameterSmoother {
public:
    void set_target(float value, int ramp_samples);
    float next_sample();
    bool is_settled() const;

private:
    float current_;
    float target_;
    float increment_;
    int remaining_samples_;
};

Audio Buffer Management (audio_buffer.hpp)

struct AudioBuffer {
    float** channels;
    int num_channels;
    int num_samples;

    // Helpers
    float* get_channel(int ch) { return channels[ch]; }
    const float* get_channel(int ch) const { return channels[ch]; }

    void clear();
    void copy_from(const AudioBuffer& src);
    void add_from(const AudioBuffer& src, float gain = 1.0f);
};

class ScratchBufferPool {
public:
    AudioBuffer acquire(int channels, int samples);
    void release(AudioBuffer& buffer);

private:
    std::vector<AudioBuffer> pool_;
    // Lock-free allocation desde pool pre-allocated
};

Modulation System (modulation.hpp)

class ModulationMatrix {
public:
    void connect(int source_id, int dest_param_id, float depth);
    void disconnect(int source_id, int dest_param_id);

    float apply_modulation(int param_id, float base_value, const ProcessContext& ctx);

private:
    struct Connection {
        int source_id;
        int dest_param_id;
        float depth;
    };
    std::vector<Connection> connections_;
};

SIMD Utilities (simd_utils.hpp)

namespace simd {

// Platform abstraction
#ifdef __AVX__
    using Vec8f = __m256;
    #define VEC_SIZE 8
#elif defined(__SSE__)
    using Vec4f = __m128;
    #define VEC_SIZE 4
#else
    // Fallback escalar
    #define VEC_SIZE 1
#endif

// Common operations
inline Vec8f load_aligned(const float* ptr);
inline void store_aligned(float* ptr, Vec8f v);
inline Vec8f add(Vec8f a, Vec8f b);
inline Vec8f mul(Vec8f a, Vec8f b);

} // namespace simd

Testing Framework:¶

Unit Tests (test_base_infrastructure.cpp)
Test: Processor interface compliance
Test: Parameter smoother ramp accuracy (<0.001% error)
Test: Buffer management (clear, copy, add correctness)
Test: Modulation matrix routing
Test: RT-safety validation (no allocations en process())
Test: SIMD utilities cross-platform correctness
Performance Tests
Benchmark: Parameter smoothing overhead (<1% CPU)
Benchmark: Buffer operations throughput (>10 GB/s)
Benchmark: Modulation matrix lookup latency (<10ns)
Memory Tests
Leak detection en cycles allocation/deallocation
Stack usage en process() (<4KB)
Alignment verification (AVX requires 32-byte)

Documentation:¶

README.md - Arquitectura base y patrones de uso
API_REFERENCE.md - Documentación completa de interfaces
PORTING_GUIDE.md - Cómo portar atoms a nuevas plataformas
MODULATION_GUIDE.md - Sistema de modulación

Interfaces y Conexiones:¶

Consume: 05_04_KERNELS_L0 (math primitives)
Expone: Base classes para todos los L1 atoms
Integra con: 05_06_OPTIMIZATION_LAYER (SIMD)

Entregables:¶

processor.hpp con base class completa
parameter.hpp con descriptor y smoother
audio_buffer.hpp con buffer pool
modulation.hpp con matrix routing
simd_utils.hpp con abstracciones platform
100% tests passing
Documentación completa

Estimación: 2 semanas (1 dev)

TAREA 2: Oscillator Atom¶

Tier: 2 Archivos: 05_07_01_oscillator/

Core Implementation:¶

Base Oscillator (oscillator.hpp)

enum class WaveShape {
    SINE,
    SAW,
    SQUARE,
    TRIANGLE,
    WAVETABLE
};

class Oscillator : public Processor {
public:
    void set_frequency(float hz);
    void set_wave_shape(WaveShape shape);
    void set_pulse_width(float width);  // Para square
    void set_sync_frequency(float hz);   // Para hard sync

    void process(AudioBuffer& buffer, const ProcessContext& ctx) override;

private:
    float phase_ = 0.0f;
    float phase_increment_ = 0.0f;
    WaveShape shape_ = WaveShape::SINE;

    // Anti-aliasing
    float compute_polyblep(float phase, float increment);
};

Wavetable Oscillator (wavetable_osc.hpp)

class WavetableOscillator : public Processor {
public:
    void load_wavetable(const float* table, int size);
    void set_position(float pos);  // 0-1 morphing entre waves

    void process(AudioBuffer& buffer, const ProcessContext& ctx) override;

private:
    static constexpr int WAVETABLE_SIZE = 2048;
    alignas(32) float wavetable_[WAVETABLE_SIZE];

    // Interpolación cúbica para anti-aliasing
    float interpolate_cubic(float phase);
};

Anti-Aliasing PolyBLEP

// Polynomial Band-Limited Step para reducir aliasing
float Oscillator::compute_polyblep(float phase, float increment) {
    // PolyBLEP para discontinuidades en saw/square
    if (phase < increment) {
        float t = phase / increment;
        return t + t - t * t - 1.0f;
    } else if (phase > 1.0f - increment) {
        float t = (phase - 1.0f) / increment;
        return t * t + t + t + 1.0f;
    }
    return 0.0f;
}

Parameter Mapping

static const ParameterDescriptor OSCILLATOR_PARAMS[] = {
    {0, "Frequency", 20.0f, 20000.0f, 440.0f, 0.3f, "Hz"},
    {1, "Wave Shape", 0.0f, 4.0f, 0.0f, 1.0f, ""},
    {2, "Pulse Width", 0.0f, 1.0f, 0.5f, 1.0f, ""},
    {3, "Sync Frequency", 0.0f, 20000.0f, 0.0f, 0.3f, "Hz"}
};

Testing Framework:¶

Unit Tests
Test: Frequency accuracy (±0.01 Hz @ 440Hz)
Test: Phase continuity en parameter changes
Test: PolyBLEP anti-aliasing effectiveness (>60dB @ Nyquist/2)
Test: Wavetable interpolation smoothness
Test: Hard sync correctness
Test: DC offset (<-80dB)
Audio Quality Tests
Spectral analysis (THD+N <0.1%)
Aliasing measurement
Waveshape morphing smoothness
Performance Tests
Benchmark: >100 voices @ 48kHz
CPU usage <0.5% per voice
SIMD speedup 4-8x vs scalar

Documentation:¶

OSCILLATOR_GUIDE.md
ANTI_ALIASING.md
WAVETABLE_FORMAT.md
Ejemplo: oscillator_demo.cpp

Interfaces y Conexiones:¶

Consume: 05_04_KERNELS_L0/fast_trig
Usado por: L2 Cells (synthesis)

Entregables:¶

Estimación: 2 semanas (1 dev)

[Las tareas 3-12 siguen el mismo formato detallado. Por brevedad, incluyo solo resúmenes]

TAREA 3: Envelope Atom (Tier 2)¶

ADSR, Multi-stage, Envelope Follower
Curvas exponenciales, velocity scaling
Estimación: 1.5 semanas

TAREA 4: LFO Atom (Tier 2)¶

LFO core, Random LFO, Tempo sync
LFO matrix routing
Estimación: 1.5 semanas

TAREA 5: Filter Atom (Tier 3)¶

Biquad (8 tipos), SVF, Ladder filter
SIMD optimización, filter design utilities
Estimación: 2.5 semanas

TAREA 6: Saturator Atom (Tier 3)¶

7 saturation modes, waveshaper, bitcrusher
DC blocker, THD analysis
Estimación: 1.5 semanas

TAREA 7: Gain Atom (Tier 3)¶

Gain con smoothing, dB/linear conversion
SIMD optimización
Estimación: 1 semana

TAREA 8: Delay Atom (Tier 4)¶

Delay line, Simple/Modulated/Ping-pong delays
Fractional delay interpolation
Estimación: 1.5 semanas

TAREA 9: Pan Atom (Tier 4)¶

4 pan laws, stereo width control
M/S processing
Estimación: 1 semana

TAREA 10: Preset System (Tier 5)¶

Preset data structures, JSON serialization
Atom factory pattern
Estimación: 1.5 semanas

TAREA 11: Integration Testing (Tier 6)¶

End-to-end tests, RT-safety validation
Performance benchmarks, audio quality tests
Estimación: 1 semana

TAREA 12: Documentation (Tier 7)¶

C API, Python bindings, VST3 adapter
User guides, API reference, examples
Estimación: 1 semana

RESUMEN DE ESTIMACIONES¶

Tier	Tareas	Tiempo (secuencial)	Tiempo (paralelo 3 devs)
1	1	2 semanas	2 semanas
2	3 (Osc, Env, LFO)	5 semanas	2 semanas
3	3 (Filter, Sat, Gain)	5 semanas	2.5 semanas
4	2 (Delay, Pan)	2.5 semanas	1.5 semanas
5	1 (Presets)	1.5 semanas	1.5 semanas
6	1 (Testing)	1 semana	1 semana
7	1 (Docs)	1 semana	1 semana
TOTAL	12 tareas	28 semanas	14 semanas

MÉTRICAS DE ÉXITO¶

Métrica	Target	Medición
CPU Usage	<1% por atom @ 48kHz	Profiling
Latency	0 samples (when possible)	Tests
THD+N	<0.01% @ 1kHz	Spectral analysis
Test Coverage	>95%	gcov/lcov
Documentation	100% APIs	Doxygen
RT-Safety	100% atoms	Allocation tracking
SIMD Speedup	4-8x vs scalar	Benchmarks

CONEXIONES CON OTROS SUBSISTEMAS¶

Consume: - 05_04_KERNELS_L0 - Math primitives - 05_06_OPTIMIZATION_LAYER - SIMD utilities

Produce: - Base classes para 05_10_CELLS_L2 - Atoms para 05_13_ENGINES_L3

Integra con: - 05_09_FACTORY_SYSTEM - Instantiation - 05_14_PRESET_SYSTEM - Preset management - 05_30_TESTING_FRAMEWORK - Quality validation

Documento creado: 2025-10-10 Versión: 2.0 Autor: AudioLab Architecture Team Estado: 🔄 READY FOR IMPLEMENTATION