The TransportMaster interface can be used to sync ARDOURs tempo to an external source like MTC, MIDI Clock, etc. as well as a single internal pseudo master we call "UI" because it is controlled from any of the user interfaces for Ardour (GUI, control surfaces, OSC, etc.) More...

#include <transport_master.h>

Inheritance diagram for ARDOUR::TransportMaster:

[legend]

Public Member Functions
	TransportMaster (SyncSource t, std::string const &name)

virtual	~TransportMaster ()

virtual void	pre_process (pframes_t nframes, samplepos_t now, std::optional< samplepos_t >)=0

virtual bool	speed_and_position (double &speed, samplepos_t &position, samplepos_t &lp, samplepos_t &when, samplepos_t now)

virtual void	reset (bool with_position)=0

virtual bool	locked () const =0

virtual bool	ok () const =0

virtual bool	usable () const

virtual bool	starting () const

virtual samplecnt_t	resolution () const =0

virtual samplecnt_t	update_interval () const =0

virtual bool	requires_seekahead () const =0

virtual samplecnt_t	seekahead_distance () const

virtual bool	sample_clock_synced () const

virtual void	set_sample_clock_synced (bool)

virtual std::string	delta_string () const

sampleoffset_t	current_delta () const

virtual std::string	position_string () const =0

virtual bool	can_loop () const

virtual Location *	loop_location () const

bool	has_loop () const

SyncSource	type () const

TransportRequestSource	request_type () const

std::string	name () const

void	set_name (std::string const &)

int	set_state (XMLNode const &, int)

XMLNode &	get_state () const

virtual void	set_session (Session *)

std::shared_ptr< Port >	port () const

bool	check_collect ()

virtual void	set_collect (bool)

bool	collect () const

virtual void	init ()=0

virtual void	check_backend ()

virtual bool	allow_request (TransportRequestSource, TransportRequestType) const

std::string	allowed_request_string () const

TransportRequestType	request_mask () const

void	set_request_mask (TransportRequestType)

bool	removeable () const

void	set_removeable (bool yn)

std::string	display_name (bool sh=true) const

virtual void	unregister_port ()

void	connect_port_using_state ()

virtual void	create_port ()=0

Public Member Functions inherited from PBD::Stateful
	Stateful ()

virtual	~Stateful ()

virtual bool	apply_change (PropertyBase const &)

PropertyChange	apply_changes (PropertyList const &)

const OwnedPropertyList &	properties () const

void	add_property (PropertyBase &s)

void	add_extra_xml (XMLNode &)

XMLNode *	extra_xml (const std::string &str, bool add_if_missing=false)

void	save_extra_xml (const XMLNode &)

const PBD::ID &	id () const

bool	set_id (const XMLNode &)

void	set_id (const std::string &)

void	reset_id ()

void	clear_changes ()

virtual void	clear_owned_changes ()

PropertyList *	get_changes_as_properties (PBD::Command *) const

virtual void	rdiff (std::vector< PBD::Command * > &) const

bool	changed () const

virtual PropertyList *	property_factory (const XMLNode &) const

virtual void	suspend_property_changes ()

virtual void	resume_property_changes ()

bool	property_changes_suspended () const

Static Public Member Functions
static std::shared_ptr< TransportMaster >	factory (SyncSource, std::string const &, bool removeable)

static std::shared_ptr< TransportMaster >	factory (XMLNode const &)

static void	make_property_quarks ()

Static Public Attributes
static const std::string	state_node_name

Static Public Attributes inherited from PBD::Stateful
static int	current_state_version

static int	loading_state_version

Protected Member Functions
virtual void	connection_handler (std::weak_ptr< ARDOUR::Port >, std::string name1, std::weak_ptr< ARDOUR::Port >, std::string name2, bool yn)

virtual void	register_properties ()

virtual std::string	format_delta_time (sampleoffset_t) const

Protected Member Functions inherited from PBD::Stateful
void	add_instant_xml (XMLNode &, const std::string &directory_path)

XMLNode *	instant_xml (const std::string &str, const std::string &directory_path)

void	add_properties (XMLNode &) const

PropertyChange	set_values (XMLNode const &)

virtual void	post_set (const PropertyChange &)

virtual void	send_change (const PropertyChange &)

virtual void	mid_thaw (const PropertyChange &)

bool	regenerate_xml_or_string_ids () const

Protected Attributes
SyncSource	_type

PBD::Property< std::string >	_name

Session *	_session

sampleoffset_t	_current_delta

bool	_pending_collect

bool	_removeable

PBD::Property< TransportRequestType >	_request_mask

