57c6ced2759b799f87adf7ccfd9e6b4b83bf2b98
[ardour.git] / 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 FrameposMinusBeatsTest;
41 class TempoTest;
42 class XMLNode;
43
44 namespace ARDOUR {
45
46 class Meter;
47 class TempoMap;
48
49 /** Tempo, the speed at which musical time progresses (BPM). */
50 class LIBARDOUR_API Tempo {
51   public:
52         /**
53          * @param bpm Beats Per Minute
54          * @param type Note Type (default `4': quarter note)
55          */
56         Tempo (double bpm, double type=4.0) // defaulting to quarter note
57                 : _beats_per_minute (bpm), _note_type(type) {}
58
59         /*
60            quarter note beats as distinct from a beat derived from meter and pulse.
61         */
62         double beats_per_minute () const { return _beats_per_minute; }
63         void set_beats_per_minute (double bpm) { _beats_per_minute = bpm; }
64         double note_type () const { return _note_type; }
65         /** audio samples per quarter note beat.
66          * this is only useful for constant tempo and should not be used.
67          * if you want an instantaneous value for this, use frames_per_beat_at() instead.
68          * @param sr samplerate
69          */
70         double frames_per_beat (framecnt_t sr) const {
71                 return (60.0 * sr) / _beats_per_minute;
72         }
73
74   protected:
75         double _beats_per_minute;
76         double _note_type;
77 };
78
79 /** Meter, or time signature (beats per bar, and which note type is a beat). */
80 class LIBARDOUR_API Meter {
81   public:
82         Meter (double dpb, double bt)
83                 : _divisions_per_bar (dpb), _note_type (bt) {}
84
85         double divisions_per_bar () const { return _divisions_per_bar; }
86         double note_divisor() const { return _note_type; }
87
88         double frames_per_bar (const Tempo&, framecnt_t sr) const;
89         double frames_per_grid (const Tempo&, framecnt_t sr) const;
90
91   protected:
92         /** The number of divisions in a bar.  This is a floating point value because
93             there are musical traditions on our planet that do not limit
94             themselves to integral numbers of beats per bar.
95         */
96         double _divisions_per_bar;
97
98         /** The type of "note" that a division represents.  For example, 4.0 is
99             a quarter (crotchet) note, 8.0 is an eighth (quaver) note, etc.
100         */
101         double _note_type;
102 };
103
104 /** A section of timeline with a certain Tempo or Meter. */
105 class LIBARDOUR_API MetricSection {
106   public:
107         MetricSection (double pulse, double minute, PositionLockStyle pls, bool is_tempo, framecnt_t sample_rate)
108                 : _pulse (pulse), _minute (minute), _movable (true), _position_lock_style (pls), _is_tempo (is_tempo), _sample_rate (sample_rate) {}
109
110         virtual ~MetricSection() {}
111
112         const double& pulse () const { return _pulse; }
113         void set_pulse (double pulse) { _pulse = pulse; }
114
115         double minute() const { return _minute; }
116         virtual void set_minute (double m) {
117                 _minute = m;
118         }
119
120         framepos_t frame () const { return frame_at_minute (_minute); }
121
122         void set_movable (bool yn) { _movable = yn; }
123         bool movable() const { return _movable; }
124
125         /* MeterSections are not stateful in the full sense,
126            but we do want them to control their own
127            XML state information.
128         */
129         virtual XMLNode& get_state() const = 0;
130
131         PositionLockStyle position_lock_style () const { return _position_lock_style; }
132         void set_position_lock_style (PositionLockStyle ps) { _position_lock_style = ps; }
133         bool is_tempo () const { return _is_tempo; }
134
135         framepos_t frame_at_minute (const double& time) const;
136         double minute_at_frame (const framepos_t& frame) const;
137
138 private:
139
140         double             _pulse;
141         double             _minute;
142         bool               _movable;
143         PositionLockStyle  _position_lock_style;
144         const bool         _is_tempo;
145         framecnt_t         _sample_rate;
146 };
147
148 /** A section of timeline with a certain Meter. */
149 class LIBARDOUR_API MeterSection : public MetricSection, public Meter {
150   public:
151         MeterSection (double pulse, double minute, double beat, const Timecode::BBT_Time& bbt, double bpb, double note_type, PositionLockStyle pls, framecnt_t sr)
152                 : MetricSection (pulse, minute, pls, false, sr), Meter (bpb, note_type), _bbt (bbt),  _beat (beat) {}
153
154         MeterSection (const XMLNode&, const framecnt_t sample_rate);
155
156         static const std::string xml_state_node_name;
157
158         XMLNode& get_state() const;
159
160         void set_beat (std::pair<double, Timecode::BBT_Time>& w) {
161                 _beat = w.first;
162                 _bbt = w.second;
163         }
164
165         const Timecode::BBT_Time& bbt() const { return _bbt; }
166         const double& beat () const { return _beat; }
167         void set_beat (double beat) { _beat = beat; }
168
169 private:
170         Timecode::BBT_Time _bbt;
171         double _beat;
172 };
173
174 /** A section of timeline with a certain Tempo. */
175 class LIBARDOUR_API TempoSection : public MetricSection, public Tempo {
176   public:
177         enum Type {
178                 Ramp,
179                 Constant,
180         };
181
182         TempoSection (const double& pulse, const double& minute, double qpm, double note_type, Type tempo_type, PositionLockStyle pls, framecnt_t sr)
183                 : MetricSection (pulse, minute, pls, true, sr), Tempo (qpm, note_type), _type (tempo_type), _c_func (0.0), _active (true), _locked_to_meter (false)  {}
184
185         TempoSection (const XMLNode&, const framecnt_t sample_rate);
186
187         static const std::string xml_state_node_name;
188
189         XMLNode& get_state() const;
190
191         double c_func () const { return _c_func; }
192         void set_c_func (double c_func) { _c_func = c_func; }
193
194         void set_type (Type type);
195         Type type () const { return _type; }
196
197         bool active () const { return _active; }
198         void set_active (bool yn) { _active = yn; }
199
200         bool locked_to_meter ()  const { return _locked_to_meter; }
201         void set_locked_to_meter (bool yn) { _locked_to_meter = yn; }
202
203         double tempo_at_minute (const double& minute) const;
204         double minute_at_tempo (const double& bpm, const double& pulse) const;
205
206         double tempo_at_pulse (const double& pulse) const;
207         double pulse_at_tempo (const double& bpm, const double& minute) const;
208
209         double pulse_at_minute (const double& minute) const;
210         double minute_at_pulse (const double& pulse) const;
211
212         double compute_c_func_pulse (const double& end_bpm, const double& end_pulse) const;
213         double compute_c_func_minute (const double& end_bpm, const double& end_minute) const;
214
215         Timecode::BBT_Time legacy_bbt () { return _legacy_bbt; }
216
217   private:
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 _tempo_at_time (const double& time) const;
227         double _time_at_tempo (const double& tempo) const;
228
229         double _tempo_at_pulse (const double& pulse) const;
230         double _pulse_at_tempo (const double& 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         Type _type;
244         double _c_func;
245         bool _active;
246         bool _locked_to_meter;
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), _minute (0.0), _pulse (0.0) {}
259
260         void set_tempo (const Tempo& t)              { _tempo = &t; }
261         void set_meter (const Meter& m)              { _meter = &m; }
262         void set_minute (double m)                   { _minute = m; }
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_minute (section->minute());
275                 set_pulse (section->pulse());
276         }
277
278         const Meter&              meter() const { return *_meter; }
279         const Tempo&              tempo() const { return *_tempo; }
280         double                    minute() const { return _minute; }
281         const double&             pulse() const { return _pulse; }
282
283   private:
284         const Meter*       _meter;
285         const Tempo*       _tempo;
286         double             _minute;
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                 Meter               meter;
309                 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.divisions_per_bar(), m.note_divisor()), 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, uint32_t bar_mod = 0);
331
332         static const Tempo& default_tempo() { return _default_tempo; }
333         static const Meter& default_meter() { return _default_meter; }
334
335         /* because tempos may be ramped, this is only valid for the instant requested.*/
336         double frames_per_beat_at (const framepos_t&, const framecnt_t& sr) const;
337
338         const TempoSection& tempo_section_at_frame (framepos_t frame) const;
339         const MeterSection& meter_section_at_frame (framepos_t frame) const;
340         const MeterSection& meter_section_at_beat (double beat) const;
341
342         /** add a tempo section locked to pls. ignored values will be set in recompute_tempi()
343          * @param pulse pulse position of new section. ignored if pls == AudioTime
344          * @param frame frame position of new section. ignored if pls == MusicTime
345          * @param type type of new tempo section (Ramp, Constant)
346          */
347         TempoSection* add_tempo (const Tempo&, const double& pulse, const framepos_t& frame, TempoSection::Type type, PositionLockStyle pls);
348
349         /** add an meter section locked to pls.. ignored values will be set in recompute_meters()
350          * @param beat beat position of new section
351          * @param where bbt position of new section
352          * @param frame frame position of new section. ignored if pls == MusicTime
353          */
354         MeterSection* add_meter (const Meter&, const double& beat, const Timecode::BBT_Time& where, PositionLockStyle pls);
355
356         void remove_tempo (const TempoSection&, bool send_signal);
357         void remove_meter (const MeterSection&, bool send_signal);
358
359         void replace_tempo (const TempoSection&, const Tempo&, const double& pulse, const framepos_t& frame
360                             , TempoSection::Type type, PositionLockStyle pls);
361
362         void replace_meter (const MeterSection&, const Meter&, const Timecode::BBT_Time& where, PositionLockStyle pls);
363
364         framepos_t round_to_bar  (framepos_t frame, RoundMode dir);
365         framepos_t round_to_beat (framepos_t frame, RoundMode dir);
366         framepos_t round_to_beat_subdivision (framepos_t fr, int sub_num, RoundMode dir);
367         framepos_t round_to_quarter_note_subdivision (framepos_t fr, int sub_num, RoundMode dir);
368
369         void set_length (framepos_t frames);
370
371         XMLNode& get_state (void);
372         int set_state (const XMLNode&, int version);
373
374         void dump (const Metrics& metrics, std::ostream&) const;
375         void clear ();
376
377         TempoMetric metric_at (Timecode::BBT_Time bbt) const;
378
379         /** Return the TempoMetric at frame @p t, and point @p last to the latest
380          * metric change <= t, if it is non-NULL.
381          */
382         TempoMetric metric_at (framepos_t, Metrics::const_iterator* last=NULL) const;
383
384         Metrics::const_iterator metrics_end() { return _metrics.end(); }
385
386         void change_existing_tempo_at (framepos_t, double bpm, double note_type);
387         void change_initial_tempo (double bpm, double note_type);
388
389         void insert_time (framepos_t, framecnt_t);
390         bool remove_time (framepos_t where, framecnt_t amount);  //returns true if anything was moved
391
392         int n_tempos () const;
393         int n_meters () const;
394
395         framecnt_t frame_rate () const { return _frame_rate; }
396
397         /* TEMPO- AND METER-SENSITIVE FUNCTIONS
398
399            bbt_at_frame(), frame_at_bbt(), beat_at_frame(), frame_at_beat()
400            and bbt_duration_at()
401            are all sensitive to tempo and meter, and will give answers
402            that align with the grid formed by tempo and meter sections.
403
404            They SHOULD NOT be used to determine the position of events
405            whose location is canonically defined in Evoral::Beats.
406         */
407
408         double beat_at_frame (const framecnt_t& frame) const;
409         framepos_t frame_at_beat (const double& beat) const;
410
411         const Meter& meter_at_frame (framepos_t) const;
412
413         /* bbt - it's nearly always better to use meter-based beat (above)
414            unless tick resolution is desirable.
415         */
416         Timecode::BBT_Time bbt_at_frame (framepos_t when);
417         Timecode::BBT_Time bbt_at_frame_rt (framepos_t when);
418         framepos_t frame_at_bbt (const Timecode::BBT_Time&);
419
420         double beat_at_bbt (const Timecode::BBT_Time& bbt);
421         Timecode::BBT_Time bbt_at_beat (const double& beats);
422
423         double quarter_note_at_bbt (const Timecode::BBT_Time& bbt);
424         double quarter_note_at_bbt_rt (const Timecode::BBT_Time& bbt);
425         Timecode::BBT_Time bbt_at_quarter_note (const double& quarter_note);
426
427         framecnt_t bbt_duration_at (framepos_t, const Timecode::BBT_Time&, int dir);
428         framepos_t framepos_plus_bbt (framepos_t pos, Timecode::BBT_Time b) const;
429
430         /* TEMPO-SENSITIVE FUNCTIONS
431
432            These next 2 functions will all take tempo in account and should be
433            used to determine position (and in the last case, distance in beats)
434            when tempo matters but meter does not.
435
436            They SHOULD be used to determine the position of events
437            whose location is canonically defined in Evoral::Beats.
438         */
439
440         framepos_t framepos_plus_qn (framepos_t, Evoral::Beats) const;
441         Evoral::Beats framewalk_to_qn (framepos_t pos, framecnt_t distance) const;
442
443         /* quarter note related functions are also tempo-sensitive and ignore meter.
444         */
445         double quarter_note_at_frame (const framepos_t frame);
446         double quarter_note_at_frame_rt (const framepos_t frame);
447         framepos_t frame_at_quarter_note (const double quarter_note);
448
449         framecnt_t frames_between_quarter_notes (const double start, const double end);
450
451         double quarter_note_at_beat (const double beat);
452         double beat_at_quarter_note (const double beat);
453
454         double exact_qn_at_frame (const framepos_t& frame, const int32_t sub_num);
455         double exact_beat_at_frame (const framepos_t& frame, const int32_t sub_num);
456
457         Tempo tempo_at_frame (const framepos_t& frame) const;
458         framepos_t frame_at_tempo (const Tempo& tempo) const;
459         Tempo tempo_at_quarter_note (const double& beat) const;
460         double quarter_note_at_tempo (const Tempo& tempo) const;
461
462         void gui_move_tempo (TempoSection*, const framepos_t& frame, const int& sub_num);
463         void gui_move_meter (MeterSection*, const framepos_t& frame);
464         bool gui_change_tempo (TempoSection*, const Tempo& bpm);
465         void gui_dilate_tempo (TempoSection* tempo, const framepos_t& frame, const framepos_t& end_frame);
466
467         std::pair<double, framepos_t> predict_tempo_position (TempoSection* section, const Timecode::BBT_Time& bbt);
468         bool can_solve_bbt (TempoSection* section, const Timecode::BBT_Time& bbt);
469
470         PBD::Signal0<void> MetricPositionChanged;
471         void fix_legacy_session();
472
473 private:
474
475         double beat_at_minute_locked (const Metrics& metrics, const double& minute) const;
476         double minute_at_beat_locked (const Metrics& metrics, const double& beat) const;
477
478         double pulse_at_beat_locked (const Metrics& metrics, const double& beat) const;
479         double beat_at_pulse_locked (const Metrics& metrics, const double& pulse) const;
480
481         double pulse_at_minute_locked (const Metrics& metrics, const double& minute) const;
482         double minute_at_pulse_locked (const Metrics& metrics, const double& pulse) const;
483
484         Tempo tempo_at_minute_locked (const Metrics& metrics, const double& minute) const;
485         double minute_at_tempo_locked (const Metrics& metrics, const Tempo& tempo) const;
486
487         Tempo tempo_at_pulse_locked (const Metrics& metrics, const double& pulse) const;
488         double pulse_at_tempo_locked (const Metrics& metrics, const Tempo& tempo) const;
489
490         Timecode::BBT_Time bbt_at_minute_locked (const Metrics& metrics, const double& minute) const;
491         double minute_at_bbt_locked (const Metrics& metrics, const Timecode::BBT_Time&) const;
492
493         double beat_at_bbt_locked (const Metrics& metrics, const Timecode::BBT_Time& bbt) const ;
494         Timecode::BBT_Time bbt_at_beat_locked (const Metrics& metrics, const double& beats) const;
495
496         double pulse_at_bbt_locked (const Metrics& metrics, const Timecode::BBT_Time& bbt) const;
497         Timecode::BBT_Time bbt_at_pulse_locked (const Metrics& metrics, const double& pulse) const;
498
499         double minute_at_quarter_note_locked (const Metrics& metrics, const double quarter_note) const;
500         double quarter_note_at_minute_locked (const Metrics& metrics, const double minute) const;
501
502         double quarter_note_at_beat_locked (const Metrics& metrics, const double beat) const;
503         double beat_at_quarter_note_locked (const Metrics& metrics, const double beat) const;
504
505         double minutes_between_quarter_notes_locked (const Metrics& metrics, const double start_qn, const double end_qn);
506
507         const TempoSection& tempo_section_at_minute_locked (const Metrics& metrics, double minute) const;
508         const TempoSection& tempo_section_at_beat_locked (const Metrics& metrics, const double& beat) const;
509
510         const MeterSection& meter_section_at_minute_locked (const Metrics& metrics, double minute) const;
511         const MeterSection& meter_section_at_beat_locked (const Metrics& metrics, const double& beat) const;
512
513         bool check_solved (const Metrics& metrics) const;
514         bool set_active_tempos (const Metrics& metrics, const framepos_t& frame);
515
516         bool solve_map_minute (Metrics& metrics, TempoSection* section, const double& minute);
517         bool solve_map_pulse (Metrics& metrics, TempoSection* section, const double& pulse);
518         bool solve_map_minute (Metrics& metrics, MeterSection* section, const double& minute);
519         bool solve_map_bbt (Metrics& metrics, MeterSection* section, const Timecode::BBT_Time& bbt);
520
521         double exact_beat_at_frame_locked (const Metrics& metrics, const framepos_t& frame, const int32_t sub_num);
522         double exact_qn_at_frame_locked (const Metrics& metrics, const framepos_t& frame, const int32_t sub_num);
523
524         double minute_at_frame (const framepos_t frame) const;
525         framepos_t frame_at_minute (const double minute) const;
526
527         friend class ::BBTTest;
528         friend class ::FrameposPlusBeatsTest;
529         friend class ::FrameposMinusBeatsTest;
530         friend class ::TempoTest;
531
532         static Tempo    _default_tempo;
533         static Meter    _default_meter;
534
535         Metrics                       _metrics;
536         framecnt_t                    _frame_rate;
537         mutable Glib::Threads::RWLock lock;
538
539         void recompute_tempi (Metrics& metrics);
540         void recompute_meters (Metrics& metrics);
541         void recompute_map (Metrics& metrics, framepos_t end = -1);
542
543         framepos_t round_to_type (framepos_t fr, RoundMode dir, BBTPointType);
544
545         const MeterSection& first_meter() const;
546         MeterSection&       first_meter();
547         const TempoSection& first_tempo() const;
548         TempoSection&       first_tempo();
549
550         void do_insert (MetricSection* section);
551
552         TempoSection* add_tempo_locked (const Tempo&, double pulse, double minute
553                                , TempoSection::Type type, PositionLockStyle pls, bool recompute, bool locked_to_meter = false);
554
555         MeterSection* add_meter_locked (const Meter&, double beat, const Timecode::BBT_Time& where, PositionLockStyle pls, bool recompute);
556
557         bool remove_tempo_locked (const TempoSection&);
558         bool remove_meter_locked (const MeterSection&);
559
560         TempoSection* copy_metrics_and_point (const Metrics& metrics, Metrics& copy, TempoSection* section);
561         MeterSection* copy_metrics_and_point (const Metrics& metrics, Metrics& copy, MeterSection* section);
562 };
563
564 }; /* namespace ARDOUR */
565
566 std::ostream& operator<< (std::ostream&, const ARDOUR::Meter&);
567 std::ostream& operator<< (std::ostream&, const ARDOUR::Tempo&);
568 std::ostream& operator<< (std::ostream&, const ARDOUR::MetricSection&);
569
570 #endif /* __ardour_tempo_h__ */