JACK (Jack Audio Connection Kit) server driver. More...

#include <JackAudioDriver.h>

Inheritance diagram for JackAudioDriver:

Public Types
enum class	Timebase { Controller = 1 , Listener = 0 , None = -1 }
	Whether Hydrogen or another program is in Timebase control. More...

Public Member Functions
	JackAudioDriver (JackProcessCallback m_processCallback)
	Constructor of the JACK server driver.

	~JackAudioDriver ()
	Destructor of the JACK server driver.

bool	checkBBTPos () const
	Used within the unit tests and checks whether the last JACK transport position retrieved has valid BBT information.

void	clearPerTrackAudioBuffers (uint32_t nFrames)
	Resets the buffers contained in m_pTrackOutputPortsL and m_pTrackOutputPortsR.

virtual int	connect () override
	Connects to output ports via the JACK server.

void	deactivate ()
	Deactivates the JACK client of Hydrogen and disconnects all ports belonging to it.

virtual void	disconnect () override
	Disconnects the JACK client of the Hydrogen from the JACK server.

virtual unsigned	getBufferSize () override

bool	getConnectDefaults ()

const jack_position_t &	getJackPosition () const

virtual float *	getOut_L () override
	Get content in the left stereo output port.

virtual float *	getOut_R () override
	Get content in the right stereo output port.

virtual unsigned	getSampleRate () override

float	getTimebaseControllerBpm () const

Timebase	getTimebaseState () const

float *	getTrackOut_L (std::shared_ptr< Instrument > instr, std::shared_ptr< InstrumentComponent > pCompo)
	Convenience function looking up the track number of a component of an instrument using in m_trackMap using their IDs Instrument::__id and InstrumentComponent::__related_drumkit_componentID.

float *	getTrackOut_L (unsigned nTrack)
	Get content of left output port of a specific track.

float *	getTrackOut_R (std::shared_ptr< Instrument > instr, std::shared_ptr< InstrumentComponent > pCompo)
	Convenience function looking up the track number of a component of an instrument using in m_trackMap using their IDs Instrument::__id and InstrumentComponent::__related_drumkit_componentID.

float *	getTrackOut_R (unsigned nTrack)
	Get content of right output port of a specific track.

virtual int	getXRuns () const override
	Get the number of XRuns that occurred since the audio driver has started.

virtual int	init (unsigned bufferSize) override
	Initializes the JACK audio driver.

void	initTimebaseControl ()
	Acquires control of JACK Timebase.

void	locateTransport (long long nFrame)
	Re-positions the transport position to nFrame.

void	makeTrackOutputs (std::shared_ptr< Song > pSong)
	Creates per component output ports for each instrument.

void	releaseTimebaseControl ()
	Release Hydrogen from the JACK Timebase control.

void	relocateUsingBBT ()
	Uses the bar-beat-tick information to relocate the transport position.

void	setConnectDefaults (bool flag)

void	startTransport ()
	Tells the JACK server to start transport.

void	stopTransport ()
	Tells the JACK server to stop transport.

void	updateTransportPosition ()
	The function queries the transport position and additional information from the JACK server, writes them to m_JackTransportPos and in m_JackTransportState, and updates the AudioEngine in case of a mismatch.

Public Member Functions inherited from Object< JackAudioDriver >
	Object ()

	Object (const Object< JackAudioDriver > &other)

Public Member Functions inherited from Base
	Base ()

	Base (const Base &other)

virtual const char *	class_name () const

void	logBacktrace () const
	Print the current stack at point into the debug log.

void	Print (bool bShort=true) const
	Prints content of toQString() via DEBUGLOG.

virtual QString	toQString (const QString &sPrefix="", bool bShort=true) const
	Formatted string version for debugging purposes.

Public Member Functions inherited from AudioOutput
	AudioOutput ()=default

virtual	~AudioOutput ()

virtual int	getLatency ()
	Approximate audio latency (in frames) A reasonable approximation is the buffer time on most audio systems.

Public Member Functions inherited from Object< AudioOutput >
	Object ()

	Object (const Object< AudioOutput > &other)

Static Public Member Functions
static double	bbtToTick (const jack_position_t &pos)

static bool	isBBTValid (const jack_position_t &pos)

static int	jackDriverBufferSize (jack_nframes_t nframes, void *arg)
	Callback function for the JACK audio server to set the buffer size jackServerBufferSize.

static int	jackDriverSampleRate (jack_nframes_t nframes, void *param)
	Callback function for the JACK audio server to set the sample rate jackServerSampleRate.