PBD::Property< bool >	_sclock_synced

PBD::Property< bool >	_collect

PBD::Property< bool >	_connected

SafeTime	current

int	transport_direction

int	dll_initstate

double	t0

double	t1

double	e2

double	b

double	c

std::shared_ptr< Port >	_port

XMLNode	port_node

PBD::ScopedConnection	port_connection

PBD::ScopedConnection	backend_connection

Protected Attributes inherited from PBD::Stateful
XMLNode *	_extra_xml

XMLNode *	_instant_xml

PBD::PropertyChange	_pending_changed

Glib::Threads::Mutex	_lock

std::string	_xml_node_name
	name of node to use for this object in XML More...

OwnedPropertyList *	_properties

Additional Inherited Members
Public Attributes inherited from PBD::Stateful
PBD::Signal< void(const PropertyChange &)>	PropertyChanged

Detailed Description

The TransportMaster interface can be used to sync ARDOURs tempo to an external source like MTC, MIDI Clock, etc. as well as a single internal pseudo master we call "UI" because it is controlled from any of the user interfaces for Ardour (GUI, control surfaces, OSC, etc.)

Definition at line 146 of file transport_master.h.

Constructor & Destructor Documentation

◆ TransportMaster()

ARDOUR::TransportMaster::TransportMaster	(	SyncSource	t,
		std::string const &	name
	)

◆ ~TransportMaster()

virtual ARDOUR::TransportMaster::~TransportMaster ( )

virtual

Member Function Documentation

◆ allow_request()

virtual bool ARDOUR::TransportMaster::allow_request	(	TransportRequestSource	,
		TransportRequestType
	)		const

virtual

Reimplemented in ARDOUR::Engine_TransportMaster.

◆ allowed_request_string()

std::string ARDOUR::TransportMaster::allowed_request_string ( ) const

◆ can_loop()

virtual bool ARDOUR::TransportMaster::can_loop ( ) const

inlinevirtual

Definition at line 316 of file transport_master.h.

◆ check_backend()

virtual void ARDOUR::TransportMaster::check_backend ( )

inlinevirtual

Reimplemented in ARDOUR::Engine_TransportMaster.

Definition at line 381 of file transport_master.h.

◆ check_collect()

bool ARDOUR::TransportMaster::check_collect ( )

◆ collect()

bool ARDOUR::TransportMaster::collect ( ) const

inline

Definition at line 370 of file transport_master.h.

◆ connect_port_using_state()

void ARDOUR::TransportMaster::connect_port_using_state ( )

◆ connection_handler()

virtual void ARDOUR::TransportMaster::connection_handler	(	std::weak_ptr< ARDOUR::Port >	,
		std::string	name1,
		std::weak_ptr< ARDOUR::Port >	,
		std::string	name2,
		bool	yn
	)

protectedvirtual

Reimplemented in ARDOUR::MIDIClock_TransportMaster, ARDOUR::LTC_TransportMaster, and ARDOUR::MTC_TransportMaster.

◆ create_port()

virtual void ARDOUR::TransportMaster::create_port ( )

pure virtual

Implemented in ARDOUR::Engine_TransportMaster, ARDOUR::MIDIClock_TransportMaster, ARDOUR::LTC_TransportMaster, and ARDOUR::MTC_TransportMaster.

◆ current_delta()

sampleoffset_t ARDOUR::TransportMaster::current_delta ( ) const

inline

Definition at line 304 of file transport_master.h.

◆ delta_string()

virtual std::string ARDOUR::TransportMaster::delta_string ( ) const

inlinevirtual

Returns: - current time-delta between engine and sync-source

Reimplemented in ARDOUR::Engine_TransportMaster, ARDOUR::MIDIClock_TransportMaster, ARDOUR::LTC_TransportMaster, and ARDOUR::MTC_TransportMaster.

Definition at line 299 of file transport_master.h.

◆ display_name()

std::string ARDOUR::TransportMaster::display_name ( bool sh = true ) const

◆ factory() [1/2]

static std::shared_ptr<TransportMaster> ARDOUR::TransportMaster::factory	(	SyncSource	,
		std::string const &	,
		bool	removeable
	)

static

◆ factory() [2/2]

static std::shared_ptr<TransportMaster> ARDOUR::TransportMaster::factory ( XMLNode const & )

static

◆ format_delta_time()

virtual std::string ARDOUR::TransportMaster::format_delta_time ( sampleoffset_t ) const

protectedvirtual

◆ get_state()

XMLNode& ARDOUR::TransportMaster::get_state ( ) const

virtual

Implements PBD::Stateful.

