JACK Audio Connection Kit (JACK) Client for Python

This Python module provides bindings for the JACK library.

Documentation:
http://jackclient-python.rtfd.org/
Code:
http://github.com/spatialaudio/jackclient-python/

Requirements

Python:
Of course, you’ll need Python. Any version where CFFI (see below) is supported should work. If you don’t have Python installed yet, you should get one of the distributions which already include CFFI (and many other useful things), e.g. Anaconda.
CFFI:

The C Foreign Function Interface for Python is used to access the C-API of the JACK library from within Python. It supports CPython 2.6, 2.7, 3.x; and is distributed with PyPy 2.0 beta2 or later. You should install it with your package manager (if it’s not installed already), or you can get it with pip:

pip install cffi --user
JACK library:
The JACK library must be installed on your system (and CFFI must be able to find it). Again, you should use your package manager to install it. Make sure you install both the JACK daemon (called jackd) and the development package (libjack-dev or similar). If you prefer, you can of course also download the sources and compile everything locally.
setuptools:

This is needed for the installation of the Python module. Most systems will have this installed already, but if not, you can install it with your package manager or you can get it with pip:

pip install setuptools --user

Installation

Once you have installed the above-mentioned dependencies, you can use pip to download and install the latest release with a single command:

pip install JACK-Client --user

If you want to install it system-wide for all users (assuming you have the necessary rights), you can just drop the --user option.

To un-install, use:

pip uninstall JACK-Client

If you prefer, you can also download the package from PyPI, extract it, change to the main directory and install it using:

python setup.py install --user

If you want to get the newest development version from Github:

git clone https://github.com/spatialaudio/jackclient-python.git
cd jackclient-python
python setup.py develop --user

This way, your installation always stays up-to-date, even if you pull new changes from the Github repository.

If you prefer, you can also replace the last command with:

pip install --user -e .

... where -e stands for --editable.

If you want to avoid installation altogether, you can simply copy jack.py to your working directory (or to any directory in your Python path).

Usage

First, import the module:

import jack

Then, you most likely want to create a new JACK client:

client = jack.Client("MyGreatClient")

You probably want to create some input and output ports, too:

client.inports.register("input_1")
client.outports.register("output_1")

These functions return the newly created port, so you can save it for later:

in2 = client.inports.register("input_2")
out2 = client.outports.register("output_2")

To see what you can do with the returned objects, have a look at the documentation of the class jack.OwnPort.

You can also check what other JACK ports are available:

portlist = client.get_ports()

If you want, you can also set all kinds of callback functions, for details see the API documentation for the class jack.Client.

Once you are ready to run, you should activate your client:

client.activate()

Once the client is activated, you can make connections (this isn’t possible before activating the client):

client.connect("system:capture_1", "MyGreatClient:input_1")
client.connect("MyGreatClient:output_1", "system:playback_1")

You can also use the port objects from before instead of port names:

client.connect(out2, "system:playback_2")
in2.connect("system:capture_2")

You can also disconnect ports, there are again several possibilities:

client.disconnect("system:capture_1", "MyGreatClient:input_1")
client.disconnect(out2, "system:playback_2")
# disconnect all connections with in2:
in2.disconnect()

If you don’t need your ports anymore, you can un-register them:

in2.unregister()
# unregister all output ports:
client.outports.clear()

Finally, you can de-activate your JACK client and close it:

client.deactivate()
client.close()

API Documentation

JACK Client for Python.

http://jackclient-python.rtfd.org/

jack.CALL_AGAIN = 0

Possible return value for process callback.

jack.STOP_CALLING = 1

Possible return value for process callback.

jack.SUCCESS = 0

Possible return value for several callbacks.

jack.FAILURE = 1

Possible return value for several callbacks.

class jack.Client(name, use_exact_name=False, no_start_server=False, servername=None, session_id=None)[source]

Create a new JACK client.

Parameters:

name (str) – The desired client name of at most client_name_size() characters. The name scope is local to each server. Unless forbidden by the use_exact_name option, the server will modify this name to create a unique variant, if needed.
Other Parameters:
 
  • use_exact_name (bool) – Whether an error should be raised if name is not unique.
  • no_start_server (bool) – Do not automatically start the JACK server when it is not already running. This option is always selected if JACK_NO_START_SERVER is defined in the calling process environment.
  • servername (str) – 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.
  • session_id (str) – Pass a SessionID Token. This allows the sessionmanager to identify the client again.
