04_CORE - API Reference

📚 API que Ofrece CORE a los Plugins

Esta es la API REAL disponible en 04_CORE. Cada subsistema ofrece clases, funciones y tipos que TUS plugins pueden usar.

---

🎯 04_00 - Type System (Tipos de datos)

Sample Types

#include "04_00_type_system/00_fundamental_types/sample_types.hpp"

// Tipos de muestras de audio
using Sample = float;                    // Muestra mono
using StereoSample = std::array<float, 2>;  // Muestra estéreo
using AudioFrame<N> = std::array<float, N>;  // Frame de N canales

// Conversión entre tipos
Sample monoFromStereo(const StereoSample& stereo);

Time Types

#include "04_00_type_system/00_fundamental_types/time_types.hpp"

class Seconds { double value; };         // Tiempo en segundos
class Milliseconds { double value; };    // Tiempo en milisegundos
class Samples { size_t value; };         // Tiempo en muestras

// Conversión
Samples timeToSamples(Seconds time, double sampleRate);
Seconds samplesToTime(Samples samples, double sampleRate);

Frequency Types

#include "04_00_type_system/00_fundamental_types/frequency_types.hpp"

class Hertz { double value; };           // Frecuencia en Hz
class Kilohertz { double value; };       // Frecuencia en kHz

// Conversión
double toNormalizedFrequency(Hertz freq, double sampleRate);

DB Conversion

#include "04_00_type_system/04_conversion_traits/db_conversion.hpp"

// Conversión dB ↔ gain lineal
float db_to_gain(float db);              // -60dB → 0.001
float gain_to_db(float gain);            // 2.0 → +6dB

// Conversión dB ↔ amplitud
float db_to_amplitude(float db);
float amplitude_to_db(float amplitude);

---

🔢 04_02 - Math Primitives (Matemáticas DSP)

Fast Trig (Rápido)

#include "04_02_math_primitives/fast_trig.hpp"

// 5-10x más rápido que std::sin/cos
float fast_sin(float x);
float fast_cos(float x);
float fast_tan(float x);

// Variantes con precisión ajustable
float fast_sin_precise(float x);  // Más lento pero más preciso

Fast Exp/Log

#include "04_02_math_primitives/fast_exp_log.hpp"

// 3-5x más rápido que std::exp/log
float fast_exp(float x);
float fast_log(float x);
float fast_pow(float base, float exp);

// Para conversiones dB
float fast_exp2(float x);  // 2^x
float fast_log2(float x);  // log2(x)

Interpolation

#include "04_02_math_primitives/interpolation.hpp"

// Interpolación para delays, pitch shifting, etc.
float linearInterpolate(float a, float b, float t);
float cubicInterpolate(float a, float b, float c, float d, float t);
float hermiteInterpolate(float a, float b, float c, float d, float t);

---

💾 04_03 - Memory Management (Contenedores RT-safe)

RingBuffer (Delay lines)

#include "04_03_memory_management/ring_buffer.hpp"

template<typename T>
class RingBuffer {
public:
    void resize(size_t size);              // Configura tamaño
    void write(T value);                   // Escribe muestra
    T read(size_t delay_samples);          // Lee con delay
    T readInterpolated(float delay);       // Lee con interpolación
    void clear();                          // Limpia buffer
};

// Uso:
RingBuffer<float> delayLine;
delayLine.resize(48000);  // 1 segundo @ 48kHz
delayLine.write(input);
float delayed = delayLine.readInterpolated(22050.5f);  // 0.5s

TripleBuffer (UI ↔ Audio)

#include "04_03_memory_management/triple_buffer.hpp"

template<typename T>
class TripleBuffer {
public:
    void write(const T& data);             // Escribe desde UI thread
    bool read(T& data);                    // Lee desde audio thread
};

// Uso (comunicación entre threads sin locks):
TripleBuffer<PluginState> stateBuffer;

// UI thread:
stateBuffer.write(newState);

// Audio thread:
PluginState state;
if (stateBuffer.read(state)) {
    // Actualizar parámetros
}

WaitFreeSPSC (Queue sin locks)

#include "04_03_memory_management/wait_free_spsc.hpp"