static QString	JackTransportPosToQString (const jack_position_t &pPos)

static int	jackXRunCallback (void *arg)
	Report an XRun event to the GUI.

static Timebase	TimebaseFromInt (int nState)

static QString	TimebaseToQString (const Timebase &t)

static void	transportToBBT (const TransportPosition &transportPos, jack_position_t *pPos)

Static Public Member Functions inherited from Base
static const char *	_class_name ()
	return the class name

static QString	base_clock (const QString &sMsg)
	Measures the current time and stores it in __last_clock.

static QString	base_clock_in (const QString &sMsg)

static int	bootstrap (Logger *logger, bool count=false)
	must be called before any Object instantiation !

static bool	count_active ()

static int	getAliveObjectCount ()

static object_map_t	getObjectMap ()

static Logger *	logger ()
	return the logger instance

static int	objects_count ()

static void	printObjectMapDiff (object_map_t map)
	Creates the difference between a snapshot of the object map and its current state and prints it to std::cout.

static void	set_count (bool flag)
	enable/disable class instances counting

static void	write_objects_map_to (std::ostream &out, object_map_t *map=nullptr)
	output the full objects map to a given ostream

static void	write_objects_map_to_cerr ()
	output objects map to stderr

Static Public Member Functions inherited from AudioOutput
static QStringList	getDevices ()

Data Fields
jack_client_t *	m_pClient
	Object holding the external client session with the JACK server.

Static Public Attributes
static jack_nframes_t	jackServerBufferSize = 0
	Buffer size of the JACK audio server.

static unsigned long	jackServerSampleRate = 0
	Sample rate of the JACK audio server.

static int	jackServerXRuns = 0
	Number of XRuns since the driver started.

static JackAudioDriver *	pJackDriverInstance = nullptr
	Instance of the JackAudioDriver.

Static Public Attributes inherited from Base
static QString	sPrintIndention = " "
	String used to format the debugging string output of some core classes.

Private Types
enum class	TimebaseTracking { Valid , OnHold , None }
	Used internally to keep track of the current Timebase state. More...

Private Member Functions
void	printState () const
	Show debugging information.

void	setTrackOutput (int n, std::shared_ptr< Instrument > instr, std::shared_ptr< InstrumentComponent > pCompo, std::shared_ptr< Song > pSong)
	Renames the n 'th port of JACK client and creates it if it's not already present.

Static Private Member Functions
static void	jackDriverShutdown (void *arg)
	Callback function for the JACK audio server to shutting down the JACK driver.

static void	JackTimebaseCallback (jack_transport_state_t state, jack_nframes_t nFrames, jack_position_t pJackPosition, int new_pos, void arg)
	Callback function for the JACK server to supply additional timebase information.

static QString	JackTransportStateToQString (const jack_transport_state_t &pPos)

static QString	TimebaseTrackingToQString (const TimebaseTracking &t)

Private Attributes
bool	m_bConnectDefaults
	Specifies whether the default left and right (master) audio JACK ports will be automatically connected to the system's sink when registering the JACK client in connect().

float	m_fLastTimebaseBpm
	Stores the last tempo sent by an external Timebase controller.

jack_position_t	m_JackTransportPos
	Current transport position obtained using jack_transport_query() (jack/transport.h).

jack_transport_state_t	m_JackTransportState
	Current transport state returned by jack_transport_query() (jack/transport.h).

int	m_lastTransportBits
	Remembers the BBT capability bit received in a JACK process cycle.

jack_position_t	m_nextJackTransportPos
	Use for relocation if Hydrogen is Timebase controller (and needs to provide valid BBT information in addition to just a frame).

long long	m_nTimebaseFrameOffset
	Stores an intended deviation of our transport position from the one hold by the JACK server.

int	m_nTrackPortCount
	Total number of output ports currently in use.

jack_port_t *	m_pOutputPort1
	Left source port.

jack_port_t *	m_pOutputPort2
	Right source port.

JackProcessCallback	m_processCallback
	Main process callback.

jack_port_t *	m_pTrackOutputPortsL [MAX_INSTRUMENTS]
	Vector of all left audio output ports currently used by the local JACK client.

jack_port_t *	m_pTrackOutputPortsR [MAX_INSTRUMENTS]
	Vector of all right audio output ports currently used by the local JACK client.

QString	m_sOutputPortName1
	Destination of the left source port m_pOutputPort1, for which a connection will be established in connect().

QString	m_sOutputPortName2
	Destination of the right source port m_pOutputPort2, for which a connection will be established in connect().

