timeline_offline_renderer.hpp

Go to the documentation of this file.

#pragma once
 
// One-shot transport-aware offline renderer for a prepared Timeline graph.
//
// WHY THIS EXISTS AND WHY IT IS NOT OfflineSignalGraphHost.
//
// OfflineSignalGraphHost deliberately drives the *no-transport*
// SignalGraph::process() overload: its whole contract is "block partitioning is
// the only difference between online and offline", which requires that nodes
// receive nothing else that varies. Timeline graph nodes are the opposite case
// — TimelineGraphPlaybackBinding::process() needs the exact block and transport
// state for that block, because note scheduling, automation evaluation and PDC
// all read it. Driving a Timeline slice through the legacy offline host does not
// fail loudly; it renders silence. So this is a separate renderer whose block
// loop is MasterTransport::begin_block() -> TimelineGraphPlaybackBinding::
// process(). OfflineSignalGraphHost and core/playback are unchanged.
//
// The renderer is one-shot and fail-closed: it either returns a complete render
// or a status and no audio. There is no partial success, because a truncated
// bounce that looks like a short file is the failure mode this is meant to make
// impossible.
//
// Bounds are authored in ticks and derived to samples ONLY through the program's
// own compiled tempo map, so a tempo change inside the region is honoured
// exactly rather than approximated from a nominal rate.
 
#include <pulp/audio/audio_file.hpp>
#include <pulp/host/timeline_graph_binding.hpp>
#include <pulp/playback/program.hpp>
#include <pulp/playback/transport.hpp>
#include <pulp/timebase/compiled_tempo_map.hpp>
 
#include <cstdint>
#include <span>
 
namespace pulp::host {

enum class TimelineOfflineRenderCode : std::uint8_t {
    Ok = 0,
    InvalidRange,
    InvalidLimits,
    SampleRateMismatch,
    InvalidProgram,
    BindingRejected,
    TransportRejected,
    ProcessFailed,
};

struct TimelineOfflineRenderConfig {
    double sample_rate = 0.0;
    int block_frames = 0;
    int output_channels = 0;
    std::uint64_t max_output_frames = 0;
    std::uint32_t maximum_note_events_per_track_per_block = 256;
};

struct TimelineOfflineRenderOptions {
    timebase::TickPosition start_tick{0};
    timebase::TickPosition end_tick{0};
    std::uint32_t tail_frames = 0;
};

struct TimelineOfflineRenderResult {
    TimelineOfflineRenderCode code = TimelineOfflineRenderCode::Ok;
    audio::AudioFileData audio;
    std::uint64_t region_frames = 0;
    std::uint64_t tail_frames = 0;
    TimelineGraphAdmission admission{};
    TimelineGraphProcessResult process{};
    playback::TransportError transport_error = playback::TransportError::None;
 
    constexpr explicit operator bool() const noexcept {
        return code == TimelineOfflineRenderCode::Ok;
    }
};

TimelineOfflineRenderResult render_timeline_offline(
    SignalGraph& graph, TimelineGraphPlaybackBinding& binding,
    const playback::PlaybackProgram& program,
    std::span<const TimelineTrackGraphRoute> routes,
    const TimelineOfflineRenderConfig& config,
    const TimelineOfflineRenderOptions& options);
 
} // namespace pulp::host