Skip to content

AudioLab Core Interfaces

Core interface definitions for the AudioLab framework. This module provides the foundational abstractions for all audio components.

📁 Structure

04_01_core_interfaces/
├── 00_processing_interfaces/     # Audio/MIDI/Event processing
│   ├── iaudio_processor.hpp      # Core audio processing
│   ├── imidi_processor.hpp       # MIDI handling
│   ├── ievent_processor.hpp      # Event processing
│   └── imodulation_processor.hpp # Modulation sources
│
├── 01_lifecycle_interfaces/      # Component lifecycle
│   ├── icomponent.hpp            # Base component interface
│   ├── iactivatable.hpp          # Activation state management
│   ├── isuspendable.hpp          # Suspend/resume capability
│   └── iresettable.hpp           # Reset functionality
│
├── 02_state_interfaces/          # State management
│   ├── istateful.hpp             # State save/load
│   ├── ipresetable.hpp           # Preset management
│   ├── iserializable.hpp         # Serialization
│   └── iundoable.hpp             # Undo/redo support
│
├── 03_communication_interfaces/  # Inter-component communication
│   ├── imessageable.hpp          # Message passing (NEW)
│   └── iobservable.hpp           # Observer pattern (NEW)
│
└── 04_factory_interfaces/        # Object creation
    ├── icomponent_factory.hpp    # Component factory (NEW)
    └── icloneable.hpp            # Clone pattern (NEW)

🎯 Newly Implemented Interfaces

Communication Interfaces

IMessageable

// Message-based communication
struct Message {
    uint32_t type;
    void* data;
    uint32_t size;
};

class IMessageable {
    virtual void sendMessage(const Message& msg) = 0;
    virtual bool supportsMessageType(uint32_t type) const = 0;
};

// Usage
Message msg{MSG_PARAMETER_CHANGED, &value, sizeof(float)};
component->sendMessage(msg);

Use cases: - Parameter updates - State change notifications - Event broadcasting - Inter-component communication

IObservable / IObserver ✨ FULLY IMPLEMENTED

Thread-Safe, RT-Safe Observer Pattern with RCU

// Observer pattern for event notifications
class IObserver {
    virtual void onNotify(void* sender, uint32_t eventType, void* eventData) = 0;
};

class IObservable {
    virtual void attach(IObserver* observer) = 0;
    virtual void detach(IObserver* observer) = 0;
    virtual void notify(uint32_t eventType, void* eventData = nullptr) = 0;
};

// Concrete implementation with RCU pattern
#include "observable.hpp"

Observable observable;
MyObserver observer;

observable.attach(&observer);  // Thread-safe, may allocate
observable.notify(EVENT_VALUE_CHANGED, &newValue);  // RT-safe, no locks!
observable.detach(&observer);  // Thread-safe, may allocate
observable.collectGarbage();  // Call periodically to reclaim memory

Key Features: - ✅ Lock-free notify (RT-safe, no allocation) - ✅ Thread-safe attach/detach (uses CAS) - ✅ RCU pattern for concurrent access - ✅ Safe to detach during notification - ✅ Handles nullptr observers - ✅ Deferred deletion with grace period - ✅ Comprehensive test suite (8 tests)

Performance: - Notify: O(n) where n = observers, ~0.1-1μs per 10 observers - Attach/Detach: O(n) + allocation, uses compare-and-swap - Memory: One atomic pointer + vector per observable

Usage Example: 

#include "observable.hpp"

class ParameterObserver : public IObserver {
    void onNotify(void* sender, uint32_t eventType, void* eventData) override {
        if (eventType == EVENT_VALUE_CHANGED) {
            float* value = static_cast<float*>(eventData);
            updateUI(*value);  // Update UI with new value
        }
    }
};

// In plugin class
Observable parameterChanged;
ParameterObserver uiObserver;

// GUI thread: register observer
parameterChanged.attach(&uiObserver);

// Audio thread: notify observers (RT-safe!)
void processBlock(AudioBuffer& buffer) {
    if (parameterChanged) {
        float newValue = smoothedParameter.getValue();
        parameterChanged.notify(EVENT_VALUE_CHANGED, &newValue);
    }
    parameterChanged.collectGarbage();  // Clean up old lists
}

// GUI thread: unregister observer
parameterChanged.detach(&uiObserver);

Use cases: - Multi-listener scenarios - Decoupled event broadcasting - UI updates - State synchronization

Factory Interfaces

IComponentFactory

// Abstract factory for component creation
class IComponentFactory {
    virtual std::unique_ptr<IComponent> createComponent(ComponentID id) = 0;
    virtual bool supportsComponent(ComponentID id) const = 0;
};

// Usage
auto component = factory->createComponent(COMPONENT_REVERB);
if (component && component->initialize()) {
    // Use component
}

Use cases: - Plugin instantiation - Effect chain creation - Dynamic component loading - Dependency injection

ICloneable

// CRTP-based cloning interface
template<typename T>
class ICloneable {
    virtual std::unique_ptr<T> clone() const = 0;
    virtual std::unique_ptr<T> shallowCopy() const;
};

// Usage
class MyProcessor : public ICloneable<MyProcessor> {
    std::unique_ptr<MyProcessor> clone() const override {
        auto copy = std::make_unique<MyProcessor>();
        copy->param1_ = this->param1_;
        return copy;
    }
};

Use cases: - Component duplication - Parallel processing (one instance per thread) - State copying - Preset cloning

