Jack Utils Context manipulation API

Typedefs
typedef int(*	ju_save_cb) (ju_ctx_t *ctx, void *ud)
	Save callback, that called each time when user sends save command from session manager, or, in case of no session manager, on SIGTERM and at exiting Jack Audio Processing. More...

Functions
JU_API ju_ctx_t *()	ju_ctx_init (ju_cstr_t n, ju_cstr_t pn, int has_gui)
	Allocates and Initializes jackutils context structure. More...
JU_API void()	ju_ctx_uninit (ju_ctx_t *x)
	Destroy context and release resources. More...
JU_API ju_cstr_t()	ju_get_name (ju_ctx_t *x)
	Returns real JACK client name. More...
JU_API ju_cstr_t()	ju_jack_info (void)
	Returns information about JACK library. More...
JU_API int()	ju_start (ju_ctx_t *x, ju_process_func_t c)
	Starts JACK Audio Processing. More...
JU_API void()	ju_stop (ju_ctx_t *x)
	Stops client processing. More...
JU_PROC size_t()	ju_length (ju_ctx_t *x)
	This function may be called only after starting Jack Audio Processing! More...
JU_API jack_nframes_t()	ju_samplerate (ju_ctx_t *x)
	Returns global JACK samplerate. More...
JU_API int()	ju_is_online (ju_ctx_t *x, int t)
	Checks is server online, and are we started Jack Audio Processing ju_start(). More...
JU_API int()	ju_need_gui (ju_ctx_t *x)
	Returns is GUI enabled for us. More...
JU_API void()	ju_set_gui (ju_ctx_t *x, int b)
	Set ju_need_gui returned value and send it to session manager. More...
JU_API ju_cstr_t()	ju_osc_info (ju_ctx_t *ctx)
	Returns information about session manager, if available. More...
JU_API ju_cstr_t()	ju_osc_path (ju_ctx_t *ctx)
	Returns OSC path to store your session data. More...
JU_API void()	ju_pool_events (ju_ctx_t *ctx)
	Call this in main loop to recieve and process messages from session manager. More...
JU_API void()	ju_onsave (ju_ctx_t *ctx, ju_save_cb cb, void *ud)
	Sets custom on_save callback. More...

Detailed Description

Typedef Documentation

ju_save_cb

typedef int(* ju_save_cb) (ju_ctx_t *ctx, void *ud)

Save callback, that called each time when user sends save command from session manager, or, in case of no session manager, on SIGTERM and at exiting Jack Audio Processing.

Parameters

ctx	JackUtils Context
ud	userdata

Returns

0 in case of sucessful saving data, any other number otherwise

Since

JackUtils 4.0

Function Documentation

ju_ctx_init()

JU_API ju_ctx_t *() ju_ctx_init	(	ju_cstr_t	n,
		ju_cstr_t	pn,
		int	has_gui
	)

Allocates and Initializes jackutils context structure.

Connection with the session manager will be establilshed in this function too!

Parameters

n	client name (may be changed by server)
pn	filename of current executable (argv[0] value)
has_gui	has GUI?

Returns

new context on sucess. NULL on failture.

References ju_ctx_s::client, ju_ctx_s::close, CLOSE_PORT_NAME, ju_ctx_s::length, ju_ctx_s::mdata, ju_ctx_s::mutex, ju_ctx_s::osc, ju_ctx_s::samplerate, ju_ctx_s::session_path, and ju_ctx_s::works.

ju_ctx_uninit()

JU_API void() ju_ctx_uninit

(

ju_ctx_t *

x

)

Destroy context and release resources.

Parameters

x	JackuUtils context

ju_get_name()

JU_API ju_cstr_t() ju_get_name

(

ju_ctx_t *

x

)

Returns real JACK client name.

Parameters

x	JackuUtils context

ju_is_online()

JU_API int() ju_is_online	(	ju_ctx_t *	x,
		int	t
	)

Checks is server online, and are we started Jack Audio Processing ju_start().

UPDATE: since Session manager support was added. If connection with session manager is exists, this function will returns 0 ONLY in case of session manager stops us or JACK server is crashed.