◆ has_loop()

bool ARDOUR::TransportMaster::has_loop ( ) const

inline

Definition at line 325 of file transport_master.h.

◆ init()

virtual void ARDOUR::TransportMaster::init ( )

pure virtual

Implemented in ARDOUR::Engine_TransportMaster, ARDOUR::MIDIClock_TransportMaster, ARDOUR::LTC_TransportMaster, and ARDOUR::MTC_TransportMaster.

◆ locked()

virtual bool ARDOUR::TransportMaster::locked ( ) const

pure virtual

reports to ARDOUR whether the TransportMaster is currently synced to its external time source.

Returns: - when returning false, the transport will stop rolling

Implemented in ARDOUR::Engine_TransportMaster, ARDOUR::MIDIClock_TransportMaster, ARDOUR::LTC_TransportMaster, and ARDOUR::MTC_TransportMaster.

◆ loop_location()

virtual Location* ARDOUR::TransportMaster::loop_location ( ) const

inlinevirtual

Definition at line 321 of file transport_master.h.

◆ make_property_quarks()

static void ARDOUR::TransportMaster::make_property_quarks ( )

static

◆ name()

std::string ARDOUR::TransportMaster::name ( ) const

inline

Definition at line 349 of file transport_master.h.

◆ ok()

virtual bool ARDOUR::TransportMaster::ok ( ) const

pure virtual

reports to ARDOUR whether the slave is in a sane state

Returns: - when returning false, the transport will be stopped and the slave disconnected from ARDOUR.

Implemented in ARDOUR::Engine_TransportMaster, ARDOUR::MIDIClock_TransportMaster, ARDOUR::LTC_TransportMaster, and ARDOUR::MTC_TransportMaster.

◆ port()

std::shared_ptr<Port> ARDOUR::TransportMaster::port ( ) const

inline

Definition at line 363 of file transport_master.h.

◆ position_string()

virtual std::string ARDOUR::TransportMaster::position_string ( ) const

pure virtual

Implemented in ARDOUR::Engine_TransportMaster, ARDOUR::MIDIClock_TransportMaster, ARDOUR::LTC_TransportMaster, and ARDOUR::MTC_TransportMaster.

◆ pre_process()

virtual void ARDOUR::TransportMaster::pre_process	(	pframes_t	nframes,
		samplepos_t	now,
		std::optional< samplepos_t >
	)

pure virtual

Implemented in ARDOUR::Engine_TransportMaster, ARDOUR::MIDIClock_TransportMaster, ARDOUR::LTC_TransportMaster, and ARDOUR::MTC_TransportMaster.

◆ register_properties()

virtual void ARDOUR::TransportMaster::register_properties ( )

protectedvirtual

Reimplemented in ARDOUR::TimecodeTransportMaster.

◆ removeable()

bool ARDOUR::TransportMaster::removeable ( ) const

inline

Definition at line 395 of file transport_master.h.

◆ request_mask()

TransportRequestType ARDOUR::TransportMaster::request_mask ( ) const

inline

Definition at line 385 of file transport_master.h.

◆ request_type()

TransportRequestSource ARDOUR::TransportMaster::request_type ( ) const

inline

Definition at line 334 of file transport_master.h.

◆ requires_seekahead()

virtual bool ARDOUR::TransportMaster::requires_seekahead ( ) const

pure virtual

Returns: - when returning true, ARDOUR will wait for seekahead_distance() before transport starts rolling

Implemented in ARDOUR::Engine_TransportMaster, ARDOUR::MIDIClock_TransportMaster, ARDOUR::LTC_TransportMaster, and ARDOUR::MTC_TransportMaster.

◆ reset()

virtual void ARDOUR::TransportMaster::reset ( bool with_position )

pure virtual

Implemented in ARDOUR::Engine_TransportMaster, ARDOUR::MIDIClock_TransportMaster, ARDOUR::LTC_TransportMaster, and ARDOUR::MTC_TransportMaster.

◆ resolution()

virtual samplecnt_t ARDOUR::TransportMaster::resolution ( ) const

pure virtual

Returns: - the timing resolution of the TransportMaster - If the distance of ARDOURs transport to the slave becomes greater than the resolution, sound will stop

Implemented in ARDOUR::Engine_TransportMaster, ARDOUR::MIDIClock_TransportMaster, ARDOUR::LTC_TransportMaster, and ARDOUR::MTC_TransportMaster.

◆ sample_clock_synced()

virtual bool ARDOUR::TransportMaster::sample_clock_synced ( ) const

inlinevirtual

