offline_processor.hpp

Go to the documentation of this file.

#pragma once
 
// Offline audio processing — render an entire file through a processor chain.
// Useful for batch processing, bouncing, and golden-file test generation.
 
#include <pulp/audio/audio_file.hpp>
#include <functional>
#include <string>
#include <optional>
#include <vector>
#include <cstdint>
 
namespace pulp::audio {

using OfflineProcessCallback = std::function<void(
    const float* input, float* output,
    int channels, int block_size, double sample_rate
)>;

struct OfflineRenderBlockContext {
    uint64_t block_index = 0;
    uint64_t sample_position = 0;
    int frames = 0;
    int scheduled_block_size = 0;
    double sample_rate = 0.0;
    double time_seconds = 0.0;
    double position_beats = 0.0;
    double tempo_bpm = 120.0;
    double render_speed_ratio = 1.0;
    uint64_t state_generation = 0;
    uint64_t deterministic_seed = 0;
};
 
enum class OfflineRenderTailPolicy : uint8_t {
    Truncate = 0,
    RenderTail,
};
 
enum class OfflineRenderExecutionScope : uint8_t {
    RealtimeAudioThread = 0,
    OfflineAnalysis,
    BackgroundAnalysis,
};
 
enum class OfflineRenderComputeBackend : uint8_t {
    Cpu = 0,
    Gpu,
};
 
struct OfflineRenderComputePolicy {
    OfflineRenderExecutionScope scope = OfflineRenderExecutionScope::OfflineAnalysis;
    OfflineRenderComputeBackend requested_backend = OfflineRenderComputeBackend::Cpu;
    bool gpu_available = false;
    bool allow_cpu_fallback = true;
};
 
struct OfflineRenderComputeDecision {
    bool accepted = false;
    OfflineRenderComputeBackend backend = OfflineRenderComputeBackend::Cpu;
    bool used_cpu_fallback = false;
    const char* reason = "";
 
    bool uses_gpu() const noexcept {
        return accepted && backend == OfflineRenderComputeBackend::Gpu;
    }
};
 
struct OfflineRenderResourceRef {
    std::string id;
    std::string path;
    std::string content_sha256;
    std::string cache_key;
    uint64_t generation = 0;
    uint64_t decoded_bytes = 0;
    bool required = true;
    bool staged = true;
};

struct OfflineRenderOptions {
    int fallback_block_size = 512;
    std::vector<int> block_size_schedule;
    uint64_t start_sample_position = 0;
    double start_position_beats = 0.0;
    double tempo_bpm = 120.0;
    double render_speed_ratio = 1.0;
    uint64_t state_generation = 0;
    uint64_t deterministic_seed = 0;
    OfflineRenderTailPolicy tail_policy = OfflineRenderTailPolicy::Truncate;
    uint64_t tail_frames = 0;
    std::vector<OfflineRenderResourceRef> resources;
};
 
struct OfflineRenderStem {
    std::string name;
    uint32_t first_channel = 0;
    uint32_t channel_count = 0;
};
 
struct OfflineRenderedStem {
    std::string name;
    AudioFileData audio;
};
 
struct OfflineRenderStemResult {
    AudioFileData mix;
    std::vector<OfflineRenderedStem> stems;
};
 
struct OfflineRenderComparison {
    uint32_t channels = 0;
    uint64_t frames = 0;
    float peak_error = 0.0f;
    double rms_error = 0.0;
 
    bool passes(float peak_tolerance, double rms_tolerance) const noexcept;
};
 
struct OfflineRenderManifestChunk {
    uint64_t start_frame = 0;
    uint64_t frame_count = 0;
    int scheduled_block_size = 0;
};
 
struct OfflineRenderArtifactManifest {
    uint32_t format_version = 1;
    uint32_t sample_rate = 0;
    uint32_t channels = 0;
    uint64_t frames = 0;
    std::string audio_sha256;
    std::string render_plan_sha256;
    uint64_t start_sample_position = 0;
    double start_position_beats = 0.0;
    double tempo_bpm = 120.0;
    double render_speed_ratio = 1.0;
    uint64_t state_generation = 0;
    uint64_t deterministic_seed = 0;
    OfflineRenderTailPolicy tail_policy = OfflineRenderTailPolicy::Truncate;
    uint64_t tail_frames = 0;
    std::vector<int> block_size_schedule;
    std::vector<OfflineRenderResourceRef> resources;
    std::vector<OfflineRenderManifestChunk> chunks;
    std::string resource_set_sha256;
    bool cache_reusable = true;
    uint32_t missing_optional_resources = 0;
 
    bool matches_audio(const AudioFileData& audio) const noexcept;
};

using OfflineRenderCallback = std::function<void(
    const float* input, float* output,
    int channels, const OfflineRenderBlockContext& context
)>;

std::optional<AudioFileData> offline_render(
    const AudioFileData& input,
    OfflineRenderCallback render_fn,
    const OfflineRenderOptions& options = {}
);

std::optional<OfflineRenderStemResult> offline_render_stems(
    const AudioFileData& input,
    OfflineRenderCallback render_fn,
    const OfflineRenderOptions& options,
    const std::vector<OfflineRenderStem>& stems
);

std::optional<OfflineRenderComparison> compare_offline_render_audio(
    const AudioFileData& actual,
    const AudioFileData& expected
);

std::optional<std::string> offline_render_audio_sha256(
    const AudioFileData& audio
);

std::optional<OfflineRenderArtifactManifest> create_offline_render_manifest(
    const AudioFileData& rendered_audio,
    const OfflineRenderOptions& options = {}
);

OfflineRenderComputeDecision evaluate_offline_render_compute_policy(
    const OfflineRenderComputePolicy& policy
);

std::optional<AudioFileData> offline_process(
    const AudioFileData& input,
    OfflineProcessCallback process_fn,
    int block_size = 512
);

bool offline_process_file(
    const std::string& input_path,
    const std::string& output_path,
    OfflineProcessCallback process_fn,
    int block_size = 512
);

AudioFileData apply_gain(const AudioFileData& input, float gain_linear);
 
}  // namespace pulp::audio