Main interface of the JACK API. More...

#include <jack/systemdeps.h>
#include <jack/types.h>
#include <jack/transport.h>
#include <jack/weakmacros.h>

Detailed Description

Main interface of the JACK API.

The functions in this file cover the (biggest) core parts of the whole JACK API.

This file is logical subdivided into the following functional groups:

More documentation about the data types involved, can be found in types.h.

MIDI support: Please note that MIDI support of the JACK API is covered by a separate file, refer to Reading and writing MIDI data for more about MIDI.

Definition in file jack.h.

Functions
void	jack_get_version (int major_ptr, int minor_ptr, int micro_ptr, int proto_ptr) JACK_OPTIONAL_WEAK_EXPORT
const char *	jack_get_version_string () JACK_OPTIONAL_WEAK_EXPORT
jack_client_t *	jack_client_open (const char client_name, jack_options_t options, jack_status_t status,...) JACK_OPTIONAL_WEAK_EXPORT
jack_client_t *	jack_client_new (const char *client_name) JACK_OPTIONAL_WEAK_DEPRECATED_EXPORT
int	jack_client_close (jack_client_t *client) JACK_OPTIONAL_WEAK_EXPORT
int	jack_client_name_size (void) JACK_OPTIONAL_WEAK_EXPORT
char *	jack_get_client_name (jack_client_t *client) JACK_OPTIONAL_WEAK_EXPORT
int	jack_internal_client_new (const char client_name, const char load_name, const char *load_init) JACK_OPTIONAL_WEAK_DEPRECATED_EXPORT
void	jack_internal_client_close (const char *client_name) JACK_OPTIONAL_WEAK_DEPRECATED_EXPORT
int	jack_activate (jack_client_t *client) JACK_OPTIONAL_WEAK_EXPORT
int	jack_deactivate (jack_client_t *client) JACK_OPTIONAL_WEAK_EXPORT
int	jack_get_client_pid (const char *name) JACK_OPTIONAL_WEAK_EXPORT
jack_native_thread_t	jack_client_thread_id (jack_client_t *client) JACK_OPTIONAL_WEAK_EXPORT
int	jack_is_realtime (jack_client_t *client) JACK_OPTIONAL_WEAK_EXPORT
int	jack_gui_switch_to_client (jack_client_t client, const char client_name) JACK_OPTIONAL_WEAK_EXPORT
int	jack_app_register (jack_register_flags_t flags) JACK_OPTIONAL_WEAK_EXPORT
bool	jack_server_installed () JACK_OPTIONAL_WEAK_EXPORT
bool	jack_server_running () JACK_OPTIONAL_WEAK_EXPORT
jack_nframes_t	jack_thread_wait (jack_client_t *client, int status) JACK_OPTIONAL_WEAK_EXPORT
jack_nframes_t	jack_cycle_wait (jack_client_t *client) JACK_OPTIONAL_WEAK_EXPORT
void	jack_cycle_signal (jack_client_t *client, int status) JACK_OPTIONAL_WEAK_EXPORT
int	jack_set_process_thread (jack_client_t client, JackThreadCallback thread_callback, void arg) JACK_OPTIONAL_WEAK_EXPORT
int	jack_set_thread_init_callback (jack_client_t client, JackThreadInitCallback thread_init_callback, void arg) JACK_OPTIONAL_WEAK_EXPORT
void	jack_on_shutdown (jack_client_t client, JackShutdownCallback shutdown_callback, void arg) JACK_OPTIONAL_WEAK_EXPORT
void	jack_on_info_shutdown (jack_client_t client, JackInfoShutdownCallback shutdown_callback, void arg) JACK_WEAK_EXPORT
int	jack_set_process_callback (jack_client_t client, JackProcessCallback process_callback, void arg) JACK_OPTIONAL_WEAK_EXPORT
int	jack_set_freewheel_callback (jack_client_t client, JackFreewheelCallback freewheel_callback, void arg) JACK_OPTIONAL_WEAK_EXPORT
int	jack_set_buffer_size_callback (jack_client_t client, JackBufferSizeCallback bufsize_callback, void arg) JACK_OPTIONAL_WEAK_EXPORT
int	jack_set_sample_rate_callback (jack_client_t client, JackSampleRateCallback srate_callback, void arg) JACK_OPTIONAL_WEAK_EXPORT
int	jack_set_client_registration_callback (jack_client_t client, JackClientRegistrationCallback registration_callback, void arg) JACK_OPTIONAL_WEAK_EXPORT
int	jack_set_port_registration_callback (jack_client_t client, JackPortRegistrationCallback registration_callback, void arg) JACK_OPTIONAL_WEAK_EXPORT
int	jack_set_port_connect_callback (jack_client_t client, JackPortConnectCallback connect_callback, void arg) JACK_OPTIONAL_WEAK_EXPORT
int	jack_set_port_rename_callback (jack_client_t client, JackPortRenameCallback rename_callback, void arg) JACK_OPTIONAL_WEAK_EXPORT
int	jack_set_graph_order_callback (jack_client_t client, JackGraphOrderCallback graph_callback, void ) JACK_OPTIONAL_WEAK_EXPORT
int	jack_set_xrun_callback (jack_client_t client, JackXRunCallback xrun_callback, void arg) JACK_OPTIONAL_WEAK_EXPORT
int	jack_set_latency_callback (jack_client_t client, JackLatencyCallback latency_callback, void ) JACK_WEAK_EXPORT
int	jack_set_freewheel (jack_client_t *client, int onoff) JACK_OPTIONAL_WEAK_EXPORT
int	jack_set_buffer_size (jack_client_t *client, jack_nframes_t nframes) JACK_OPTIONAL_WEAK_EXPORT
jack_nframes_t	jack_get_sample_rate (jack_client_t *) JACK_OPTIONAL_WEAK_EXPORT
jack_nframes_t	jack_get_buffer_size (jack_client_t *) JACK_OPTIONAL_WEAK_EXPORT
int	jack_engine_takeover_timebase (jack_client_t *) JACK_OPTIONAL_WEAK_DEPRECATED_EXPORT
float	jack_cpu_load (jack_client_t *client) JACK_OPTIONAL_WEAK_EXPORT
float	jack_get_max_cpu_load (jack_client_t *client) JACK_OPTIONAL_WEAK_EXPORT
float	jack_set_max_cpu_load (jack_client_t *client, float max_cpu_load) JACK_OPTIONAL_WEAK_EXPORT
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) JACK_OPTIONAL_WEAK_EXPORT
int	jack_port_unregister (jack_client_t client, jack_port_t port) JACK_OPTIONAL_WEAK_EXPORT
void *	jack_port_get_buffer (jack_port_t *port, jack_nframes_t) JACK_OPTIONAL_WEAK_EXPORT
const char *	jack_port_name (const jack_port_t *port) JACK_OPTIONAL_WEAK_EXPORT
const char *	jack_port_short_name (const jack_port_t *port) JACK_OPTIONAL_WEAK_EXPORT
int	jack_port_flags (const jack_port_t *port) JACK_OPTIONAL_WEAK_EXPORT
const char *	jack_port_type (const jack_port_t *port) JACK_OPTIONAL_WEAK_EXPORT
jack_port_type_id_t	jack_port_type_id (const jack_port_t *port) JACK_OPTIONAL_WEAK_EXPORT
int	jack_port_is_mine (const jack_client_t client, const jack_port_t port) JACK_OPTIONAL_WEAK_EXPORT
int	jack_port_connected (const jack_port_t *port) JACK_OPTIONAL_WEAK_EXPORT
int	jack_port_connected_to (const jack_port_t port, const char port_name) JACK_OPTIONAL_WEAK_EXPORT
const char **	jack_port_get_connections (const jack_port_t *port) JACK_OPTIONAL_WEAK_EXPORT
const char **	jack_port_get_all_connections (const jack_client_t client, const jack_port_t port) JACK_OPTIONAL_WEAK_EXPORT
int	jack_port_tie (jack_port_t src, jack_port_t dst) JACK_OPTIONAL_WEAK_DEPRECATED_EXPORT
int	jack_port_untie (jack_port_t *port) JACK_OPTIONAL_WEAK_DEPRECATED_EXPORT
int	jack_port_set_name (jack_port_t port, const char port_name) JACK_OPTIONAL_WEAK_EXPORT
int	jack_port_set_alias (jack_port_t port, const char alias) JACK_OPTIONAL_WEAK_EXPORT
int	jack_port_unset_alias (jack_port_t port, const char alias) JACK_OPTIONAL_WEAK_EXPORT
int	jack_port_get_aliases (const jack_port_t port, char const aliases[2]) JACK_OPTIONAL_WEAK_EXPORT
int	jack_port_request_monitor (jack_port_t *port, int onoff) JACK_OPTIONAL_WEAK_EXPORT
int	jack_port_request_monitor_by_name (jack_client_t client, const char port_name, int onoff) JACK_OPTIONAL_WEAK_EXPORT
int	jack_port_ensure_monitor (jack_port_t *port, int onoff) JACK_OPTIONAL_WEAK_EXPORT
int	jack_port_monitoring_input (jack_port_t *port) JACK_OPTIONAL_WEAK_EXPORT
int	jack_connect (jack_client_t client, const char source_port, const char *destination_port) JACK_OPTIONAL_WEAK_EXPORT
int	jack_disconnect (jack_client_t client, const char source_port, const char *destination_port) JACK_OPTIONAL_WEAK_EXPORT
int	jack_port_disconnect (jack_client_t client, jack_port_t port) JACK_OPTIONAL_WEAK_EXPORT
int	jack_port_name_size (void) JACK_OPTIONAL_WEAK_EXPORT
int	jack_port_type_size (void) JACK_OPTIONAL_WEAK_EXPORT
size_t	jack_port_type_get_buffer_size (jack_client_t client, const char port_type) JACK_WEAK_EXPORT
void	jack_port_set_latency (jack_port_t *port, 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 *client) 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 client, 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
const char **	jack_get_ports (jack_client_t client, const char port_name_pattern, const char *type_name_pattern, unsigned long flags) JACK_OPTIONAL_WEAK_EXPORT
jack_port_t *	jack_port_by_name (jack_client_t client, const char port_name) JACK_OPTIONAL_WEAK_EXPORT
jack_port_t *	jack_port_by_id (jack_client_t *client, jack_port_id_t port_id) JACK_OPTIONAL_WEAK_EXPORT
jack_nframes_t	jack_frames_since_cycle_start (const jack_client_t *) JACK_OPTIONAL_WEAK_EXPORT
jack_nframes_t	jack_frame_time (const jack_client_t *) JACK_OPTIONAL_WEAK_EXPORT
jack_nframes_t	jack_last_frame_time (const jack_client_t *client) JACK_OPTIONAL_WEAK_EXPORT
int	jack_get_cycle_times (const jack_client_t client, jack_nframes_t current_frames, jack_time_t current_usecs, jack_time_t next_usecs, float *period_usecs) JACK_OPTIONAL_WEAK_EXPORT
jack_time_t	jack_frames_to_time (const jack_client_t *client, jack_nframes_t) JACK_OPTIONAL_WEAK_EXPORT
jack_nframes_t	jack_time_to_frames (const jack_client_t *client, jack_time_t) JACK_OPTIONAL_WEAK_EXPORT
jack_time_t	jack_get_time () JACK_OPTIONAL_WEAK_EXPORT
void	jack_set_error_function (void(func)(const char )) JACK_OPTIONAL_WEAK_EXPORT
void	jack_set_info_function (void(func)(const char )) JACK_OPTIONAL_WEAK_EXPORT
void	jack_free (void *ptr) JACK_OPTIONAL_WEAK_EXPORT

