---

jack.h File Reference

#include <jack/types.h>
#include <jack/error.h>
#include <jack/transport.h>

Go to the source code of this file.

Functions
jack_client_t *	jack_client_new (const char *client_name)
int	jack_client_close (jack_client_t *client)
void	jack_on_shutdown (jack_client_t *client, void(*function)(void *arg), void *arg)
int	jack_set_process_callback (jack_client_t *, JackProcessCallback process_callback, void *arg)
int	jack_set_buffer_size_callback (jack_client_t *, JackBufferSizeCallback bufsize_callback, void *arg)
int	jack_set_sample_rate_callback (jack_client_t *, JackSampleRateCallback srate_callback, void *arg)
int	jack_set_port_registration_callback (jack_client_t *, JackPortRegistrationCallback registration_callback, void *arg)
int	jack_set_graph_order_callback (jack_client_t *, JackGraphOrderCallback graph_callback, void *)
int	jack_set_xrun_callback (jack_client_t *, JackXRunCallback xrun_callback, void *arg)
int	jack_activate (jack_client_t *client)
int	jack_deactivate (jack_client_t *client)
jack_port_t *	jack_port_register (jack_client_t *, const char *port_name, const char *port_type, unsigned long flags, unsigned long buffer_size)
int	jack_port_unregister (jack_client_t *, jack_port_t *)
const char *	jack_port_name (const jack_port_t *port)
const char *	jack_port_short_name (const jack_port_t *port)
int	jack_port_flags (const jack_port_t *port)
const char *	jack_port_type (const jack_port_t *port)
int	jack_port_is_mine (const jack_client_t *, const jack_port_t *port)
int	jack_port_connected (const jack_port_t *port)
int	jack_port_connected_to (const jack_port_t *port, const char *portname)
int	jack_port_connected_to_port (const jack_port_t *port, const jack_port_t *other_port)
const char **	jack_port_get_connections (const jack_port_t *port)
int	jack_port_set_name (jack_port_t *port, const char *name)
void *	jack_port_get_buffer (jack_port_t *, jack_nframes_t)
int	jack_connect (jack_client_t *, const char *source_port, const char *destination_port)
int	jack_disconnect (jack_client_t *, const char *source_port, const char *destination_port)
int	jack_port_connect (jack_client_t *, jack_port_t *src, jack_port_t *dst)
int	jack_port_disconnect (jack_client_t *, jack_port_t *)
int	jack_port_tie (jack_port_t *src, jack_port_t *dst)
int	jack_port_untie (jack_port_t *port)
int	jack_port_lock (jack_client_t *, jack_port_t *)
int	jack_port_unlock (jack_client_t *, jack_port_t *)
jack_nframes_t	jack_port_get_latency (jack_port_t *port)
jack_nframes_t	jack_port_get_total_latency (jack_client_t *, jack_port_t *port)
void	jack_port_set_latency (jack_port_t *, jack_nframes_t)
int	jack_port_request_monitor (jack_port_t *port, int onoff)
int	jack_port_request_monitor_by_name (jack_client_t *client, const char *port_name, int onoff)
int	jack_port_ensure_monitor (jack_port_t *port, int onoff)
int	jack_port_monitoring_input (jack_port_t *port)
unsigned long	jack_get_sample_rate (jack_client_t *)
jack_nframes_t	jack_get_buffer_size (jack_client_t *)
const char **	jack_get_ports (jack_client_t *, const char *port_name_pattern, const char *type_name_pattern, unsigned long flags)
jack_port_t *	jack_port_by_name (jack_client_t *, const char *portname)
jack_port_t *	jack_port_by_id (jack_client_t *client, jack_port_id_t id)
int	jack_engine_takeover_timebase (jack_client_t *)
void	jack_update_time (jack_client_t *, jack_nframes_t)
jack_nframes_t	jack_frames_since_cycle_start (const jack_client_t *)
jack_nframes_t	jack_frame_time (const jack_client_t *)
float	jack_cpu_load (jack_client_t *client)

---

Function Documentation

int jack_activate (  jack_client_t *    client )

Tell the Jack server that the program is ready to start processing audio.

int jack_client_close (  jack_client_t *    client )

Disconnects from Jack server.

jack_client_t* jack_client_new (  const char *    client_name )

Attemps to become a client of the Jack server.

int jack_connect (  jack_client_t *   , const char *    source_port, const char *    destination_port )

Establishes a connection between two ports. When a connection exists, data written to the source port will be available to be read at the destination port. The types of both ports must be identical to establish a connection. The flags of the source port must include PortIsOutput. The flags of the destination port must include PortIsInput.

float jack_cpu_load (  jack_client_t *    client )

This returns the current CPU load estimated by JACK as a percentage. The load is computed by measuring the number of cycles it took to execute all clients as a fraction of the total number of cycles represented by the data that was processed.

int jack_deactivate (  jack_client_t *    client )

