OfflineProcessing.h

// DSPark - Professional Audio DSP Framework
// Copyright (c) 2026 Cristian Moresi - MIT License
 
#pragma once
 
#if !defined(DSPARK_NO_OFFLINE) && (defined(__cpp_exceptions) || defined(_CPPUNWIND))
#define DSPARK_HAS_OFFLINE 1
#else
#define DSPARK_HAS_OFFLINE 0
#endif
 
#if DSPARK_HAS_OFFLINE
 
#include "AudioBuffer.h"
#include "DspMath.h"
 
#include <algorithm>
#include <array>
#include <atomic>
#include <bit>
#include <cmath>
#include <cstddef>
#include <cstdint>
#include <cstring>
#include <limits>
#include <memory>
#include <memory_resource>
#include <new>
#include <type_traits>
 
namespace dspark
{
 
enum class OfflineStatus : std::uint8_t
{
    Success,
    NoChange,
    EmptyInput,
    InvalidInput,
    UnsupportedLayout,
    NonFiniteInput,
    SourceMismatch,
    SourceReadFailed,
    SinkFailed,
    CallbackFailed,
    Cancelled,
    MemoryLimit,
    AllocationFailure,
    NumericalFailure,
    TargetUnreachable 
};
 
[[nodiscard]] inline bool offlineSucceeded(OfflineStatus status) noexcept
{
    return status == OfflineStatus::Success || status == OfflineStatus::NoChange;
}
 
struct OfflineAudioSpec
{
    double sampleRate = 48000;
    int channels = 0;
    std::int64_t frames = 0;
    std::uint64_t sourceId = 0;
    std::uint64_t revision = 0;
    std::int64_t timelineOrigin = 0; 
 
    [[nodiscard]] bool isValid() const noexcept
    {
        return std::isfinite(sampleRate) && sampleRate >= 1 &&
               sampleRate <= static_cast<double>(std::numeric_limits<int>::max()) && channels > 0 &&
               channels <= 16 && frames >= 0 && timelineOrigin >= 0 &&
               frames <= std::numeric_limits<std::int64_t>::max() - timelineOrigin;
    }
    bool operator==(const OfflineAudioSpec &) const noexcept = default;
};
 
struct OfflineRegion
{
    std::int64_t begin = 0;
    std::int64_t end = 0;
    bool operator==(const OfflineRegion &) const noexcept = default;
};
 
enum class OfflinePhase : std::uint8_t
{
    Analyze,
    Plan,
    Verify,
    Render
};
 
struct OfflineProgress
{
    OfflinePhase phase = OfflinePhase::Analyze;
    std::int64_t completed = 0;
    std::int64_t total = 0;
};
 
struct OfflineJobOptions
{
    int blockFrames = 4096;
    std::size_t memoryBudgetBytes = 256u * 1024u * 1024u;
    const std::atomic<bool> *cancel = nullptr;
    void *progressContext = nullptr;
    bool (*progress)(void *, OfflineProgress) = nullptr; 
};
 
struct OfflineGainRenderInfo
{
    bool bandlimited = false; 
    bool targetFeasible = true; 
    bool representabilityLimited = false; 
    bool boundaryCalibrated = false; 
    double deltaScale = 1; 
    double boundaryGain = 1; 
    double leftBoundaryGain = 1; 
    double rightBoundaryGain = 1; 
    double minimumControlGain = 1; 
    double maximumControlGain = 1; 
};
 
template <FloatType T> class OfflineAudioSource
{
  public:
    virtual ~OfflineAudioSource() = default;
    [[nodiscard]] virtual OfflineAudioSpec getSpec() const noexcept = 0;
    virtual bool read(std::int64_t first, AudioBufferView<T> destination) = 0;
};
 
template <FloatType T, int MaxChannels = 16>
class OfflineBufferSource final : public OfflineAudioSource<T>
{
  public:
    OfflineBufferSource(AudioBufferView<const T, MaxChannels> audio, double sampleRate,
                        std::uint64_t sourceId = 0, std::uint64_t revision = 0,
                        std::int64_t timelineOrigin = 0) noexcept
        : audio_(audio), spec_{sampleRate, audio.getNumChannels(), audio.getNumSamples(), sourceId,
                               revision,   timelineOrigin}
    {
    }
 
