tempo_map.h

// SPDX-FileCopyrightText: © 2025-2026 Alexandros Theodotou <alex@zrythm.org>
// SPDX-License-Identifier: LicenseRef-ZrythmLicense
 
#pragma once
 
#include <cstdint>
#include <span>
#include <string_view>
#include <vector>
 
#include "dsp/tick_types.h"
#include "utils/units.h"
 
#include <nlohmann/json_fwd.hpp>
 
namespace zrythm::dsp
{

template <units::tick_t::NTTP PPQ> class FixedPpqTempoMap
{
  friend class TempoMapWrapper;
 
public:
  enum class CurveType : std::uint8_t
  {
    Constant, 
    Linear    
  };

  struct TempoEvent
  {
    units::tick_t tick;    
    units::bpm_t  bpm{};   
    CurveType     curve{}; 
 
    friend void to_json (nlohmann::json &j, const TempoEvent &e);
    friend void from_json (const nlohmann::json &j, TempoEvent &e);
  };

  struct TimeSignatureEvent
  {
    units::tick_t tick;          
    int           numerator{};   
    int           denominator{}; 
 
    constexpr auto quarters_per_bar () const
    {
      return (numerator * 4) / denominator;
    }
 
    constexpr auto ticks_per_bar () const
    {
      return quarters_per_bar () * FixedPpqTempoMap::get_ppq ();
    }
 
    constexpr auto ticks_per_beat () const
    {
      return ticks_per_bar () / numerator;
    }
 
    constexpr auto
    is_different_time_signature (const TimeSignatureEvent &other) const
    {
      return numerator != other.numerator || denominator != other.denominator;
    }
 
    friend void to_json (nlohmann::json &j, const TimeSignatureEvent &e);
    friend void from_json (const nlohmann::json &j, TimeSignatureEvent &e);
  };

  struct MusicalPosition
  {
    int bar{ 1 };       
    int beat{ 1 };      
    int sixteenth{ 1 }; 
    int tick{};         
 
    friend bool
    operator== (const MusicalPosition &lhs, const MusicalPosition &rhs) =
      default;
  };

  explicit FixedPpqTempoMap (units::precise_sample_rate_t sampleRate)
      : sample_rate_ (sampleRate)
  {
    rebuild_time_signature_cache ();
  }

  void set_sample_rate (units::precise_sample_rate_t sampleRate)
  {
    sample_rate_ = sampleRate;
  }

  void add_tempo_event (units::tick_t tick, units::bpm_t bpm, CurveType curve);

  void remove_tempo_event (units::tick_t tick);

  void
  add_time_signature_event (units::tick_t tick, int numerator, int denominator);

  void remove_time_signature_event (units::tick_t tick);

  auto tick_to_seconds (TimelineTick tick) const -> units::precise_second_t;

  units::precise_sample_t tick_to_samples (TimelineTick tick) const
  {
    return tick_to_seconds (tick) * sample_rate_;
  }
 
  units::sample_t tick_to_samples_rounded (TimelineTick tick) const
  {
    return au::round_as<int64_t> (units::samples, tick_to_samples (tick));
  }

  TimelineTick seconds_to_tick (units::precise_second_t seconds) const;

  TimelineTick samples_to_tick (units::precise_sample_t samples) const
  {
    const auto seconds = samples / sample_rate_;
    return seconds_to_tick (seconds);
  }

  TimeSignatureEvent time_signature_at_tick (units::tick_t tick) const;

  units::bpm_t tempo_at_tick (units::tick_t tick) const;

  std::span<const TempoEvent> tempo_events () const noexcept { return events_; }

  std::span<const TimeSignatureEvent> time_signature_events () const noexcept
  {
    return time_sig_events_;
  }

  MusicalPosition tick_to_musical_position (units::tick_t tick) const;
 
  MusicalPosition samples_to_musical_position (units::sample_t samples) const;

  TimelineTickI musical_position_to_tick (const MusicalPosition &pos) const;

  static consteval auto get_ppq () { return from_nttp (PPQ); }

  auto get_sample_rate () const { return sample_rate_; }

  units::bpm_t base_bpm () const { return base_bpm_; }

  void set_base_bpm (units::bpm_t bpm)
  {
    base_bpm_ = bpm;
    rebuild_cumulative_times ();
  }

  const TimeSignatureEvent &base_time_signature () const
  {
    return base_time_sig_;
  }

  void set_base_time_signature (int numerator, int denominator)
  {
    throw_if_invalid_time_signature (numerator, denominator);
    base_time_sig_.numerator = numerator;
    base_time_sig_.denominator = denominator;
    rebuild_time_signature_cache ();
  }

  std::span<const TimeSignatureEvent>
  effective_time_signature_events () const noexcept
  {
    return effective_time_sig_events_;
  }
 
private:
  void rebuild_cumulative_times ();

  void rebuild_time_signature_cache ();

  static void throw_if_invalid_time_signature (int numerator, int denominator);

  units::precise_second_t compute_segment_time (
    const TempoEvent &start,
    const TempoEvent &end,
    units::tick_t     segmentTicks) const;

  void clear_tempo_events ()
  {
    events_.clear ();
    cumulative_seconds_.clear ();
  }

  void clear_time_signature_events ()
  {
    time_sig_events_.clear ();
    rebuild_time_signature_cache ();
  }
 
  static constexpr std::string_view kTempoChangesKey = "tempoChanges";
  static constexpr std::string_view kTimeSignaturesKey = "timeSignatures";
  static constexpr std::string_view kBaseBpmKey = "baseBpm";
  static constexpr std::string_view kBaseTimeSignatureKey = "baseTimeSignature";
  friend void to_json (nlohmann::json &j, const FixedPpqTempoMap &tempo_map);
  friend void from_json (const nlohmann::json &j, FixedPpqTempoMap &tempo_map);
 
private:
  units::precise_sample_rate_t sample_rate_; 
  static constexpr auto        ticks_per_sixteenth_ =
    from_nttp (PPQ) / 4; 
 
  // Base tempo and time signature anchored at tick 0. These govern the region
  // from tick 0 up to the first inserted event (constant), unless an inserted
  // event exists at tick 0.
  units::bpm_t       base_bpm_{ units::bpm (120.0) };
  TimeSignatureEvent base_time_sig_{ units::ticks (0), 4, 4 };
 
  std::vector<TempoEvent>         events_;          
  std::vector<TimeSignatureEvent> time_sig_events_; 
  std::vector<units::precise_second_t>
    cumulative_seconds_; 
  // Cache of time-signature events with the base signature prepended at tick 0
  // when no inserted event sits there. Rebuilt on every mutation so the read
  // path (@ref effective_time_signature_events) stays allocation-free.
  std::vector<TimeSignatureEvent> effective_time_sig_events_;
};

using TempoMap = FixedPpqTempoMap<units::PPQ>;
 
extern template class FixedPpqTempoMap<units::PPQ>;
}