Tells the Jack server that the program should be removed from the processing graph. As a side effect, this will disconnect any and all ports belonging to the client, since inactive clients are not allowed to be connected to any other ports.

int jack_disconnect (  jack_client_t *   , const char *    source_port, const char *    destination_port )

Removes a connection between two ports. The types of both ports must be identical to establish a connection. The flags of the source port must include PortIsOutput. The flags of the destination port must include PortIsInput.

int jack_engine_takeover_timebase (  jack_client_t *    )

If a client is told (by the user) to become the timebase for the entire system, it calls this function. If it returns zero, then the client has the responsibility to call jack_set_transport_info()) at the end of its process() callback.

jack_nframes_t jack_frame_time (  const jack_client_t *    )

Return an estimate of the current time in frames. It is a running counter - no significance should be attached to the return value. it should be used to compute the difference between a previously returned value.

jack_nframes_t jack_frames_since_cycle_start (  const jack_client_t *    )

This estimates the time that has passed since the start jack server started calling the process() callbacks of all its clients.

jack_nframes_t jack_get_buffer_size (  jack_client_t *    )

This returns the current maximum size that will ever be passed to the "process" callback. It should only be used *before* the client has been activated. After activation, the client will be notified of buffer size changes if it registers a buffer_size callback.

const char** jack_get_ports (  jack_client_t *   , const char *    port_name_pattern, const char *    type_name_pattern, unsigned long    flags )

Parameters: port_name_pattern  A regular expression used to select ports by name. If NULL or of zero length, no selection based on name will be carried out. type_name_pattern  A regular expression used to select ports by type. If NULL or of zero length, no selection based on type will be carried out. flags  A value used to select ports by their flags. If zero, no selection based on flags will be carried out. This function returns a NULL-terminated array of ports that match the specified arguments. The caller is responsible for calling free(3) any non-NULL returned value.

unsigned long jack_get_sample_rate (  jack_client_t *    )

This returns the sample rate of the jack system, as set by the user when jackd was started.

void jack_on_shutdown (  jack_client_t *    client, void(*    function)(void *arg), void *    arg )

Parameters: client  The Jack client structure. function  The jack_shutdown function pointer. arg  The arguments for the jack_shutdown function. Register a function (and argument) to be called if and when the JACK server shuts down the client thread. The function must be written as if it were an asynchonrous POSIX signal handler --- use only async-safe functions, and remember that it is executed from another thread. A typical function might set a flag or write to a pipe so that the rest of the application knows that the JACK client thread has shut down. NOTE: clients do not need to call this. It exists only to help more complex clients understand what is going on. If called, it must be called before jack_client_activate().

jack_port_t* jack_port_by_id (  jack_client_t *    client, jack_port_id_t    id )

Searchs for and returns the jack_port_t of id @id.

jack_port_t* jack_port_by_name (  jack_client_t *   , const char *    portname )

Searchs for and returns the jack_port_t with the name value from portname.

int jack_port_connect (  jack_client_t *   , jack_port_t *    src, jack_port_t *    dst )

Performs the exact same function as jack_connect(), but it uses port handles rather than names, which avoids the name lookup inherent in the name-based version. It is envisaged that clients connecting their own ports will use these two, whereas generic connection clients (e.g. patchbays) will use the name-based versions.

int jack_port_connected (  const jack_port_t *    port )

This returns TRUE or FALSE to indicate if there are any connections to/from the port argument.

int jack_port_connected_to (  const jack_port_t *    port, const char *    portname )

This returns TRUE or FALSE if the port argument is DIRECTLY connected to the port with the name given in 'portname'

int jack_port_connected_to_port (  const jack_port_t *    port, const jack_port_t *    other_port )

This returns TRUE or FALSE if the two ports are directly connected to each other.

int jack_port_disconnect (  jack_client_t *   , jack_port_t *    )

Performs the exact same function as jack_disconnect(), but it uses port handles rather than names, which avoids the name lookup inherent in the name-based version. It is envisaged that clients disconnecting their own ports will use these two, whereas generic connection clients (e.g. patchbays) will use the name-based versions.

int jack_port_ensure_monitor (  jack_port_t *    port, int    onoff )

If JackPortCanMonitor is set for a port, then this function will turn on input monitoring if it was off, and will turn it off it only one request has been made to turn it on. If JackPortCanMonitor is not set, then this function will do nothing.

int jack_port_flags (  const jack_port_t *    port )

Returns the flags of the jack_port_t.

void* jack_port_get_buffer (  jack_port_t *   , jack_nframes_t    )

This returns a pointer to the memory area associated with the specified port. For an output port, it will be a memory area that can be written to; for an input port, it will be an area containing the data from the port's connection(s), or zero-filled. if there are multiple inbound connections, the data will be mixed appropriately. You may cache the value returned, but only between calls to your "blocksize" callback. For this reason alone, you should either never cache the return value or ensure you have a "blocksize" callback and be sure to invalidate the cached address from there.