template<typename T>
class WaitFreeSPSC {
public:
    bool push(const T& item);              // RT-safe push
    bool pop(T& item);                     // RT-safe pop
    size_t size() const;
};

// Uso (enviar eventos desde audio thread):
WaitFreeSPSC<MidiEvent> midiQueue;

// Audio thread:
midiQueue.push(noteOnEvent);

// UI thread:
MidiEvent event;
while (midiQueue.pop(event)) {
    displayMidiEvent(event);
}

---

⚡ 04_04 - Realtime Safety (Seguridad RT)

RT Annotations

#include "04_04_realtime_safety/rt_annotations.hpp"

// Marcar funciones RT-safe
void RT_SAFE processAudio() noexcept;

// Marcar funciones NO RT-safe
void RT_UNSAFE allocateMemory();

// Asserts en desarrollo
RT_ASSERT(condition, "Error message");

---

🎚️ 04_08 - Parameter System

Parameter (Con smoothing)

#include "04_08_parameter_system/parameter.hpp"
#include "04_08_parameter_system/parameter_info.hpp"
#include "04_08_parameter_system/parameter_range.hpp"

// Crear parámetro
ParameterInfo info("gain", "Gain", "dB", "Amplifier");
ParameterRange range(-60.0f, 12.0f, 0.0f);  // min, max, default
Parameter<float> gainParam(info, range, 0.0f);

// Configurar smoothing
gainParam.set_smoothing_time(20.0f, 48000.0f);  // 20ms @ 48kHz

// Desde UI thread (cambiar valor)
gainParam.set_value(-6.0f);                     // Nuevo valor en dB

// Desde audio thread (obtener valor suavizado)
for (int i = 0; i < numSamples; i++) {
    float gain = gainParam.get_smoothed_value();  // ← RT-safe, suave
    output[i] = input[i] * db_to_gain(gain);
}

Parameter Range

#include "04_08_parameter_system/parameter_range.hpp"

// Rango lineal
ParameterRange linear(0.0f, 1.0f, 0.5f);

// Rango logarítmico (para frecuencias)
ParameterRange logFreq = ParameterRange::logarithmic(
    20.0f,      // min (20 Hz)
    20000.0f,   // max (20 kHz)
    1000.0f     // default (1 kHz)
);

// Conversión normalized [0,1] ↔ valor real
float normalized = logFreq.toNormalized(1000.0f);  // 0.5
float freq = logFreq.fromNormalized(0.5f);         // 1000.0

---

🎵 04_10 - Audio Processor (Clase base)

AudioProcessor (Template Method Pattern)

#include "04_10_audio_processor/audio_processor.hpp"

class MyPlugin : public audiolab::core::AudioProcessor {
public:
    MyPlugin() : AudioProcessor(ProcessorInfo{
        "My Plugin", "AudioLab", "com.audiolab.myplugin", "1.0.0"
    }) {}

protected:
    // Llamado una vez al inicio
    void on_prepare(const ProcessorConfig& config) override {
        sampleRate_ = config.sample_rate;
        delayLine_.resize(config.sample_rate * 2.0);  // 2 segundos
    }

    // Llamado cada bloque de audio (RT-SAFE)
    void on_process(
        const float* const* inputs,
        float** outputs,
        uint32_t num_samples
    ) noexcept override {
        for (uint32_t i = 0; i < num_samples; i++) {
            float input = inputs[0][i];
            delayLine_.write(input);
            float delayed = delayLine_.read(sampleRate_ * 0.5);  // 0.5s
            outputs[0][i] = input * 0.5f + delayed * 0.5f;
        }
    }

    // Llamado al finalizar
    void on_release() override {
        delayLine_.clear();
    }

private:
    double sampleRate_ = 48000.0;
    RingBuffer<float> delayLine_;
};

---

📊 04_05 - Buffer Management

AudioBuffer

#include "04_05_buffer_management/audio_buffer.hpp"

template<typename SampleType, size_t MaxChannels = 8>
class AudioBuffer {
public:
    void resize(size_t numChannels, size_t numSamples);
    SampleType* getChannelPointer(size_t channel);
    const SampleType* getChannelPointer(size_t channel) const;
    void clear();
    size_t getNumChannels() const;
    size_t getNumSamples() const;
};