Timebase	m_timebaseState
	Whether Hydrogen is receiving relocation and tempo changes as part of BBT information, it sends them itself, or just uses internal position information.

TimebaseTracking	m_timebaseTracking
	Whether the current timebase state is stable or about to change.

int	m_trackMap [MAX_INSTRUMENTS][MAX_COMPONENTS]
	Matrix containing the track number of each component of all instruments.

Friends
class	AudioEngineTests

Additional Inherited Members
Protected Member Functions inherited from Object< JackAudioDriver >
	~Object ()

Protected Member Functions inherited from Base
	~Base ()

Protected Member Functions inherited from Object< AudioOutput >
	~Object ()

Static Protected Member Functions inherited from Base
static void	registerClass (const char name, const atomic_obj_cpt_t counters)

Static Protected Attributes inherited from Base
static bool	__count = false
	should we count class instances

static timeval	__last_clock = { 0, 0 }

static Logger *	__logger = nullptr

static bool	bLogColors = true

Detailed Description

JACK (Jack Audio Connection Kit) server driver.

Transport Control:

Each JACK client can start and stop the transport or relocate the current transport position. The request will take place in cycles. During the first the status of the transport changes to JackTransportStarting to inform all clients a change is about to happen. During the second the status is again JackTransportRolling and the transport position is updated according to the request.

Also note that Hydrogen overwrites its local TransportPosition only with the transport position of the JACK server if there is a mismatch due to a relocation triggered by another JACK client. During normal transport the current position TransportPosition::m_nFrames will be always the same as the one of JACK during a cycle and incremented by the buffer size in audioEngine_process() at the very end of the cycle. The same happens for the transport information of the JACK server but in parallel.

Timebase support:

The JACK Timebase controller is responsible for providing additional transport information to the JACK server apart from the transport position in frames, like current beat, bar, tick, tick size, speed etc. Unlike many other application, Hydrogen does not respond to changes in measure since these would have to be mapped to the length of the current pattern (In case this leads to repeated glitches or unwanted behavior Timebase synchronization can be turned off entirely using Preferences::m_bJackTimebaseEnabled). Every client can take control by supplying a callback (for Hydrogen this would be JackTimebaseCallback()) but there can be at most one Timebase controller at a time. Having none at all is perfectly fine too. Apart from this additional responsibility, the registered client has no other rights compared to others.

After the status of the JACK transport has changed from JackTransportStarting to JackTransportRolling, the Timebase controller needs an additional cycle to update its information.

Note that we do not use the original terms coined in the Timebase API. Instead, we refer to controller and listener.

Definition at line 96 of file JackAudioDriver.h.

Member Enumeration Documentation

◆ Timebase

enum class Timebase

strong

Whether Hydrogen or another program is in Timebase control.

Enumerator

Controller

Hydrogen itself is Timebase controller and provides its current tempo to other Timebase listeners.

Listener

An external program is Timebase controller and Hydrogen will disregard all tempo markers on the Timeline and, instead, only use the BPM provided by JACK.

Note: the JACK standard is using a different term we do not want to repeat or spread.

None

Only normal clients registered.

Definition at line 103 of file JackAudioDriver.h.

◆ TimebaseTracking

enum class TimebaseTracking

strongprivate

Used internally to keep track of the current Timebase state.

While Hydrogen can drop Timebase control on its own, it can not be observed directly whether another application has taken over as Timebase controller. When the JACK server is releasing Hydrogen in the later case, it won't advertise this fact but simply won't call the JackTimebaseCallback() anymore. But since this will be called in every cycle after updateTransportPosition(), we make the former set the tracking state to Valid and the latter to OnHold. If we encounter a second process cycle with OnHold, we have been released.

A second use case is relocation triggered by a JACK client other than the Timebase controller. The JACK server won't have any corresponding BBT information at hand and distribute the frame information without the BBT capability. The process cycle afterwards the controller starts again to send BBT. This intermediate state will be covered by OnHold too, as we do not want the timebase state (and timeline support) to glitch on each relocation. Instead, we cache the last tempo and pretend to still have BBT information. will be updated accordingly.

Enumerator
Valid	Current timebase state is on par with JACK server.
OnHold	We are uncertain of the current timebase state and wait a processing cycle to determine what to do next.
None	Null element.

Definition at line 403 of file JackAudioDriver.h.

Constructor & Destructor Documentation

◆ JackAudioDriver()

JackAudioDriver ( JackProcessCallback m_processCallback )

Constructor of the JACK server driver.

Parameters

m_processCallback Function that is called by the AudioEngine during every processing cycle.