Returns: - when returning true, ARDOUR will use transport speed 1.0 no matter what the slave returns

Reimplemented in ARDOUR::Engine_TransportMaster.

Definition at line 290 of file transport_master.h.

◆ seekahead_distance()

virtual samplecnt_t ARDOUR::TransportMaster::seekahead_distance ( ) const

inlinevirtual

Returns: the number of samples that this slave wants to seek ahead. Relevant only if requires_seekahead() returns true.

Reimplemented in ARDOUR::LTC_TransportMaster, and ARDOUR::MTC_TransportMaster.

Definition at line 281 of file transport_master.h.

◆ set_collect()

virtual void ARDOUR::TransportMaster::set_collect ( bool )

virtual

◆ set_name()

void ARDOUR::TransportMaster::set_name ( std::string const & )

◆ set_removeable()

void ARDOUR::TransportMaster::set_removeable ( bool yn )

inline

Definition at line 399 of file transport_master.h.

◆ set_request_mask()

void ARDOUR::TransportMaster::set_request_mask ( TransportRequestType )

◆ set_sample_clock_synced()

virtual void ARDOUR::TransportMaster::set_sample_clock_synced ( bool )

virtual

Reimplemented in ARDOUR::LTC_TransportMaster.

◆ set_session()

virtual void ARDOUR::TransportMaster::set_session ( Session * )

virtual

Reimplemented in ARDOUR::MIDIClock_TransportMaster, ARDOUR::LTC_TransportMaster, and ARDOUR::MTC_TransportMaster.

◆ set_state()

int ARDOUR::TransportMaster::set_state	(	XMLNode const &	,
		int
	)

virtual

Implements PBD::Stateful.

◆ speed_and_position()

virtual bool ARDOUR::TransportMaster::speed_and_position	(	double &	speed,
		samplepos_t &	position,
		samplepos_t &	lp,
		samplepos_t &	when,
		samplepos_t	now
	)

virtual

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 position 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:

TransportMaster::ok() should return true, otherwise playback will stop immediately and the method will not be called
when the references speed and position are passed into the TransportMaster they are uninitialized

After the method call the following postconditions should be met:

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
the references speed and position should be assigned to the TransportMasters current requested transport speed and transport position.
TransportMaster::resolution() should be greater than the maximum distance of ARDOURs transport position to the slaves requested transport position.
TransportMaster::locked() should return true, otherwise Session::no_roll will be called
TransportMaster::starting() should be false, otherwise the transport will not move until it becomes true

Parameters

speed	- The transport speed requested
position	- The transport position requested
lp	last position (used for flywheel)
when	last timestamp (used for flywheel)
now	monotonic sample time

Returns: - The return value is currently ignored (see Session::follow_slave)

Reimplemented in ARDOUR::Engine_TransportMaster.

◆ starting()

virtual bool ARDOUR::TransportMaster::starting ( ) const

inlinevirtual

reports to ARDOUR whether the slave is in the process of starting to roll

Returns: - when returning false, transport will not move until this method returns true

Reimplemented in ARDOUR::Engine_TransportMaster.

Definition at line 251 of file transport_master.h.

◆ type()

SyncSource ARDOUR::TransportMaster::type ( ) const

inline

Definition at line 330 of file transport_master.h.

◆ unregister_port()

virtual void ARDOUR::TransportMaster::unregister_port ( )

virtual

Reimplemented in ARDOUR::MIDIClock_TransportMaster, and ARDOUR::MTC_TransportMaster.

◆ update_interval()

virtual samplecnt_t ARDOUR::TransportMaster::update_interval ( ) const

pure virtual

Returns: - the expected update interval for the data source used by this transport master. Even if the data is effectively continuous, this number indicates how long it is between changes to the known position of the master.

Implemented in ARDOUR::Engine_TransportMaster, ARDOUR::MIDIClock_TransportMaster, ARDOUR::LTC_TransportMaster, and ARDOUR::MTC_TransportMaster.

◆ usable()

virtual bool ARDOUR::TransportMaster::usable ( ) const

inlinevirtual

reports to ARDOUR whether it is possible to use this slave

Returns: - true if the slave can be used.

Only the JACK ("Engine") slave is ever likely to return false, if JACK is not being used for the Audio/MIDI backend.

Reimplemented in ARDOUR::Engine_TransportMaster.

Definition at line 240 of file transport_master.h.

Member Data Documentation

◆ _collect

PBD::Property<bool> ARDOUR::TransportMaster::_collect

protected

Definition at line 419 of file transport_master.h.

◆ _connected

PBD::Property<bool> ARDOUR::TransportMaster::_connected