    [[nodiscard]] OfflineAudioSpec getSpec() const noexcept override
    {
        return spec_;
    }
    bool read(std::int64_t first, AudioBufferView<T> destination) override
    {
        const int count = destination.getNumSamples();
        if (first < 0 || count < 0 || count > spec_.frames || first > spec_.frames - count ||
            destination.getNumChannels() != spec_.channels)
            return false;
        for (int ch = 0; ch < spec_.channels; ++ch)
        {
            if (count == 0)
                continue;
            if (!audio_.getChannel(ch) || !destination.getChannel(ch))
                return false;
            std::memmove(destination.getChannel(ch), audio_.getChannel(ch) + first,
                         static_cast<std::size_t>(count) * sizeof(T));
        }
        return true;
    }
 
  private:
    AudioBufferView<const T, MaxChannels> audio_;
    OfflineAudioSpec spec_;
};
 
template <FloatType T> class OfflineAudioSink
{
  public:
    virtual ~OfflineAudioSink() = default;
    virtual bool begin(const OfflineAudioSpec &spec) = 0;
    virtual bool write(std::int64_t first, AudioBufferView<const T> block) = 0;
    virtual bool commit() = 0;
    virtual void abort() noexcept = 0;
};
 
struct OfflineFingerprint
{
    std::uint64_t first = 14695981039346656037ull;
    std::uint64_t second = 0x9e3779b97f4a7c15ull;
    bool operator==(const OfflineFingerprint &) const noexcept = default;
};
 
namespace detail
{
 
struct OfflineFailure
{
    OfflineStatus status;
};
 
[[noreturn]] inline void offlineFail(OfflineStatus status)
{
    throw OfflineFailure{status};
}
 
// Called only inside a catch block. Transport and callback failures are translated
// at their boundary; an otherwise unexpected internal error is numerical failure.
[[nodiscard]] inline OfflineStatus offlineExceptionStatus() noexcept
{
    try
    {
        throw;
    }
    catch (const OfflineFailure &failure)
    {
        return failure.status;
    }
    catch (const std::bad_alloc &)
    {
        return OfflineStatus::AllocationFailure;
    }
    catch (...)
    {
        return OfflineStatus::NumericalFailure;
    }
}
 
[[nodiscard]] inline std::size_t offlineBytes(std::uint64_t count, std::size_t size)
{
    if (count > std::numeric_limits<std::size_t>::max() / size)
        offlineFail(OfflineStatus::MemoryLimit);
    return static_cast<std::size_t>(count) * size;
}
 
template <typename T> struct OfflineScratchDeleter
{
    std::pmr::memory_resource *resource = nullptr;
    std::size_t count = 0;
    void operator()(T *pointer) const noexcept
    {
        if (resource)
        {
            std::destroy_n(pointer, count);
            resource->deallocate(pointer, count * sizeof(T), alignof(T));
        }
        else
            delete[] pointer;
    }
};
template <typename T>
using OfflineScratchArray = std::unique_ptr<T[], OfflineScratchDeleter<T>>;
 
class OfflineSession final
{
  public:
    explicit OfflineSession(const OfflineJobOptions &options) : options_(options)
    {
        if (options.blockFrames < 1)
            offlineFail(OfflineStatus::InvalidInput);
    }
    void charge(std::size_t bytes)
    {
        if (bytes > options_.memoryBudgetBytes - bytes_)
            offlineFail(OfflineStatus::MemoryLimit);
        bytes_ += bytes;
    }
    template <typename U> [[nodiscard]] std::unique_ptr<U[]> allocate(std::uint64_t count)
    {
        charge(offlineBytes(count, sizeof(U)));
        return std::make_unique<U[]>(static_cast<std::size_t>(count));
    }
    // A resource accounts for every upstream request itself and must outlive
    // its scratch arrays. Without one, allocation preserves the original path.
    void useScratchResource(std::pmr::memory_resource &resource) noexcept
    {
        scratch_ = &resource;
    }
    template <typename U> [[nodiscard]] OfflineScratchArray<U> allocateScratch(std::uint64_t count)
    {
        if (!scratch_)
            return {allocate<U>(count).release(), {}};
        const auto bytes = offlineBytes(count, sizeof(U));
        auto *data = static_cast<U *>(scratch_->allocate(bytes, alignof(U)));
        try
        {
            std::uninitialized_value_construct_n(data, static_cast<std::size_t>(count));
        }
        catch (...)
        {
            scratch_->deallocate(data, bytes, alignof(U));
            throw;
        }
        return {data, {scratch_, static_cast<std::size_t>(count)}};
    }
    [[nodiscard]] std::size_t bytes() const noexcept
    {
        return bytes_;
    }
    void checkpoint(OfflinePhase phase, std::int64_t completed, std::int64_t total) const
    {
        if (options_.cancel && options_.cancel->load(std::memory_order_relaxed))
            offlineFail(OfflineStatus::Cancelled);
        if (options_.progress)
        {
            bool proceed = false;
            try
            {
                proceed = options_.progress(options_.progressContext, {phase, completed, total});
            }
            catch (...)
            {
                offlineFail(OfflineStatus::CallbackFailed);
            }
            if (!proceed)
                offlineFail(OfflineStatus::Cancelled);
        }
    }
 
