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                 uint32_t            bar;
 311                 uint32_t            beat;
 312
 313                 BBTPoint (const MeterSection& m, const Tempo& t, framepos_t f,
 314                           uint32_t b, uint32_t e)
 315                 : frame (f), meter (&m), tempo (t.beats_per_minute(), t.note_type()), bar (b), beat (e) {}
 316
 317                 Timecode::BBT_Time bbt() const { return Timecode::BBT_Time (bar, beat, 0); }
 318                 operator Timecode::BBT_Time() const { return bbt(); }
 319                 operator framepos_t() const { return frame; }
 320                 bool is_bar() const { return beat == 1; }
 321         };
 322
 323         template<class T> void apply_with_metrics (T& obj, void (T::*method)(const Metrics&)) {
 324                 Glib::Threads::RWLock::ReaderLock lm (lock);
 325                 (obj.*method)(_metrics);
 326         }
 327
 328         void get_grid (std::vector<BBTPoint>&,
 329                        framepos_t start, framepos_t end);
 330
 331         /* TEMPO- AND METER-SENSITIVE FUNCTIONS
 332
 333            bbt_time(), beat_at_frame(), frame_at_beat(), tick_at_frame(),
 334            frame_at_tick(),frame_time() and bbt_duration_at()
 335            are all sensitive to tempo and meter, and will give answers
 336            that align with the grid formed by tempo and meter sections.
 337
 338            They SHOULD NOT be used to determine the position of events
 339            whose location is canonically defined in beats.
 340         */
 341
 342         void bbt_time (framepos_t when, Timecode::BBT_Time&);
 343
 344         double beat_at_frame (const framecnt_t& frame) const;
 345         framecnt_t frame_at_beat (const double& beat) const;
 346
 347         framepos_t frame_time (const Timecode::BBT_Time&);
 348         framecnt_t bbt_duration_at (framepos_t, const Timecode::BBT_Time&, int dir);
 349
 350         /* TEMPO-SENSITIVE FUNCTIONS
 351
 352            These next 4 functions will all take tempo in account and should be
 353            used to determine position (and in the last case, distance in beats)
 354            when tempo matters but meter does not.
 355
 356            They SHOULD be used to determine the position of events
 357            whose location is canonically defined in beats.
 358         */
 359
 360         framepos_t framepos_plus_bbt (framepos_t pos, Timecode::BBT_Time b) const;
 361         framepos_t framepos_plus_beats (framepos_t, Evoral::Beats) const;
 362         framepos_t framepos_minus_beats (framepos_t, Evoral::Beats) const;
 363         Evoral::Beats framewalk_to_beats (framepos_t pos, framecnt_t distance) const;
 364
 365         static const Tempo& default_tempo() { return _default_tempo; }
 366         static const Meter& default_meter() { return _default_meter; }
 367
 368         const Tempo tempo_at (const framepos_t& frame) const;
 369         double frames_per_beat_at (const framepos_t&, const framecnt_t& sr) const;
 370
 371         const Meter& meter_at (framepos_t) const;
 372
 373         const TempoSection& tempo_section_at (framepos_t frame) const;
 374         const MeterSection& meter_section_at (framepos_t frame) const;
 375
 376         void add_tempo (const Tempo&, const double& pulse, TempoSection::Type type);
 377         void add_tempo (const Tempo&, const framepos_t& frame, TempoSection::Type type);
 378
 379         void add_meter (const Meter&, const double& beat, const Timecode::BBT_Time& where);
 380         void add_meter (const Meter&, const framepos_t& frame);
 381
 382         void remove_tempo (const TempoSection&, bool send_signal);
 383         void remove_meter (const MeterSection&, bool send_signal);
 384
 385         framepos_t predict_tempo_frame (TempoSection* section, const Tempo& bpm, const Timecode::BBT_Time& bbt);
 386         double predict_tempo_pulse (TempoSection* section, const Tempo& bpm, const framepos_t& frame);
 387
 388         void replace_tempo (const TempoSection&, const Tempo&, const double& where, TempoSection::Type type);
 389         void replace_tempo (const TempoSection&, const Tempo&, const framepos_t& frame, TempoSection::Type type);
 390
 391         void gui_move_tempo_frame (TempoSection*, const Tempo& bpm, const framepos_t& frame);
 392         void gui_move_tempo_beat (TempoSection*, const Tempo& bpm, const double& frame);
 393         void gui_move_meter (MeterSection*, const Meter& mt, const framepos_t& frame);
 394         void gui_move_meter (MeterSection*, const Meter& mt, const double& beat);
 395         bool gui_change_tempo (TempoSection*, const Tempo& bpm);
 396
 397         bool can_solve_bbt (TempoSection* section, const Tempo& bpm, const Timecode::BBT_Time& bbt);
 398
 399         void replace_meter (const MeterSection&, const Meter&, const Timecode::BBT_Time& where);
 400         void replace_meter (const MeterSection&, const Meter&, const framepos_t& frame);
 401
 402         framepos_t round_to_bar  (framepos_t frame, RoundMode dir);
 403         framepos_t round_to_beat (framepos_t frame, RoundMode dir);
 404         framepos_t round_to_beat_subdivision (framepos_t fr, int sub_num, RoundMode dir);
 405
 406         void set_length (framepos_t frames);
 407
 408         XMLNode& get_state (void);
 409         int set_state (const XMLNode&, int version);
 410
 411         void dump (const Metrics& metrics, std::ostream&) const;
 412         void clear ();
 413
 414         TempoMetric metric_at (Timecode::BBT_Time bbt) const;
 415
 416         /** Return the TempoMetric at frame @p t, and point @p last to the latest
 417          * metric change <= t, if it is non-NULL.
 418          */
 419         TempoMetric metric_at (framepos_t, Metrics::const_iterator* last=NULL) const;
 420
 421         Metrics::const_iterator metrics_end() { return _metrics.end(); }
 422
 423         void change_existing_tempo_at (framepos_t, double bpm, double note_type);
 424         void change_initial_tempo (double bpm, double note_type);
 425
 426         void insert_time (framepos_t, framecnt_t);
 427         bool remove_time (framepos_t where, framecnt_t amount);  //returns true if anything was moved
 428
 429         int n_tempos () const;
 430         int n_meters () const;
 431
 432         framecnt_t frame_rate () const { return _frame_rate; }
 433
 434         double bbt_to_beats (const Timecode::BBT_Time& bbt);
 435         Timecode::BBT_Time beats_to_bbt (const double& beats);
 436         Timecode::BBT_Time pulse_to_bbt (const double& pulse);
 437
 438         double pulse_at_beat (const double& beat) const;
 439         double beat_at_pulse (const double& pulse) const;
 440
 441         PBD::Signal0<void> MetricPositionChanged;
 442
 443 private:
 444         double pulse_at_beat_locked (const Metrics& metrics, const double& beat) const;
 445         double beat_at_pulse_locked (const Metrics& metrics, const double& pulse) const;
 446         double pulse_at_frame_locked (const Metrics& metrics, const framecnt_t& frame) const;
 447         framecnt_t frame_at_pulse_locked (const Metrics& metrics, const double& beat) const;
 448
 449         double beat_offset_at (const Metrics& metrics, const double& beat) const;
 450         frameoffset_t frame_offset_at (const Metrics& metrics, const framepos_t& frame) const;
 451
 452         double beat_at_frame_locked (const Metrics& metrics, const framecnt_t& frame) const;
 453         framecnt_t frame_at_beat_locked (const Metrics& metrics, const double& beat) const;
 454         double bbt_to_beats_locked (const Metrics& metrics, const Timecode::BBT_Time& bbt) const ;
 455         Timecode::BBT_Time beats_to_bbt_locked (const Metrics& metrics, const double& beats) const;
 456
 457         framepos_t frame_time_locked (const Metrics& metrics, const Timecode::BBT_Time&) const;
 458
 459         const MeterSection& meter_section_at_locked (framepos_t frame) const;
 460         const TempoSection& tempo_section_at_locked (framepos_t frame) const;
 461
 462         bool check_solved (Metrics& metrics, bool by_frame);
 463         bool solve_map (Metrics& metrics, TempoSection* section, const Tempo& bpm, const framepos_t& frame);
 464         bool solve_map (Metrics& metrics, TempoSection* section, const Tempo& bpm, const double& pulse);
 465         void solve_map (Metrics& metrics, MeterSection* section, const Meter& mt, const framepos_t& frame);
 466         void solve_map (Metrics& metrics, MeterSection* section, const Meter& mt, const double& pulse);
 467
 468         friend class ::BBTTest;
 469         friend class ::FrameposPlusBeatsTest;
 470         friend class ::TempoTest;
 471
 472         static Tempo    _default_tempo;
 473         static Meter    _default_meter;
 474
 475         Metrics                       _metrics;
 476         framecnt_t                    _frame_rate;
 477         mutable Glib::Threads::RWLock lock;
 478
 479         void recompute_tempos (Metrics& metrics);
 480         void recompute_meters (Metrics& metrics);
 481         void recompute_map (Metrics& metrics, framepos_t end = -1);
 482
 483         framepos_t round_to_type (framepos_t fr, RoundMode dir, BBTPointType);
 484
 485         const MeterSection& first_meter() const;
 486         MeterSection&       first_meter();
 487         const TempoSection& first_tempo() const;
 488         TempoSection&       first_tempo();
 489
 490         void do_insert (MetricSection* section);
 491
 492         void add_tempo_locked (const Tempo&, double pulse, bool recompute, TempoSection::Type type);
 493         void add_tempo_locked (const Tempo&, framepos_t frame, bool recompute, TempoSection::Type type);
 494
 495         void add_meter_locked (const Meter&, double beat, Timecode::BBT_Time where, bool recompute);
 496         void add_meter_locked (const Meter&, framepos_t frame, bool recompute);
 497
 498         bool remove_tempo_locked (const TempoSection&);
 499         bool remove_meter_locked (const MeterSection&);
 500
 501         TempoSection* copy_metrics_and_point (Metrics& copy, TempoSection* section);
 502 };
 503
 504 }; /* namespace ARDOUR */
 505
 506 std::ostream& operator<< (std::ostream&, const ARDOUR::Meter&);
 507 std::ostream& operator<< (std::ostream&, const ARDOUR::Tempo&);
 508 std::ostream& operator<< (std::ostream&, const ARDOUR::MetricSection&);
 509
 510 #endif /* __ardour_tempo_h__ */