Variables
void(*	jack_error_callback )(const char *msg) JACK_OPTIONAL_WEAK_EXPORT
void(*	jack_info_callback )(const char *msg) JACK_OPTIONAL_WEAK_EXPORT

Function Documentation

void jack_get_version	(	int *	major_ptr,
		int *	minor_ptr,
		int *	micro_ptr,
		int *	proto_ptr
	)

Call this function to get version of the JACK, in form of several numbers

Parameters

major_ptr	pointer to variable receiving major version of JACK.
minor_ptr	pointer to variable receiving minor version of JACK.
major_ptr	pointer to variable receiving micro version of JACK.
major_ptr	pointer to variable receiving protocol version of JACK.

const char* jack_get_version_string ( )

Call this function to get version of the JACK, in form of a string

Returns: Human readable string describing JACK version being used.

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

int jack_gui_switch_to_client	(	jack_client_t *	client,
		const char *	client_name
	)

Bring the given JACK client's app GUI into foreground. If you pass "jack" as argument to this function, the JACK (server) app will come into foreground.

Parameters

client	- own client handle
client_name	- name of foreign client to be brought in foreground

Since: JACKiOS 1.9.10.2

Note: This function is currently only implemented on iOS, on all other architectures a call of this function will fail.

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

int jack_app_register ( jack_register_flags_t flags )