class Ports(client, flag)[source]

A list of input/output ports.

This class is not meant to be instantiated directly. It is only used as Client.inports and Client.outports.

The ports can be accessed by indexing or by iteration.

New ports can be added with register(), existing ports can be removed by calling their OwnPort.unregister() method.

register(shortname, is_terminal=False)[source]

Create a new input/output port.

The new OwnPort object is automatically added to Client.inports/Client.outports.

Parameters:

  • shortname (str) – 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 port_name_size() is the maximum length of this full name. Exceeding that will cause the port registration to fail.

    The port name must be unique among all ports owned by this client. If the name is not unique, the registration will fail.

  • is_terminal (bool) – For an input port: If True, the data received by the port will not be passed on or made available at any other port. For an output port: If True, the data available at the port does not originate from any other port

    Audio synthesizers, I/O hardware interface clients, HDR systems are examples of clients that would set this flag for their ports.
Returns:

OwnPort – A new OwnPort instance.
clear()[source]

Unregister all ports in the list.

See also

OwnPort.unregister()

Client.name[source]

The name of the JACK client (read-only).

Client.samplerate[source]

The sample rate of the JACK system (read-only).

Client.blocksize[source]

The JACK block size (must be a power of two).

The current maximum size that will ever be passed to the process callback. It should only be queried before activate() has been called. This size may change, clients that depend on it must register a callback with set_blocksize_callback() so they will be notified if it does.

Changing the blocksize stops the JACK engine process cycle, then calls all registered callback functions (see set_blocksize_callback()) before restarting the process cycle. This will cause a gap in the audio flow, so it should only be done at appropriate stopping points.

Client.realtime[source]

Whether JACK is running with -R (--realtime).

Client.frames_since_cycle_start[source]

Time since start of audio block.

The estimated time in frames that has passed since the JACK server began the current process cycle.

Client.frame_time[source]

The estimated current time in frames.

This is intended for use in other threads (not the process callback). The return value can be compared with the value of last_frame_time to relate time in other threads to JACK time.

Client.last_frame_time[source]

The precise time at the start of the current process cycle.

This may only be used from the process callback (see set_process_callback()), and can be used to interpret timestamps generated by frame_time in other threads with respect to the current process cycle.

This is the only jack time function that returns exact time: when used during the process callback it always returns the same value (until the next process callback, where it will return that value + blocksize, etc). The return value is guaranteed to be monotonic and linear in this fashion unless an xrun occurs (see set_xrun_callback()). If an xrun occurs, clients must check this value again, as time may have advanced in a non-linear way (e.g. cycles may have been skipped).

Client.xrun_delayed_usecs[source]

Delay in microseconds due to the most recent XRUN occurrence.

This probably only makes sense when queried from a callback defined using set_xrun_callback().

Client.inports[source]

A list of input Ports.

New ports can be created and added to this list with the register() method. When OwnPort.unregister() is called on one of the items in this list, this port is removed from the list. The clear() method can be used to unregister all input ports at once.

See also

Ports, OwnPort

Client.outports[source]

A list of output Ports.

New ports can be created and added to this list with the register() method. When OwnPort.unregister() is called on one of the items in this list, this port is removed from the list. The clear() method can be used to unregister all output ports at once.

See also

Ports, OwnPort

Client.owns(port)[source]

Check if a given port belongs to self.

Parameters:port (str or Port) – Full port name or Port/OwnPort object.
Client.activate()[source]

Activate JACK client.

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

Client.deactivate()[source]

De-activate JACK client.

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

Client.cpu_load()[source]

Return 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 blocksize and samplerate.

Client.close(ignore_errors=True)[source]

Close the JACK client.

Client.connect(source, destination)[source]

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.

The port types must be identical.

Parameters:
  • source (str or Port) – One end of the connection. Must be an output port.
  • destination (str or Port) – The other end of the connection. Must be an input port.
Client.disconnect(source, destination)[source]

Remove a connection between two ports.

Parameters:source, destination (str or Port) – See connect().
Client.transport_start()[source]

Start JACK transport.

Client.transport_stop()[source]

Stop JACK transport.

Client.transport_locate(frame)[source]

Reposition the JACK transport to a new frame number.

Parameters:frame (int) – Frame number.
Client.set_freewheel(onoff)[source]

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 activate(). This restriction does not apply to other systems (e.g. Linux kernel 2.6 or OS X).