Definition at line 123 of file JackAudioDriver.cpp.

◆ ~JackAudioDriver()

~JackAudioDriver ( )

Destructor of the JACK server driver.

Calling disconnect().

Definition at line 158 of file JackAudioDriver.cpp.

Member Function Documentation

◆ bbtToTick()

double bbtToTick ( const jack_position_t & pos )

static

Definition at line 345 of file JackAudioDriver.cpp.

◆ checkBBTPos()

bool checkBBTPos ( ) const

Used within the unit tests and checks whether the last JACK transport position retrieved has valid BBT information.

◆ clearPerTrackAudioBuffers()

void clearPerTrackAudioBuffers ( uint32_t nFrames )

Resets the buffers contained in m_pTrackOutputPortsL and m_pTrackOutputPortsR.

Parameters

nFrames Size of the buffers used in the audio process callback function.

Definition at line 286 of file JackAudioDriver.cpp.

◆ connect()

int connect ( )

overridevirtual

Connects to output ports via the JACK server.

Returns

0 : on success.

1 : The activation of the JACK client using did fail.
2 : The connections to m_sOutputPortName1 and m_sOutputPortName2 could not be established and the there were either no JACK ports holding the JackPortIsInput flag found or no connection to them could be established.

Implements AudioOutput.

Definition at line 163 of file JackAudioDriver.cpp.

◆ deactivate()

void deactivate ( )

Deactivates the JACK client of Hydrogen and disconnects all ports belonging to it.

Definition at line 264 of file JackAudioDriver.cpp.

◆ disconnect()

void disconnect ( )

overridevirtual

Disconnects the JACK client of the Hydrogen from the JACK server.

Implements AudioOutput.

Definition at line 244 of file JackAudioDriver.cpp.

◆ getBufferSize()

unsigned getBufferSize ( )

overridevirtual

Returns: Global variable jackServerBufferSize.

Implements AudioOutput.

Definition at line 276 of file JackAudioDriver.cpp.

◆ getConnectDefaults()

bool getConnectDefaults ( )

inline

Returns: m_bConnectDefaults

Definition at line 188 of file JackAudioDriver.h.

◆ getJackPosition()

const jack_position_t & getJackPosition ( ) const

Definition at line 305 of file JackAudioDriver.cpp.

◆ getOut_L()

float * getOut_L ( )

overridevirtual

Get content in the left stereo output port.

Returns: Pointer to buffer content of type jack_default_audio_sample_t* (jack/types.h)

Implements AudioOutput.

Definition at line 778 of file JackAudioDriver.cpp.

◆ getOut_R()

float * getOut_R ( )

overridevirtual

Get content in the right stereo output port.

Returns: Pointer to buffer content of type jack_default_audio_sample_t* (jack/types.h)

Implements AudioOutput.

Definition at line 792 of file JackAudioDriver.cpp.

◆ getSampleRate()

unsigned getSampleRate ( )

overridevirtual

Returns: Global variable jackServerSampleRate.

Implements AudioOutput.

Definition at line 281 of file JackAudioDriver.cpp.

◆ getTimebaseControllerBpm()

float getTimebaseControllerBpm ( ) const

Returns: the BPM reported by the current (external) Timebase controller or NAN if there is none.

Definition at line 1424 of file JackAudioDriver.cpp.

◆ getTimebaseState()

JackAudioDriver::Timebase getTimebaseState ( ) const

Returns: m_timebaseState

Definition at line 1417 of file JackAudioDriver.cpp.

◆ getTrackOut_L() [1/2]

float * getTrackOut_L	(	std::shared_ptr< Instrument >	instr,
		std::shared_ptr< InstrumentComponent >	pCompo )

Convenience function looking up the track number of a component of an instrument using in m_trackMap using their IDs Instrument::__id and InstrumentComponent::__related_drumkit_componentID.

Using the track number it then calls getTrackOut_L( unsigned ) and returns its result.

Parameters

instr	Pointer to an Instrument
pCompo	Pointer to one of the instrument's components.

Returns: Pointer to buffer content of type jack_default_audio_sample_t* (jack/types.h)

Definition at line 826 of file JackAudioDriver.cpp.

◆ getTrackOut_L() [2/2]

float * getTrackOut_L ( unsigned nTrack )

Get content of left output port of a specific track.

Parameters

nTrack Track number. Must not be bigger than m_nTrackPortCount.

Returns: Pointer to buffer content of type jack_default_audio_sample_t* (jack/types.h)

Definition at line 798 of file JackAudioDriver.cpp.

