device.hpp

Go to the documentation of this file.

#pragma once
 
#include <pulp/audio/audio_io_timing.hpp>
#include <pulp/audio/buffer.hpp>
#include <cstdint>
#include <functional>
#include <memory>
#include <mutex>
#include <optional>
#include <string>
#include <utility>
#include <vector>
 
namespace pulp::audio {
 
// Information about an audio device
struct DeviceInfo {
    std::string id;              // Platform-specific unique ID
    std::string name;            // Human-readable name
    int max_input_channels = 0;
    int max_output_channels = 0;
    std::vector<double> sample_rates;  // Supported sample rates
    std::vector<int> buffer_sizes;     // Supported buffer sizes
    bool is_default_input = false;
    bool is_default_output = false;
};
 
// WASAPI (Windows) sharing model. `shared` routes through the system audio
// engine (default — coexists with other apps); `exclusive` takes sole ownership
// of the endpoint for lower latency. Non-Windows backends (CoreAudio / ALSA /
// JACK) ignore this and always use their native path.
enum class ShareMode { shared, exclusive };
 
// Configuration for opening a device
struct DeviceConfig {
    std::string device_id;       // Empty = default device
    double sample_rate = 48000.0;
    int buffer_size = 256;
    int input_channels = 0;
    int output_channels = 2;
    ShareMode share_mode = ShareMode::shared;  // Windows WASAPI only; see above
 
    // Windows WASAPI only: opt into the shared-mode low-latency path
    // (IAudioClient3::InitializeSharedAudioStream at the engine's minimum
    // period). Only honored when `share_mode == ShareMode::shared`; ignored
    // in exclusive mode (which already drives at the device minimum period)
    // and on every non-Windows backend. Defaults false so existing callers
    // and other backends are unaffected. If IAudioClient3 is unavailable or
    // the low-latency init fails, the backend honestly degrades to the
    // standard shared-mode Initialize at the requested buffer size.
    bool low_latency = false;
};
 
// Audio callback context — passed to the render function
struct CallbackContext {
    double sample_rate = 0;
    int buffer_size = 0;
    uint64_t sample_position = 0;  // Running sample count
};
 
// The audio callback: receives input, fills output
// Called on the real-time audio thread — no allocation, no locks, no blocking.
using AudioCallback = std::function<void(
    const BufferView<const float>& input,
    BufferView<float>& output,
    const CallbackContext& context
)>;
 
// Abstract audio device interface
class AudioDevice {
public:
    using WorkgroupChangeCallback = std::function<void(void* workgroup)>;
 
    virtual ~AudioDevice() = default;
 
    virtual bool open(const DeviceConfig& config) = 0;
    virtual void close() = 0;
    virtual bool start(AudioCallback callback) = 0;
    virtual void stop() = 0;
 
    virtual bool is_open() const = 0;
    virtual bool is_running() const = 0;
    virtual DeviceInfo info() const = 0;
    virtual double sample_rate() const = 0;
    virtual int buffer_size() const = 0;

    virtual void* callback_workgroup() const { return nullptr; }

    virtual std::uint64_t xrun_count() const { return 0; }

    virtual void reset_xrun_counter() {}

    virtual void set_workgroup_change_callback(WorkgroupChangeCallback callback) {
        if (callback) callback(callback_workgroup());
    }

    virtual void quiesce_workgroup_changes() {}
};

std::optional<AudioIoTiming> query_audio_io_timing(
    const AudioDevice& device) noexcept;
 
// Audio system — enumerates devices and creates device instances
class AudioSystem {
public:
    virtual ~AudioSystem() = default;
 
    virtual std::vector<DeviceInfo> enumerate_devices() = 0;
    virtual std::unique_ptr<AudioDevice> create_device(const std::string& device_id = "") = 0;
    virtual DeviceInfo default_output_device() = 0;
    virtual DeviceInfo default_input_device() = 0;

    using DeviceChangeCallback = std::function<void()>;

    virtual void set_device_change_callback(DeviceChangeCallback cb) {
        std::lock_guard<std::mutex> lock(device_change_callback_mutex_);
        if (cb) {
            device_change_callback_ = std::make_shared<DeviceChangeCallback>(std::move(cb));
        } else {
            device_change_callback_.reset();
        }
    }

    void fire_device_change() {
        std::shared_ptr<DeviceChangeCallback> callback;
        {
            std::lock_guard<std::mutex> lock(device_change_callback_mutex_);
            callback = device_change_callback_;
        }
        if (callback && *callback) (*callback)();
    }

    bool has_device_change_callback() const {
        std::lock_guard<std::mutex> lock(device_change_callback_mutex_);
        return static_cast<bool>(device_change_callback_ && *device_change_callback_);
    }
 
private:
    mutable std::mutex device_change_callback_mutex_;
    std::shared_ptr<DeviceChangeCallback> device_change_callback_;
};
 
// Create the platform-appropriate audio system
std::unique_ptr<AudioSystem> create_audio_system();
 
} // namespace pulp::audio