Ensures that the calling iOS app is registered to the JACK system. App developers should always call this function when their app is launched. It will check whether the calling app is already registered to the JACK system. If the app is already registered, the function will return immediately and nothing happens. If the app is not yet registered and JACK server is running at this point, the app informations are transmitted in the background to the JACK server and stored persistenly on disc. If the app is not yet registered and the JACK server is not running at this point, it will try to launch the JACK server app, switch for a short moment to the JACK server app, the app informations are stored persistently on disc, then it will automatically switch back to the original app and exit the JACK server automatically. You can control the exact behavior in the latter case with the flags argument.

You don't have to check by yourself, whether you have called this function before. This function will check by itself whether or not it is necessary to register or re-register your app to the JACK system. You might simply call this function in your app delegate's didFinishLaunchingWithOptions method.

Note: Even though it is essentially not mandatory for your app to call this function at all, we definitely recommend you to do so. If your app is not registered to the local JACK installation, users will not be able to launch your app directly from the JACK control app. So for a optimum user experience your app should be registered to the local JACK system installation as soon as your app was launched the first time, which is ensured by this call.

Parameters

flags - defines the exact behavior for app registration

Returns: 0 always (might change in future)

Since: JACKiOS 1.9.10.2

Note: This function works only on iOS.

bool jack_server_installed ( )

