Skip to content

05_12_CALIBRATION_SYSTEM - Sistema de Calibración y Ajuste Fino DSP

🎯 Propósito

El Calibration System es el sistema de ajuste fino y optimización paramétrica que asegura que cada componente DSP opere en su punto óptimo. Es la infraestructura que calibra filtros para respuesta plana, ajusta ganancias para headroom óptimo, compensa no-linealidades, y afina parámetros para máxima calidad sonora.

Metáfora: Si los componentes DSP son instrumentos musicales, el Calibration System es el afinador maestro más el luthier que ajusta la acción, la entonación, y la respuesta de cada instrumento.

📦 Estructura

05_12_CALIBRATION_SYSTEM/
├── 05_12_00_calibration_framework/     # Framework base de calibración
│   ├── include/
│   │   ├── CalibrationTarget.hpp      # Definición de targets y specs
│   │   ├── CalibrationProcess.hpp     # Pipeline de calibración
│   │   └── MultiObjectiveOptimizer.hpp # Optimización multi-objetivo
│   ├── src/
│   └── tests/
│
├── 05_12_01_frequency_calibration/     # Calibración de respuesta en frecuencia
├── 05_12_02_dynamics_calibration/      # Calibración de dinámicas
├── 05_12_03_nonlinear_calibration/     # Calibración de no-linealidades
├── 05_12_04_modulation_calibration/    # Calibración de modulación
├── 05_12_05_level_calibration/         # Calibración de niveles
├── 05_12_06_latency_calibration/       # Calibración de latencia
├── 05_12_07_reference_matching/        # Matching de referencias
├── 05_12_08_psychoacoustic_calibration/ # Calibración psicoacústica
├── 05_12_09_adaptive_calibration/      # Calibración adaptativa
├── 05_12_10_standards_compliance/      # Conformidad con estándares
│
├── 05_12_interfaces/                   # Interfaces públicas
├── 05_12_documentation/                # Documentación técnica
├── 05_12_test_integration/             # Tests de integración
└── examples/                           # Ejemplos de uso

🔧 Componentes Principales

1. Calibration Framework (00)

Framework base que define estructuras, interfaces, y procesos comunes para todos los tipos de calibración.

Características: - CalibrationTarget: Define qué y cómo calibrar - CalibrationProcess: Pipeline estándar de 5 etapas - MultiObjectiveOptimizer: Optimización Pareto para múltiples objetivos - CalibrationSignalGenerator: Generadores de señales de test

2. Frequency Calibration (01)

Ajuste preciso de respuesta en frecuencia para filtros, EQs, y procesadores espectrales.

3. Dynamics Calibration (02)

Calibración de compresores, limiters, gates, y expanders para comportamiento exacto.

4. Nonlinear Calibration (03)

Ajuste de saturadores y procesadores no-lineales para características armónicas específicas.

5. Modulation Calibration (04)

Calibración de LFOs, envelopes, y moduladores para rangos musicales.

6. Level Calibration (05)

Gestión precisa de gain staging y headroom a través de la cadena de señal.

7. Latency Calibration (06)

Medición y compensación precisa de latencia introducida por procesamiento.

8. Reference Matching (07)

Emulación precisa de hardware y matching de referencias target.

9. Psychoacoustic Calibration (08)

Ajuste basado en modelos de percepción auditiva humana.

10. Adaptive Calibration (09)

Auto-calibración que aprende y se ajusta basándose en uso y feedback.

11. Standards Compliance (10)

Calibración según normas AES, EBU, ITU, y otros estándares industriales.

🚀 Uso Básico

Ejemplo Simple: Calibrar un Filtro

#include "CalibrationTarget.hpp"
#include "CalibrationProcess.hpp"
#include "frequency_calibration/FilterCalibrator.hpp"

using namespace AudioLab::Calibration;

// 1. Create your filter component
auto filter = std::make_shared<MyLowPassFilter>();

