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         double beats_per_minute () const { return _beats_per_minute; }
  59         void set_beats_per_minute (double bpm) { _beats_per_minute = bpm; }
  60         double note_type () const { return _note_type; }
  61         double pulses_per_minute () const { return _beats_per_minute / _note_type; }
  62         /** audio samples per beat
  63          * @param sr samplerate
  64          */
  65         double frames_per_beat (framecnt_t sr) const {
  66                 return (60.0 * sr) / _beats_per_minute;
  67         }
  68         double frames_per_pulse (framecnt_t sr) const {
  69                 return (_note_type * 60.0 * sr) / _beats_per_minute;
  70         }
  71
  72   protected:
  73         double _beats_per_minute;
  74         double _note_type;
  75 };
  76
  77 /** Meter, or time signature (beats per bar, and which note type is a beat). */
  78 class LIBARDOUR_API Meter {
  79   public:
  80         Meter (double dpb, double bt)
  81                 : _divisions_per_bar (dpb), _note_type (bt) {}
  82
  83         double divisions_per_bar () const { return _divisions_per_bar; }
  84         double note_divisor() const { return _note_type; }
  85
  86         double frames_per_bar (const Tempo&, framecnt_t sr) const;
  87         double frames_per_grid (const Tempo&, framecnt_t sr) const;
  88
  89   protected:
  90         /** The number of divisions in a bar.  This is a floating point value because
  91             there are musical traditions on our planet that do not limit
  92             themselves to integral numbers of beats per bar.
  93         */
  94         double _divisions_per_bar;
  95
  96         /** The type of "note" that a division represents.  For example, 4.0 is
  97             a quarter (crotchet) note, 8.0 is an eighth (quaver) note, etc.
  98         */
  99         double _note_type;
 100 };
 101
 102 /** A section of timeline with a certain Tempo or Meter. */
 103 class LIBARDOUR_API MetricSection {
 104   public:
 105         MetricSection (double pulse)
 106                 : _pulse (pulse), _frame (0), _movable (true), _position_lock_style (PositionLockStyle::MusicTime) {}
 107         MetricSection (framepos_t frame)
 108                 : _pulse (0.0), _frame (frame), _movable (true), _position_lock_style (PositionLockStyle::AudioTime) {}
 109
 110         virtual ~MetricSection() {}
 111
 112         const double& pulse () const { return _pulse; }
 113         void set_pulse (double pulse) { _pulse = pulse; }
 114
 115         framepos_t frame() const { return _frame; }
 116         virtual void set_frame (framepos_t f) {
 117                 _frame = f;
 118         }
 119
 120         void set_movable (bool yn) { _movable = yn; }
 121         bool movable() const { return _movable; }
 122
 123         /* MeterSections are not stateful in the full sense,
 124            but we do want them to control their own
 125            XML state information.
 126         */
 127         virtual XMLNode& get_state() const = 0;
 128
 129         PositionLockStyle position_lock_style () const { return _position_lock_style; }
 130         void set_position_lock_style (PositionLockStyle ps) { _position_lock_style = ps; }
 131
 132 private:
 133         double             _pulse;
 134         framepos_t         _frame;
 135         bool               _movable;
 136         PositionLockStyle  _position_lock_style;
 137 };
 138
 139 /** A section of timeline with a certain Meter. */
 140 class LIBARDOUR_API MeterSection : public MetricSection, public Meter {
 141   public:
 142         MeterSection (double pulse, double beat, const Timecode::BBT_Time& bbt, double bpb, double note_type)
 143                 : MetricSection (pulse), Meter (bpb, note_type), _bbt (bbt),  _beat (beat) {}
 144         MeterSection (framepos_t frame, double beat, double bpb, double note_type)
 145                 : MetricSection (frame), Meter (bpb, note_type), _bbt (1, 1, 0), _beat (beat) {}
 146         MeterSection (const XMLNode&);
 147
 148         static const std::string xml_state_node_name;
 149
 150         XMLNode& get_state() const;
 151
 152         void set_pulse (double w) {
 153                 MetricSection::set_pulse (w);
 154         }
 155         void set_beat (std::pair<double, Timecode::BBT_Time>& w) {
 156                 _beat = w.first;
 157                 _bbt = w.second;
 158         }
 159
 160         const Timecode::BBT_Time& bbt() const { return _bbt; }
 161         const double& beat () const { return _beat; }
 162         void set_beat (double beat) { _beat = beat; }
 163
 164 private:
 165         Timecode::BBT_Time _bbt;
 166         double _beat;
 167 };
 168
 169 /** A section of timeline with a certain Tempo. */
 170 class LIBARDOUR_API TempoSection : public MetricSection, public Tempo {
 171   public:
 172         enum Type {
 173                 Ramp,
 174                 Constant,
 175         };
 176
 177         TempoSection (const double& beat, double qpm, double note_type, Type tempo_type)
 178                 : MetricSection (beat), Tempo (qpm, note_type), _bar_offset (-1.0), _type (tempo_type), _c_func (0.0), _active (true)  {}
 179         TempoSection (framepos_t frame, double qpm, double note_type, Type tempo_type)
 180                 : MetricSection (frame), Tempo (qpm, note_type), _bar_offset (-1.0), _type (tempo_type), _c_func (0.0), _active (true) {}
 181         TempoSection (const XMLNode&);
 182
 183         static const std::string xml_state_node_name;
 184
 185         XMLNode& get_state() const;
 186
 187         void update_bar_offset_from_bbt (const Meter&);
 188         void update_bbt_time_from_bar_offset (const Meter&);
 189         double bar_offset() const { return _bar_offset; }
 190
 191         bool active () const { return _active; }
 192         void set_active (bool yn) { _active = yn; }
 193
 194         void set_type (Type type);
 195         Type type () const { return _type; }
 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 framecnt_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         double get_c_func () const { return _c_func; }
 210         void set_c_func (double c_func) { _c_func = c_func; }
 211
 212         Timecode::BBT_Time legacy_bbt () { return _legacy_bbt; }
 213
 214   private:
 215
 216         framecnt_t minute_to_frame (const double& time, const framecnt_t& frame_rate) const;
 217         double frame_to_minute (const framecnt_t& frame, const framecnt_t& frame_rate) const;
 218
 219         /*  tempo ramp functions. zero-based with time in minutes,
 220          * 'tick tempo' in ticks per minute and tempo in bpm.
 221          *  time relative to section start.
 222          */
 223         double a_func (double end_tpm, double c_func) const;
 224         double c_func (double end_tpm, double end_time) const;
 225
 226         double pulse_tempo_at_time (const double& time) const;
 227         double time_at_pulse_tempo (const double& pulse_tempo) const;
 228
 229         double pulse_tempo_at_pulse (const double& pulse) const;
 230         double pulse_at_pulse_tempo (const double& pulse_tempo) const;
 231
 232         double pulse_at_time (const double& time) const;
 233         double time_at_pulse (const double& pulse) const;
 234
 235         /* this value provides a fractional offset into the bar in which
 236            the tempo section is located in. A value of 0.0 indicates that
 237            it occurs on the first beat of the bar, a value of 0.5 indicates
 238            that it occurs halfway through the bar and so on.
 239
 240            this enables us to keep the tempo change at the same relative
 241            position within the bar if/when the meter changes.
 242         */
 243         double _bar_offset;
 244         Type _type;
 245         double _c_func;
 246         bool _active;
 247         Timecode::BBT_Time _legacy_bbt;
 248 };
 249
 250 typedef std::list<MetricSection*> Metrics;
 251
 252 /** Helper class to keep track of the Meter *AND* Tempo in effect
 253     at a given point in time.
 254 */
 255 class LIBARDOUR_API TempoMetric {
 256   public:
 257         TempoMetric (const Meter& m, const Tempo& t)
 258                 : _meter (&m), _tempo (&t), _frame (0) {}
 259
 260         void set_tempo (const Tempo& t)              { _tempo = &t; }
 261         void set_meter (const Meter& m)              { _meter = &m; }
 262         void set_frame (framepos_t f)                { _frame = f; }
 263         void set_pulse (const double& p)             { _pulse = p; }
 264
 265         void set_metric (const MetricSection* section) {
 266                 const MeterSection* meter;
 267                 const TempoSection* tempo;
 268                 if ((meter = dynamic_cast<const MeterSection*>(section))) {
 269                         set_meter(*meter);
 270                 } else if ((tempo = dynamic_cast<const TempoSection*>(section))) {
 271                         set_tempo(*tempo);
 272                 }
 273
 274                 set_frame (section->frame());
 275                 set_pulse (section->pulse());
 276         }
 277
 278         const Meter&              meter() const { return *_meter; }
 279         const Tempo&              tempo() const { return *_tempo; }
 280         framepos_t                frame() const { return _frame; }
 281         const double&             pulse() const { return _pulse; }
 282
 283   private:
 284         const Meter*       _meter;
 285         const Tempo*       _tempo;
 286         framepos_t         _frame;
 287         double             _pulse;
 288 };
 289
 290 /** Tempo Map - mapping of timecode to musical time.
 291  * convert audio-samples, sample-rate to Bar/Beat/Tick, Meter/Tempo
 292  */
 293 class LIBARDOUR_API TempoMap : public PBD::StatefulDestructible
 294 {
 295   public:
 296         TempoMap (framecnt_t frame_rate);
 297         ~TempoMap();
 298
 299         /* measure-based stuff */
 300
 301         enum BBTPointType {
 302                 Bar,
 303                 Beat,
 304         };
 305
 306         struct BBTPoint {
 307                 framepos_t          frame;
 308                 const MeterSection* meter;
 309                 const Tempo tempo;
 310                 double              c;
 311                 uint32_t            bar;
 312                 uint32_t            beat;
 313
 314                 BBTPoint (const MeterSection& m, const Tempo& t, framepos_t f,
 315                           uint32_t b, uint32_t e, double func_c)
 316                 : frame (f), meter (&m), tempo (t.beats_per_minute(), t.note_type()), c (func_c), bar (b), beat (e) {}
 317
 318                 Timecode::BBT_Time bbt() const { return Timecode::BBT_Time (bar, beat, 0); }
 319                 operator Timecode::BBT_Time() const { return bbt(); }
 320                 operator framepos_t() const { return frame; }
 321                 bool is_bar() const { return beat == 1; }
 322         };
 323
 324         template<class T> void apply_with_metrics (T& obj, void (T::*method)(const Metrics&)) {
 325                 Glib::Threads::RWLock::ReaderLock lm (lock);
 326                 (obj.*method)(_metrics);
 327         }
 328
 329         void get_grid (std::vector<BBTPoint>&,
 330                        framepos_t start, framepos_t end);
 331
 332         /* TEMPO- AND METER-SENSITIVE FUNCTIONS
 333
 334            bbt_time(), beat_at_frame(), frame_at_beat(), tick_at_frame(),
 335            frame_at_tick(),frame_time() and bbt_duration_at()
 336            are all sensitive to tempo and meter, and will give answers
 337            that align with the grid formed by tempo and meter sections.
 338
 339            They SHOULD NOT be used to determine the position of events
 340            whose location is canonically defined in beats.
 341         */
 342
 343         void bbt_time (framepos_t when, Timecode::BBT_Time&);
 344
 345         double beat_at_frame (const framecnt_t& frame) const;
 346         framecnt_t frame_at_beat (const double& beat) const;
 347
 348         framepos_t frame_time (const Timecode::BBT_Time&);
 349         framecnt_t bbt_duration_at (framepos_t, const Timecode::BBT_Time&, int dir);
 350
 351         /* TEMPO-SENSITIVE FUNCTIONS
 352
 353            These next 4 functions will all take tempo in account and should be
 354            used to determine position (and in the last case, distance in beats)
 355            when tempo matters but meter does not.
 356
 357            They SHOULD be used to determine the position of events
 358            whose location is canonically defined in beats.
 359         */
 360
 361         framepos_t framepos_plus_bbt (framepos_t pos, Timecode::BBT_Time b) const;
 362         framepos_t framepos_plus_beats (framepos_t, Evoral::Beats) const;
 363         framepos_t framepos_minus_beats (framepos_t, Evoral::Beats) const;
 364         Evoral::Beats framewalk_to_beats (framepos_t pos, framecnt_t distance) const;
 365
 366         static const Tempo& default_tempo() { return _default_tempo; }
 367         static const Meter& default_meter() { return _default_meter; }
 368
 369         const Tempo tempo_at (const framepos_t& frame) const;
 370         double frames_per_beat_at (const framepos_t&, const framecnt_t& sr) const;
 371
 372         const Meter& meter_at (framepos_t) const;
 373
 374         const TempoSection& tempo_section_at (framepos_t frame) const;
 375         const MeterSection& meter_section_at (framepos_t frame) const;
 376         const MeterSection& meter_section_at (const double& beat) const;
 377
 378         void add_tempo (const Tempo&, const double& pulse, TempoSection::Type type);
 379         void add_tempo (const Tempo&, const framepos_t& frame, TempoSection::Type type);
 380
 381         void add_meter (const Meter&, const double& beat, const Timecode::BBT_Time& where);
 382         void add_meter (const Meter&, const framepos_t& frame);
 383
 384         void remove_tempo (const TempoSection&, bool send_signal);
 385         void remove_meter (const MeterSection&, bool send_signal);
 386
 387         framepos_t predict_tempo_frame (TempoSection* section, const Tempo& bpm, const Timecode::BBT_Time& bbt);
 388         double predict_tempo_pulse (TempoSection* section, const Tempo& bpm, const framepos_t& frame);
 389
 390         void replace_tempo (const TempoSection&, const Tempo&, const double& where, TempoSection::Type type);
 391         void replace_tempo (const TempoSection&, const Tempo&, const framepos_t& frame, TempoSection::Type type);
 392
 393         void gui_move_tempo_frame (TempoSection*, const Tempo& bpm, const framepos_t& frame);
 394         void gui_move_tempo_beat (TempoSection*, const Tempo& bpm, const double& frame);
 395         void gui_move_meter (MeterSection*, const Meter& mt, const framepos_t& frame);
 396         void gui_move_meter (MeterSection*, const Meter& mt, const double& beat);
 397         bool gui_change_tempo (TempoSection*, const Tempo& bpm);
 398
 399         bool can_solve_bbt (TempoSection* section, const Tempo& bpm, const Timecode::BBT_Time& bbt);
 400
 401         void replace_meter (const MeterSection&, const Meter&, const Timecode::BBT_Time& where);
 402         void replace_meter (const MeterSection&, const Meter&, const framepos_t& frame);
 403
 404         framepos_t round_to_bar  (framepos_t frame, RoundMode dir);
 405         framepos_t round_to_beat (framepos_t frame, RoundMode dir);
 406         framepos_t round_to_beat_subdivision (framepos_t fr, int sub_num, RoundMode dir);
 407         void round_bbt (Timecode::BBT_Time& when, const int32_t& snap_divisor);
 408
 409         void set_length (framepos_t frames);
 410
 411         XMLNode& get_state (void);
 412         int set_state (const XMLNode&, int version);
 413
 414         void dump (const Metrics& metrics, std::ostream&) const;
 415         void clear ();
 416
 417         TempoMetric metric_at (Timecode::BBT_Time bbt) const;
 418
 419         /** Return the TempoMetric at frame @p t, and point @p last to the latest
 420          * metric change <= t, if it is non-NULL.
 421          */
 422         TempoMetric metric_at (framepos_t, Metrics::const_iterator* last=NULL) const;
 423
 424         Metrics::const_iterator metrics_end() { return _metrics.end(); }
 425
 426         void change_existing_tempo_at (framepos_t, double bpm, double note_type);
 427         void change_initial_tempo (double bpm, double note_type);
 428
 429         void insert_time (framepos_t, framecnt_t);
 430         bool remove_time (framepos_t where, framecnt_t amount);  //returns true if anything was moved
 431
 432         int n_tempos () const;
 433         int n_meters () const;
 434
 435         framecnt_t frame_rate () const { return _frame_rate; }
 436
 437         double bbt_to_beats (const Timecode::BBT_Time& bbt);
 438         Timecode::BBT_Time beats_to_bbt (const double& beats);
 439         Timecode::BBT_Time pulse_to_bbt (const double& pulse);
 440
 441         double pulse_at_beat (const double& beat) const;
 442         double beat_at_pulse (const double& pulse) const;
 443
 444         PBD::Signal0<void> MetricPositionChanged;
 445
 446 private:
 447         double pulse_at_beat_locked (const Metrics& metrics, const double& beat) const;
 448         double beat_at_pulse_locked (const Metrics& metrics, const double& pulse) const;
 449         double pulse_at_frame_locked (const Metrics& metrics, const framecnt_t& frame) const;
 450         framecnt_t frame_at_pulse_locked (const Metrics& metrics, const double& beat) const;
 451
 452         double beat_offset_at (const Metrics& metrics, const double& beat) const;
 453         frameoffset_t frame_offset_at (const Metrics& metrics, const framepos_t& frame) const;
 454
 455         double beat_at_frame_locked (const Metrics& metrics, const framecnt_t& frame) const;
 456         framecnt_t frame_at_beat_locked (const Metrics& metrics, const double& beat) const;
 457         double bbt_to_beats_locked (const Metrics& metrics, const Timecode::BBT_Time& bbt) const ;
 458         Timecode::BBT_Time beats_to_bbt_locked (const Metrics& metrics, const double& beats) const;
 459
 460         framepos_t frame_time_locked (const Metrics& metrics, const Timecode::BBT_Time&) const;
 461
 462         const MeterSection& meter_section_at_locked (framepos_t frame) const;
 463         const TempoSection& tempo_section_at_locked (framepos_t frame) const;
 464         const Tempo tempo_at_locked (const framepos_t& frame) const;
 465
 466         bool check_solved (Metrics& metrics, bool by_frame);
 467         bool solve_map (Metrics& metrics, TempoSection* section, const Tempo& bpm, const framepos_t& frame);
 468         bool solve_map (Metrics& metrics, TempoSection* section, const Tempo& bpm, const double& pulse);
 469         void solve_map (Metrics& metrics, MeterSection* section, const Meter& mt, const framepos_t& frame);
 470         void solve_map (Metrics& metrics, MeterSection* section, const Meter& mt, const double& pulse);
 471
 472         friend class ::BBTTest;
 473         friend class ::FrameposPlusBeatsTest;
 474         friend class ::TempoTest;
 475
 476         static Tempo    _default_tempo;
 477         static Meter    _default_meter;
 478
 479         Metrics                       _metrics;
 480         framecnt_t                    _frame_rate;
 481         mutable Glib::Threads::RWLock lock;
 482
 483         void recompute_tempos (Metrics& metrics);
 484         void recompute_meters (Metrics& metrics);
 485         void recompute_map (Metrics& metrics, framepos_t end = -1);
 486
 487         framepos_t round_to_type (framepos_t fr, RoundMode dir, BBTPointType);
 488
 489         const MeterSection& first_meter() const;
 490         MeterSection&       first_meter();
 491         const TempoSection& first_tempo() const;
 492         TempoSection&       first_tempo();
 493
 494         void do_insert (MetricSection* section);
 495
 496         void add_tempo_locked (const Tempo&, double pulse, bool recompute, TempoSection::Type type);
 497         void add_tempo_locked (const Tempo&, framepos_t frame, bool recompute, TempoSection::Type type);
 498
 499         void add_meter_locked (const Meter&, double beat, Timecode::BBT_Time where, bool recompute);
 500         void add_meter_locked (const Meter&, framepos_t frame, bool recompute);
 501
 502         bool remove_tempo_locked (const TempoSection&);
 503         bool remove_meter_locked (const MeterSection&);
 504
 505         TempoSection* copy_metrics_and_point (Metrics& copy, TempoSection* section);
 506 };
 507
 508 }; /* namespace ARDOUR */
 509
 510 std::ostream& operator<< (std::ostream&, const ARDOUR::Meter&);
 511 std::ostream& operator<< (std::ostream&, const ARDOUR::Tempo&);
 512 std::ostream& operator<< (std::ostream&, const ARDOUR::MetricSection&);
 513
 514 #endif /* __ardour_tempo_h__ */