Overview

This software imlements D-Bus endpoint for JACK server.

Brief History

Initial version of jackdbus was created as part of LADI project and was ad-hoc modification of JACK1 codebase. jackdbus for JACK1 was maintained first as a setup of ad-hoc patches, then via Mercural and then via Git. In 2008/2009, jackdbus was ported to jackdmp codebase along with an implementation of the newly designed for the new need control API for JACK. The result of this merge became known as JACK2. As of 2022, jackdbus is again maintained in LADI project. The jackaudio.org version of jackdbus is considered older/alternative implementation.

For LADI specific issues, submit issues or pull request to LADI project. For related discussions, you are invited to join Libera.Chat channel #ladi

Important Do not submit LADI specific issues to jackaudio project.

D-Bus access

D-Bus is an object model that provides IPC mechanism. D-Bus supports autoactivation of objects, thus making it simple and reliable to code a "single instance" application or daemon, and to launch applications and daemons on demand when their services are needed.

Improvements over classical "jackd" approach:

  • Simplified single thread model for control and monitor applications. Various D-Bus language bindings make it trivial to write control and monitor applications using scripting languages like Python, Ruby, Perl, etc..

  • A log file is available for inspection even when autoactivation happens by the first launched JACK application.

  • A real configuration file is used to persist settings to be manipulated through configuration interface of JACK D-Bus object.

  • Improved graph inspection and control mechanism. JACK graph is versioned. Connections, ports and clients have unique (monotonically increasing) numeric IDs.

  • High level abstraction of JACK settings. Allows applications that can configure JACK to expose parameters that were not known at compile (or tarball release) time. Recent real world examples are the JACK MIDI driver parameters and support for FFADO driver in QJackCtl. Upgrading of JACK requires upgrade of QJackCtl in order to make new settings available in the GUI.

How it works

Autoactivation and starting/stopping JACK server

First, application that issues D-Bus method call to JACK controller object, causes D-Bus session daemon to activate the object by starting the jackdbus executable. Activating controller object does not start the server. Instead controller object has several interfaces. The most important of them is the control interface. Control interface contains methods for starting and stopping JACK server, loading and unloading of internal clients (netjack), setting buffer size and resetting xrun counter. It also contains methods for querying information required by monitoring applications:

  • whether JACK server is started

  • whether JACK server is running in realtime mode

  • sample rate

  • DSP load

  • current buffer size

  • latency

  • xrun counter

JACK server autostart is achieved by libjack calling "jack server start" method of JACK control D-Bus interface.

JACK settings

Applications that want to manage JACK settings can query and set all settings that were traditionally specified as jackd command-line parameters. Interface abstraction provides virtual tree of parameter containers with container leaves that contain parameters. Parameters are accessed using simple addressing scheme (array of strings) where address defines path to parameter, like "drivers", "alsa", "dither".

Overview of the tree of standard settings’ addresses:

  • "engine"

  • "engine", "driver"

  • "engine", "realtime"

  • "engine", …more engine parameters

  • "driver", "device"

  • "driver", …more driver parameters

  • "drivers", "alsa", "device"

  • "drivers", "alsa", …more alsa driver parameters

  • "drivers", …more drivers

  • "internals", "netmanager", "multicast ip"

  • "internals", "netmanager", …more netmanager parameters

  • "internals", …more internals

JACK settings are persisted. I.e. they are automatically saved by jackdbus when they are set. Next time user starts JACK server, last saved settings will be automatically used. Changing JACK settings through the configure D-Bus interface takes effect on next JACK server start. On the fly change of the buffer size, as available in the libjack (jack.h) API, is also possible through the control D-Bus interface.

JACK parameter constraints

JACK internal modules that provide parameters visible through control API can provide information about parameter valid range (like realtime priority) or whether parameter should be presented as enumeration. Enumeration parameters can be strict and non-strict. Example of strict enum parameter is dither parameter of ALSA driver, it has only predefined valid values: "shaped noise", "rectangular", "triangualr" and "none".

Example of non-strict parameter is device parameter of ALSA driver. It is useful to provide some detected device strings as choices to user, but still allow user to specify custom string that ALSA layer is supposed to understand.

JACK patchbay

In order to simplify patchbay applications, extended functionality is provided. There is a method that returns the current graph state. Graph state has unique monotonically increasing version number and contains info about all clients, their ports and connections. Connections, ports and clients have unique numeric IDs that are guaranteed not to be reused. Notifica tions about graph changes are provided using D-Bus signals.

JACK D-Bus enabled applications

jack_control

JACK contains "jack_control" executable a 300 lines of Python exposing JACK D-Bus functionality. It allows chained execution of several commands. For example "jack control ds alsa dps midi-driver raw eps realtime on eps relatime-priority 70 start" selects ALSA driver, enables JACK MIDI raw backend, enables realtime mode, sets realtime priority to 70 and starts JACK server.

LADI Tools

LADI Tools is a set of programs to configure, control and monitor JACK. It provides tray icon, Window Maker style dockapp, G15 keyboard LCD display integration application, configuration utility for managing JACK settings and log file monitor application.

All tools are written in Python.

Patchage

Patchage, the ubiquitous canvas modular patch bay can be compiled to use D-Bus instead of libjack to communicate with JACK.

Doing so also enables JACK server start/stop functionality in Patchage.

LADI Session handler (LADISH)

LADISH, a rewrite of LASH session handler uses D-Bus to communicate with JACK.

Various JACK related features are implemented:

  • Saving of JACK settings as part of "studio" session.

  • Handling of "JACK server crash" scenario: restarting JACK server, notifying JACK applications that JACK server reappeared so they can reconnect to it, and restoring JACK connections.

References