You can call this function to check whether the main JACK app, which includes the JACK server, is currently installed on the iOS device. Without JACK server being installed, the JACK system cannot be used. So you may use this function in your app to decide whether or not to show JACK related functions in your app, or for explicitly showing the user that the main JACK app is not installed and recommending the user to install it.

Returns: true if JACK is installed on the iOS device

Since: JACKiOS 1.9.10.2

Note: This function works only on iOS.

bool jack_server_running ( )

You can call this function to check whether the JACK server is currently running. The JACK system cannot be used while JACK server is not running.

Since: JACKiOS 1.9.10.2

int jack_set_latency_callback	(	jack_client_t *	client,
		JackLatencyCallback	latency_callback,
		void *
	)

Tell the Jack server to call latency_callback whenever it is necessary to recompute the latencies for some or all Jack ports.

latency_callback will be called twice each time it is needed, once being passed JackCaptureLatency and once JackPlaybackLatency. See Managing and determining latency for the definition of each type of latency and related functions.

IMPORTANT: Most JACK clients do NOT need to register a latency callback.

Clients that meet any of the following conditions do NOT need to register a latency callback:

have only input ports
have only output ports
their output is totally unrelated to their input
their output is not delayed relative to their input (i.e. data that arrives in a given process() callback is processed and output again in the same callback)

Clients NOT registering a latency callback MUST also satisfy this condition:

have no multiple distinct internal signal pathways

This means that if your client has more than 1 input and output port, and considers them always "correlated" (e.g. as a stereo pair), then there is only 1 (e.g. stereo) signal pathway through the client. This would be true, for example, of a stereo FX rack client that has a left/right input pair and a left/right output pair.

However, this is somewhat a matter of perspective. The same FX rack client could be connected so that its two input ports were connected to entirely separate sources. Under these conditions, the fact that the client does not register a latency callback MAY result in port latency values being incorrect.

Clients that do not meet any of those conditions SHOULD register a latency callback.

See the documentation for jack_port_set_latency_range() on how the callback should operate. Remember that the mode argument given to the latency callback will need to be passed into jack_port_set_latency_range()

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

void jack_free ( void * ptr )

The free function to be used on memory returned by jack_port_get_connections, jack_port_get_all_connections, jack_get_ports and jack_get_internal_client_name functions. This is MANDATORY on Windows when otherwise all nasty runtime version related crashes can occur. Developers are strongly encouraged to use this function instead of the standard "free" function in new code.

Detailed Description

Functions

Variables

Function Documentation