transport.hpp

Go to the documentation of this file.

#pragma once
 
#include <pulp/audio/rt_safety_contract.hpp>
#include <pulp/playback/tempo_sync.hpp>
#include <pulp/runtime/seqlock.hpp>
#include <pulp/timebase/compiled_meter_map.hpp>
#include <pulp/timebase/compiled_tempo_map.hpp>
#include <pulp/timebase/loop_region.hpp>
 
#include <array>
#include <cstdint>
#include <type_traits>
 
namespace pulp::playback {
 
enum class TransportError {
    None,
    NotPrepared,
    InvalidMeter,
    InvalidLoop,
    LoopTooShortForMaximumBlock,
    InvalidFrameCount,
    InvalidScrubWindow,
    ScrubWindowTooShortForMaximumBlock,
    NotScrubbing,
    InvalidTempo,
    InvalidTempoSyncConfig,
    TempoSyncHostTimeRequired,
    TempoSyncUnavailable,
    InvalidTempoSyncState,
    PlaybackEpochExhausted,
};
 
namespace detail {
TransportError advance_playback_epoch(std::uint64_t& epoch) noexcept;
}
 
using MeterSignature = timebase::MeterSignature;
using LoopRegion = timebase::LoopRegion;
 
struct TransportRange {
    std::uint32_t sample_offset = 0;
    std::uint32_t frame_count = 0;
    timebase::SamplePosition timeline_sample_start{};
    timebase::TickPosition timeline_tick_start{};
    timebase::TickPosition timeline_tick_end{};
    timebase::MonotonicBeat monotonic_start{};
    timebase::MonotonicBeat monotonic_end{};
    timebase::BarPosition bar_start{};
    double tempo_bpm = 120.0;
    bool tempo_changed = false;
    bool discontinuity = false;
    bool host_beat_mapping = false;
    double host_tick_start = 0.0;
    double host_tick_end = 0.0;
    bool has_precise_host_ticks = false;
    std::uint64_t playback_epoch = 0;
    std::uint64_t loop_pass_index = 0;
};
 
struct TransportSnapshot {
    const timebase::CompiledTempoMap* tempo_map = nullptr;
    timebase::RationalRate sample_rate{};
    std::uint64_t block_index = 0;
    std::uint64_t playback_epoch = 0;
    std::uint32_t frame_count = 0;
    MeterSignature meter{};
    LoopRegion loop{};
    bool is_playing = false;
    bool scrubbing = false;
    bool transport_changed = false;
    bool transport_started = false;
    bool reset_requested = false;
    bool time_sig_changed = false;
    double tempo_bpm = 120.0;
    std::array<TransportRange, 2> ranges{};
    std::uint8_t range_count = 0;
    double host_loop_start_beats = 0.0;
    double host_loop_end_beats = 0.0;
    bool has_precise_host_loop = false;
};

struct TransportPlayhead {
    std::uint64_t sequence = 0;
    std::uint64_t playback_epoch = 0;
    timebase::TickPosition position{};
    LoopRegion loop{};
    double tempo_bpm = 120.0;
    bool is_playing = false;
    bool scrubbing = false;
 
    constexpr bool operator==(const TransportPlayhead&) const = default;
};

struct TransportLoopState {
    std::uint64_t sequence = 0;
    LoopRegion loop{};
    bool prepared = false;
 
    constexpr bool operator==(const TransportLoopState&) const = default;
};
 
static_assert(std::is_trivially_copyable_v<TransportPlayhead>);
static_assert(std::is_trivially_copyable_v<TransportLoopState>);

bool valid_transport_ranges(const TransportSnapshot& transport) noexcept;

long double
host_mapped_document_sample_at_output_offset(const TransportRange& range,
                                             const timebase::CompiledTempoMap& tempo_map,
                                             std::uint32_t output_offset) noexcept;

bool host_mapped_output_offset_for_tick(const TransportRange& range,
                                        timebase::TickPosition document_tick,
                                        std::uint32_t& output_offset) noexcept;
 
struct MasterTransportConfig {
    std::uint32_t max_buffer_size = 0;
    MeterSignature meter{};
    LoopRegion loop{};
    timebase::TickPosition initial_position{};
    bool initially_playing = false;
    TempoSyncSource* tempo_sync_source = nullptr;
    double tempo_sync_quantum_beats = 4.0;
};

class MasterTransport {
  public:
    static constexpr audio::RtSafetyClass begin_block_rt_safety_class =
        audio::RtSafetyClass::AudioCallbackSafeAfterPrepare;
 
    MasterTransport() = default;

