jack.h File Reference

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

Go to the source code of this file.

Functions

jack_client_tjack_client_open (const char *client_name, jack_options_t options, jack_status_t *status,...)
jack_client_tjack_client_new (const char *client_name)
int jack_client_close (jack_client_t *client)
int jack_client_name_size (void)
char * jack_get_client_name (jack_client_t *client)
int jack_internal_client_new (const char *client_name, const char *load_name, const char *load_init)
void jack_internal_client_close (const char *client_name)
int jack_is_realtime (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 *client, JackProcessCallback process_callback, void *arg)
int jack_set_thread_init_callback (jack_client_t *client, JackThreadInitCallback thread_init_callback, void *arg)
int jack_set_freewheel_callback (jack_client_t *client, JackFreewheelCallback freewheel_callback, void *arg)
int jack_set_freewheel (jack_client_t *client, int onoff)
int jack_set_buffer_size (jack_client_t *client, jack_nframes_t nframes)
int jack_set_buffer_size_callback (jack_client_t *client, JackBufferSizeCallback bufsize_callback, void *arg)
int jack_set_sample_rate_callback (jack_client_t *client, 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_tjack_port_register (jack_client_t *client, 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 *)
void * jack_port_get_buffer (jack_port_t *, jack_nframes_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 *port_name)
const char ** jack_port_get_connections (const jack_port_t *port)
const char ** jack_port_get_all_connections (const jack_client_t *client, const jack_port_t *port)
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_recompute_total_latencies (jack_client_t *)
int jack_port_set_name (jack_port_t *port, const char *port_name)
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)
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_disconnect (jack_client_t *, jack_port_t *)
int jack_port_name_size (void)
int jack_port_type_size (void)
jack_nframes_t 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_tjack_port_by_name (jack_client_t *, const char *port_name)
jack_port_tjack_port_by_id (jack_client_t *client, jack_port_id_t port_id)
int jack_engine_takeover_timebase (jack_client_t *)
jack_nframes_t jack_frames_since_cycle_start (const jack_client_t *)
jack_nframes_t jack_frame_time (const jack_client_t *)
jack_nframes_t jack_last_frame_time (const jack_client_t *client)
float jack_cpu_load (jack_client_t *client)
pthread_t jack_client_thread_id (jack_client_t *)
void jack_set_error_function (void(*func)(const char *))

Variables

void(* jack_error_callback )(const char *msg)


Function Documentation

int jack_activate jack_client_t client  ) 
 

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

Returns:
0 on success, otherwise a non-zero error code

int jack_client_close jack_client_t client  ) 
 

Disconnects an external client from a JACK server.

Returns:
0 on success, otherwise a non-zero error code

int jack_client_name_size void   ) 
 

Returns:
the maximum number of characters in a JACK client name including the final NULL character. This value is a constant.

jack_client_t* jack_client_new const char *  client_name  ) 
 

Attempt to become an external client of the Jack server.

JACK is evolving a mechanism for automatically starting the server when needed. As a transition, jack_client_new() only does this when $JACK_START_SERVER is defined in the environment of the calling process. In the future this will become normal behavior. For full control of this feature, use jack_client_open(), instead. In either case, defining $JACK_NO_START_SERVER disables this feature.

Parameters:
client_name of at most jack_client_name_size() characters. If this name is already in use, the request fails.
Returns:
Opaque client handle if successful, otherwise NULL.
Note:
Failure generally means that the JACK server is not running. If there was some other problem, it will be reported via the jack_error_callback mechanism. Use jack_client_open() and check the status parameter for more detailed information.

jack_client_t* jack_client_open const char *  client_name,
jack_options_t  options,
jack_status_t status,
  ...
 

Open an external client session with a JACK server. This interface is more complex but more powerful than jack_client_new(). With it, clients may choose which of several servers to connect, and control whether and how to start the server automatically, if it was not already running. There is also an option for JACK to generate a unique client name, when necessary.

Parameters:
client_name of at most jack_client_name_size() characters. The name scope is local to each server. Unless forbidden by the JackUseExactName option, the server will modify this name to create a unique variant, if needed.
options formed by OR-ing together JackOptions bits. Only the JackOpenOptions bits are allowed.
status (if non-NULL) an address for JACK to return information from the open operation. This status word is formed by OR-ing together the relevant JackStatus bits.
Optional parameters: depending on corresponding [options bits] additional parameters may follow status (in this order).

  • [JackServerName] (char *) server_name selects from among several possible concurrent server instances. Server names are unique to each user. If unspecified, use "default" unless $JACK_DEFAULT_SERVER is defined in the process environment.