Parameters:onoff (bool) – If True, freewheel mode starts. Otherwise freewheel mode ends.

See also

set_freewheel_callback()

Client.set_shutdown_callback(callback, userdata=None)[source]

Register shutdown callback.

Register a function (and optional 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 activate().

Note

application should typically signal another thread to correctly finish cleanup, that is by calling close() (since close() cannot be called directly in the context of the thread that calls the shutdown callback).

Parameters:

  • callback (callable) – User-supplied function that is called whenever the JACK daemon is shutdown. It must have this signature:

    callback(status:int, reason:str, userdata) -> None

    The argument status can be decoded with decode_status().

    Note that after server shutdown, self is not deallocated by libjack, the application is responsible to properly use close() to release client ressources.

    Warning

    close() cannot be safely used inside the shutdown callback and has to be called outside of the callback context.

  • userdata (anything) – This will be passed as third argument when callback is called.
Client.set_process_callback(callback, userdata=None)[source]

Register process callback.

Tell the Jack server to call callback whenever there is work be done, passing userdata 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.

Note

This function cannot be called while the client is activated (after activate() has been called).

Parameters:

  • callback (callable) – User-supplied function that is called by the engine anytime there is work to be done. It must have this signature:

    callback(frames:int, userdata) -> int

    The argument frames specifies the number of frames that have to be processed in the current audio block. It will be the same number as blocksize and it will be a power of two. The callback must return zero on success (if callback shall be called again for the next audio block) and non-zero on error (if callback shall not be called again). You can use CALL_AGAIN and STOP_CALLING, respectively.

  • userdata (anything) – This will be passed as second argument whenever callback is called.
Client.set_freewheel_callback(callback, userdata=None)[source]

Register freewheel callback.

Tell the JACK server to call callback whenever we enter or leave “freewheel” mode, passing userdata as the second argument. The first argument to the callback will be True if JACK is entering freewheel mode, and False otherwise.

All “notification events” are received in a separated non RT thread, the code in the supplied function does not need to be suitable for real-time execution.

Note

this function cannot be called while the client is activated (after activate() has been called).

Parameters:

  • callback (callable) – User-supplied function that is called whenever jackd starts or stops freewheeling. It must have this signature:

    callback(starting:bool, userdata) -> None

  • userdata (anything) – This will be passed as second argument whenever callback is called.

See also

set_freewheel()

Client.set_blocksize_callback(callback, userdata=None)[source]

Register blocksize callback.

Tell JACK to call 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 callback before activating themselves.

All “notification events” are received in a separated non RT thread, the code in the supplied function does not need to be suitable for real-time execution.

Note

this function cannot be called while the client is activated (after activate() has been called).

Parameters:

  • callback (callable) – User-supplied function that is invoked whenever the JACK engine buffer size changes. It must have this signature:

    callback(blocksize:int, userdata) -> int

    The callback must return zero on success and non-zero on error. You can use SUCCESS and FAILURE, respectively.

    Although this function is called in the JACK process thread, the normal process cycle is suspended during its operation, causing a gap in the audio flow. So, the callback can allocate storage, touch memory not previously referenced, and perform other operations that are not realtime safe.

  • userdata (anything) – This will be passed as second argument whenever callback is called.
Client.set_samplerate_callback(callback, userdata=None)[source]

Register samplerate callback.

Tell the JACK server to call callback whenever the system sample rate changes.

All “notification events” are received in a separated non RT thread, the code in the supplied function does not need to be suitable for real-time execution.

Note

this function cannot be called while the client is activated (after activate() has been called).

Parameters:

  • callback (callable) – User-supplied function that is called when the engine sample rate changes. It must have this signature:

    callback(samplerate:int, userdata) -> int

    The argument samplerate is the new engine sample rate. The callback must return zero on success and non-zero on error. You can use SUCCESS and FAILURE, respectively.

  • userdata (anything) – This will be passed as second argument whenever callback is called.
Client.set_client_registration_callback(callback, userdata=None)[source]

Register client registration callback.

Tell the JACK server to call callback whenever a client is registered or unregistered, passing userdata as a parameter.

All “notification events” are received in a separated non RT thread, the code in the supplied function does not need to be suitable for real-time execution.

Note

this function cannot be called while the client is activated (after activate() has been called).

Parameters:

  • callback (callable) – User-supplied function that is called whenever a client is registered or unregistered. It must have this signature:

    callback(name:str, register:bool, userdata) -> None

    The first argument contains the client name, the second argument is True if the client is being registered and False if the client is being unregistered.

  • userdata (anything) – This will be passed as third argument whenever callback is called.
Client.set_port_registration_callback(callback, userdata=None)[source]

Register port registration callback.

Tell the JACK server to call callback whenever a port is registered or unregistered, passing userdata as a parameter.

All “notification events” are received in a separated non RT thread, the code in the supplied function does not need to be suitable for real-time execution.

Note

this function cannot be called while the client is activated (after activate() has been called).

Parameters:

  • callback (callable) – User-supplied function function that is called whenever a port is registered or unregistered. It must have this signature:

    callback(port:Port, register:bool, userdata) -> None

    The first argument is a Port object (or an OwnPort), the second argument is True if the port is being registered, False if the port is being unregistered.

  • userdata (anything) – This will be passed as third argument whenever callback is called.
Client.set_port_connect_callback(callback, userdata=None)[source]

Register port connect callback.

Tell the JACK server to call callback whenever a port is connected or disconnected, passing userdata as a parameter.

All “notification events” are received in a separated non RT thread, the code in the supplied function does not need to be suitable for real-time execution.

Note

this function cannot be called while the client is activated (after activate() has been called).

Parameters:

  • callback (callable) – User-supplied function that is called whenever a port is connected or disconnected. It must have this signature:

    callback(a:Port, b:Port, connect:bool, userdata) -> None

    The first and second arguments contain Port (or OwnPort) objects of the ports which are connected or disconnected. The third argument is True if the ports were connected and False if the ports were disconnected.

  • userdata (anything) – This will be passed as fourth argument whenever callback is called.
Client.set_port_rename_callback(callback, userdata=None)[source]

Register port rename callback.

Tell the JACK server to call callback whenever a port is renamed, passing userdata as a parameter.

All “notification events” are received in a separated non RT thread, the code in the supplied function does not need to be suitable for real-time execution.

Note

this function cannot be called while the client is activated (after activate() has been called).

Parameters:

  • callback (callable) – User-supplied function that is called whenever the port name has been changed. It must have this signature:

    callback(port:Port, old:str, new:str, userdata) -> int

    The first argument is the port that has been renamed (a Port or OwnPort object); the second and third argument is the old and new name, respectively. The callback must return zero on success and non-zero on error. You can use SUCCESS and FAILURE, respectively.

  • userdata (anything) – This will be passed as fourth argument whenever callback is called.
Client.set_graph_order_callback(callback, userdata=None)[source]

Register graph order callback.

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

All “notification events” are received in a separated non RT thread, the code in the supplied function does not need to be suitable for real-time execution.

Note

this function cannot be called while the client is activated (after activate() has been called).

Parameters:

  • callback (callable) – User-supplied function that is called whenever the processing graph is reordered. It must have this signature:

    callback(userdata) -> int

    The callback must return zero on success and non-zero on error. You can use SUCCESS and FAILURE, respectively.

  • userdata (anything) – This will be passed as argument whenever callback is called.
Client.set_xrun_callback(callback, userdata=None)[source]

Register xrun callback.

Tell the JACK server to call callback whenever there is an xrun, passing userdata as a parameter.

All “notification events” are received in a separated non RT thread, the code in the supplied function does not need to be suitable for real-time execution.

Note

this function cannot be called while the client is activated (after activate() has been called).

Parameters:

  • callback (callable) – User-supplied function that is called whenever an xrun has occured. It must have this signature:

    callback(userdata) -> int

    The callback must return zero on success and non-zero on error. You can use SUCCESS and FAILURE, respectively.

  • userdata (anything) – This will be passed as argument whenever callback is called.

See also

xrun_delayed_usecs

Client.get_uuid_for_client_name(name)[source]

Get the session ID for a client name.

The session manager needs this to reassociate a client name to the session ID.

Client.get_client_name_by_uuid(uuid)[source]

Get the client name for a session ID.

In order to snapshot the graph connections, the session manager needs to map session IDs to client names.

Client.get_port_by_name(name)[source]

Get port by name.

Given a full port name, this returns a Port or an OwnPort object.

Client.get_all_connections(port)[source]

Return a list of ports which the given port is connected to.

This differs from OwnPort.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 graph order callback.
  2. You need not be the owner of the port to get information about its connections.
Client.get_ports(name_pattern='', type_pattern='', is_input=False, is_output=False, is_physical=False, can_monitor=False, is_terminal=False)[source]

Return a list of selected ports.

Parameters:
  • name_pattern (str) – A regular expression used to select ports by name. If empty, no selection based on name will be carried out.
  • type_pattern (str) – A regular expression used to select ports by type. If empty, no selection based on type will be carried out.
  • is_input, is_output, is_physical, can_monitor, is_terminal (bool) – Select ports by their flags. If none of them are True, no selection based on flags will be carried out.
Returns:

list of Port/OwnPort – All ports that satisfy the given conditions.
class jack.Port(port_ptr)[source]

A JACK port.

This class cannot be instantiated directly. Instead, instances of this class are returned from Client.get_port_by_name(), Client.get_ports(), Client.get_all_connections() and OwnPort.connections. In addition, instances of this class are available in the callbacks which are set with Client.set_port_registration_callback(), Client.set_port_connect_callback() or Client.set_port_rename_callback().

Note, however, that if the used Client owns the respective port, instances of OwnPort (instead of Port) will be created.

name[source]

Full name of the JACK port (read-only).

shortname[source]

Short name of the JACK port, not including “client_name:”.

Must be unique among all ports owned by a client.

May be modified at any time. If the resulting full name (including the “client_name:” prefix) is longer than port_name_size(), it will be truncated.

uuid[source]

The UUID of the JACK port.

is_input[source]

Can the port receive data?

is_output[source]

Can data be read from this port?

is_physical[source]

Does it correspond to some kind of physical I/O connector?

can_monitor[source]

Does a call to request_monitor() make sense?

is_terminal[source]

Is the data consumed/generated?

type[source]

Port type.

type_id[source]

Port type ID.

request_monitor(onoff)[source]

Set input monitoring.

If can_monitor is True, turn input monitoring on or off. Otherwise, do nothing.

Parameters:onoff (bool) – If True, switch monitoring on; if False, switch it off.
class jack.OwnPort(port_ptr, client)[source]

A JACK port owned by a Client object.

This class is derived from Port. Therfore, OwnPort objects can do everything that Port objects can, plus some more things.

This class cannot be instantiated directly. Instead, instances of this class are returned from Client.get_port_by_name(), Client.get_ports(), Client.get_all_connections() and connections. In addition, instances of this class are available in the callbacks which are set with Client.set_port_registration_callback(), Client.set_port_connect_callback() or Client.set_port_rename_callback().

Note, however, that if the used Client doesn’t own the respective port, instances of Port (instead of OwnPort) will be created.

New JACK ports can be created with the register() method of Client.inports and Client.outports.

number_of_connections[source]

Number of connections to or from port.

connections[source]

List of ports which the port is connected to.

is_connected_to(port)[source]

Am I directly connected to port?

Parameters:port (str or Port) – Full port name or Port/OwnPort object.
connect(port)[source]

Connect to given port:

Parameters:port (str or Port) – Full port name or Port/OwnPort object.

See also

Client.connect()

disconnect()[source]

Disconnect all connections of this port.

unregister()[source]

Unregister port.

Remove the port from the client, disconnecting any existing connections. This also removes the port from Client.inports/Client.outports.

get_buffer()[source]

Get buffer for audio data.

This returns a buffer holding 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.

Caching output ports is DEPRECATED in Jack 2.0, due to some new optimization (like “pipelining”). Port buffers have to be retrieved in each callback for proper functioning.

get_array()[source]

Get audio buffer as NumPy array.

See also

get_buffer()

jack.decode_status(status)[source]

Return string corresponding to JackStatus error code.

exception jack.JackError[source]

Exception for all kinds of JACK-related errors.

jack.version()[source]

Get tuple of major/minor/micro/protocol version.

jack.version_string()[source]

Get human-readable JACK version.

jack.client_name_size()[source]

Return the maximum number of characters in a JACK client name.

This includes the final NULL character. This value is a constant.

jack.port_name_size()[source]

Maximum length of port names.

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.set_error_function(callback=None)[source]

Set the callback for error message display.

Set it to None to restore the default error callback function (which prints the error message plus a newline to stderr).

jack.set_info_function(callback=None)[source]

Set the callback for info message display.

Set it to None to restore default info callback function (which prints the info message plus a newline to stderr).

jack.client_pid(name)[source]

Return PID of a JACK client.

Parameters:name (str) – Name of the JACK client whose PID shall be returned.
Returns:int – PID of name. If not available, 0 will be returned.

Index