// 2. Define calibration target
CalibrationTarget target("LowPass_1kHz", filter);

// 3. Add specification
CalibrationSpecification spec(TargetType::FREQUENCY_RESPONSE);
spec.measurement.sampleRate = 48000.0;
spec.measurement.blockSize = 512;
spec.errorThreshold = 0.1f;  // ±0.1dB

// Define ideal response (flat to 1kHz, then -6dB/octave)
spec.idealResponse = {/* frequency response curve */};
spec.tolerances = {/* per-frequency tolerances */};

target.addSpecification(spec);

// 4. Create calibrator and calibrate
FilterCalibrator calibrator;
CalibrationResult result = calibrator.calibrate(target);

// 5. Check results
if (result.success) {
    std::cout << "Calibration successful!\n";
    std::cout << "Final error: " << result.finalError << " dB\n";
    std::cout << "Iterations: " << result.iterationsUsed << "\n";

    // Apply calibrated parameters
    for (const auto& [name, value] : result.parameters) {
        filter->setParameter(name, value);
    }
} else {
    std::cout << "Calibration failed: " << result.notes << "\n";
}

Ejemplo con Multi-Objetivo

// Calibrate with multiple competing objectives
CalibrationSpecification freqSpec(TargetType::FREQUENCY_RESPONSE);
freqSpec.importance = 1.0f;  // High priority
target.addSpecification(freqSpec);

CalibrationSpecification phaseSpec(TargetType::PHASE_RESPONSE);
phaseSpec.importance = 0.5f;  // Medium priority
target.addSpecification(phaseSpec);

// The optimizer will find Pareto-optimal solution
MultiObjectiveCalibrator calibrator;
CalibrationResult result = calibrator.calibrate(target);

📊 Pipeline de Calibración

El sistema usa un pipeline estándar de 5 etapas:

1. Preparación

  • Identificar componente a calibrar
  • Cargar especificaciones target
  • Setup de señales de test
  • Inicializar optimizer

2. Medición

  • Inyectar stimulus (sweep, impulse, etc.)
  • Capturar respuesta
  • Analizar comportamiento
  • Calcular error vs target

3. Optimización

  • Ajustar parámetros
  • Iterar medición
  • Converger hasta error mínimo
  • Verificar constraints

4. Validación

  • Test edge cases (extremos de entrada)
  • Verificar estabilidad (no oscilación)
  • Comprobar consistencia (reproducible)
  • Confirmar standards (cumple specs)

5. Almacenamiento

  • Guardar calibración
  • Documentar proceso
  • Control de versiones
  • Aplicar a componente

🎯 Tipos de Calibración

Frequency Response

  • Calibración de filtros para respuesta plana
  • Matching de curvas EQ
  • Compensación de fase

Dynamics

  • Curvas de compresión precisas
  • Tiempos de attack/release
  • Gates y expanders

Nonlinear

  • Contenido armónico específico
  • Transfer functions
  • Saturación y distorsión

Modulation

  • Rangos de LFO musicales
  • Curvas de envelope
  • Depths de modulación

Level

  • Gain staging óptimo
  • Unity gain calibration
  • Headroom management

Latency

  • Medición sample-accurate
  • Compensación de delays
  • Phase-locked loops

Reference Matching

  • Emulación de hardware
  • Null test calibration
  • Component matching

Psychoacoustic

  • Loudness calibration (LUFS)
  • Equal loudness curves
  • Masking-aware optimization

Adaptive

  • Auto-calibración continua
  • Machine learning calibration
  • User preference learning

Standards Compliance

  • AES17 audio measurement
  • EBU R128 loudness
  • ITU-R BS.1770
  • Sample rate accuracy

🔬 Algoritmos de Optimización

Gradient Descent

Para problemas suaves con gradientes calculables: 

GradientDescentOptimizer optimizer;
optimizer.setLearningRate(0.01f);
optimizer.setMomentum(0.9f);

