path: root/libs/ardour/ardour/slave.h

/*
    Copyright (C) 2002 Paul Davis

    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 2 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program; if not, write to the Free Software
    Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

*/

#ifndef __ardour_slave_h__
#define __ardour_slave_h__

#include <vector>

#include <glibmm/threads.h>

#include <ltc.h>

#include "pbd/signals.h"

#include "temporal/time.h"

#include "ardour/libardour_visibility.h"
#include "ardour/types.h"
#include "midi++/parser.h"
#include "midi++/types.h"


/* used for delta_string(): */
#define PLUSMINUS(A) ( ((A)<0) ? "-" : (((A)>0) ? "+" : "\u00B1") )
#define LEADINGZERO(A) ( (A)<10 ? "   " : (A)<100 ? "  " : (A)<1000 ? " " : "" )

namespace ARDOUR {

class TempoMap;
class Session;
class AudioEngine;
class MidiPort;

/**
 * @class Slave
 *
 * @brief The Slave interface can be used to sync ARDOURs tempo to an external source
 * like MTC, MIDI Clock, etc.
 *
 * The name of the interface may be a bit misleading: A subclass of Slave actually
 * acts as a time master for ARDOUR, that means ARDOUR will try to follow the
 * speed and transport position of the implementation of Slave.
 * Therefore it is rather that class, that makes ARDOUR a slave by connecting it
 * to its external time master.
 */
class LIBARDOUR_API Slave {
  public:
	Slave() { }
	virtual ~Slave() {}

	/**
	 * This is the most important function to implement:
	 * Each process cycle, Session::follow_slave will call this method.
	 *  and after the method call they should
	 *
	 * Session::follow_slave will then try to follow the given
	 * <em>position</em> using a delay locked loop (DLL),
	 * starting with the first given transport speed.
	 * If the values of speed and position contradict each other,
	 * ARDOUR will always follow the position and disregard the speed.
	 * Although, a correct speed is important so that ARDOUR
	 * can sync to the master time source quickly.
	 *
	 * For background information on delay locked loops,
	 * see http://www.kokkinizita.net/papers/usingdll.pdf
	 *
	 * The method has the following precondition:
	 * <ul>
	 *   <li>
	 *       Slave::ok() should return true, otherwise playback will stop
	 *       immediately and the method will not be called
	 *   </li>
	 *   <li>
	 *     when the references speed and position are passed into the Slave
	 *     they are uninitialized
	 *   </li>
	 * </ul>
	 *
	 * After the method call the following postconditions should be met:
	 * <ul>
	 *    <li>
	 *       The first position value on transport start should be 0,
	 *       otherwise ARDOUR will try to locate to the new position
	 *       rather than move to it
	 *    </li>
	 *    <li>
	 *      the references speed and position should be assigned
	 *      to the Slaves current requested transport speed
	 *      and transport position.
	 *    </li>
	 *   <li>
	 *     Slave::resolution() should be greater than the maximum distance of
	 *     ARDOURs transport position to the slaves requested transport position.
	 *   </li>
	 *   <li>Slave::locked() should return true, otherwise Session::no_roll will be called</li>
	 *   <li>Slave::starting() should be false, otherwise the transport will not move until it becomes true</li>	 *
	 * </ul>
	 *
	 * @param speed - The transport speed requested
	 * @param position - The transport position requested
	 * @return - The return value is currently ignored (see Session::follow_slave)
	 */
	virtual bool speed_and_position (double& speed, samplepos_t& position) = 0;

	/**
	 * reports to ARDOUR whether the Slave is currently synced to its external
	 * time source.
	 *
	 * @return - when returning false, the transport will stop rolling
	 */
	virtual bool locked() const = 0;

	/**
	 * reports to ARDOUR whether the slave is in a sane state
	 *
	 * @return - when returning false, the transport will be stopped and the slave
	 * disconnected from ARDOUR.
	 */
	virtual bool ok() const = 0;

	/**
	 * reports to ARDOUR whether the slave is in the process of starting
	 * to roll
	 *
	 * @return - when returning false, transport will not move until this method returns true
	 */
	virtual bool starting() const { return false; }