protected

Definition at line 420 of file transport_master.h.

◆ _current_delta

sampleoffset_t ARDOUR::TransportMaster::_current_delta

protected

Definition at line 414 of file transport_master.h.

◆ _name

PBD::Property<std::string> ARDOUR::TransportMaster::_name

protected

Definition at line 412 of file transport_master.h.

◆ _pending_collect

bool ARDOUR::TransportMaster::_pending_collect

protected

Definition at line 415 of file transport_master.h.

◆ _port

std::shared_ptr<Port> ARDOUR::TransportMaster::_port

protected

Definition at line 434 of file transport_master.h.

◆ _removeable

bool ARDOUR::TransportMaster::_removeable

protected

Definition at line 416 of file transport_master.h.

◆ _request_mask

PBD::Property<TransportRequestType> ARDOUR::TransportMaster::_request_mask

protected

Definition at line 417 of file transport_master.h.

◆ _sclock_synced

PBD::Property<bool> ARDOUR::TransportMaster::_sclock_synced

protected

Definition at line 418 of file transport_master.h.

◆ _session

Session* ARDOUR::TransportMaster::_session

protected

Definition at line 413 of file transport_master.h.

◆ _type

SyncSource ARDOUR::TransportMaster::_type

protected

Definition at line 411 of file transport_master.h.

◆ b

double ARDOUR::TransportMaster::b

protected

Definition at line 432 of file transport_master.h.

◆ backend_connection

PBD::ScopedConnection ARDOUR::TransportMaster::backend_connection

protected

Definition at line 441 of file transport_master.h.

◆ c

double ARDOUR::TransportMaster::c

protected

Definition at line 432 of file transport_master.h.

◆ current

SafeTime ARDOUR::TransportMaster::current

protected

Definition at line 422 of file transport_master.h.

◆ dll_initstate

int ARDOUR::TransportMaster::dll_initstate

protected

Definition at line 427 of file transport_master.h.

◆ e2

double ARDOUR::TransportMaster::e2

protected

Definition at line 431 of file transport_master.h.

◆ port_connection

PBD::ScopedConnection ARDOUR::TransportMaster::port_connection

protected

Definition at line 440 of file transport_master.h.

◆ port_node

XMLNode ARDOUR::TransportMaster::port_node

mutableprotected

Definition at line 436 of file transport_master.h.

◆ state_node_name

const std::string ARDOUR::TransportMaster::state_node_name

static

Definition at line 358 of file transport_master.h.

◆ t0

double ARDOUR::TransportMaster::t0

protected

Definition at line 429 of file transport_master.h.

◆ t1

double ARDOUR::TransportMaster::t1

protected

Definition at line 430 of file transport_master.h.

◆ transport_direction

int ARDOUR::TransportMaster::transport_direction

protected

Definition at line 426 of file transport_master.h.

The documentation for this class was generated from the following file:

transport_master.h

Public Member Functions

Static Public Member Functions

Static Public Attributes

Protected Member Functions

Protected Attributes

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ TransportMaster()

◆ ~TransportMaster()

Member Function Documentation

◆ allow_request()

◆ allowed_request_string()

◆ can_loop()

◆ check_backend()

◆ check_collect()

◆ collect()

◆ connect_port_using_state()

◆ connection_handler()

◆ create_port()

◆ current_delta()

◆ delta_string()

◆ display_name()

◆ factory() [1/2]

◆ factory() [2/2]

◆ format_delta_time()

◆ get_state()

◆ has_loop()

◆ init()

◆ locked()

◆ loop_location()

◆ make_property_quarks()

◆ name()

◆ ok()

◆ port()

◆ position_string()

◆ pre_process()

◆ register_properties()

◆ removeable()

◆ request_mask()

◆ request_type()

◆ requires_seekahead()

◆ reset()

◆ resolution()

◆ sample_clock_synced()

◆ seekahead_distance()

◆ set_collect()

◆ set_name()

◆ set_removeable()

◆ set_request_mask()

◆ set_sample_clock_synced()

◆ set_session()

◆ set_state()

◆ speed_and_position()

◆ starting()

◆ type()

◆ unregister_port()

◆ update_interval()

◆ usable()

Member Data Documentation

◆ _collect

◆ _connected

◆ _current_delta

◆ _name

◆ _pending_collect

◆ _port

◆ _removeable

◆ _request_mask

◆ _sclock_synced

◆ _session

◆ _type

◆ b

◆ backend_connection

◆ c

◆ current

◆ dll_initstate

◆ e2

◆ port_connection

◆ port_node

◆ state_node_name