Else if there is no connection with session manager, this function will return 0 only if jack is crashed OR __close port is connected. __close port is NOT created if session manager is available!

Parameters

x	JackUtils context
t	timeout in MILLISeconds to wait (-1 forever, 0 - no sleep)

Returns

1 if Jack Audio Processing is still works

ju_jack_info()

JU_API ju_cstr_t() ju_jack_info

(

void

)

Returns information about JACK library.

Returns

constant string with general information

ju_length()

JU_PROC size_t() ju_length

(

ju_ctx_t *

x

)

This function may be called only after starting Jack Audio Processing!

Parameters

x

context

Returns

length of sample arrays of ports

ju_need_gui()

JU_API int() ju_need_gui

(

ju_ctx_t *

x

)

Returns is GUI enabled for us.

If this functions returns true, then you SHOULD show your window. Else you SHOULD hide it, and draw nothing.

If there is no session manager, returns true until ju_set_gui is not called.

Parameters

x

context

Returns

1 if enabled.

References ju_ctx_s::gui_showed, and ju_ctx_s::mdata.

ju_onsave()

JU_API void() ju_onsave	(	ju_ctx_t *	ctx,
		ju_save_cb	cb,
		void *	ud
	)

Sets custom on_save callback.

Parameters

ctx	JackUtils context
cb	callback
ud	userdata passed to callback

Since

JackUtils 4.0

ju_osc_info()

JU_API ju_cstr_t() ju_osc_info

(

ju_ctx_t *

ctx

)

Returns information about session manager, if available.

Parameters

ctx

context

Returns

session manager info string or NULL if session manager is not available

ju_osc_path()

JU_API ju_cstr_t() ju_osc_path

(

ju_ctx_t *

ctx

)

Returns OSC path to store your session data.

If there is no session manager, returns "~/.local/share/jackutils/"

From NSM Documentation : returns a path name in the form client_name.ID, assigned to the client for storing its project data. The client MUST choose one of the four strategies below to save, so that every file in the session can be traced back to a client and, vice versa, a client name.ID can be used to look up all its files. (For example to clean up the session dir) :

1. The client has no state and does not save at all 1.1 and it MUST NOT misuse e.g. ~/.config to save session specific information e.g. synth-instrument settings
2. The client may use the path client_name.ID directly, resulting in a file client_name.ID in the session directory
3. The client may append its native file extension (e.g. .json) to the path client_name.ID
4. The client may use the path as directory, creating arbitrary files below, for example recorded .wav. 4.1 and it MUST NOT use the client ID below this point. This way the data stays transferable by hand to another client instance (in another session).

Parameters

ctx

context

Returns

path to load and save session data

ju_pool_events()

JU_API void() ju_pool_events

(

ju_ctx_t *

ctx

)

Call this in main loop to recieve and process messages from session manager.

Parameters

ctx

context

References ju_ctx_s::osc.

ju_samplerate()

JU_API jack_nframes_t() ju_samplerate

(

ju_ctx_t *

x

)

Returns global JACK samplerate.

It does not changes during JACK server lifetime.

Parameters

x

context

Returns

sample rate

ju_set_gui()

JU_API void() ju_set_gui	(	ju_ctx_t *	x,
		int	b
	)

Set ju_need_gui returned value and send it to session manager.

If there is no session manager, setting this to 0 makes ju_is_online return 0 too! (=> closes your program)

Parameters

x	context
b	show gui

References ju_stop().

ju_start()

JU_API int() ju_start	(	ju_ctx_t *	x,
		ju_process_func_t	c
	)

Starts JACK Audio Processing.

Do this after context and port creation. ju_process_func_t will be called in another thread each time when audio data needs to be processed

This process callback should not call functions that might block for long time, like malloc(), free(), pthread_join(), sleep(), wait() and etc. => process callback should work as fast as possible!

Parameters

x	JackUtils context
c	process callack

Returns

0 on sucess

See also

ju_process_func_t ju_is_online() returns 1 after this :)

ju_stop()

JU_API void() ju_stop

(

ju_ctx_t *

x

)

Stops client processing.

Parameters

x	JackUtils Context

ju_is_online() returns 0 after this