	/**
	 * @return - the timing resolution of the Slave - If the distance of ARDOURs transport
	 * to the slave becomes greater than the resolution, sound will stop
	 */
	virtual samplecnt_t resolution() const = 0;

	/**
	 * @return - when returning true, ARDOUR will wait for seekahead_distance() before transport
	 * starts rolling
	 */
	virtual bool requires_seekahead () const = 0;

	/**
	 * @return the number of samples that this slave wants to seek ahead. Relevant
	 * only if requires_seekahead() returns true.
	 */

	virtual samplecnt_t seekahead_distance() const { return 0; }

	/**
	 * @return - when returning true, ARDOUR will use transport speed 1.0 no matter what
	 *           the slave returns
	 */
	virtual bool is_always_synced() const { return false; }

	/**
	 * @return - whether ARDOUR should use the slave speed without any adjustments
	 */
	virtual bool give_slave_full_control_over_transport_speed() const { return false; }

	/**
	 * @return - current time-delta between engine and sync-source
	 */
	virtual std::string delta_string () const { return ""; }

};

/// We need this wrapper for testability, it's just too hard to mock up a session class
class LIBARDOUR_API ISlaveSessionProxy {
  public:
	virtual ~ISlaveSessionProxy() {}
	virtual TempoMap&  tempo_map()                  const   { return *((TempoMap *) 0); }
	virtual samplecnt_t sample_rate()                 const   { return 0; }
	virtual pframes_t  samples_per_cycle()           const   { return 0; }
	virtual samplepos_t audible_sample ()             const   { return 0; }
	virtual samplepos_t transport_sample ()           const   { return 0; }
	virtual pframes_t  samples_since_cycle_start ()  const   { return 0; }
	virtual samplepos_t sample_time_at_cycle_start() const   { return 0; }
	virtual samplepos_t sample_time ()                const   { return 0; }
};


/// The Session Proxy for use in real Ardour
class LIBARDOUR_API SlaveSessionProxy : public ISlaveSessionProxy {
	Session&    session;

  public:
	SlaveSessionProxy(Session &s) : session(s) {}

	TempoMap&  tempo_map()                   const;
	samplecnt_t sample_rate()                  const;
	pframes_t  samples_per_cycle()            const;
	samplepos_t audible_sample ()              const;
	samplepos_t transport_sample ()            const;
	pframes_t  samples_since_cycle_start ()   const;
	samplepos_t sample_time_at_cycle_start()  const;
	samplepos_t sample_time ()                 const;
};

struct LIBARDOUR_API SafeTime {
	volatile int guard1;
	samplepos_t   position;
	samplepos_t   timestamp;
	double       speed;
	volatile int guard2;

	SafeTime() {
		guard1 = 0;
		position = 0;
		timestamp = 0;
		speed = 0;
		guard2 = 0;
	}
};

class LIBARDOUR_API TimecodeSlave : public Slave {
  public:
	TimecodeSlave () {}

	virtual Timecode::TimecodeFormat apparent_timecode_format() const = 0;

	/* this is intended to be used by a UI and polled from a timeout. it should
	   return a string describing the current position of the TC source. it
	   should NOT do any computation, but should use a cached value
	   of the TC source position.
	*/
	virtual std::string position_string () const = 0;

	samplepos_t        timecode_offset;
	bool              timecode_negative_offset;

	PBD::Signal1<void, bool> ActiveChanged;
};

class LIBARDOUR_API MTC_Slave : public TimecodeSlave {
  public:
	MTC_Slave (Session&, MidiPort&);
	~MTC_Slave ();

	void rebind (MidiPort&);
	bool speed_and_position (double&, samplepos_t&);

	bool locked() const;
	bool ok() const;
	void handle_locate (const MIDI::byte*);

	samplecnt_t resolution () const;
	bool requires_seekahead () const { return false; }
	samplecnt_t seekahead_distance() const;
	bool give_slave_full_control_over_transport_speed() const;

        Timecode::TimecodeFormat apparent_timecode_format() const;
        std::string position_string () const;
	std::string delta_string () const;