    TransportError prepare(const timebase::CompiledTempoMap& tempo_map,
                           const MasterTransportConfig& config) noexcept;
    TransportError set_playing(bool playing) noexcept;
    TransportError set_tempo_sync_tempo(double tempo_bpm) noexcept;
    TransportError seek(timebase::TickPosition position) noexcept;
    TransportError set_loop(LoopRegion loop) noexcept;
    TransportError set_meter(MeterSignature meter) noexcept;

    TransportError begin_scrub(std::uint32_t window_frames,
                               timebase::TickPosition position) noexcept;
    TransportError scrub_to(timebase::TickPosition position) noexcept;
    TransportError end_scrub() noexcept;
 
    TransportError begin_block(std::uint32_t frame_count, TransportSnapshot& snapshot) noexcept;
    TransportError begin_block(std::uint32_t frame_count, TempoSyncHostTime output_host_time,
                               TransportSnapshot& snapshot) noexcept;

    TransportPlayhead playhead() const noexcept { return playhead_.read(); }

    TransportLoopState loop_state() const noexcept {
        const auto desired = desired_.read();
        return {
            .sequence = desired.loop_sequence, .loop = desired.loop, .prepared = desired.prepared};
    }
 
    void reset() noexcept;
 
  private:
    struct BlockProjection;
    struct RangeProjection;
    struct DesiredState {
        MeterSignature meter{};
        LoopRegion loop{};
        timebase::TickPosition position{};
        timebase::TickPosition scrub_position{};
        std::uint32_t scrub_window_frames = 0;
        bool playing = false;
        bool scrubbing = false;
        bool prepared = false;
        std::uint64_t loop_sequence = 0;
        std::uint64_t seek_generation = 0;
        std::uint64_t scrub_generation = 0;
        std::uint64_t playing_generation = 0;
        std::uint64_t tempo_sync_tempo_generation = 0;
        double tempo_sync_tempo_bpm = 120.0;
    };
 
    static_assert(std::is_trivially_copyable_v<DesiredState>);
 
    TransportError validate_loop(LoopRegion loop) const noexcept;
    void publish_desired() noexcept;
    TransportError begin_internal_block(std::uint32_t frame_count,
                                        TransportSnapshot& snapshot) noexcept;
    TransportError begin_tempo_synced_block(std::uint32_t frame_count,
                                            std::int64_t output_host_time_micros,
                                            TransportSnapshot& snapshot) noexcept;
    void begin_projected_block(const DesiredState& desired, const BlockProjection& projection,
                               timebase::TickPosition anchor_tick,
                               TransportSnapshot& snapshot) noexcept;
    void append_projected_range(const RangeProjection& projection,
                                TransportSnapshot& snapshot) noexcept;
    void finish_projected_block(const DesiredState& desired, const BlockProjection& projection,
                                TransportSnapshot& snapshot) noexcept;
    void publish_playhead(TransportPlayhead reading) noexcept;
 
    runtime::SeqLock<DesiredState> desired_{};
    runtime::SeqLock<TransportPlayhead> playhead_{};
    std::uint64_t loop_sequence_ = 0;
    std::uint64_t playhead_sequence_ = 0;
    DesiredState control_state_{};
    const timebase::CompiledTempoMap* tempo_map_ = nullptr;
    timebase::TempoCursor tempo_cursor_{};
    TempoSyncSource* tempo_sync_source_ = nullptr;
    double tempo_sync_quantum_beats_ = 4.0;
    std::uint32_t max_buffer_size_ = 0;
 
    timebase::SamplePosition timeline_sample_{};
    timebase::TickPosition timeline_tick_{};
    timebase::MonotonicBeat monotonic_{};
    timebase::TickPosition meter_anchor_tick_{};
    timebase::BarPosition meter_anchor_bar_{};
    MeterSignature meter_anchor_signature_{};
    std::uint64_t applied_seek_generation_ = 0;
    std::uint64_t applied_scrub_generation_ = 0;
    std::uint64_t applied_tempo_sync_playing_generation_ = 0;
    std::uint64_t applied_tempo_sync_seek_generation_ = 0;
    std::uint64_t applied_tempo_sync_tempo_generation_ = 0;
    std::uint64_t block_index_ = 0;
    std::uint64_t playback_epoch_ = 0;
    bool playback_epoch_exhausted_ = false;
    std::uint64_t loop_pass_index_ = 0;
    std::uint32_t scrub_window_remaining_ = 0;
    bool previous_scrubbing_ = false;
    bool has_applied_scrub_position_ = false;
    timebase::TickPosition applied_scrub_position_{};
    bool previous_playing_ = false;
    MeterSignature previous_meter_{};
    LoopRegion previous_loop_{};
    double previous_tempo_bpm_ = 120.0;
    bool first_block_ = true;
    bool pending_discontinuity_ = false;
    bool has_expected_tempo_sync_beat_ = false;
    double expected_tempo_sync_beat_ = 0.0;
};
 
} // namespace pulp::playback