◆ getTrackOut_R() [1/2]

float * getTrackOut_R	(	std::shared_ptr< Instrument >	instr,
		std::shared_ptr< InstrumentComponent >	pCompo )

Convenience function looking up the track number of a component of an instrument using in m_trackMap using their IDs Instrument::__id and InstrumentComponent::__related_drumkit_componentID.

Using the track number it then calls getTrackOut_R( unsigned ) and returns its result.

Parameters

instr	Pointer to an Instrument
pCompo	Pointer to one of the instrument's components.

Returns: Pointer to buffer content of type jack_default_audio_sample_t* (jack/types.h)

Definition at line 831 of file JackAudioDriver.cpp.

◆ getTrackOut_R() [2/2]

float * getTrackOut_R ( unsigned nTrack )

Get content of right output port of a specific track.

Parameters

nTrack Track number. Must not be bigger than m_nTrackPortCount.

Returns: Pointer to buffer content of type jack_default_audio_sample_t* (jack/types.h)

Definition at line 812 of file JackAudioDriver.cpp.

◆ getXRuns()

int getXRuns ( ) const

overridevirtual

Get the number of XRuns that occurred since the audio driver has started.

Reimplemented from AudioOutput.

Definition at line 1432 of file JackAudioDriver.cpp.

◆ init()

int init ( unsigned bufferSize )

overridevirtual

Initializes the JACK audio driver.

Parameters

bufferSize Unused and only present to assure compatibility with the JACK API.

Returns

0 : on success.
-1 : if the pointer m_pClient obtained via jack_client_open() (jack/jack.h) is 0.
4 : unable to register the "out_L" and/or "out_R" output ports for the JACK client using jack_port_register() (jack/jack.h).

Implements AudioOutput.

Definition at line 853 of file JackAudioDriver.cpp.

◆ initTimebaseControl()

void initTimebaseControl ( )

Acquires control of JACK Timebase.

Definition at line 1250 of file JackAudioDriver.cpp.

◆ isBBTValid()

bool isBBTValid ( const jack_position_t & pos )

static

Definition at line 309 of file JackAudioDriver.cpp.

◆ jackDriverBufferSize()

int jackDriverBufferSize	(	jack_nframes_t	nframes,
		void *	arg )

static

Callback function for the JACK audio server to set the buffer size jackServerBufferSize.

Parameters

nframes	New buffer size.
arg	Not used

Returns: 0 on success

Definition at line 76 of file JackAudioDriver.cpp.

◆ jackDriverSampleRate()

int jackDriverSampleRate	(	jack_nframes_t	nframes,
		void *	param )

static

Callback function for the JACK audio server to set the sample rate jackServerSampleRate.

Parameters

nframes	New sample rate.
param	Object inheriting from the Logger class.

Returns: 0 on success

Definition at line 63 of file JackAudioDriver.cpp.

◆ jackDriverShutdown()

void jackDriverShutdown ( void * arg )

staticprivate

Callback function for the JACK audio server to shutting down the JACK driver.

Parameters

arg Unused.

Definition at line 85 of file JackAudioDriver.cpp.

◆ JackTimebaseCallback()

void JackTimebaseCallback	(	jack_transport_state_t	state,
		jack_nframes_t	nFrames,
		jack_position_t *	pJackPosition,
		int	new_pos,
		void *	arg )

staticprivate

Callback function for the JACK server to supply additional timebase information.

The function it will be called after the audioEngine_process() function and only if the m_JackTransportState is JackTransportRolling.

What is the BBT information?

There is no formal definition in the JACK API but the way it is interpreted by Hydrogen is the following:

bar: Number of patterns passed since the beginning of the song. beat: Number of quarters passed since the beginning of the pattern. tick: Number of ticks passed since the last beat (with respect to the current frame).

A tick is an internal measure representing the smallest resolution of the transport position in terms of the patterns. It consist of pAudioEngine->getTickSize() frames, which changes depending on the current tempo.

Parameters

state	Unused.
nFrames	Unused.
pJackPosition	Current transport position.
new_pos	Unused.
arg	Pointer to a JackAudioDriver instance.

Definition at line 1330 of file JackAudioDriver.cpp.

◆ JackTransportPosToQString()

QString JackTransportPosToQString ( const jack_position_t & pPos )

static

Definition at line 1448 of file JackAudioDriver.cpp.

◆ JackTransportStateToQString()

QString JackTransportStateToQString ( const jack_transport_state_t & pPos )

staticprivate

Definition at line 1471 of file JackAudioDriver.cpp.

◆ jackXRunCallback()