  private:
	Session&    session;
	MidiPort*   port;
	PBD::ScopedConnectionList port_connections;
	PBD::ScopedConnection     config_connection;
	bool        can_notify_on_unknown_rate;

	static const int sample_tolerance;

	SafeTime       current;
	samplepos_t     mtc_frame;               /* current time */
	double         mtc_frame_dll;
	samplepos_t     last_inbound_frame;      /* when we got it; audio clocked */
	MIDI::byte     last_mtc_fps_byte;
	samplepos_t     window_begin;
	samplepos_t     window_end;
	samplepos_t     first_mtc_timestamp;
	bool           did_reset_tc_format;
	Timecode::TimecodeFormat saved_tc_format;
	Glib::Threads::Mutex    reset_lock;
	uint32_t       reset_pending;
	bool           reset_position;
	int            transport_direction;
	int            busy_guard1;
	int            busy_guard2;

	double         speedup_due_to_tc_mismatch;
	double         quarter_frame_duration;
	Timecode::TimecodeFormat mtc_timecode;
	Timecode::TimecodeFormat a3e_timecode;
	Timecode::Time timecode;
	bool           printed_timecode_warning;
	sampleoffset_t  current_delta;

	/* DLL - chase MTC */
	double t0; ///< time at the beginning of the MTC quater sample
	double t1; ///< calculated end of the MTC quater sample
	double e2; ///< second order loop error
	double b, c, omega; ///< DLL filter coefficients

	/* DLL - sync engine */
	int    engine_dll_initstate;
	double te0; ///< time at the beginning of the engine process
	double te1; ///< calculated sync time
	double ee2; ///< second order loop error
	double be, ce, oe; ///< DLL filter coefficients

	void reset (bool with_pos);
	void queue_reset (bool with_pos);
	void maybe_reset ();

	void update_mtc_qtr (MIDI::Parser&, int, samplepos_t);
	void update_mtc_time (const MIDI::byte *, bool, samplepos_t);
	void update_mtc_status (MIDI::MTC_Status);
	void read_current (SafeTime *) const;
	void reset_window (samplepos_t);
	bool outside_window (samplepos_t) const;
	void init_mtc_dll(samplepos_t, double);
	void init_engine_dll (samplepos_t, samplepos_t);
	void parse_timecode_offset();
	void parameter_changed(std::string const & p);
};

class LIBARDOUR_API LTC_Slave : public TimecodeSlave {
public:
	LTC_Slave (Session&);
	~LTC_Slave ();

	bool speed_and_position (double&, samplepos_t&);

	bool locked() const;
	bool ok() const;

	samplecnt_t resolution () const;
	bool requires_seekahead () const { return false; }
	samplecnt_t seekahead_distance () const { return 0; }
	bool give_slave_full_control_over_transport_speed() const { return true; }

	Timecode::TimecodeFormat apparent_timecode_format() const;
	std::string position_string() const;
	std::string delta_string() const;

  private:
	void parse_ltc(const pframes_t, const Sample* const, const samplecnt_t);
	void process_ltc(samplepos_t const);
	void init_engine_dll (samplepos_t, int32_t);
	bool detect_discontinuity(LTCFrameExt *, int, bool);
	bool detect_ltc_fps(int, bool);
	bool equal_ltc_sample_time(LTCFrame *a, LTCFrame *b);
	void reset (bool with_ts = true);
	void resync_xrun();
	void resync_latency();
	void parse_timecode_offset();
	void parameter_changed(std::string const & p);

	Session&       session;
	bool           did_reset_tc_format;
	Timecode::TimecodeFormat saved_tc_format;

	LTCDecoder *   decoder;
	double         samples_per_ltc_frame;
	Timecode::Time timecode;
	LTCFrameExt    prev_sample;
	bool           fps_detected;

	samplecnt_t     monotonic_cnt;
	samplecnt_t     last_timestamp;
	samplecnt_t     last_ltc_sample;
	double         ltc_speed;
	sampleoffset_t  current_delta;
	int            delayedlocked;

