libs/ardour/ardour/tempo.h

   1 /*
   2     Copyright (C) 2000 Paul Davis
   3
   4     This program is free software; you can redistribute it and/or modify
   5     it under the terms of the GNU General Public License as published by
   6     the Free Software Foundation; either version 2 of the License, or
   7     (at your option) any later version.
   8
   9     This program is distributed in the hope that it will be useful,
  10     but WITHOUT ANY WARRANTY; without even the implied warranty of
  11     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12     GNU General Public License for more details.
  13
  14     You should have received a copy of the GNU General Public License
  15     along with this program; if not, write to the Free Software
  16     Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  17
  18 */
  19
  20 #ifndef __ardour_tempo_h__
  21 #define __ardour_tempo_h__
  22
  23 #include <list>
  24 #include <string>
  25 #include <vector>
  26 #include <cmath>
  27 #include <glibmm/threads.h>
  28
  29 #include "pbd/undo.h"
  30
  31 #include "pbd/stateful.h"
  32 #include "pbd/statefuldestructible.h"
  33
  34 #include "evoral/Beats.hpp"
  35
  36 #include "ardour/ardour.h"
  37
  38 class BBTTest;
  39 class FrameposPlusBeatsTest;
  40 class TempoTest;
  41 class XMLNode;
  42
  43 namespace ARDOUR {
  44
  45 class Meter;
  46 class TempoMap;
  47
  48 /** Tempo, the speed at which musical time progresses (BPM). */
  49 class LIBARDOUR_API Tempo {
  50   public:
  51         /**
  52          * @param bpm Beats Per Minute
  53          * @param type Note Type (default `4': quarter note)
  54          */
  55         Tempo (double bpm, double type=4.0) // defaulting to quarter note
  56                 : _beats_per_minute (bpm), _note_type(type) {}
  57
  58         /* ..or more aptly 'pulse divisions per minute'.
  59            Nothing to do with actual beats, which are defined by the meter and tempo.
  60         */
  61         double beats_per_minute () const { return _beats_per_minute; }
  62         void set_beats_per_minute (double bpm) { _beats_per_minute = bpm; }
  63         double note_type () const { return _note_type; }
  64         double pulses_per_minute () const { return _beats_per_minute / _note_type; }
  65         /** audio samples per beat
  66          * @param sr samplerate
  67          */
  68         double frames_per_beat (framecnt_t sr) const {
  69                 return (60.0 * sr) / _beats_per_minute;
  70         }
  71         double frames_per_pulse (framecnt_t sr) const {
  72                 return (_note_type * 60.0 * sr) / _beats_per_minute;
  73         }
  74
  75   protected:
  76         double _beats_per_minute;
  77         double _note_type;
  78 };
  79
  80 /** Meter, or time signature (beats per bar, and which note type is a beat). */
  81 class LIBARDOUR_API Meter {
  82   public:
  83         Meter (double dpb, double bt)
  84                 : _divisions_per_bar (dpb), _note_type (bt) {}
  85
  86         double divisions_per_bar () const { return _divisions_per_bar; }
  87         double note_divisor() const { return _note_type; }
  88
  89         double frames_per_bar (const Tempo&, framecnt_t sr) const;
  90         double frames_per_grid (const Tempo&, framecnt_t sr) const;
  91
  92   protected:
  93         /** The number of divisions in a bar.  This is a floating point value because
  94             there are musical traditions on our planet that do not limit
  95             themselves to integral numbers of beats per bar.
  96         */
  97         double _divisions_per_bar;
  98
  99         /** The type of "note" that a division represents.  For example, 4.0 is
 100             a quarter (crotchet) note, 8.0 is an eighth (quaver) note, etc.
 101         */
 102         double _note_type;
 103 };
 104
 105 /** A section of timeline with a certain Tempo or Meter. */
 106 class LIBARDOUR_API MetricSection {
 107   public:
 108         MetricSection (double pulse, framepos_t frame, PositionLockStyle pls, bool is_tempo)
 109                 : _pulse (pulse), _frame (frame), _movable (true), _position_lock_style (pls), _is_tempo (is_tempo) {}
 110
 111         virtual ~MetricSection() {}
 112
 113         const double& pulse () const { return _pulse; }
 114         void set_pulse (double pulse) { _pulse = pulse; }
 115
 116         framepos_t frame() const { return _frame; }
 117         virtual void set_frame (framepos_t f) {
 118                 _frame = f;
 119         }
 120
 121         void set_movable (bool yn) { _movable = yn; }
 122         bool movable() const { return _movable; }
 123
 124         /* MeterSections are not stateful in the full sense,
 125            but we do want them to control their own
 126            XML state information.
 127         */
 128         virtual XMLNode& get_state() const = 0;
 129
 130         PositionLockStyle position_lock_style () const { return _position_lock_style; }
 131         void set_position_lock_style (PositionLockStyle ps) { _position_lock_style = ps; }
 132         bool is_tempo () const { return _is_tempo; }
 133
 134 private:
 135         double             _pulse;
 136         framepos_t         _frame;
 137         bool               _movable;
 138         PositionLockStyle  _position_lock_style;
 139         const bool         _is_tempo;
 140 };
 141
 142 /** A section of timeline with a certain Meter. */
 143 class LIBARDOUR_API MeterSection : public MetricSection, public Meter {
 144   public:
 145         MeterSection (double pulse, framepos_t frame, double beat, const Timecode::BBT_Time& bbt, double bpb, double note_type, PositionLockStyle pls)
 146                 : MetricSection (pulse, frame, pls, false), Meter (bpb, note_type), _bbt (bbt),  _beat (beat) {}
 147
 148         MeterSection (const XMLNode&);
 149
 150         static const std::string xml_state_node_name;
 151
 152         XMLNode& get_state() const;
 153
 154         void set_beat (std::pair<double, Timecode::BBT_Time>& w) {
 155                 _beat = w.first;
 156                 _bbt = w.second;
 157         }
 158
 159         const Timecode::BBT_Time& bbt() const { return _bbt; }
 160         const double& beat () const { return _beat; }
 161         void set_beat (double beat) { _beat = beat; }
 162
 163 private:
 164         Timecode::BBT_Time _bbt;
 165         double _beat;
 166 };
 167
 168 /** A section of timeline with a certain Tempo. */
 169 class LIBARDOUR_API TempoSection : public MetricSection, public Tempo {
 170   public:
 171         enum Type {
 172                 Ramp,
 173                 Constant,
 174         };
 175
 176         TempoSection (const double& pulse, const framepos_t& frame, double qpm, double note_type, Type tempo_type, PositionLockStyle pls)
 177                 : MetricSection (pulse, frame, pls, true), Tempo (qpm, note_type), _type (tempo_type), _c_func (0.0), _active (true), _locked_to_meter (false)  {}
 178
 179         TempoSection (const XMLNode&);
 180
 181         static const std::string xml_state_node_name;
 182
 183         XMLNode& get_state() const;
 184
 185         double c_func () const { return _c_func; }
 186         void set_c_func (double c_func) { _c_func = c_func; }
 187
 188         void set_type (Type type);
 189         Type type () const { return _type; }
 190
 191         bool active () const { return _active; }
 192         void set_active (bool yn) { _active = yn; }
 193
 194         bool locked_to_meter ()  const { return _locked_to_meter; }
 195         void set_locked_to_meter (bool yn) { _locked_to_meter = yn; }
 196
 197         double tempo_at_frame (const framepos_t& frame, const framecnt_t& frame_rate) const;
 198         framepos_t frame_at_tempo (const double& ppm, const double& beat, const framecnt_t& frame_rate) const;
 199
 200         double tempo_at_pulse (const double& pulse) const;
 201         double pulse_at_tempo (const double& ppm, const framepos_t& frame, const framecnt_t& frame_rate) const;
 202
 203         double pulse_at_frame (const framepos_t& frame, const framepos_t& frame_rate) const;
 204         framepos_t frame_at_pulse (const double& pulse, const framecnt_t& frame_rate) const;
 205
 206         double compute_c_func_pulse (const double& end_bpm, const double& end_pulse, const framecnt_t& frame_rate);
 207         double compute_c_func_frame (const double& end_bpm, const framepos_t& end_frame, const framecnt_t& frame_rate) const;
 208
 209         Timecode::BBT_Time legacy_bbt () { return _legacy_bbt; }
 210
 211   private:
 212
 213         framepos_t minute_to_frame (const double& time, const framecnt_t& frame_rate) const;
 214         double frame_to_minute (const framepos_t& frame, const framecnt_t& frame_rate) const;
 215
 216         /*  tempo ramp functions. zero-based with time in minutes,
 217          * 'tick tempo' in ticks per minute and tempo in bpm.
 218          *  time relative to section start.
 219          */
 220         double a_func (double end_tpm, double c_func) const;
 221         double c_func (double end_tpm, double end_time) const;
 222
 223         double pulse_tempo_at_time (const double& time) const;
 224         double time_at_pulse_tempo (const double& pulse_tempo) const;
 225
 226         double pulse_tempo_at_pulse (const double& pulse) const;
 227         double pulse_at_pulse_tempo (const double& pulse_tempo) const;
 228
 229         double pulse_at_time (const double& time) const;
 230         double time_at_pulse (const double& pulse) const;
 231
 232         /* this value provides a fractional offset into the bar in which
 233            the tempo section is located in. A value of 0.0 indicates that
 234            it occurs on the first beat of the bar, a value of 0.5 indicates
 235            that it occurs halfway through the bar and so on.
 236
 237            this enables us to keep the tempo change at the same relative
 238            position within the bar if/when the meter changes.
 239         */
 240         Type _type;
 241         double _c_func;
 242         bool _active;
 243         bool _locked_to_meter;
 244         Timecode::BBT_Time _legacy_bbt;
 245 };
 246
 247 typedef std::list<MetricSection*> Metrics;
 248
 249 /** Helper class to keep track of the Meter *AND* Tempo in effect
 250     at a given point in time.
 251 */
 252 class LIBARDOUR_API TempoMetric {
 253   public:
 254         TempoMetric (const Meter& m, const Tempo& t)
 255                 : _meter (&m), _tempo (&t), _frame (0) {}
 256
 257         void set_tempo (const Tempo& t)              { _tempo = &t; }
 258         void set_meter (const Meter& m)              { _meter = &m; }
 259         void set_frame (framepos_t f)                { _frame = f; }
 260         void set_pulse (const double& p)             { _pulse = p; }
 261
 262         void set_metric (const MetricSection* section) {
 263                 const MeterSection* meter;
 264                 const TempoSection* tempo;
 265                 if ((meter = dynamic_cast<const MeterSection*>(section))) {
 266                         set_meter(*meter);
 267                 } else if ((tempo = dynamic_cast<const TempoSection*>(section))) {
 268                         set_tempo(*tempo);
 269                 }
 270
 271                 set_frame (section->frame());
 272                 set_pulse (section->pulse());
 273         }
 274
 275         const Meter&              meter() const { return *_meter; }
 276         const Tempo&              tempo() const { return *_tempo; }
 277         framepos_t                frame() const { return _frame; }
 278         const double&             pulse() const { return _pulse; }
 279
 280   private:
 281         const Meter*       _meter;
 282         const Tempo*       _tempo;
 283         framepos_t         _frame;
 284         double             _pulse;
 285 };
 286
 287 /** Tempo Map - mapping of timecode to musical time.
 288  * convert audio-samples, sample-rate to Bar/Beat/Tick, Meter/Tempo
 289  */
 290 class LIBARDOUR_API TempoMap : public PBD::StatefulDestructible
 291 {
 292   public:
 293         TempoMap (framecnt_t frame_rate);
 294         ~TempoMap();
 295
 296         /* measure-based stuff */
 297
 298         enum BBTPointType {
 299                 Bar,
 300                 Beat,
 301         };
 302
 303         struct BBTPoint {
 304                 framepos_t          frame;
 305                 Meter               meter;
 306                 Tempo               tempo;
 307                 double              c;
 308                 uint32_t            bar;
 309                 uint32_t            beat;
 310
 311                 BBTPoint (const MeterSection& m, const Tempo& t, framepos_t f,
 312                           uint32_t b, uint32_t e, double func_c)
 313                 : frame (f), meter (m.divisions_per_bar(), m.note_divisor()), tempo (t.beats_per_minute(), t.note_type()), c (func_c), bar (b), beat (e) {}
 314
 315                 Timecode::BBT_Time bbt() const { return Timecode::BBT_Time (bar, beat, 0); }
 316                 operator Timecode::BBT_Time() const { return bbt(); }
 317                 operator framepos_t() const { return frame; }
 318                 bool is_bar() const { return beat == 1; }
 319         };
 320
 321         template<class T> void apply_with_metrics (T& obj, void (T::*method)(const Metrics&)) {
 322                 Glib::Threads::RWLock::ReaderLock lm (lock);
 323                 (obj.*method)(_metrics);
 324         }
 325
 326         void get_grid (std::vector<BBTPoint>&,
 327                        framepos_t start, framepos_t end);
 328
 329         static const Tempo& default_tempo() { return _default_tempo; }
 330         static const Meter& default_meter() { return _default_meter; }
 331
 332         /* because tempos may be ramped, this is only valid for the instant requested.*/
 333         double frames_per_beat_at (const framepos_t&, const framecnt_t& sr) const;
 334
 335         const TempoSection& tempo_section_at_frame (framepos_t frame) const;
 336         const MeterSection& meter_section_at_frame (framepos_t frame) const;
 337         const MeterSection& meter_section_at_beat (double beat) const;
 338
 339         /** add a tempo section locked to pls. ignored values will be set in recompute_tempi()
 340          * @param pulse pulse position of new section. ignored if pls == AudioTime
 341          * @param frame frame position of new section. ignored if pls == MusicTime
 342          * @param type type of new tempo section (Ramp, Constant)
 343          */
 344         TempoSection* add_tempo (const Tempo&, const double& pulse, const framepos_t& frame, TempoSection::Type type, PositionLockStyle pls);
 345
 346         /** add an meter section locked to pls.. ignored values will be set in recompute_meters()
 347          * @param beat beat position of new section
 348          * @param where bbt position of new section
 349          * @param frame frame position of new section. ignored if pls == MusicTime
 350          */
 351         MeterSection* add_meter (const Meter&, const double& beat, const Timecode::BBT_Time& where, const framepos_t& frame, PositionLockStyle pls);
 352
 353         void remove_tempo (const TempoSection&, bool send_signal);
 354         void remove_meter (const MeterSection&, bool send_signal);
 355
 356         void replace_tempo (const TempoSection&, const Tempo&, const double& pulse, const framepos_t& frame
 357                             , TempoSection::Type type, PositionLockStyle pls);
 358
 359         void replace_meter (const MeterSection&, const Meter&, const Timecode::BBT_Time& where, const framepos_t& frame
 360                             , PositionLockStyle pls);
 361
 362         framepos_t round_to_bar  (framepos_t frame, RoundMode dir);
 363         framepos_t round_to_beat (framepos_t frame, RoundMode dir);
 364         framepos_t round_to_beat_subdivision (framepos_t fr, int sub_num, RoundMode dir);
 365
 366         void set_length (framepos_t frames);
 367
 368         XMLNode& get_state (void);
 369         int set_state (const XMLNode&, int version);
 370
 371         void dump (const Metrics& metrics, std::ostream&) const;
 372         void clear ();
 373
 374         TempoMetric metric_at (Timecode::BBT_Time bbt) const;
 375
 376         /** Return the TempoMetric at frame @p t, and point @p last to the latest
 377          * metric change <= t, if it is non-NULL.
 378          */
 379         TempoMetric metric_at (framepos_t, Metrics::const_iterator* last=NULL) const;
 380
 381         Metrics::const_iterator metrics_end() { return _metrics.end(); }
 382
 383         void change_existing_tempo_at (framepos_t, double bpm, double note_type);
 384         void change_initial_tempo (double bpm, double note_type);
 385
 386         void insert_time (framepos_t, framecnt_t);
 387         bool remove_time (framepos_t where, framecnt_t amount);  //returns true if anything was moved
 388
 389         int n_tempos () const;
 390         int n_meters () const;
 391
 392         framecnt_t frame_rate () const { return _frame_rate; }
 393
 394         /* TEMPO- AND METER-SENSITIVE FUNCTIONS
 395
 396            bbt_at_frame(), frame_at_bbt(), beat_at_frame(), frame_at_beat(), tempo_at_beat()
 397            and bbt_duration_at()
 398            are all sensitive to tempo and meter, and will give answers
 399            that align with the grid formed by tempo and meter sections.
 400
 401            They SHOULD NOT be used to determine the position of events
 402            whose location is canonically defined in beats.
 403         */
 404
 405         double beat_at_frame (const framecnt_t& frame) const;
 406         framepos_t frame_at_beat (const double& beat) const;
 407
 408         Tempo tempo_at_frame (const framepos_t& frame) const;
 409         framepos_t frame_at_tempo (const Tempo& tempo) const;
 410
 411         Tempo tempo_at_beat (const double& beat) const;
 412
 413         const Meter& meter_at_frame (framepos_t) const;
 414
 415         /* you probably only need to use pulses when moving tempos */
 416         double pulse_at_beat (const double& beat) const;
 417         double beat_at_pulse (const double& pulse) const;
 418
 419         double pulse_at_frame (const framecnt_t& frame) const;
 420         framepos_t frame_at_pulse (const double& pulse) const;
 421
 422         /* bbt - it's nearly always better to use beats.*/
 423         Timecode::BBT_Time bbt_at_frame (framepos_t when);
 424         Timecode::BBT_Time bbt_at_frame_rt (framepos_t when);
 425         framepos_t frame_at_bbt (const Timecode::BBT_Time&);
 426
 427         double beat_at_bbt (const Timecode::BBT_Time& bbt);
 428         Timecode::BBT_Time bbt_at_beat (const double& beats);
 429
 430         double pulse_at_bbt (const Timecode::BBT_Time& bbt);
 431         Timecode::BBT_Time bbt_at_pulse (const double& pulse);
 432
 433         framecnt_t bbt_duration_at (framepos_t, const Timecode::BBT_Time&, int dir);
 434
 435         /* TEMPO-SENSITIVE FUNCTIONS
 436
 437            These next 4 functions will all take tempo in account and should be
 438            used to determine position (and in the last case, distance in beats)
 439            when tempo matters but meter does not.
 440
 441            They SHOULD be used to determine the position of events
 442            whose location is canonically defined in beats.
 443         */
 444
 445         framepos_t framepos_plus_bbt (framepos_t pos, Timecode::BBT_Time b) const;
 446         framepos_t framepos_plus_beats (framepos_t, Evoral::Beats) const;
 447         framepos_t framepos_minus_beats (framepos_t, Evoral::Beats) const;
 448         Evoral::Beats framewalk_to_beats (framepos_t pos, framecnt_t distance) const;
 449
 450         void gui_move_tempo (TempoSection*, const framepos_t& frame, const int& sub_num);
 451         void gui_move_meter (MeterSection*, const framepos_t& frame);
 452         bool gui_change_tempo (TempoSection*, const Tempo& bpm);
 453         void gui_dilate_tempo (TempoSection* tempo, const framepos_t& frame, const framepos_t& end_frame, const double& pulse);
 454
 455         double exact_beat_at_frame (const framepos_t& frame, const int32_t sub_num);
 456
 457         std::pair<double, framepos_t> predict_tempo_position (TempoSection* section, const Timecode::BBT_Time& bbt);
 458         bool can_solve_bbt (TempoSection* section, const Timecode::BBT_Time& bbt);
 459
 460         PBD::Signal0<void> MetricPositionChanged;
 461         void fix_legacy_session();
 462
 463 private:
 464
 465         double beat_at_frame_locked (const Metrics& metrics, const framecnt_t& frame) const;
 466         framepos_t frame_at_beat_locked (const Metrics& metrics, const double& beat) const;
 467
 468         double pulse_at_beat_locked (const Metrics& metrics, const double& beat) const;
 469         double beat_at_pulse_locked (const Metrics& metrics, const double& pulse) const;
 470
 471         double pulse_at_frame_locked (const Metrics& metrics, const framepos_t& frame) const;
 472         framepos_t frame_at_pulse_locked (const Metrics& metrics, const double& pulse) const;
 473
 474         Tempo tempo_at_frame_locked (const Metrics& metrics, const framepos_t& frame) const;
 475         framepos_t frame_at_tempo_locked (const Metrics& metrics, const Tempo& tempo) const;
 476
 477         Timecode::BBT_Time bbt_at_frame_locked (const Metrics& metrics, const framepos_t& frame) const;
 478         framepos_t frame_at_bbt_locked (const Metrics& metrics, const Timecode::BBT_Time&) const;
 479
 480         double beat_at_bbt_locked (const Metrics& metrics, const Timecode::BBT_Time& bbt) const ;
 481         Timecode::BBT_Time bbt_at_beat_locked (const Metrics& metrics, const double& beats) const;
 482
 483         double pulse_at_bbt_locked (const Metrics& metrics, const Timecode::BBT_Time& bbt) const;
 484         Timecode::BBT_Time bbt_at_pulse_locked (const Metrics& metrics, const double& pulse) const;
 485
 486         const TempoSection& tempo_section_at_frame_locked (const Metrics& metrics, framepos_t frame) const;
 487         const TempoSection& tempo_section_at_beat_locked (const Metrics& metrics, const double& beat) const;
 488
 489         const MeterSection& meter_section_at_frame_locked (const Metrics& metrics, framepos_t frame) const;
 490         const MeterSection& meter_section_at_beat_locked (const Metrics& metrics, const double& beat) const;
 491
 492         bool check_solved (const Metrics& metrics) const;
 493         bool set_active_tempos (const Metrics& metrics, const framepos_t& frame);
 494
 495         bool solve_map_frame (Metrics& metrics, TempoSection* section, const framepos_t& frame);
 496         bool solve_map_pulse (Metrics& metrics, TempoSection* section, const double& pulse);
 497         bool solve_map_frame (Metrics& metrics, MeterSection* section, const framepos_t& frame);
 498         bool solve_map_bbt (Metrics& metrics, MeterSection* section, const Timecode::BBT_Time& bbt);
 499
 500         double exact_beat_at_frame_locked (const Metrics& metrics, const framepos_t& frame, const int32_t sub_num);
 501
 502         friend class ::BBTTest;
 503         friend class ::FrameposPlusBeatsTest;
 504         friend class ::TempoTest;
 505
 506         static Tempo    _default_tempo;
 507         static Meter    _default_meter;
 508
 509         Metrics                       _metrics;
 510         framecnt_t                    _frame_rate;
 511         mutable Glib::Threads::RWLock lock;
 512
 513         void recompute_tempi (Metrics& metrics);
 514         void recompute_meters (Metrics& metrics);
 515         void recompute_map (Metrics& metrics, framepos_t end = -1);
 516
 517         framepos_t round_to_type (framepos_t fr, RoundMode dir, BBTPointType);
 518
 519         const MeterSection& first_meter() const;
 520         MeterSection&       first_meter();
 521         const TempoSection& first_tempo() const;
 522         TempoSection&       first_tempo();
 523
 524         void do_insert (MetricSection* section);
 525
 526         TempoSection* add_tempo_locked (const Tempo&, double pulse, framepos_t frame
 527                                , TempoSection::Type type, PositionLockStyle pls, bool recompute, bool locked_to_meter = false);
 528
 529         MeterSection* add_meter_locked (const Meter&, double beat, const Timecode::BBT_Time& where, framepos_t frame
 530                                         , PositionLockStyle pls, bool recompute);
 531
 532         bool remove_tempo_locked (const TempoSection&);
 533         bool remove_meter_locked (const MeterSection&);
 534
 535         TempoSection* copy_metrics_and_point (const Metrics& metrics, Metrics& copy, TempoSection* section);
 536         MeterSection* copy_metrics_and_point (const Metrics& metrics, Metrics& copy, MeterSection* section);
 537 };
 538
 539 }; /* namespace ARDOUR */
 540
 541 std::ostream& operator<< (std::ostream&, const ARDOUR::Meter&);
 542 std::ostream& operator<< (std::ostream&, const ARDOUR::Tempo&);
 543 std::ostream& operator<< (std::ostream&, const ARDOUR::MetricSection&);
 544
 545 #endif /* __ardour_tempo_h__ */