int jackXRunCallback ( void * arg )

static

Report an XRun event to the GUI.

Definition at line 96 of file JackAudioDriver.cpp.

◆ locateTransport()

void locateTransport ( long long nFrame )

Re-positions the transport position to nFrame.

The new position takes effect in two process cycles during which JACK's state will be in JackTransportStarting and the transport won't be rolling.

Parameters

nFrame Requested new transport position.

Definition at line 1198 of file JackAudioDriver.cpp.

◆ makeTrackOutputs()

void makeTrackOutputs ( std::shared_ptr< Song > pSong )

Creates per component output ports for each instrument.

Definition at line 1066 of file JackAudioDriver.cpp.

◆ printState()

void printState ( ) const

private

Show debugging information.

Definition at line 1436 of file JackAudioDriver.cpp.

◆ releaseTimebaseControl()

void releaseTimebaseControl ( )

Release Hydrogen from the JACK Timebase control.

This causes the JackTimebaseCallback() callback function to not be called by the JACK server anymore.

Definition at line 1292 of file JackAudioDriver.cpp.

◆ relocateUsingBBT()

void relocateUsingBBT ( )

Uses the bar-beat-tick information to relocate the transport position.

This type of operation is triggered whenever the transport position gets relocated or the tempo is changed using JACK in the presence of an external Timebase controller.

Definition at line 497 of file JackAudioDriver.cpp.

◆ setConnectDefaults()

void setConnectDefaults ( bool flag )

inline

Parameters

flag	Sets m_bConnectDefaults

Definition at line 184 of file JackAudioDriver.h.

◆ setTrackOutput()

void setTrackOutput	(	int	n,
		std::shared_ptr< Instrument >	instr,
		std::shared_ptr< InstrumentComponent >	pCompo,
		std::shared_ptr< Song >	pSong )

private

Renames the n 'th port of JACK client and creates it if it's not already present.

If the track number n is bigger than the number of ports currently in usage m_nTrackPortCount, n + 1 - m_nTrackPortCount new stereo ports will be created using jack_port_register() (jack/jack.h) and m_nTrackPortCount updated to n + 1.

Afterwards, the n 'th port is renamed to a concatenation of "Track_", DrumkitComponent::__name, "_", n + 1, "_", Instrument::__name, and "_L", or "_R" using either jack_port_rename() (if HAVE_JACK_PORT_RENAME is defined) or jack_port_set_name() (both jack/jack.h). The former renaming function triggers a PortRename notifications to clients that have registered a port rename handler.

Parameters

n	Track number for which a port should be renamed (and created).
instr	Pointer to the corresponding Instrument.
pCompo	Pointer to the corresponding InstrumentComponent.
pSong	Pointer to the corresponding Song.

Definition at line 1116 of file JackAudioDriver.cpp.

◆ startTransport()

void startTransport ( )

Tells the JACK server to start transport.

Definition at line 1174 of file JackAudioDriver.cpp.

◆ stopTransport()

void stopTransport ( )

Tells the JACK server to stop transport.

Definition at line 1186 of file JackAudioDriver.cpp.

◆ TimebaseFromInt()

JackAudioDriver::Timebase TimebaseFromInt ( int nState )

static

Definition at line 1503 of file JackAudioDriver.cpp.

◆ TimebaseToQString()

QString TimebaseToQString ( const Timebase & t )

static

Definition at line 1459 of file JackAudioDriver.cpp.

◆ TimebaseTrackingToQString()

QString TimebaseTrackingToQString ( const TimebaseTracking & t )

staticprivate

Definition at line 1491 of file JackAudioDriver.cpp.

◆ transportToBBT()

void transportToBBT	(	const TransportPosition &	transportPos,
		jack_position_t *	pPos )

static

Definition at line 413 of file JackAudioDriver.cpp.

◆ updateTransportPosition()

void updateTransportPosition ( )

The function queries the transport position and additional information from the JACK server, writes them to m_JackTransportPos and in m_JackTransportState, and updates the AudioEngine in case of a mismatch.

Definition at line 561 of file JackAudioDriver.cpp.

Friends And Related Symbol Documentation

◆ AudioEngineTests

friend class AudioEngineTests

friend

Definition at line 379 of file JackAudioDriver.h.

Field Documentation

◆ jackServerBufferSize

jack_nframes_t jackServerBufferSize = 0

static

Buffer size of the JACK audio server.

Definition at line 323 of file JackAudioDriver.h.

◆ jackServerSampleRate

unsigned long jackServerSampleRate = 0

static

