libs/ardour/ardour/transport_master.h

   1 /*
   2     Copyright (C) 2002 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_transport_master_h__
  21 #define __ardour_transport_master_h__
  22
  23 #include <vector>
  24
  25 #include <boost/optional.hpp>
  26 #include <boost/atomic.hpp>
  27
  28 #include <glibmm/threads.h>
  29 #include <glibmm/timer.h>
  30
  31 #include <ltc.h>
  32
  33 #include "pbd/i18n.h"
  34 #include "pbd/properties.h"
  35 #include "pbd/signals.h"
  36 #include "pbd/stateful.h"
  37
  38 #include "temporal/time.h"
  39
  40 #include "ardour/libardour_visibility.h"
  41 #include "ardour/region.h" /* for Properties::locked */
  42 #include "ardour/types.h"
  43
  44 #include "midi++/parser.h"
  45 #include "midi++/types.h"
  46
  47 /* used for delta_string(): */
  48 #define PLUSMINUS(A) ( ((A)<0) ? "-" : (((A)>0) ? "+" : "\u00B1") )
  49 #define LEADINGZERO(A) ( (A)<10 ? "   " : (A)<100 ? "  " : (A)<1000 ? " " : "" )
  50
  51 namespace ARDOUR {
  52
  53 class TempoMap;
  54 class Session;
  55 class AudioEngine;
  56 class Location;
  57 class MidiPort;
  58 class AudioPort;
  59 class Port;
  60
  61 namespace Properties {
  62         LIBARDOUR_API extern PBD::PropertyDescriptor<bool> fr2997;
  63         LIBARDOUR_API extern PBD::PropertyDescriptor<bool> collect;
  64         LIBARDOUR_API extern PBD::PropertyDescriptor<bool> connected;
  65         LIBARDOUR_API extern PBD::PropertyDescriptor<bool> sclock_synced;
  66         LIBARDOUR_API extern PBD::PropertyDescriptor<ARDOUR::TransportRequestType> allowed_transport_requests;
  67 };
  68
  69 struct LIBARDOUR_API SafeTime {
  70
  71         /* This object uses memory fences to provide psuedo-atomic updating of
  72          * non-atomic data. If after reading guard1 and guard2 with correct
  73          * memory fencing they have the same value, then we know that the other
  74          * members are all internally consistent.
  75          *
  76          * Traditionally, one might do this with a mutex, but this object
  77          * provides lock-free write update. The reader might block while
  78          * waiting for consistency, but this is extraordinarily unlikely. In
  79          * this sense, the design is similar to a spinlock.
  80          *
  81          * any update starts by incrementing guard1, with a memory fence to
  82          * ensure no reordering of this w.r.t later operations.
  83          *
  84          * then we update the "non-atomic" data members.
  85          *
  86          * then we update guard2, with another memory fence to prevent
  87          * reordering.
  88          *
  89          * ergo, if guard1 == guard2, the update of the non-atomic members is
  90          * complete and the values stored there are consistent.
  91          */
  92
  93         boost::atomic<int> guard1;
  94         samplepos_t        position;
  95         samplepos_t        timestamp;
  96         double             speed;
  97         boost::atomic<int> guard2;
  98
  99         SafeTime() {
 100                 guard1.store (0);
 101                 position = 0;
 102                 timestamp = 0;
 103                 speed = 0;
 104                 guard2.store (0);
 105         }
 106
 107         void reset () {
 108                 guard1.store (0);
 109                 position = 0;
 110                 timestamp  = 0;
 111                 speed = 0;
 112                 guard2.store (0);
 113         }
 114
 115         void update (samplepos_t p, samplepos_t t, double s) {
 116                 guard1.fetch_add (1, boost::memory_order_acquire);
 117                 position = p;
 118                 timestamp = t;
 119                 speed = s;
 120                 guard2.fetch_add (1, boost::memory_order_acquire);
 121         }
 122
 123         void safe_read (SafeTime& dst) const {
 124                 int tries = 0;
 125
 126                 do {
 127                         if (tries == 10) {
 128                                 std::cerr << X_("SafeTime: atomic read of current time failed, sleeping!") << std::endl;
 129                                 Glib::usleep (20);
 130                                 tries = 0;
 131                         }
 132                         dst.guard1.store (guard1.load (boost::memory_order_seq_cst), boost::memory_order_seq_cst);
 133                         dst.position = position;
 134                         dst.timestamp = timestamp;
 135                         dst.speed = speed;
 136                         dst.guard2.store (guard2.load (boost::memory_order_seq_cst), boost::memory_order_seq_cst);
 137                         tries++;
 138
 139                 } while (dst.guard1.load (boost::memory_order_seq_cst) != dst.guard2.load (boost::memory_order_seq_cst));
 140         }
 141 };
 142
 143 /**
 144  * @class TransportMaster
 145  *
 146  * @brief The TransportMaster interface can be used to sync ARDOURs tempo to an external source
 147  * like MTC, MIDI Clock, etc. as well as a single internal pseudo master we
 148  * call "UI" because it is controlled from any of the user interfaces for
 149  * Ardour (GUI, control surfaces, OSC, etc.)
 150  *
 151  */
 152 class LIBARDOUR_API TransportMaster : public PBD::Stateful {
 153   public:
 154
 155         TransportMaster (SyncSource t, std::string const & name);
 156         virtual ~TransportMaster();
 157
 158         static boost::shared_ptr<TransportMaster> factory (SyncSource, std::string const &);
 159         static boost::shared_ptr<TransportMaster> factory (XMLNode const &);
 160
 161         virtual void pre_process (pframes_t nframes, samplepos_t now, boost::optional<samplepos_t>) = 0;
 162
 163         /**
 164          * This is the most important function to implement:
 165          * Each process cycle, Session::follow_slave will call this method.
 166          *  and after the method call they should
 167          *
 168          * Session::follow_slave will then try to follow the given
 169          * <em>position</em> using a delay locked loop (DLL),
 170          * starting with the first given transport speed.
 171          * If the values of speed and position contradict each other,
 172          * ARDOUR will always follow the position and disregard the speed.
 173          * Although, a correct speed is important so that ARDOUR
 174          * can sync to the master time source quickly.
 175          *
 176          * For background information on delay locked loops,
 177          * see http://www.kokkinizita.net/papers/usingdll.pdf
 178          *
 179          * The method has the following precondition:
 180          * <ul>
 181          *   <li>
 182          *       TransportMaster::ok() should return true, otherwise playback will stop
 183          *       immediately and the method will not be called
 184          *   </li>
 185          *   <li>
 186          *     when the references speed and position are passed into the TransportMaster
 187          *     they are uninitialized
 188          *   </li>
 189          * </ul>
 190          *
 191          * After the method call the following postconditions should be met:
 192          * <ul>
 193          *    <li>
 194          *       The first position value on transport start should be 0,
 195          *       otherwise ARDOUR will try to locate to the new position
 196          *       rather than move to it
 197          *    </li>
 198          *    <li>
 199          *      the references speed and position should be assigned
 200          *      to the TransportMasters current requested transport speed
 201          *      and transport position.
 202          *    </li>
 203          *   <li>
 204          *     TransportMaster::resolution() should be greater than the maximum distance of
 205          *     ARDOURs transport position to the slaves requested transport position.
 206          *   </li>
 207          *   <li>TransportMaster::locked() should return true, otherwise Session::no_roll will be called</li>
 208          *   <li>TransportMaster::starting() should be false, otherwise the transport will not move until it becomes true</li>   *
 209          * </ul>
 210          *
 211          * @param speed - The transport speed requested
 212          * @param position - The transport position requested
 213          * @return - The return value is currently ignored (see Session::follow_slave)
 214          */
 215         virtual bool speed_and_position (double& speed, samplepos_t& position, samplepos_t & lp, samplepos_t & when, samplepos_t now);
 216
 217         /**
 218          * reports to ARDOUR whether the TransportMaster is currently synced to its external
 219          * time source.
 220          *
 221          * @return - when returning false, the transport will stop rolling
 222          */
 223         virtual bool locked() const = 0;
 224
 225         /**
 226          * reports to ARDOUR whether the slave is in a sane state
 227          *
 228          * @return - when returning false, the transport will be stopped and the slave
 229          * disconnected from ARDOUR.
 230          */
 231         virtual bool ok() const = 0;
 232
 233         /**
 234          * reports to ARDOUR whether the slave is in the process of starting
 235          * to roll
 236          *
 237          * @return - when returning false, transport will not move until this method returns true
 238          */
 239         virtual bool starting() const { return false; }
 240
 241         /**
 242          * @return - the timing resolution of the TransportMaster - If the distance of ARDOURs transport
 243          * to the slave becomes greater than the resolution, sound will stop
 244          */
 245         virtual samplecnt_t resolution() const = 0;
 246
 247         /**
 248          * @return - when returning true, ARDOUR will wait for seekahead_distance() before transport
 249          * starts rolling
 250          */
 251         virtual bool requires_seekahead () const = 0;
 252
 253         /**
 254          * @return the number of samples that this slave wants to seek ahead. Relevant
 255          * only if requires_seekahead() returns true.
 256          */
 257
 258         virtual samplecnt_t seekahead_distance() const { return 0; }
 259
 260         /**
 261          * @return - when returning true, ARDOUR will use transport speed 1.0 no matter what
 262          *           the slave returns
 263          */
 264         virtual bool sample_clock_synced() const { return _sclock_synced; }
 265         virtual void set_sample_clock_synced (bool);
 266
 267         /**
 268          * @return - current time-delta between engine and sync-source
 269          */
 270         virtual std::string delta_string() const { return ""; }
 271
 272         sampleoffset_t current_delta() const { return _current_delta; }
 273
 274         /* this is intended to be used by a UI and polled from a timeout. it should
 275            return a string describing the current position of the TC source. it
 276            should NOT do any computation, but should use a cached value
 277            of the TC source position.
 278         */
 279         virtual std::string position_string() const = 0;
 280
 281         virtual bool can_loop() const { return false; }
 282
 283         virtual Location* loop_location() const { return 0; }
 284         bool has_loop() const { return loop_location() != 0; }
 285
 286         SyncSource type() const { return _type; }
 287         TransportRequestSource request_type() const {
 288                 switch (_type) {
 289                 case Engine: /* also JACK */
 290                         return TRS_Engine;
 291                 case MTC:
 292                         return TRS_MTC;
 293                 case LTC:
 294                         return TRS_LTC;
 295                 case MIDIClock:
 296                         break;
 297                 }
 298                 return TRS_MIDIClock;
 299         }
 300
 301         std::string name() const { return _name; }
 302         void set_name (std::string const &);
 303
 304         int set_state (XMLNode const &, int);
 305         XMLNode& get_state();
 306
 307         static const std::string state_node_name;
 308         static void make_property_quarks ();
 309
 310         virtual void set_session (Session*);
 311
 312         boost::shared_ptr<Port> port() const { return _port; }
 313
 314         bool check_collect();
 315         virtual void set_collect (bool);
 316         bool collect() const { return _collect; }
 317
 318         /* called whenever the manager starts collecting (processing) this
 319            transport master. Typically will re-initialize any state used to
 320            deal with incoming data.
 321         */
 322         virtual void init() = 0;
 323
 324         virtual void check_backend() {}
 325         virtual bool allow_request (TransportRequestSource, TransportRequestType) const;
 326
 327         TransportRequestType request_mask() const { return _request_mask; }
 328         void set_request_mask (TransportRequestType);
 329
 330         void get_current (double&, samplepos_t&, samplepos_t);
 331
 332   protected:
 333         SyncSource      _type;
 334         PBD::Property<std::string>   _name;
 335         Session*        _session;
 336         sampleoffset_t  _current_delta;
 337         bool            _pending_collect;
 338         PBD::Property<TransportRequestType> _request_mask; /* lists transport requests still accepted when we're in control */
 339         PBD::Property<bool> _locked;
 340         PBD::Property<bool> _sclock_synced;
 341         PBD::Property<bool> _collect;
 342         PBD::Property<bool> _connected;
 343
 344         SafeTime current;
 345
 346         /* DLL - chase incoming data */
 347
 348         int    transport_direction;
 349         int    dll_initstate;
 350
 351         double t0;
 352         double t1;
 353         double e2;
 354         double b, c;
 355
 356         boost::shared_ptr<Port>  _port;
 357
 358         PBD::ScopedConnection port_connection;
 359         bool connection_handler (boost::weak_ptr<ARDOUR::Port>, std::string name1, boost::weak_ptr<ARDOUR::Port>, std::string name2, bool yn);
 360
 361         PBD::ScopedConnection backend_connection;
 362
 363         virtual void register_properties ();
 364 };
 365
 366 /** a helper class for any TransportMaster that receives its input via a MIDI
 367  * port
 368  */
 369 class LIBARDOUR_API TransportMasterViaMIDI {
 370   public:
 371         boost::shared_ptr<MidiPort> midi_port() const { return _midi_port; }
 372         boost::shared_ptr<Port> create_midi_port (std::string const & port_name);
 373
 374   protected:
 375         TransportMasterViaMIDI () {};
 376
 377         MIDI::Parser                 parser;
 378         boost::shared_ptr<MidiPort> _midi_port;
 379 };
 380
 381 class LIBARDOUR_API TimecodeTransportMaster : public TransportMaster {
 382   public:
 383         TimecodeTransportMaster (std::string const & name, SyncSource type);
 384
 385         virtual Timecode::TimecodeFormat apparent_timecode_format() const = 0;
 386         samplepos_t        timecode_offset;
 387         bool              timecode_negative_offset;
 388
 389         bool fr2997() const { return _fr2997; }
 390         void set_fr2997 (bool);
 391
 392   protected:
 393         void register_properties ();
 394
 395   private:
 396         PBD::Property<bool> _fr2997;
 397 };
 398
 399 class LIBARDOUR_API MTC_TransportMaster : public TimecodeTransportMaster, public TransportMasterViaMIDI {
 400   public:
 401         MTC_TransportMaster (std::string const &);
 402         ~MTC_TransportMaster ();
 403
 404         void set_session (Session*);
 405
 406         void pre_process (pframes_t nframes, samplepos_t now, boost::optional<samplepos_t>);
 407
 408         bool locked() const;
 409         bool ok() const;
 410         void handle_locate (const MIDI::byte*);
 411
 412         samplecnt_t resolution () const;
 413         bool requires_seekahead () const { return false; }
 414         samplecnt_t seekahead_distance() const;
 415         void init ();
 416
 417         Timecode::TimecodeFormat apparent_timecode_format() const;
 418         std::string position_string() const;
 419         std::string delta_string() const;
 420
 421   private:
 422         PBD::ScopedConnectionList port_connections;
 423         PBD::ScopedConnection     config_connection;
 424         bool        can_notify_on_unknown_rate;
 425
 426         static const int sample_tolerance;
 427
 428         samplepos_t    mtc_frame;               /* current time */
 429         double         mtc_frame_dll;
 430         samplepos_t    last_inbound_frame;      /* when we got it; audio clocked */
 431         MIDI::byte     last_mtc_fps_byte;
 432         samplepos_t    window_begin;
 433         samplepos_t    window_end;
 434         samplepos_t    first_mtc_timestamp;
 435         bool           did_reset_tc_format;
 436         Timecode::TimecodeFormat saved_tc_format;
 437         Glib::Threads::Mutex    reset_lock;
 438         uint32_t       reset_pending;
 439         bool           reset_position;
 440         int            transport_direction;
 441         int            busy_guard1;
 442         int            busy_guard2;
 443
 444         double         speedup_due_to_tc_mismatch;
 445         double         quarter_frame_duration;
 446         Timecode::TimecodeFormat mtc_timecode;
 447         Timecode::TimecodeFormat a3e_timecode;
 448         Timecode::Time timecode;
 449         bool           printed_timecode_warning;
 450
 451         void reset (bool with_pos);
 452         void queue_reset (bool with_pos);
 453         void maybe_reset ();
 454
 455         void update_mtc_qtr (MIDI::Parser&, int, samplepos_t);
 456         void update_mtc_time (const MIDI::byte *, bool, samplepos_t);
 457         void update_mtc_status (MIDI::MTC_Status);
 458         void reset_window (samplepos_t);
 459         bool outside_window (samplepos_t) const;
 460         void init_mtc_dll(samplepos_t, double);
 461         void parse_timecode_offset();
 462         void parameter_changed(std::string const & p);
 463 };
 464
 465 class LIBARDOUR_API LTC_TransportMaster : public TimecodeTransportMaster {
 466 public:
 467         LTC_TransportMaster (std::string const &);
 468         ~LTC_TransportMaster ();
 469
 470         void set_session (Session*);
 471
 472         void pre_process (pframes_t nframes, samplepos_t now, boost::optional<samplepos_t>);
 473
 474         bool locked() const;
 475         bool ok() const;
 476
 477         samplecnt_t resolution () const;
 478         bool requires_seekahead () const { return false; }
 479         samplecnt_t seekahead_distance () const { return 0; }
 480         void init ();
 481
 482         Timecode::TimecodeFormat apparent_timecode_format() const;
 483         std::string position_string() const;
 484         std::string delta_string() const;
 485
 486   private:
 487         void parse_ltc(const pframes_t, const Sample* const, const samplecnt_t);
 488         void process_ltc(samplepos_t const);
 489         void init_dll (samplepos_t, int32_t);
 490         bool detect_discontinuity(LTCFrameExt *, int, bool);
 491         bool detect_ltc_fps(int, bool);
 492         bool equal_ltc_sample_time(LTCFrame *a, LTCFrame *b);
 493         void reset (bool with_ts = true);
 494         void resync_xrun();
 495         void resync_latency();
 496         void parse_timecode_offset();
 497         void parameter_changed(std::string const & p);
 498
 499         bool           did_reset_tc_format;
 500         Timecode::TimecodeFormat saved_tc_format;
 501
 502         LTCDecoder *   decoder;
 503         double         samples_per_ltc_frame;
 504         Timecode::Time timecode;
 505         LTCFrameExt    prev_sample;
 506         bool           fps_detected;
 507
 508         samplecnt_t    monotonic_cnt;
 509         int            delayedlocked;
 510
 511         int            ltc_detect_fps_cnt;
 512         int            ltc_detect_fps_max;
 513         bool           printed_timecode_warning;
 514         bool           sync_lock_broken;
 515         Timecode::TimecodeFormat ltc_timecode;
 516         Timecode::TimecodeFormat a3e_timecode;
 517         double         samples_per_timecode_frame;
 518
 519         PBD::ScopedConnectionList port_connections;
 520         PBD::ScopedConnection     config_connection;
 521         LatencyRange  ltc_slave_latency;
 522 };
 523
 524 class LIBARDOUR_API MIDIClock_TransportMaster : public TransportMaster, public TransportMasterViaMIDI {
 525   public:
 526         MIDIClock_TransportMaster (std::string const & name, int ppqn = 24);
 527
 528         /// Constructor for unit tests
 529         ~MIDIClock_TransportMaster ();
 530
 531         void set_session (Session*);
 532
 533         void pre_process (pframes_t nframes, samplepos_t now, boost::optional<samplepos_t>);
 534
 535         void rebind (MidiPort&);
 536
 537         bool locked() const;
 538         bool ok() const;
 539         bool starting() const;
 540
 541         samplecnt_t resolution () const;
 542         bool requires_seekahead () const { return false; }
 543         void init ();
 544
 545         std::string position_string() const;
 546         std::string delta_string() const;
 547
 548         float bpm() const { return _bpm; }
 549
 550   protected:
 551         PBD::ScopedConnectionList port_connections;
 552
 553         /// pulses per quarter note for one MIDI clock sample (default 24)
 554         int         ppqn;
 555
 556         /// the duration of one ppqn in sample time
 557         double      one_ppqn_in_samples;
 558
 559         /// the timestamp of the first MIDI clock message
 560         samplepos_t  first_timestamp;
 561
 562         /// the time stamp and should-be transport position of the last inbound MIDI clock message
 563         samplepos_t  last_timestamp;
 564         double      should_be_position;
 565
 566         /// the number of midi clock messages received (zero-based)
 567         /// since start
 568         long midi_clock_count;
 569
 570         /// a DLL to track MIDI clock
 571
 572         double _speed;
 573         bool _running;
 574         double _bpm;
 575
 576         void reset ();
 577         void start (MIDI::Parser& parser, samplepos_t timestamp);
 578         void contineu (MIDI::Parser& parser, samplepos_t timestamp);
 579         void stop (MIDI::Parser& parser, samplepos_t timestamp);
 580         void position (MIDI::Parser& parser, MIDI::byte* message, size_t size, samplepos_t timestamp);
 581         // we can't use continue because it is a C++ keyword
 582         void calculate_one_ppqn_in_samples_at(samplepos_t time);
 583         samplepos_t calculate_song_position(uint16_t song_position_in_sixteenth_notes);
 584         void calculate_filter_coefficients (double qpm);
 585         void update_midi_clock (MIDI::Parser& parser, samplepos_t timestamp);
 586 };
 587
 588 class LIBARDOUR_API Engine_TransportMaster : public TransportMaster
 589 {
 590   public:
 591         Engine_TransportMaster (AudioEngine&);
 592         ~Engine_TransportMaster  ();
 593
 594         void pre_process (pframes_t nframes, samplepos_t now,  boost::optional<samplepos_t>);
 595         bool speed_and_position (double& speed, samplepos_t& pos, samplepos_t &, samplepos_t &, samplepos_t);
 596
 597         bool starting() const { return _starting; }
 598         bool locked() const;
 599         bool ok() const;
 600         samplecnt_t resolution () const { return 1; }
 601         bool requires_seekahead () const { return false; }
 602         bool sample_clock_synced() const { return true; }
 603         void init ();
 604         void check_backend();
 605         bool allow_request (TransportRequestSource, TransportRequestType) const;
 606
 607         std::string position_string() const;
 608         std::string delta_string() const;
 609
 610   private:
 611         AudioEngine& engine;
 612         bool _starting;
 613 };
 614
 615 } /* namespace */
 616
 617 #endif /* __ardour_transport_master_h__ */