Returns:
Opaque client handle if successful. If this is NULL, the open operation failed, *status includes JackFailure and the caller is not a JACK client.

pthread_t jack_client_thread_id jack_client_t  ) 
 

Returns:
the pthread ID of the thread running the JACK client side code.

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

Establish 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.

Precondition:
The port types must be identical.

The JackPortFlags of the source_port must include JackPortIsOutput.

The JackPortFlags of the destination_port must include JackPortIsInput.

Returns:
0 on success, EEXIST if the connection is already made, otherwise a non-zero error code

float jack_cpu_load jack_client_t client  ) 
 

Returns:
the current CPU load estimated by JACK. This is a running average of the time it takes to execute a full process cycle for all clients as a percentage of the real time available per cycle determined by the buffer size and sample rate.

int jack_deactivate jack_client_t client  ) 
 

Tell the Jack server to remove this client from the process graph. Also, disconnect all ports belonging to it, since inactive clients have no port connections.

Returns:
0 on success, otherwise a non-zero error code

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

Remove a connection between two ports.

Precondition:
The port types must be identical.

The JackPortFlags of the source_port must include JackPortIsOutput.

The JackPortFlags of the destination_port must include JackPortIsInput.

Returns:
0 on success, otherwise a non-zero error code

int jack_engine_takeover_timebase jack_client_t  ) 
 

Old-style interface to become the timebase for the entire JACK subsystem.

Deprecated:
This function still exists for compatibility with the earlier transport interface, but it does nothing. Instead, see transport.h and use jack_set_timebase_callback().
Returns:
ENOSYS, function not implemented.

jack_nframes_t jack_frame_time const jack_client_t  ) 
 

Returns:
an estimate of the current time in frames. This is a running counter, no significance should be attached to its value, but it can be compared to a previously returned value.

jack_nframes_t jack_frames_since_cycle_start const jack_client_t  ) 
 

Returns:
the time in frames that has passed since the JACK server began the current process cycle.

jack_nframes_t jack_get_buffer_size jack_client_t  ) 
 

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. This size may change, clients that depend on it must register a bufsize_callback so they will be notified if it does.
See also:
jack_set_buffer_size_callback()

char* jack_get_client_name jack_client_t client  ) 
 

Returns:
pointer to actual client name. This is useful when JackUseExactName is not specified on open and JackNameNotUnique status was returned. In that case, the actual name will differ from the client_name requested.

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.
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.
See also:
jack_port_name_size(), jack_port_type_size()

jack_nframes_t jack_get_sample_rate jack_client_t  ) 
 

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

void jack_internal_client_close const char *  client_name  ) 
 

Remove an internal client from a JACK server.

Deprecated:
Please use jack_internal_client_load().

int jack_internal_client_new const char *  client_name,
const char *  load_name,
const char *  load_init
 

Load an internal client into the Jack server.

Internal clients run inside the JACK server process. They can use most of the same functions as external clients. Each internal client must declare jack_initialize() and jack_finish() entry points, called at load and unload times. See inprocess.c for an example of how to write an internal client.

Deprecated:
Please use jack_internal_client_load().
Parameters:
client_name of at most jack_client_name_size() characters.
load_name of a shared object file containing the code for the new client.
load_init an arbitary string passed to the jack_initialize() routine of the new client (may be NULL).
Returns:
0 if successful.

int jack_is_realtime jack_client_t client  ) 
 

Parameters:
client pointer to JACK client structure.
Check if the JACK subsystem is running with -R (--realtime).

Returns:
1 if JACK is running realtime, 0 otherwise

jack_nframes_t jack_last_frame_time const jack_client_t client  ) 
 

Returns:
the frame_time after the last processing of the graph this is only to be used from the process callback.
This function can be used to put timestamps generated by jack_frame_time() in correlation to the current process cycle.

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

Parameters:
client pointer to 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. It should be called before jack_client_activate().

jack_port_t* jack_port_by_id jack_client_t client,
jack_port_id_t  port_id
 

Returns:
address of the jack_port_t of a port_id.

jack_port_t* jack_port_by_name jack_client_t ,
const char *  port_name
 

Returns:
address of the jack_port_t named port_name.
See also:
jack_port_name_size()

int jack_port_connected const jack_port_t port  ) 
 

Returns:
number of connections to or from port.
Precondition:
The calling client must own port.

