:title: LADI JACK Audio Connection Kit
:docinfo: private-header
:keywords: LADI, JACK, jack-audio-connection-kit, jackdbus, jack2
:toc:

= (LADI) jackdbus

image:https://github.com/LADI/jackdbus/actions/workflows/build.yml/badge.svg["Build status badge", link="https://github.com/LADI/jackdbus/actions"]
image:https://repology.org/badge/tiny-repos/jack-audio-connection-kit.svg["Repology bandge", link="https://repology.org/metapackage/jack-audio-connection-kit/versions"]

== Overview
This software implements D-Bus endpoint for JACK server.

== Brief History
Initial version of link:https://github.com/LADI/jackdbus[jackdbus] was created
as part of LADI project and was ad-hoc modification of link:https://jackdbus.ladish.org/jack1-design.html[JACK1] link:https://github.com/jackaudio/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
link:https://web.archive.org/web/20170106162202/http://lac.linuxaudio.org/2009/cdm/Thursday/01_Letz/01.pdf[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
link:https://libera.chat/[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, https://gitea.ladish.org/LADI/jack_control/src/branch/main/jack_control.py[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
https://gitea.ladish.org/LADI/laditools[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
https://drobilla.net/software/patchage.html[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.

Various JACK related features are implemented:

==== LADI Session handler (LADISH)
https://ladish.org/[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.

==== QjackCtl JACK Audio Connection Kit - Qt GUI Interface
https://qjackctl.sourceforge.io/[QjackCtl] is a simple Qt application
to control the JACK sound server daemon, is another jackdbus frontend.

==== KXStudio Cadence
https://kx.studio/Applications:Cadence[Cadence], a set of tools
useful for audio production, is another jackdbus frontend.

==== Studio Controls
https://ovenwerks.github.io/studio-controls/[Studio Controls], a way to
configure your Linux-based audio installation for real-time audio, is
another jackdbus frontend.

== Source
Tarballs:

 * link:https://dl.ladish.org/jackdbus/[https://dl.ladish.org/jackdbus/ (signed) tarballs]

GIT repositories:

 * https://gitea.ladish.org/LADI/jackdbus[Upstream development GIT repository] +
   Self-hosted upstream
 * https://repo.or.cz/jackdbus.git[Primary backup GIT repository at repo.or.cz] +
   Cloud hosted

== Packaging
https://jackdbus.ladish.org/packaging.html[Packaging HOWTO]

References
----------
. link:https://web.archive.org/web/20170106162202/http://lac.linuxaudio.org/2009/cdm/Thursday/01_Letz/01.pdf[What's new in JACK2?]