Sample rate of the JACK audio server.

Definition at line 319 of file JackAudioDriver.h.

◆ jackServerXRuns

int jackServerXRuns = 0

static

Number of XRuns since the driver started.

Definition at line 329 of file JackAudioDriver.h.

◆ m_bConnectDefaults

bool m_bConnectDefaults

private

Specifies whether the default left and right (master) audio JACK ports will be automatically connected to the system's sink when registering the JACK client in connect().

Definition at line 585 of file JackAudioDriver.h.

◆ m_fLastTimebaseBpm

float m_fLastTimebaseBpm

private

Stores the last tempo sent by an external Timebase controller.

In case of Timebase::Listener and TimebaseTracking::OnHold - a relocation was done by a client other than the current Timebase controller - the JACK server does not have any BBT information to share for at least one cycle. We have guard against this or else we have some spurious state changes. If such a thing happens, it is very likely that the controller will still be controller and we will still be listener once transport is starting again. Therefore, we pretend to still be in this state instead of dropping Timebase state too and offer the last tempo to the remainder of Hydrogen.

Definition at line 608 of file JackAudioDriver.h.

◆ m_JackTransportPos

jack_position_t m_JackTransportPos

private

Current transport position obtained using jack_transport_query() (jack/transport.h).

It corresponds to the first frame of the current cycle.

The valid member of m_JackTransportPos will show which fields contain valid data. Thus, if it is set to JackPositionBBT, bar, beat, and tick information are provided by the current Timebase controller in addition to the transport information in frames. It is of class jack_position_bits_t (jack/types.h) and is an enumerator with five different options:

JackPositionBBT = 0x10 : Bar, Beat, Tick
JackPositionTimecode = 0x20 : External timecode
JackBBTFrameOffset = 0x40 : Frame offset of BBT information
JackAudioVideoRatio = 0x80 : audio frames per video frame
JackVideoFrameOffset = 0x100 : frame offset of first video frame

Definition at line 574 of file JackAudioDriver.h.

◆ m_JackTransportState

jack_transport_state_t m_JackTransportState

private

Current transport state returned by jack_transport_query() (jack/transport.h).

It is valid for the entire cycle and can have five different values:

JackTransportStopped = 0 : Transport is halted
JackTransportRolling = 1 : Transport is playing
JackTransportLooping = 2 : For OLD_TRANSPORT, now ignored
JackTransportStarting = 3 : Waiting for sync ready
JackTransportNetStarting = 4 : Waiting for sync ready on the network

The actual number of states depends on your JACK version. The listing above was done for version 1.9.12.

Definition at line 551 of file JackAudioDriver.h.

◆ m_lastTransportBits

int m_lastTransportBits

private

Remembers the BBT capability bit received in a JACK process cycle.

In case a regular client triggeres a relocation, the transport bit will be 0 and we rely on just the frame position to relocate internally. However, in the next process cycle the JACK Timebase controller will have added additional BBT information to that location. Since we want to use its tempo, we also have to use the remainder of the BBT information and trigger a relocation (although the overall frame might not even have changed). In addition, the Timebase controller could alter its capabilities.

The behavior above has the negativ side effect that we might not relocate to the exact frame we requested ourselves. But AFAICS this is a bug in the JACK API.

Definition at line 634 of file JackAudioDriver.h.

◆ m_nextJackTransportPos

jack_position_t m_nextJackTransportPos

private

Use for relocation if Hydrogen is Timebase controller (and needs to provide valid BBT information in addition to just a frame).

Definition at line 578 of file JackAudioDriver.h.

◆ m_nTimebaseFrameOffset

long long m_nTimebaseFrameOffset

private

Stores an intended deviation of our transport position from the one hold by the JACK server.

In case we act as listener we will relocate based on the provided BBT information. This is done by converting them into a tick and calculating the corresponding frame. That resultant frame does not necessarily have to coincide with the one broadcasted by the JACK server. But this is no problems as BBT takes precedeence.

Definition at line 618 of file JackAudioDriver.h.

◆ m_nTrackPortCount

int m_nTrackPortCount

private

Total number of output ports currently in use.

Definition at line 522 of file JackAudioDriver.h.

◆ m_pClient

jack_client_t* m_pClient

Object holding the external client session with the JACK server.

Definition at line 124 of file JackAudioDriver.h.

◆ m_pOutputPort1

jack_port_t* m_pOutputPort1

private

Left source port.

Definition at line 494 of file JackAudioDriver.h.

◆ m_pOutputPort2

jack_port_t* m_pOutputPort2

private

Right source port.