// Uso:
AudioBuffer<float, 2> stereoBuffer;
stereoBuffer.resize(2, 512);  // 2 canales, 512 muestras

float* left = stereoBuffer.getChannelPointer(0);
float* right = stereoBuffer.getChannelPointer(1);

---

🔀 04_07 - Event Dispatcher

Event System

#include "04_07_event_dispatcher/event.hpp"
#include "04_07_event_dispatcher/event_dispatcher.hpp"

enum class EventType {
    NoteOn,
    NoteOff,
    ParameterChange
};

struct MidiEvent {
    EventType type;
    uint8_t note;
    uint8_t velocity;
    uint32_t timestamp;  // En samples
};

// Dispatcher
EventDispatcher<MidiEvent> dispatcher;

// Registrar listener
dispatcher.addEventListener([](const MidiEvent& event) {
    if (event.type == EventType::NoteOn) {
        startNote(event.note, event.velocity);
    }
});

// Enviar evento
dispatcher.dispatchEvent(MidiEvent{EventType::NoteOn, 60, 127, 0});

---

🛡️ 04_12 - Error Recovery

Error Handler

#include "04_12_error_recovery/error_handler.hpp"

// Reportar errores desde audio thread (RT-safe)
ErrorHandler::reportError(
    ErrorCode::BufferUnderrun,
    "Audio buffer underrun detected"
);

// Desde UI thread, recuperar errores
auto errors = ErrorHandler::getErrors();
for (const auto& error : errors) {
    logError(error.code, error.message);
}

---

📝 Ejemplo Completo: Simple Gain Plugin

#include "04_10_audio_processor/audio_processor.hpp"
#include "04_08_parameter_system/parameter.hpp"
#include "04_00_type_system/04_conversion_traits/db_conversion.hpp"

class SimpleGain : public audiolab::core::AudioProcessor {
public:
    SimpleGain()
        : AudioProcessor(ProcessorInfo{
            "Simple Gain", "AudioLab", "com.audiolab.gain", "1.0.0"
          })
        , gainParam_(
            ParameterInfo("gain", "Gain", "dB", "Amplifier"),
            ParameterRange(-60.0f, 12.0f, 0.0f),
            0.0f  // default
          )
    {}

protected:
    void on_prepare(const ProcessorConfig& config) override {
        gainParam_.set_smoothing_time(20.0f, config.sample_rate);
    }

    void on_process(
        const float* const* inputs,
        float** outputs,
        uint32_t num_samples
    ) noexcept override {
        for (uint32_t i = 0; i < num_samples; i++) {
            float gainDb = gainParam_.get_smoothed_value();  // RT-safe
            float gainLin = db_to_gain(gainDb);              // Conversión

            outputs[0][i] = inputs[0][i] * gainLin;
        }
    }

private:
    Parameter<float> gainParam_;
};

---

🔗 Cómo Usar CORE en Tu Plugin

1. Incluir headers

#include "04_CORE/04_03_memory_management/ring_buffer.hpp"
#include "04_CORE/04_08_parameter_system/parameter.hpp"
// etc.

2. Enlazar con librería (CMakeLists.txt)

target_link_libraries(my_plugin PRIVATE audiolab_core)

3. ¡Usar la API!

RingBuffer<float> delayLine;  // ← Listo para usar
Parameter<float> param;
float result = fast_sin(phase);

---

📊 Resumen de APIs por Subsistema

Subsistema	API Principal	Uso
04_00	Sample, Hertz, db_to_gain()	Tipos y conversiones
04_02	fast_sin(), fast_exp()	Matemáticas optimizadas
04_03	RingBuffer<T>, TripleBuffer<T>	Contenedores RT-safe
04_04	RT_SAFE, RT_ASSERT()	Anotaciones RT
04_05	AudioBuffer<T>	Buffers de audio
04_07	EventDispatcher<T>	Eventos
04_08	Parameter<T>	Parámetros con smoothing
04_10	AudioProcessor	Clase base para plugins
04_12	ErrorHandler	Manejo de errores

---

Esto es lo que CORE ofrece: una API completa de utilidades para construir plugins de audio profesionales sin reinventar la rueda.