int jack_port_connected_to const jack_port_t port,
const char *  port_name
 

Returns:
TRUE if the locally-owned port is directly connected to the port_name.
See also:
jack_port_name_size()

int jack_port_disconnect jack_client_t ,
jack_port_t
 

Perform the same function as jack_disconnect() using port handles rather than names. This avoids the name lookup inherent in the name-based version.

Clients connecting their own ports are likely to use this function, while generic connection clients (e.g. patchbays) would use jack_disconnect().

int jack_port_ensure_monitor jack_port_t port,
int  onoff
 

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

Returns:
0 on success, otherwise a non-zero error code

int jack_port_flags const jack_port_t port  ) 
 

Returns:
the JackPortFlags of the jack_port_t.

const char** jack_port_get_all_connections const jack_client_t client,
const jack_port_t port
 

Returns:
a null-terminated array of full port names to which the port is connected. If none, returns NULL.
The caller is responsible for calling free(3) on any non-NULL returned value.

This differs from jack_port_get_connections() in two important respects:

1) You may not call this function from code that is executed in response to a JACK event. For example, you cannot use it in a GraphReordered handler.

2) You need not be the owner of the port to get information about its connections.

See also:
jack_port_name_size()

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.

FOR OUTPUT PORTS ONLY --------------------- 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  ) 
 

Returns:
a null-terminated array of full port names to which the port is connected. If none, returns NULL.
The caller is responsible for calling free(3) on any non-NULL returned value.

Parameters:
port locally owned jack_port_t pointer.
See also:
jack_port_name_size(), jack_port_get_all_connections()

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.

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:
TRUE 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.

Returns:
0 on success, otherwise a non-zero error code

int jack_port_monitoring_input jack_port_t port  ) 
 

Returns:
TRUE if input monitoring has been requested for port.

const char* jack_port_name const jack_port_t port  ) 
 

Returns:
the full name of the jack_port_t (including the "client_name:" prefix).
See also:
jack_port_name_size().

int jack_port_name_size void   ) 
 

Returns:
the maximum number of characters in a full JACK port name including the final NULL character. This value is a constant.
A port's full name contains the owning client name concatenated with a colon (:) followed by its short name and a NULL character.

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

Create a new port for the client. This is an object used for moving data of any type in or out of the client. Ports may be connected in various ways.

Each port has a short name. The port's full name contains the name of the client concatenated with a colon (:) followed by its short name. The jack_port_name_size() is the maximum length of this full name. Exceeding that will cause the port registration to fail and return NULL.

All ports have a type, which may be any non-NULL and non-zero length string, passed as an argument. Some port types are built into the JACK API, currently only JACK_DEFAULT_AUDIO_TYPE.

Parameters:
client pointer to JACK client structure.
port_name non-empty short name for the new port (not including the leading "client_name:").
port_type port type name. If longer than jack_port_type_size(), only that many characters are significant.
flags JackPortFlags bit mask.
buffer_size must be non-zero if this is not a built-in port_type. Otherwise, it is ignored.
Returns:
jack_port_t pointer on success, otherwise NULL.

int jack_port_request_monitor jack_port_t port,
int  onoff
 

If JackPortCanMonitor is set for this port, turn input monitoring on or off. Otherwise, do nothing.

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

If JackPortCanMonitor is set for this port_name, turn input monitoring on or off. Otherwise, do nothing.

Returns:
0 on success, otherwise a non-zero error code.
See also:
jack_port_name_size()

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 *  port_name
 

Modify a port's short name. May be called at any time. If the resulting full name (including the "client_name:" prefix) is longer than jack_port_name_size(), it will be truncated.

Returns:
0 on success, otherwise a non-zero error code.

const char* jack_port_short_name const jack_port_t port  ) 
 

Returns:
the short name of the jack_port_t (not including the "client_name:" prefix).
See also:
jack_port_name_size().

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.

Returns:
0 on success, otherwise a non-zero error code

const char* jack_port_type const jack_port_t port  ) 
 

Returns:
the port type, at most jack_port_type_size() characters including a final NULL.

int jack_port_type_size void   ) 
 

Returns:
the maximum number of characters in a JACK port type name including the final NULL character. This value is a constant.

int jack_port_unlock jack_client_t ,
jack_port_t
 

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

Returns:
0 on success, otherwise a non-zero error code

int jack_port_unregister jack_client_t ,
jack_port_t
 

Remove the port from the client, disconnecting any existing connections.

Returns:
0 on success, otherwise a non-zero error code

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().