Definition at line 498 of file JackAudioDriver.h.

◆ m_processCallback

JackProcessCallback m_processCallback

private

Main process callback.

Definition at line 490 of file JackAudioDriver.h.

◆ m_pTrackOutputPortsL

jack_port_t* m_pTrackOutputPortsL[MAX_INSTRUMENTS]

private

Vector of all left audio output ports currently used by the local JACK client.

Definition at line 527 of file JackAudioDriver.h.

◆ m_pTrackOutputPortsR

jack_port_t* m_pTrackOutputPortsR[MAX_INSTRUMENTS]

private

Vector of all right audio output ports currently used by the local JACK client.

Definition at line 532 of file JackAudioDriver.h.

◆ m_sOutputPortName1

QString m_sOutputPortName1

private

Destination of the left source port m_pOutputPort1, for which a connection will be established in connect().

Definition at line 503 of file JackAudioDriver.h.

◆ m_sOutputPortName2

QString m_sOutputPortName2

private

Destination of the right source port m_pOutputPort2, for which a connection will be established in connect().

Definition at line 508 of file JackAudioDriver.h.

◆ m_timebaseState

Timebase m_timebaseState

private

Whether Hydrogen is receiving relocation and tempo changes as part of BBT information, it sends them itself, or just uses internal position information.

Definition at line 592 of file JackAudioDriver.h.

◆ m_timebaseTracking

TimebaseTracking m_timebaseTracking

private

Whether the current timebase state is stable or about to change.

Definition at line 595 of file JackAudioDriver.h.

◆ m_trackMap

int m_trackMap[MAX_INSTRUMENTS][MAX_COMPONENTS]

private

Matrix containing the track number of each component of all instruments.

Its rows represent the instruments and its columns their components. m_trackMap[2][1]=6 thus therefore mean the output of the second component of the third instrument is assigned the seventh output port. Since its total size is defined by MAX_INSTRUMENTS and MAX_COMPONENTS, most of its entries will be zero.

Definition at line 518 of file JackAudioDriver.h.

◆ pJackDriverInstance

JackAudioDriver * pJackDriverInstance = nullptr

static

Instance of the JackAudioDriver.

Definition at line 327 of file JackAudioDriver.h.

Public Types

Public Member Functions

Static Public Member Functions

Data Fields

Static Public Attributes

Private Types

Private Member Functions

Static Private Member Functions

Private Attributes

Friends

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

◆ Timebase

◆ TimebaseTracking

Constructor & Destructor Documentation

◆ JackAudioDriver()

◆ ~JackAudioDriver()

Member Function Documentation

◆ bbtToTick()

◆ checkBBTPos()

◆ clearPerTrackAudioBuffers()

◆ connect()

◆ deactivate()

◆ disconnect()

◆ getBufferSize()

◆ getConnectDefaults()

◆ getJackPosition()

◆ getOut_L()

◆ getOut_R()

◆ getSampleRate()

◆ getTimebaseControllerBpm()

◆ getTimebaseState()

◆ getTrackOut_L() [1/2]

◆ getTrackOut_L() [2/2]

◆ getTrackOut_R() [1/2]

◆ getTrackOut_R() [2/2]

◆ getXRuns()

◆ init()

◆ initTimebaseControl()

◆ isBBTValid()

◆ jackDriverBufferSize()

◆ jackDriverSampleRate()

◆ jackDriverShutdown()

◆ JackTimebaseCallback()

◆ JackTransportPosToQString()

◆ JackTransportStateToQString()

◆ jackXRunCallback()

◆ locateTransport()

◆ makeTrackOutputs()

◆ printState()

◆ releaseTimebaseControl()

◆ relocateUsingBBT()

◆ setConnectDefaults()

◆ setTrackOutput()

◆ startTransport()

◆ stopTransport()

◆ TimebaseFromInt()

◆ TimebaseToQString()

◆ TimebaseTrackingToQString()

◆ transportToBBT()

◆ updateTransportPosition()

Friends And Related Symbol Documentation

◆ AudioEngineTests

Field Documentation

◆ jackServerBufferSize

◆ jackServerSampleRate

◆ jackServerXRuns

◆ m_bConnectDefaults

◆ m_fLastTimebaseBpm

◆ m_JackTransportPos

◆ m_JackTransportState

◆ m_lastTransportBits

◆ m_nextJackTransportPos

◆ m_nTimebaseFrameOffset

◆ m_nTrackPortCount

◆ m_pClient

◆ m_pOutputPort1

◆ m_pOutputPort2

◆ m_processCallback