Crudebyte Logo
jack.h File Reference

Main interface of the JACK API. More...

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

Go to the source code of this file.

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.


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_tjack_client_open (const char *client_name, jack_options_t options, jack_status_t *status,...) JACK_OPTIONAL_WEAK_EXPORT
jack_client_tjack_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_tjack_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_tjack_port_by_name (jack_client_t *client, const char *port_name) JACK_OPTIONAL_WEAK_EXPORT
jack_port_tjack_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


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

major_ptrpointer to variable receiving major version of JACK.
minor_ptrpointer to variable receiving minor version of JACK.
major_ptrpointer to variable receiving micro version of JACK.
major_ptrpointer 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

Human readable string describing JACK version being used.
int jack_is_realtime ( jack_client_t client)
clientpointer to JACK client structure.

Check if the JACK subsystem is running with -R (–realtime).

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.

client- own client handle
client_name- name of foreign client to be brought in foreground
This function is currently only implemented on iOS, on all other architectures a call of this function will fail.
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.

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.
flags- defines the exact behavior for app registration
0 always (might change in future)
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.

true if JACK is installed on the iOS device
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.

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

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.

Copyright © MMXIII Crudebyte. All rights reserved.