Returns:
0 on success, otherwise a non-zero error code

int jack_recompute_total_latencies jack_client_t  ) 
 

int jack_set_buffer_size jack_client_t client,
jack_nframes_t  nframes
 

Change the buffer size passed to the process_callback.

This operation stops the JACK engine process cycle, then calls all registered bufsize_callback functions before restarting the process cycle. This will cause a gap in the audio flow, so it should only be done at appropriate stopping points.

See also:
jack_set_buffer_size_callback()
Parameters:
client pointer to JACK client structure.
nframes new buffer size. Must be a power of two.
Returns:
0 on success, otherwise a non-zero error code

int jack_set_buffer_size_callback jack_client_t client,
JackBufferSizeCallback  bufsize_callback,
void *  arg
 

Tell JACK to call bufsize_callback whenever the size of the the buffer that will be passed to the process_callback is about to change. Clients that depend on knowing the buffer size must supply a bufsize_callback before activating themselves.

Parameters:
client pointer to JACK client structure.
bufsize_callback function to call when the buffer size changes.
arg argument for bufsize_callback.
Returns:
0 on success, otherwise a non-zero error code

void jack_set_error_function void(*)(const char *)  func  ) 
 

Set the jack_error_callback for error message display.

The JACK library provides two built-in callbacks for this purpose: default_jack_error_callback() and silent_jack_error_callback().

int jack_set_freewheel jack_client_t client,
int  onoff
 

Start/Stop JACK's "freewheel" mode.

When in "freewheel" mode, JACK no longer waits for any external event to begin the start of the next process cycle.

As a result, freewheel mode causes "faster than realtime" execution of a JACK graph. If possessed, real-time scheduling is dropped when entering freewheel mode, and if appropriate it is reacquired when stopping.

IMPORTANT: on systems using capabilities to provide real-time scheduling (i.e. Linux kernel 2.4), if onoff is zero, this function must be called from the thread that originally called jack_activate(). This restriction does not apply to other systems (e.g. Linux kernel 2.6 or OS X).

Parameters:
client pointer to JACK client structure
onoff if non-zero, freewheel mode starts. Otherwise freewheel mode ends.
Returns:
0 on success, otherwise a non-zero error code.

int jack_set_freewheel_callback jack_client_t client,
JackFreewheelCallback  freewheel_callback,
void *  arg
 

Tell the Jack server to call freewheel_callback whenever we enter or leave "freewheel" mode, passing arg as the second argument. The first argument to the callback will be non-zero if JACK is entering freewheel mode, and zero otherwise.

Returns:
0 on success, otherwise a non-zero error code.

int jack_set_graph_order_callback jack_client_t ,
JackGraphOrderCallback  graph_callback,
void * 
 

Tell the JACK server to call graph_callback whenever the processing graph is reordered, passing arg as a parameter.

Returns:
0 on success, otherwise a non-zero error code

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 parameter.

Returns:
0 on success, otherwise a non-zero error code

int jack_set_process_callback jack_client_t client,
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.

The code in the supplied function must be suitable for real-time execution. That means that it cannot call functions that might block for a long time.  This includes malloc, free, printf, pthread_mutex_lock, sleep, wait, poll, select, pthread_join, pthread_cond_wait, etc, etc.  See http://jackit.sourceforge.net/docs/design/design.html#SECTION00411000000000000000 for more information.

Returns:
0 on success, otherwise a non-zero error code, causing JACK to remove that client from the process() graph.

int jack_set_sample_rate_callback jack_client_t client,
JackSampleRateCallback  srate_callback,
void *  arg
 

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

Returns:
0 on success, otherwise a non-zero error code

int jack_set_thread_init_callback jack_client_t client,
JackThreadInitCallback  thread_init_callback,
void *  arg
 

Tell JACK to call thread_init_callback once just after the creation of the thread in which all other callbacks will be handled.

The code in the supplied function does not need to be suitable for real-time execution.

Returns:
0 on success, otherwise a non-zero error code, causing JACK to remove that client from the process() graph.

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 a parameter.

Returns:
0 on success, otherwise a non-zero error code


Variable Documentation

void(* jack_error_callback)(const char *msg)
 

Display JACK error message.

Set via jack_set_error_function(), otherwise a JACK-provided default will print msg (plus a newline) to stderr.

Parameters:
msg error message text (no newline at end).


Generated on Tue Aug 1 11:35:04 2006 for JACK-AUDIO-CONNECTION-KIT by  doxygen 1.4.6