Crate jack

Expand description

Rust bindings for JACK, a real-time audio and midi library. These bindings are compatible with all implementations of JACK (Pipewire JACK, JACK1, and JACK2).

Linking, dynamic loading, and packaging

libjack is shared among all clients on the system, so there must only be a single system-wide version of it. Applications typically should not ship their own copy of libjack. This is an issue for distributing JACK compatible applications on Windows and macOS. On Linux and BSDs, this is not an issue for system packages because the application and JACK server are both distributed by the system package manager.

To handle this, use the dlopen Cargo feature, which is enabled by default. This feature dynamically loads libjack at runtime rather than linking libjack at build time. If the user does not have JACK installed at runtime, Client::new will return Error::LoadLibraryError. In this case, have your application show an error message directing the user to install JACK from https://jackaudio.org/downloads/ and, if available, fall back to another audio API.

With the dlopen feature, neither libjack nor the JACK pkgconfig file need to be present at build time. This is convenient for automated Windows and macOS builds as well as cross compiling.

If your application cannot be used without JACK, Linux and BSD packagers may prefer to link libjack at build time. To do this, disable the dlopen feature by using default-features = false in your application’s Cargo.toml. For example:

[target.'cfg(any(windows, target_vendor = "apple"))'.dependencies]
jack = "0.9"

[target.'cfg(not(any(windows, target_vendor = "apple")))'.dependencies]
jack = { version = "0.9", default-features = false }

You can set the environment variable RUST_JACK_DLOPEN to on to enable the dlopen feature without needing to edit your application’s Cargo.toml. This can be useful for cross compiling to Linux with a different CPU architecture.

Server

JACK provides a high priority server to manipulate audio and midi across applications. The rust jack crate does not provide server creation functionality, so a server has to be set up with the jackd commandline tool, qjackctl the gui tool, or another method.

Client

Typically, applications connect clients to the server. For the rust jack crate, a connection can be made with client::Client::new, which returns a client::Client.

The Client can query the server for information, register ports, and manage connections for ports.

To commence processing audio/midi and other information in real-time, rust jack provides the Client::activate_async, which consumes the Client, an object that implements NotificationHandler and an object that implements ProcessHandler and returns a AsyncClient. AsyncClient processes the data in real-time with the provided handlers.

Port

A Client may obtain port information through the Client::port_by_id and Client::port_by_name methods. These ports can be used to manage connections or to obtain port metadata, though their port data (audio buffers and midi buffers) cannot be accessed safely.

Ports can be registered with the Client::register_port method. This requires a PortSpec. The jack crate comes with common specs such as AudioIn, AudioOut, MidiIn, and MidiOut.

To access the data of registered ports, use their specialized methods within a ProcessHandler callback. For example, Port<AudioIn>::as_mut_slice returns a audio buffer that can be written to.

Structs

AsyncClient

A JACK client that is processing data asynchronously, in real-time.

AudioIn

AudioIn implements the PortSpec trait which, defines an endpoint for JACK. In this case, it is a readable 32 bit floating point buffer for audio.

AudioOut

AudioOut implements the PortSpec trait, which defines an endpoint for JACK. In this case, it is a mutable 32 bit floating point buffer for audio.

CLIENT_NAME_SIZE

The maximum string length for port names.

Client

ClientOptions

Option flags for opening a JACK client.

ClientStatus

Status flags for JACK clients.

ClosureProcessHandler

Wrap a closure that can handle the process callback. This is called every time data from ports is available from JACK.

CycleTimes

Internal cycle timing information.

MidiIn

MidiIn implements the PortSpec trait, which defines an endpoint for JACK. In this case, it defines midi input.

MidiIter

Iterate through Midi Messages within a Port<MidiIn>.

MidiOut

MidiOut implements the PortSpec trait, which defines an endpoint for JACK. In this case, it defines a midi output.

MidiWriter

Write midi events to an output midi port.

PORT_NAME_SIZE

The maximum string length for port names.

PORT_TYPE_SIZE

The maximum string length for jack type names.

Port

An endpoint to interact with JACK data streams, for audio, midi, etc…

PortFlags

Flags for specifying port options.

ProcessScope

ProcessScope provides information on the client and frame time information within a process callback.

RawMidi

Contains 8bit raw midi information along with a timestamp relative to the process cycle.

RingBuffer

A lock-free ringbuffer. The key attribute of a ringbuffer is that it can be safely accessed by two threads simultaneously, one reading from the buffer and the other writing to it - without using any synchronization or mutual exclusion primitives. For this to work correctly, there can only be a single reader and a single writer thread. Their identities cannot be interchanged.

RingBufferReader

Read end of the ring buffer. Can only be used from one thread (can be different from the write thread).

RingBufferWriter

Write end of the ring buffer. Can only be used from one thread (can be a different from the read thread).

Transport

A structure for querying and manipulating the JACK transport.

TransportBBT

Transport Bar Beat Tick data.

TransportPosition

A structure representing the transport position.

TransportStatePosition

A helper struct encapsulating both TransportState and TransportPosition.

Unowned

PortSpec for a port that holds has no readable or writeable data from JACK on the created client. It can be used to connect ports or to obtain metadata.