	int            ltc_detect_fps_cnt;
	int            ltc_detect_fps_max;
	bool           printed_timecode_warning;
	bool           sync_lock_broken;
	Timecode::TimecodeFormat ltc_timecode;
	Timecode::TimecodeFormat a3e_timecode;

	PBD::ScopedConnectionList port_connections;
	PBD::ScopedConnection     config_connection;
        LatencyRange  ltc_slave_latency;

	/* DLL - chase LTC */
	int    transport_direction;
	int    engine_dll_initstate;
	double t0; ///< time at the beginning of the MTC quater sample
	double t1; ///< calculated end of the MTC quater sample
	double e2; ///< second order loop error
	double b, c; ///< DLL filter coefficients
};

class LIBARDOUR_API MIDIClock_Slave : public Slave {
  public:
	MIDIClock_Slave (Session&, MidiPort&, int ppqn = 24);

	/// Constructor for unit tests
	MIDIClock_Slave (ISlaveSessionProxy* session_proxy = 0, int ppqn = 24);
	~MIDIClock_Slave ();

	void rebind (MidiPort&);
	bool speed_and_position (double&, samplepos_t&);

	bool locked() const;
	bool ok() const;
	bool starting() const;

	samplecnt_t resolution () const;
	bool requires_seekahead () const { return false; }
	bool give_slave_full_control_over_transport_speed() const { return true; }

	void set_bandwidth (double a_bandwith) { bandwidth = a_bandwith; }
	std::string delta_string () const;

  protected:
	ISlaveSessionProxy* session;
	PBD::ScopedConnectionList port_connections;

	/// pulses per quarter note for one MIDI clock sample (default 24)
	int         ppqn;

	/// the duration of one ppqn in sample time
	double      one_ppqn_in_samples;

	/// the timestamp of the first MIDI clock message
	samplepos_t  first_timestamp;

	/// the time stamp and should-be transport position of the last inbound MIDI clock message
	samplepos_t  last_timestamp;
	double      should_be_position;

	/// the number of midi clock messages received (zero-based)
	/// since start
	long midi_clock_count;

	//the delay locked loop (DLL), see www.kokkinizita.net/papers/usingdll.pdf

	/// time at the beginning of the MIDI clock sample
	double t0;

	/// calculated end of the MIDI clock sample
	double t1;

	/// loop error = real value - expected value
	double e;

	/// second order loop error
	double e2;

	/// DLL filter bandwidth
	double bandwidth;

	/// DLL filter coefficients
	double b, c, omega;

	sampleoffset_t  current_delta;

	void reset ();
	void start (MIDI::Parser& parser, samplepos_t timestamp);
	void contineu (MIDI::Parser& parser, samplepos_t timestamp);
	void stop (MIDI::Parser& parser, samplepos_t timestamp);
	void position (MIDI::Parser& parser, MIDI::byte* message, size_t size);
	// we can't use continue because it is a C++ keyword
	void calculate_one_ppqn_in_samples_at(samplepos_t time);
	samplepos_t calculate_song_position(uint16_t song_position_in_sixteenth_notes);
	void calculate_filter_coefficients();
	void update_midi_clock (MIDI::Parser& parser, samplepos_t timestamp);
	void read_current (SafeTime *) const;
	bool stop_if_no_more_clock_events(samplepos_t& pos, samplepos_t now);

	/// whether transport should be rolling
	bool _started;

	/// is true if the MIDI Start message has just been received until
	/// the first MIDI Clock Event
	bool _starting;
};

class LIBARDOUR_API Engine_Slave : public Slave
{
  public:
	Engine_Slave (AudioEngine&);
	~Engine_Slave ();

	bool speed_and_position (double& speed, samplepos_t& pos);

	bool starting() const { return _starting; }
	bool locked() const;
	bool ok() const;
	samplecnt_t resolution () const { return 1; }
	bool requires_seekahead () const { return false; }
	bool is_always_synced() const { return true; }

  private:
        AudioEngine& engine;
	bool _starting;
};

} /* namespace */

#endif /* __ardour_slave_h__ */