const char** jack_port_get_connections (  const jack_port_t *    port )

This returns a null-terminated array of port names to which the argument port is connected. if there are no connections, it returns NULL. The caller is responsible for calling free(3) on any non-NULL returned value.

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 audio will be audible. For a physical audio input port, this is the time between the sound being audible and the corresponding frames being readable from the port.

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.

int jack_port_is_mine (  const jack_client_t *   , const jack_port_t *    port )

Returns 1 if the jack_port_t belongs to the jack_client_t.

int jack_port_lock (  jack_client_t *   , jack_port_t *    )

A client may call this function to prevent other objects from changing the connection status of a port. The port must be owned by the calling client.

int jack_port_monitoring_input (  jack_port_t *    port )

Returns a true or false value depending on whether or not input monitoring has been requested for 'port'.

const char* jack_port_name (  const jack_port_t *    port )

Returns the name of the jack_port_t.

jack_port_t* jack_port_register (  jack_client_t *   , const char *    port_name, const char *    port_type, unsigned long    flags, unsigned long    buffer_size )

This creates a new port for the client. A port is an object used for moving data in or out of the client. the data may be of any type. Ports may be connected to each other in various ways. A port has a short name, which may be any non-NULL and non-zero length string, and is passed as the first argument. A port's full name is the name of the client concatenated with a colon (:) and then its short name. A port has a type, which may be any non-NULL and non-zero length string, and is passed as the second argument. For types that are not built into the jack API (currently just JACK_DEFAULT_AUDIO_TYPE) the client MUST supply a non-zero size for the buffer as for @buffer_size. For builtin types, @buffer_size is ignored. The @flags argument is formed from a bitmask of JackPortFlags values.

int jack_port_request_monitor (  jack_port_t *    port, int    onoff )

If JackPortCanMonitor is set for a port, then these 2 functions will turn on/off input monitoring for the port. If JackPortCanMonitor is not set, then these functions will have no effect.

int jack_port_request_monitor_by_name (  jack_client_t *    client, const char *    port_name, int    onoff )

If JackPortCanMonitor is set for a port, then these 2 functions will turn on/off input monitoring for the port. If JackPortCanMonitor is not set, then these functions will have no effect.

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.

int jack_port_set_name (  jack_port_t *    port, const char *    name )

This modifies a port's name, and may be called at any time.

const char* jack_port_short_name (  const jack_port_t *    port )

Returns the short name of the jack_port_t.

int jack_port_tie (  jack_port_t *    src, jack_port_t *    dst )

A client may call this on a pair of its own ports to semi-permanently wire them together. This means that a client that wants to direct-wire an input port to an output port can call this and then no longer have to worry about moving data between them. Any data arriving at the input port will appear automatically at the output port. The 'destination' port must be an output port. The 'source' port must be an input port. Both ports must belong to the same client. You cannot use this to tie ports between clients. That is what a connection is for.

const char* jack_port_type (  const jack_port_t *    port )

Returns the type of the jack_port_t.

int jack_port_unlock (  jack_client_t *   , jack_port_t *    )

This allows other objects to change the connection status of a port.

int jack_port_unregister (  jack_client_t *   , jack_port_t *    )

This removes the port from the client, disconnecting any existing connections at the same time.

int jack_port_untie (  jack_port_t *    port )

This undoes the effect of jack_port_tie(). The port should be same as the 'destination' port passed to jack_port_tie().

int jack_set_buffer_size_callback (  jack_client_t *   , JackBufferSizeCallback    bufsize_callback, void *    arg )

Tell the Jack server to call 'bufsize_callback' whenever the maximum number of frames that could be passed to 'process()' changes. 'arg' will be supplied as a second argument.

int jack_set_graph_order_callback (  jack_client_t *   , JackGraphOrderCallback    graph_callback, void *    )

Tell the Jack server to call 'registration_callback' whenever the processing graph is reordered, passing 'arg' as an argument.

int jack_set_port_registration_callback (  jack_client_t *   , JackPortRegistrationCallback    registration_callback, void *    arg )

Tell the Jack server to call 'registration_callback' whenever a port is registered or unregistered, passing 'arg' as a second argument.

int jack_set_process_callback (  jack_client_t *   , JackProcessCallback    process_callback, void *    arg )

Tell the Jack server to call 'process_callback' whenever there is work be done, passing 'arg' as the second argument.

int jack_set_sample_rate_callback (  jack_client_t *   , JackSampleRateCallback    srate_callback, void *    arg )

Tell the Jack server to call 'srate_callback' whenever the sample rate of the system changes.

int jack_set_xrun_callback (  jack_client_t *   , JackXRunCallback    xrun_callback, void *    arg )

Tell the Jack server to call 'xrun_callback' whenever there is a xrun, passing 'arg' as an argument.

void jack_update_time (  jack_client_t *   , jack_nframes_t    )

undocumented

---