🔧 Build Instructions

Standalone Build

mkdir build && cd build
cmake -DAUDIOLAB_BUILD_TESTS=ON -DAUDIOLAB_BUILD_EXAMPLES=ON ..
cmake --build . --config Release
ctest

As Part of AudioLab

# In parent CMakeLists.txt
add_subdirectory(04_01_core_interfaces)

# Link to your target
target_link_libraries(my_plugin PRIVATE AudioLab::CoreInterfaces)

📋 Design Principles

1. Interface Segregation

Each interface has a single, focused responsibility: - IAudioProcessor → audio processing only - IComponent → lifecycle only - IMessageable → messaging only

2. Real-Time Safety

Interfaces designed for real-time audio: - processBlock() → no allocations, no locks - Message passing → lock-free where possible - State management → separate from processing

3. RAII & Smart Pointers

Factories return std::unique_ptr for: - Automatic cleanup - Clear ownership - Exception safety

4. Type Safety

  • Compile-time type checking
  • CRTP for clone pattern
  • Template-based where appropriate

🎨 Usage Patterns

1. Processor with State & Messaging

class MyEffect : public IAudioProcessor,
                 public IStateful,
                 public IMessageable {
public:
    void processBlock(float** channels, uint32_t numSamples, uint32_t numChannels) override {
        // Process audio
    }

    void sendMessage(const Message& msg) override {
        if (msg.type == MSG_PARAMETER_CHANGED) {
            updateParameter(msg.getDataAs<float>());
        }
    }

    bool saveState(void* dest, uint32_t& size) const override {
        // Save state
    }
};

2. Observable Component

class Parameter : public IObservable {
    std::vector<IObserver*> observers_;

public:
    void setValue(float newValue) {
        value_ = newValue;
        notify(EVENT_VALUE_CHANGED, &newValue);
    }

    void attach(IObserver* obs) override {
        observers_.push_back(obs);
    }

    void detach(IObserver* obs) override {
        observers_.erase(
            std::remove(observers_.begin(), observers_.end(), obs),
            observers_.end()
        );
    }

    void notify(uint32_t eventType, void* eventData) override {
        for (auto* obs : observers_) {
            obs->onNotify(this, eventType, eventData);
        }
    }
};

3. Factory for Plugins

class PluginFactory : public IComponentFactory {
public:
    std::unique_ptr<IComponent> createComponent(ComponentID id) override {
        switch (id) {
            case COMPONENT_REVERB:
                return std::make_unique<ReverbPlugin>();
            case COMPONENT_DELAY:
                return std::make_unique<DelayPlugin>();
            default:
                return nullptr;
        }
    }

    bool supportsComponent(ComponentID id) const override {
        return id == COMPONENT_REVERB || id == COMPONENT_DELAY;
    }
};

📊 Message & Event Types

Standard Message Types

enum MessageType : uint32_t {
    MSG_PARAMETER_CHANGED = 100,
    MSG_PARAMETER_BEGIN_GESTURE = 101,
    MSG_PARAMETER_END_GESTURE = 102,
    MSG_STATE_CHANGED = 200,
    MSG_SAMPLE_RATE_CHANGED = 300,
    MSG_BYPASS_CHANGED = 302,
    MSG_USER_BASE = 1000  // Custom messages start here
};

Standard Event Types

enum EventType : uint32_t {
    EVENT_VALUE_CHANGED = 100,
    EVENT_STATE_CHANGED = 200,
    EVENT_INITIALIZED = 302,
    EVENT_ACTIVATED = 303,
    EVENT_USER_BASE = 1000  // Custom events start here
};

Standard Component IDs

enum StandardComponentID : ComponentID {
    COMPONENT_REVERB = 0x52455642,  // 'REVB'
    COMPONENT_DELAY  = 0x444C4159,  // 'DLAY'
    COMPONENT_EQ     = 0x45512020,  // 'EQ  '
    COMPONENT_USER_BASE = 0x10000000
};

🧪 Testing

All interfaces include standalone tests (no framework required):

# Run tests
cd build
ctest --output-on-failure

# Or run directly
./tests/test_interfaces_simple

Tests cover: - Message construction and typed access - Observer attach/detach/notify - Factory creation and validation - Clone pattern and helpers

🔗 Dependencies

  • Type System (optional): For AudioBuffer<T> types in IAudioProcessor
  • C++17: For std::unique_ptr, constexpr, auto, override

📝 Notes

  • All interfaces are header-only (INTERFACE library)
  • No runtime dependencies
  • Platform-independent
  • Real-time safe design patterns
  • Extensive documentation with examples

✅ Status

Implemented: - ✅ IMessageable (message passing) - ✅ IObservable/IObserver (observer pattern) - ✅ IComponentFactory (abstract factory) - ✅ ICloneable (clone pattern) - ✅ CMake integration - ✅ Standalone tests - ✅ Documentation

Next Steps: - Fix demo compilation errors (signature mismatches with existing interfaces) - Add GTest-based unit tests - Integration examples with real plugins - Performance benchmarks for messaging

🎯 Summary

This module provides the communication and factory infrastructure for AudioLab:

  1. Message System: Type-safe, real-time safe message passing
  2. Observer Pattern: Decoupled event notifications
  3. Factory Pattern: Abstract component creation
  4. Clone Pattern: Object duplication with CRTP

All designed for real-time audio processing with zero-overhead abstractions.