  private:
    const OfflineJobOptions &options_;
    std::size_t bytes_ = 0;
    std::pmr::memory_resource *scratch_ = nullptr;
};
 
// Reuses released scratch blocks without refunding the cumulative job budget.
// Both backing storage and pool metadata are charged before each new request.
// Power-of-two capacity preserves the tempo worker's growth policy; exact
// capacity avoids rounding large projection maps when only geometry changes.
class OfflineMemoryPool final : public std::pmr::memory_resource
{
  public:
    explicit OfflineMemoryPool(OfflineSession &job, bool roundCapacity = true)
        : job_(job), roundCapacity_(roundCapacity) {}
    OfflineMemoryPool(const OfflineMemoryPool &) = delete;
    OfflineMemoryPool &operator=(const OfflineMemoryPool &) = delete;
    ~OfflineMemoryPool() override
    {
        while (blocks_)
        {
            auto *block = blocks_;
            blocks_ = block->next;
            if (block->alignment > alignof(std::max_align_t))
                ::operator delete(block, std::align_val_t{block->alignment});
            else
                ::operator delete(block);
        }
    }
  private:
    struct alignas(std::max_align_t) Block
    {
        Block *next;
        void *data;
        std::size_t capacity, alignment;
        bool available;
    };
    void *do_allocate(std::size_t bytes, std::size_t alignment) override
    {
        Block *best = nullptr;
        for (auto *b = blocks_; b; b = b->next)
            if (b->available && b->capacity >= bytes && b->alignment >= alignment &&
                (!best || b->capacity < best->capacity))
                best = b;
        if (best)
        {
            best->available = false;
            return best->data;
        }
        std::size_t capacity = roundCapacity_ ? 1 : std::max(std::size_t(1), bytes);
        while (capacity < bytes)
        {
            if (capacity > std::numeric_limits<std::size_t>::max() / 2)
                offlineFail(OfflineStatus::MemoryLimit);
            capacity *= 2;
        }
        alignment = std::max(alignment, alignof(Block));
        if (alignment > std::numeric_limits<std::size_t>::max() - sizeof(Block))
            offlineFail(OfflineStatus::MemoryLimit);
        const auto offset = (sizeof(Block) + alignment - 1) / alignment * alignment;
        if (capacity > std::numeric_limits<std::size_t>::max() - offset)
            offlineFail(OfflineStatus::MemoryLimit);
        const auto total = offset + capacity;
        job_.charge(total);
        void *raw = alignment > alignof(std::max_align_t)
                        ? ::operator new(total, std::align_val_t{alignment}) : ::operator new(total);
        auto *block = new (raw) Block{blocks_, static_cast<std::byte *>(raw) + offset,
                                     capacity, alignment, false};
        blocks_ = block;
        return block->data;
    }
    void do_deallocate(void *p, std::size_t, std::size_t) override
    {
        for (auto *b = blocks_; b; b = b->next)
            if (b->data == p)
            {
                b->available = true;
                return;
            }
    }
    bool do_is_equal(const std::pmr::memory_resource &other) const noexcept override
    {
        return this == &other;
    }
    OfflineSession &job_;
    bool roundCapacity_;
    Block *blocks_ = nullptr;
};
 
[[nodiscard]] inline OfflineJobOptions offlineRemaining(const OfflineJobOptions &job,
                                                        std::size_t used)
{
    if (used > job.memoryBudgetBytes)
        offlineFail(OfflineStatus::MemoryLimit);
    auto out = job;
    out.memoryBudgetBytes -= used;
    return out;
}
 
inline void offlineValidateSpec(const OfflineAudioSpec &spec, int maximumChannels = 16)
{
    if (!spec.isValid())
        offlineFail(OfflineStatus::InvalidInput);
    if (spec.channels > maximumChannels)
        offlineFail(OfflineStatus::UnsupportedLayout);
    if (spec.frames == 0)
        offlineFail(OfflineStatus::EmptyInput);
}
 
template <FloatType T> class OfflineBlock final
{
  public:
    OfflineBlock(OfflineSession &session, const OfflineAudioSpec &spec, int blockFrames)
        : frames_(static_cast<int>(std::min<std::int64_t>(spec.frames, blockFrames))),
          channels_(spec.channels),
          data_(session.allocate<T>(static_cast<std::uint64_t>(frames_) * channels_))
    {
    }
    [[nodiscard]] AudioBufferView<T> view(int count) noexcept
    {
        std::array<T *, 16> pointers{};
        for (int c = 0; c < channels_; ++c)
            pointers[static_cast<std::size_t>(c)] =
                data_.get() + static_cast<std::size_t>(c) * frames_;
        return {pointers.data(), channels_, count};
    }
    [[nodiscard]] int frames() const noexcept
    {
        return frames_;
    }
 
  private:
    int frames_, channels_;
    std::unique_ptr<T[]> data_;
};
 
template <FloatType T>
inline void offlineRead(OfflineAudioSource<T> &source, const OfflineAudioSpec &expected,
                        std::int64_t first, AudioBufferView<T> block)
{
    if (source.getSpec() != expected)
        offlineFail(OfflineStatus::SourceMismatch);
    bool ok = false;
    try
    {
        ok = source.read(first, block);
    }
    catch (...)
    {
        offlineFail(OfflineStatus::SourceReadFailed);
    }
    if (!ok)
        offlineFail(OfflineStatus::SourceReadFailed);
    if (source.getSpec() != expected)
        offlineFail(OfflineStatus::SourceMismatch);
}
 
template <FloatType T> inline void offlineHash(OfflineFingerprint &state, T sample) noexcept
{
    static_assert(std::is_same_v<T, float> || std::is_same_v<T, double>,
                  "Offline PCM supports float and double");
    const std::uint64_t word = [&] {
        if constexpr (sizeof(T) == 4)
            return static_cast<std::uint64_t>(std::bit_cast<std::uint32_t>(sample));
        else
            return std::bit_cast<std::uint64_t>(sample);
    }();
    state.first = (state.first ^ word) * 1099511628211ull;
    state.second =
        std::rotl(state.second ^ word, 27) * 0x3c79ac492ba7b653ull + 0x1c69b3f74ac4ae35ull;
}
 
} // namespace detail
} // namespace dspark
 
#endif // DSPARK_HAS_OFFLINE