Genetic Algorithm

Para espacios de búsqueda complejos: 

GeneticOptimizer optimizer;
optimizer.setPopulationSize(100);
optimizer.setMutationRate(0.1f);

Particle Swarm

Para optimización rápida: 

ParticleSwarmOptimizer optimizer;
optimizer.setSwarmSize(50);
optimizer.setInertia(0.7f);

Multi-Objective (NSGA-II)

Para objetivos competing: 

MultiObjectiveOptimizer optimizer;
optimizer.setPopulationSize(100);
optimizer.setGenerations(50);

📈 Métricas de Calidad

Error Metrics

  • RMS Error: Error cuadrático medio
  • Max Error: Error máximo absoluto
  • Mean Error: Error promedio
  • Per-Frequency Error: Error por banda de frecuencia

Convergence Metrics

  • Iterations Used: Número de iteraciones
  • Time Elapsed: Tiempo de calibración
  • Improvement Rate: Velocidad de convergencia

Quality Metrics

  • Reproducibility: Consistencia entre runs
  • Stability: No oscilación/inestabilidad
  • Standards Compliance: Cumplimiento de normas

🔗 Dependencies

Este subsistema depende de: - 00_CATALOG_REGISTRY: Para identificar componentes - 03_ALGORITHM_SPEC: Comportamiento ideal de referencia - 04_KERNELS_L0: Kernels a calibrar - 06_OPTIMIZATION_LAYER: Algoritmos de optimización - 07_ATOMS_L1: Unidades calibrables - 11_GRAPH_SYSTEM: Calibración de grafos completos - 18_QUALITY_METRICS: Validación de calidad - 37_AUDIO_QUALITY_ANALYSIS: Análisis de audio

🎓 Conceptos Clave

Calibration Target

Define qué calibrar y cómo medirlo. Contiene especificaciones, tolerancias, y constraints.

Calibration Specification

Define comportamiento ideal target, métricas de error aceptables, y prioridad en optimización multi-objetivo.

Measured Response

Datos capturados del componente bajo test: respuesta en frecuencia, fase, time-domain, métricas.

Calibration Result

Output final: parámetros optimizados, error metrics, metadata, verificación.

Multi-Objective Optimization

Optimización simultánea de objetivos competing (ej: flatness vs phase linearity). Usa Pareto optimization.

⚠️ Antipatterns a Evitar

  • Over-calibration: Calibrar hasta inestabilidad → Mantener márgenes de seguridad
  • Ignoring context: Calibrar sin considerar uso → Contexto determina targets
  • Single-point calibration: Solo calibrar un punto → Cubrir todo el rango
  • Static calibration: Calibrar una vez y olvidar → Necesita mantenimiento
  • Perceptual ignorance: Solo métricas técnicas → Percepción es lo importante

📚 Documentación Adicional

  • Ver 05_12_documentation/ para guías detalladas
  • Ver examples/ para casos de uso completos
  • Ver tests en cada subsistema para referencia de API

🏗️ Estado de Implementación

Fase 1 - Calibración Básica (En Progreso)

  • Framework de calibración fundamental
  • Calibración de frecuencia básica
  • Calibración de niveles simple
  • Medición de latencia

Fase 2 - Calibración Avanzada (Planeado)

  • Calibración de dinámicas completa
  • Calibración de no-linealidades
  • Modulation calibration
  • Reference matching

Fase 3 - Calibración Inteligente (Futuro)

  • Auto-calibración continua
  • ML-based calibration
  • Calibración psicoacústica
  • Adaptación al usuario

📞 Contacto y Contribución

Para reportar issues, sugerencias, o contribuciones: - Ver CONTRIBUTING.md en raíz del proyecto - Documentar calibration procedures en 05_12_documentation/ - Añadir tests para nuevos tipos de calibración

Version: 1.0.0 Last Updated: 2025-10-14 Status: Initial Implementation