JACK-AUDIO-CONNECTION-KIT: Managing and determining latency

JACK-AUDIO-CONNECTION-KIT

Loading...
Searching...
No Matches
Topics | Functions
Managing and determining latency
Creating & manipulating clients » The non-callback API » Setting Client Callbacks » Controlling & querying JACK server operation » Creating & manipulating ports

## Topics
| Looking up ports

## Functions
void | jack_port_set_latency (jack_port_t *, jack_nframes_t) JACK_OPTIONAL_WEAK_DEPRECATED_EXPORT
void | jack_port_get_latency_range (jack_port_t *port, jack_latency_callback_mode_t mode, jack_latency_range_t *range) JACK_WEAK_EXPORT
void | jack_port_set_latency_range (jack_port_t *port, jack_latency_callback_mode_t mode, jack_latency_range_t *range) JACK_WEAK_EXPORT
int | jack_recompute_total_latencies (jack_client_t *) JACK_OPTIONAL_WEAK_EXPORT
jack_nframes_t | jack_port_get_latency (jack_port_t *port) JACK_OPTIONAL_WEAK_DEPRECATED_EXPORT
jack_nframes_t | jack_port_get_total_latency (jack_client_t *, jack_port_t *port) JACK_OPTIONAL_WEAK_DEPRECATED_EXPORT
int | jack_recompute_total_latency (jack_client_t *, jack_port_t *port) JACK_OPTIONAL_WEAK_DEPRECATED_EXPORT

## Detailed Description

The purpose of JACK's latency API is to allow clients to easily answer two questions:

- How long has it been since the data read from a port arrived at the edge of the JACK graph (either via a physical port or being synthesized from scratch)?
- How long will it be before the data written to a port arrives at the edge of a JACK graph?

To help answering these two questions, all JACK ports have two latency values associated with them, both measured in frames:

capture latency: how long since the data read from the buffer of a port arrived at at a port marked with JackPortIsTerminal. The data will have come from the "outside world" if the terminal port is also marked with JackPortIsPhysical, or will have been synthesized by the client that owns the terminal port.

playback latency: how long until the data written to the buffer of port will reach a port marked with JackPortIsTerminal.

Both latencies might potentially have more than one value because there may be multiple pathways to/from a given port and a terminal port. Latency is therefore generally expressed a min/max pair.

In most common setups, the minimum and maximum latency are the same, but this design accomodates more complex routing, and allows applications (and thus users) to detect cases where routing is creating an anomalous situation that may either need fixing or more sophisticated handling by clients that care about latency.

See also jack_set_latency_callback for details on how clients that add latency to the signal path should interact with JACK to ensure that the correct latency figures are used.

## Function Documentation

## ◆ jack_port_get_latency()

jack_nframes_t jack_port_get_latency | ( | jack_port_t * | port | ) |

Returns
  the time (in frames) between data being available or delivered at/to a port, and the time at which it arrived at or is delivered to the "other side" of the port. E.g. for a physical audio output port, this is the time between writing to the port and when the signal will leave the connector. For a physical audio input port, this is the time between the sound arriving at the connector and the corresponding frames being readable from the port.

Deprecated
  This method will be removed in the next major release of JACK. It should not be used in new code, and should be replaced by jack_port_get_latency_range() in any existing use cases.

References jack_port_get_latency().

Referenced by jack_port_get_latency().

## ◆ jack_port_get_latency_range()

void jack_port_get_latency_range | ( | jack_port_t * | port,
|  | jack_latency_callback_mode_t | mode,
|  | jack_latency_range_t * | range )

return the latency range defined by mode for port, in frames.

See Managing and determining latency for the definition of each latency value.

This function is best used from callbacks, specifically the latency callback. Before a port is connected, this returns the default latency: zero. Therefore it only makes sense to call jack_port_get_latency_range() when the port is connected, and that gets signalled by the latency callback. See jack_set_latency_callback() for details.

References jack_port_get_latency_range().

Referenced by jack_port_get_latency_range().

## ◆ jack_port_get_total_latency()

jack_nframes_t jack_port_get_total_latency | ( | jack_client_t * | ,
|  | jack_port_t * | port )

The maximum of the sum of the latencies in every connection path that can be drawn between the port and other ports with the JackPortIsTerminal flag set.

Deprecated
  This method will be removed in the next major release of JACK. It should not be used in new code, and should be replaced by jack_port_get_latency_range() in any existing use cases.

References jack_port_get_total_latency().

Referenced by jack_port_get_total_latency().

## ◆ jack_port_set_latency()

void jack_port_set_latency | ( | jack_port_t * | ,
|  | jack_nframes_t | )

The port latency is zero by default. Clients that control physical hardware with non-zero latency should call this to set the latency to its correct value. Note that the value should include any systemic latency present "outside" the physical hardware controlled by the client. For example, for a client controlling a digital audio interface connected to an external digital converter, the latency setting should include both buffering by the audio interface and the converter.

