05_07_ATOMS_L1 - Índice de Navegación¶
📚 GUÍA RÁPIDA¶
Este documento sirve como mapa de navegación del subsistema 05_07_ATOMS_L1 (L1 Atoms). Úsalo para encontrar rápidamente la información que necesitas según tu rol y objetivo.
🎯 NAVEGACIÓN POR ROL¶
👨💼 Si eres Product Manager / Executive:¶
- Empieza aquí: RESUMEN_EJECUTIVO.md
- Visión general, ROI, timeline, métricas de negocio
- Luego revisa: README.md § Roadmap
- Fases de desarrollo, hitos, timeline
- Para detalles técnicos (opcional): PLAN_DE_DESARROLLO.md
👨💻 Si eres Developer (nuevo al proyecto):¶
- Quick Start: README.md § Quick Start
- Instalación, primer ejemplo, build instructions
- Arquitectura: README.md § Capacidades Clave
- Interface, ejemplos de código, patrones de uso
- Profundizar: PLAN_DE_DESARROLLO.md
- Detalles de implementación de cada átomo
👨💻 Si eres Developer (contribuidor):¶
- Plan completo: PLAN_DE_DESARROLLO.md
- 12 tareas detalladas, estimaciones, entregables
- Por átomo específico:
- Filters: 05_07_04_filter/
- Oscillators: 05_07_01_oscillator/
- Envelopes: 05_07_02_envelope/
- LFOs: 05_07_03_lfo/
- Delays: 05_07_07_delay/
- Saturators: 05_07_05_saturator/
- Gain: 05_07_06_gain/
- Pan: 05_07_08_pan/
- Testing: 05_07_test_integration/
🧪 Si eres QA / Tester:¶
- Criterios de calidad: README.md § Métricas de Calidad
- Test coverage: PLAN_DE_DESARROLLO.md § TAREA 11
- Test suites: 05_07_test_integration/
📝 Si eres Tech Writer / Documentation:¶
- Docs por átomo: Ver § Estructura de Documentación abajo
- API Reference: 05_07_documentation/API_REFERENCE.md
- Examples: 05_07_examples/
🏗️ Si eres Architect / Tech Lead:¶
- Arquitectura completa: README.md
- Plan técnico detallado: PLAN_DE_DESARROLLO.md
- Dependencies: README.md § Conexiones
📂 ESTRUCTURA DE CARPETAS¶
05_07_ATOMS_L1/
│
├── 📄 README.md # Documentación técnica principal
├── 📄 PLAN_DE_DESARROLLO.md # Plan detallado (12 tareas)
├── 📄 RESUMEN_EJECUTIVO.md # Executive summary, ROI, timeline
├── 📄 INDICE.md # Este archivo (navegación)
├── 📄 STATUS.md # Estado actual del proyecto
│
├── 📁 05_07_00_base_infrastructure/ # TIER 1 - Base classes
│ ├── include/
│ │ ├── processor.hpp # Processor base class
│ │ ├── parameter.hpp # Parameter system
│ │ ├── audio_buffer.hpp # Buffer management
│ │ ├── modulation.hpp # Modulation matrix
│ │ └── simd_utils.hpp # SIMD abstractions
│ ├── tests/
│ │ └── test_base_infrastructure.cpp
│ ├── README.md
│ └── CMakeLists.txt
│
├── 📁 05_07_01_oscillator/ # TIER 2 - Oscillators
│ ├── include/
│ │ ├── oscillator.hpp # Base oscillator
│ │ ├── wavetable_osc.hpp # Wavetable oscillator
│ │ └── polyblep.hpp # Anti-aliasing
│ ├── tests/
│ ├── docs/
│ │ ├── OSCILLATOR_GUIDE.md # User guide
│ │ ├── ANTI_ALIASING.md # PolyBLEP explained
│ │ └── WAVETABLE_FORMAT.md # Wavetable spec
│ ├── examples/
│ │ └── oscillator_demo.cpp
│ └── CMakeLists.txt
│
├── 📁 05_07_02_envelope/ # TIER 2 - Envelopes
│ ├── include/
│ │ ├── adsr.hpp # ADSR envelope
│ │ ├── multi_env.hpp # Multi-stage envelope
│ │ ├── follower.hpp # Envelope follower
│ │ └── envelope_curves.hpp # Curve shapes
│ ├── tests/
│ ├── docs/
│ │ ├── ENVELOPE_GUIDE.md
│ │ ├── CURVE_SHAPES.md
│ │ └── MULTI_STAGE_TUTORIAL.md
│ ├── examples/
│ └── CMakeLists.txt
│
├── 📁 05_07_03_lfo/ # TIER 2 - LFOs
│ ├── include/
│ │ ├── lfo.hpp # LFO core
│ │ ├── random_lfo.hpp # Random/S&H/Perlin
│ │ ├── tempo_sync.hpp # Tempo-synced LFO
│ │ └── lfo_matrix.hpp # Modulation routing
│ ├── tests/
│ ├── docs/
│ │ ├── LFO_GUIDE.md
│ │ ├── TEMPO_SYNC.md
│ │ └── MODULATION_ROUTING.md
│ ├── examples/
│ └── CMakeLists.txt
│
├── 📁 05_07_04_filter/ # TIER 3 - Filters
│ ├── include/
│ │ ├── biquad.hpp # Biquad filter (8 types)
│ │ ├── svf.hpp # State Variable Filter
│ │ ├── ladder.hpp # Ladder filter (Moog)
│ │ └── filter_design.hpp # Design utilities
│ ├── tests/
│ ├── docs/
│ │ ├── FILTER_COOKBOOK.md
│ │ ├── BIQUAD_MATH.md
│ │ ├── LADDER_GUIDE.md
│ │ └── FREQUENCY_RESPONSE.md
│ ├── examples/
│ │ └── eq_demo.cpp
│ └── CMakeLists.txt
│
├── 📁 05_07_05_saturator/ # TIER 3 - Saturators
│ ├── include/
│ │ ├── saturator.hpp # Saturator core
│ │ ├── saturation_curves.hpp # Saturation functions
│ │ ├── waveshaper.hpp # Waveshaper
│ │ ├── bitcrusher.hpp # Bitcrusher
│ │ └── dc_blocker.hpp # DC blocker
│ ├── tests/
│ ├── docs/
│ │ ├── SATURATION_GUIDE.md
│ │ ├── HARMONIC_ANALYSIS.md
│ │ └── WAVESHAPER_DESIGN.md
│ ├── examples/
│ │ └── guitar_amp_sim.cpp
│ └── CMakeLists.txt
│
├── 📁 05_07_06_gain/ # TIER 3 - Gain
│ ├── include/
│ │ └── gain.hpp
│ ├── tests/
│ ├── docs/
│ │ └── GAIN_GUIDE.md
│ ├── examples/
│ │ └── fader_demo.cpp
│ └── CMakeLists.txt
│
├── 📁 05_07_07_delay/ # TIER 4 - Delays
│ ├── include/
│ │ ├── delay_line.hpp # Delay line base
│ │ ├── simple_delay.hpp # Simple delay
│ │ ├── mod_delay.hpp # Modulated delay
│ │ └── pingpong_delay.hpp # Ping-pong delay
│ ├── tests/
│ ├── docs/
│ │ ├── DELAY_GUIDE.md
│ │ └── FRACTIONAL_DELAY.md
│ ├── examples/
│ │ └── echo_demo.cpp
│ └── CMakeLists.txt
│
├── 📁 05_07_08_pan/ # TIER 4 - Pan
│ ├── include/
│ │ ├── panner.hpp # Panner
│ │ └── stereo_width.hpp # Stereo width
│ ├── tests/
│ ├── docs/
│ │ ├── PANNING_GUIDE.md
│ │ └── PAN_LAWS_EXPLAINED.md
│ ├── examples/
│ │ └── stereo_mixer.cpp
│ └── CMakeLists.txt
│
├── 📁 05_07_09_preset_system/ # TIER 5 - Presets & Factory
│ ├── include/
│ │ ├── preset.hpp # Preset data structures
│ │ ├── preset_bank.hpp # Preset bank
│ │ ├── factory.hpp # Atom factory
│ │ └── preset_manager.hpp # Preset application
│ ├── tests/
│ ├── docs/
│ │ ├── PRESET_FORMAT.md
│ │ └── FACTORY_USAGE.md
│ ├── examples/
│ │ └── preset_browser.cpp
│ ├── presets/ # 50+ presets predefinidos
│ │ ├── filters/
│ │ ├── oscillators/
│ │ └── ...
│ └── CMakeLists.txt
│
├── 📁 05_07_test_integration/ # TIER 6 - Integration Tests
│ ├── test_e2e.cpp # End-to-end tests
│ ├── test_rt_safety.cpp # RT-safety validation
│ ├── test_performance.cpp # Performance benchmarks
│ ├── test_audio_quality.cpp # Audio quality tests
│ ├── README.md
│ │ ├── TESTING_STRATEGY.md
│ │ ├── QUALITY_METRICS.md
│ │ └── REGRESSION_TESTS.md
│ └── CMakeLists.txt
│
├── 📁 05_07_interfaces/ # TIER 7 - External Interfaces
│ ├── c_api/
│ │ ├── atoms_c_api.h # C API wrapper
│ │ └── atoms_c_api.cpp
│ ├── python/
│ │ ├── atoms.py # Python bindings
│ │ └── setup.py
│ ├── vst3/
│ │ └── atom_vst3_wrapper.hpp # VST3 adapter template
│ ├── README.md
│ └── CMakeLists.txt
│
└── 📁 05_07_documentation/ # TIER 7 - Documentation
├── USER_GUIDE.md # Guía completa de usuario
├── QUICK_START.md # Tutorial rápido
├── API_REFERENCE.md # Referencia API completa
├── ARCHITECTURE.md # Diseño interno
├── PERFORMANCE_GUIDE.md # Optimización
├── PORTING_GUIDE.md # Portar a nuevas plataformas
├── examples/
│ ├── simple_synth.cpp # Sintetizador básico
│ ├── filtered_noise.cpp # Noise + filter
│ ├── vibrato_effect.cpp # Vibrato (LFO + delay)
│ └── ...
└── diagrams/
├── architecture.png
├── processor_hierarchy.png
└── modulation_routing.png
📊 QUICK STATS¶
| Métrica | Valor |
|---|---|
| Átomos implementados | 8 tipos fundamentales |
| Líneas de código estimadas | ~30,000 LOC |
| Duración (paralelo) | 14 semanas (3 devs) |
| Duración (secuencial) | 28 semanas (1 dev) |
| Test coverage target | >95% |
| Performance speedup (SIMD) | 4-8x vs scalar |
| CPU usage target | <1% por atom @ 48kHz |
| Presets incluidos | 50+ |
| Documentación | 100+ páginas |
🔗 ENLACES RÁPIDOS¶
Documentos Principales:¶
- README.md - Documentación técnica principal
- PLAN_DE_DESARROLLO.md - Plan detallado (12 tareas)
- RESUMEN_EJECUTIVO.md - Executive summary, ROI
Por Átomo:¶
- Filters - Biquad, SVF, Ladder
- Oscillators - Sin, Saw, Square, Triangle, Wavetable
- Envelopes - ADSR, Multi-stage
- LFOs - Standard, Random, Tempo-synced
- Delays - Simple, Modulated, Ping-pong
- Saturators - 7 saturation modes
- Gain - Linear/dB con smoothing
- Pan - 4 pan laws, stereo width
Sistemas de Soporte:¶
- Base Infrastructure - Processor, Buffer, Parameter
- Preset System - Factory, Presets, JSON
- Integration Tests - E2E, RT-safety, Performance
- External Interfaces - C API, Python, VST3
Documentación Adicional:¶
🗺️ ROADMAP VISUAL¶
TIER 1 (Semanas 1-2) TIER 2 (Semanas 3-5)
┌─────────────────────┐ ┌─────────────────────┐
│ Base Infrastructure │────────────────→│ Oscillator │
│ • Processor │ │ • 5 waveforms │
│ • AudioBuffer │ │ • Anti-aliasing │
│ • Parameter │ │ • SIMD optimized │
│ • Modulation │ └─────────────────────┘
│ • SIMD utils │ │
└─────────────────────┘ │
│ ┌───────▼─────────────┐
│ │ Envelope │
│ │ • ADSR │
│ │ • Multi-stage │
│ │ • Velocity scaling │
│ └─────────────────────┘
│ │
│ ┌────────▼────────────┐
│ │ LFO │
│ │ • Tempo sync │
│ │ • Random modes │
│ │ • LFO matrix │
│ └─────────────────────┘
│ │
▼ ▼
TIER 3 (Semanas 6-8) TIER 4 (Semanas 9-10)
┌─────────────────────┐ ┌─────────────────────┐
│ Filter │ │ Delay │
│ • Biquad (8 types) │ │ • Simple │
│ • SVF │ │ • Modulated │
│ • Ladder (Moog) │ │ • Ping-pong │
└─────────────────────┘ └─────────────────────┘
│ │
┌─────────▼───────────┐ ┌────────▼────────────┐
│ Saturator │ │ Pan │
│ • 7 modes │ │ • 4 pan laws │
│ • Waveshaper │ │ • Stereo width │
│ • DC blocker │ │ • M/S processing │
└─────────────────────┘ └─────────────────────┘
│ │
┌─────────▼───────────┐ │
│ Gain │ │
│ • Linear/dB │ │
│ • Smoothing │ │
│ • SIMD optimized │ │
└─────────────────────┘ │
│ │
└────────────────┬───────────────────────┘
▼
TIER 5 (Semanas 11-12)
┌─────────────────────┐
│ Preset System │
│ • Factory pattern │
│ • JSON serialization│
│ • 50+ presets │
└─────────────────────┘
│
▼
TIER 6 (Semana 13)
┌─────────────────────┐
│ Integration Testing │
│ • E2E workflows │
│ • RT-safety │
│ • Performance │
└─────────────────────┘
│
▼
TIER 7 (Semana 14)
┌─────────────────────┐
│ Documentation │
│ • C API │
│ • Python bindings │
│ • VST3 adapter │
│ • User guides │
└─────────────────────┘
🔍 BÚSQUEDA RÁPIDA POR TEMA¶
Quiero aprender sobre...¶
Anti-aliasing en osciladores:¶
→ 05_07_01_oscillator/ANTI_ALIASING.md → PLAN_DE_DESARROLLO.md § TAREA 2
Diseño de filtros biquad:¶
→ 05_07_04_filter/FILTER_COOKBOOK.md → 05_07_04_filter/BIQUAD_MATH.md
Envelopes ADSR y curvas exponenciales:¶
→ 05_07_02_envelope/ENVELOPE_GUIDE.md → 05_07_02_envelope/CURVE_SHAPES.md
LFOs con tempo sync:¶
→ 05_07_03_lfo/TEMPO_SYNC.md → 05_07_03_lfo/MODULATION_ROUTING.md
Fractional delay y interpolación:¶
→ 05_07_07_delay/FRACTIONAL_DELAY.md
Pan laws y stereo width:¶
→ 05_07_08_pan/PAN_LAWS_EXPLAINED.md
Saturation y harmonic analysis:¶
→ 05_07_05_saturator/HARMONIC_ANALYSIS.md → 05_07_05_saturator/WAVESHAPER_DESIGN.md
SIMD optimization:¶
→ 05_07_00_base_infrastructure/docs/SIMD_GUIDE.md → README.md § SIMD Optimization
RT-safety y real-time constraints:¶
→ README.md § RT-Safety & Performance → 05_07_test_integration/TESTING_STRATEGY.md
Preset system y factory pattern:¶
→ 05_07_09_preset_system/PRESET_FORMAT.md → 05_07_09_preset_system/FACTORY_USAGE.md
Bindings para Python o VST3:¶
→ 05_07_interfaces/python/README.md → 05_07_interfaces/vst3/README.md
📞 CONTACTO Y SOPORTE¶
Preguntas técnicas: - Tech Lead: TBD - Email: atoms-dev@audiolab.io (TBD)
Issues y bugs: - GitHub Issues: https://github.com/audiolab/audio-lab/issues (TBD) - Bug tracker: Jira (link TBD)
Contribuciones: - Contributing guide: CONTRIBUTING.md (TBD) - Code of conduct: CODE_OF_CONDUCT.md (TBD)
Comunidad: - Discord: https://discord.gg/audiolab (TBD) - Forum: https://forum.audiolab.io (TBD)
📝 ÚLTIMA ACTUALIZACIÓN¶
Versión: 1.0 Fecha: 2025-10-10 Autor: AudioLab Architecture Team Próxima revisión: 2025-11-10 (mensual)
💡 Tip: Marca este documento como favorito - es tu punto de entrada principal al subsistema 05_07_ATOMS_L1.