Deprecated
  This method will be removed in the next major release of JACK. It should not be used in new code, and should be replaced by a latency callback that calls jack_port_set_latency_range().

References jack_port_set_latency().

Referenced by jack_port_set_latency().

## ◆ jack_port_set_latency_range()

void jack_port_set_latency_range | ( | jack_port_t * | port,
|  | jack_latency_callback_mode_t | mode,
|  | jack_latency_range_t * | range )

set the minimum and maximum latencies defined by mode for port, in frames.

See Managing and determining latency for the definition of each latency value.

This function should ONLY be used inside a latency callback. The client should determine the current value of the latency using jack_port_get_latency_range() (called using the same mode as mode) and then add some number of frames to that reflects latency added by the client.

How much latency a client adds will vary dramatically. For most clients, the answer is zero and there is no reason for them to register a latency callback and thus they should never call this function.

More complex clients that take an input signal, transform it in some way and output the result but not during the same process() callback will generally know a single constant value to add to the value returned by jack_port_get_latency_range().

Such clients would register a latency callback (see jack_set_latency_callback) and must know what input ports feed which output ports as part of their internal state. Their latency callback will update the ports' latency values appropriately.

A pseudo-code example will help. The mode argument to the latency callback will determine whether playback or capture latency is being set. The callback will use jack_port_set_latency_range() as follows:

jack_latency_range_t range;
if (mode == JackPlaybackLatency) {
foreach input_port in (all self-registered port) {
jack_port_get_latency_range (port_feeding_input_port, JackPlaybackLatency, &range);
range.min += min_delay_added_as_signal_flows_from port_feeding to input_port;
range.max += max_delay_added_as_signal_flows_from port_feeding to input_port;
jack_port_set_latency_range (input_port, JackPlaybackLatency, &range);
}
} else if (mode == JackCaptureLatency) {
foreach output_port in (all self-registered port) {
jack_port_get_latency_range (port_fed_by_output_port, JackCaptureLatency, &range);
range.min += min_delay_added_as_signal_flows_from_output_port_to_fed_by_port;
range.max += max_delay_added_as_signal_flows_from_output_port_to_fed_by_port;
jack_port_set_latency_range (output_port, JackCaptureLatency, &range);
}
}
jack_port_set_latency_range
void jack_port_set_latency_range(jack_port_t *port, jack_latency_callback_mode_t mode, jack_latency_range_t *range) JACK_WEAK_EXPORT
jack_port_get_latency_range
void jack_port_get_latency_range(jack_port_t *port, jack_latency_callback_mode_t mode, jack_latency_range_t *range) JACK_WEAK_EXPORT
_jack_latency_range::max
jack_nframes_t max
Definition types.h:289
_jack_latency_range::min
jack_nframes_t min
Definition types.h:285
JackPlaybackLatency
@ JackPlaybackLatency
Definition types.h:259
JackCaptureLatency
@ JackCaptureLatency
Definition types.h:252
jack_latency_range_t
struct _jack_latency_range jack_latency_range_t
Definition types.h:292

In this relatively simple pseudo-code example, it is assumed that each input port or output is connected to only 1 output or input port respectively.

If a port is connected to more than 1 other port, then the range.min and range.max values passed to jack_port_set_latency_range() should reflect the minimum and maximum values across all connected ports.

See the description of jack_set_latency_callback for more information.

References jack_port_set_latency_range().

Referenced by jack_port_set_latency_range().

## ◆ jack_recompute_total_latencies()

int jack_recompute_total_latencies | ( | jack_client_t * |  | ) |

Request a complete recomputation of all port latencies. This can be called by a client that has just changed the internal latency of its port using jack_port_set_latency and wants to ensure that all signal pathways in the graph are updated with respect to the values that will be returned by jack_port_get_total_latency. It allows a client to change multiple port latencies without triggering a recompute for each change.

Returns
  zero for successful execution of the request. non-zero otherwise.

References JACK_OPTIONAL_WEAK_EXPORT, and jack_recompute_total_latencies().

Referenced by jack_recompute_total_latencies().

## ◆ jack_recompute_total_latency()

int jack_recompute_total_latency | ( | jack_client_t * | ,
|  | jack_port_t * | port )

Request a complete recomputation of a port's total latency. This can be called by a client that has just changed the internal latency of its port using jack_port_set_latency and wants to ensure that all signal pathways in the graph are updated with respect to the values that will be returned by jack_port_get_total_latency.

Returns
  zero for successful execution of the request. non-zero otherwise.

Deprecated
  This method will be removed in the next major release of JACK. It should not be used in new code, and should be replaced by jack_recompute_total_latencies() in any existing use cases.

References jack_recompute_total_latency().

Referenced by jack_recompute_total_latency().