1 :title: LADI JACK Audio Connection Kit
2 :docinfo: private-header
3 :keywords: LADI, JACK, jack-audio-connection-kit, jackdbus, jack2
8 image:https://github.com/LADI/jackdbus/actions/workflows/build.yml/badge.svg["Build status badge", link="https://github.com/LADI/jackdbus/actions"]
9 image:https://repology.org/badge/tiny-repos/jack-audio-connection-kit.svg["Repology bandge", link="https://repology.org/metapackage/jack-audio-connection-kit/versions"]
12 This software implements D-Bus endpoint for JACK server.
15 Initial version of link:https://github.com/LADI/jackdbus[jackdbus] was created
16 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].
17 jackdbus for JACK1 was maintained first as a setup of ad-hoc patches,
18 then via Mercural and then via Git.
19 In 2008/2009, jackdbus was ported to jackdmp codebase along with an implementation
20 of the newly designed for the new need control API for JACK.
21 The result of this merge became known as
22 link:https://web.archive.org/web/20170106162202/http://lac.linuxaudio.org/2009/cdm/Thursday/01_Letz/01.pdf[JACK2].
23 As of 2022, jackdbus is again maintained in LADI project.
24 The jackaudio.org version of jackdbus is considered older/alternative
27 For LADI specific issues, submit issues or pull request to LADI project.
28 For related discussions, you are invited to join
29 link:https://libera.chat/[Libera.Chat] channel #ladi
31 IMPORTANT: Do not submit LADI specific issues to jackaudio project.
35 D-Bus is an object model that provides IPC mechanism.
36 D-Bus supports autoactivation of objects,
37 thus making it simple and reliable to code a "single instance" application or daemon,
38 and to launch applications and daemons on demand when their services are needed.
40 Improvements over classical "jackd" approach:
42 * Simplified single thread model for control and monitor
43 applications. Various D-Bus language bindings make it trivial to
44 write control and monitor applications using scripting languages
45 like Python, Ruby, Perl, etc..
46 * A log file is available for inspection even when autoactivation
47 happens by the first launched JACK application.
48 * A real configuration file is used to persist settings to be
49 manipulated through configuration interface of JACK D-Bus object.
50 * Improved graph inspection and control mechanism. JACK graph is
51 versioned. Connections, ports and clients have unique
52 (monotonically increasing) numeric IDs.
53 * High level abstraction of JACK settings. Allows applications that
54 can configure JACK to expose parameters that were not known at
55 compile (or tarball release) time. Recent real world examples are
56 the JACK MIDI driver parameters and support for FFADO driver in
57 QJackCtl. Upgrading of JACK requires upgrade of QJackCtl in order
58 to make new settings available in the GUI.
61 ==== Autoactivation and starting/stopping JACK server
62 First, application that issues D-Bus method call to JACK controller object,
63 causes D-Bus session daemon to activate the object by starting the jackdbus executable.
64 Activating controller object does not start the server.
65 Instead controller object has several interfaces.
66 The most important of them is the control interface.
67 Control interface contains methods for starting and stopping JACK server,
68 loading and unloading of internal clients (netjack),
69 setting buffer size and resetting xrun counter.
70 It also contains methods for querying information required by monitoring
73 * whether JACK server is started
74 * whether JACK server is running in realtime mode
81 JACK server autostart is achieved by libjack calling "jack server start" method of
82 JACK control D-Bus interface.
85 Applications that want to manage JACK settings can query
86 and set all settings that were traditionally specified as
87 jackd command-line parameters.
88 Interface abstraction provides virtual tree of parameter
89 containers with container leaves that contain parameters.
90 Parameters are accessed using simple addressing scheme (array of strings)
91 where address defines path to parameter, like "drivers", "alsa", "dither".
93 Overview of the tree of standard settings' addresses:
97 * "engine", "realtime"
98 * "engine", ...more engine parameters
100 * "driver", ...more driver parameters
101 * "drivers", "alsa", "device"
102 * "drivers", "alsa", ...more alsa driver parameters
103 * "drivers", ...more drivers
104 * "internals", "netmanager", "multicast ip"
105 * "internals", "netmanager", ...more netmanager parameters
106 * "internals", ...more internals
108 JACK settings are persisted.
109 I.e. they are automatically saved by jackdbus when they are set.
110 Next time user starts JACK server, last saved settings will be automatically used.
111 Changing JACK settings through the configure D-Bus interface takes effect on next
113 On the fly change of the buffer size, as available in the libjack
114 (jack.h) API, is also possible through the control D-Bus interface.
116 ==== JACK parameter constraints
117 JACK internal modules that provide parameters visible through control API can provide
118 information about parameter valid range (like realtime priority) or
119 whether parameter should be presented as enumeration.
120 Enumeration parameters can be strict and non-strict.
121 Example of strict enum parameter is dither parameter of ALSA driver,
122 it has only predefined valid values: "shaped noise",
123 "rectangular", "triangualr" and "none".
125 Example of non-strict parameter is device parameter of ALSA driver.
126 It is useful to provide some detected device strings as choices to user,
127 but still allow user to specify custom string that ALSA layer is supposed to
131 In order to simplify patchbay applications, extended functionality is provided.
132 There is a method that returns the current graph state.
133 Graph state has unique monotonically increasing version number
134 and contains info about all clients, their ports and connections.
135 Connections, ports and clients have unique numeric IDs
136 that are guaranteed not to be reused.
137 Notifica tions about graph changes are provided using
140 === JACK D-Bus enabled applications
143 JACK contains "jack_control" executable, https://gitea.ladish.org/LADI/jack_control/src/branch/main/jack_control.py[a 300 lines of Python] exposing
144 JACK D-Bus functionality. It allows chained execution of several commands.
145 For example "jack control ds alsa dps midi-driver raw eps realtime on
146 eps relatime-priority 70 start" selects ALSA driver, enables JACK MIDI
147 raw backend, enables realtime mode, sets realtime priority to 70 and starts
151 https://gitea.ladish.org/LADI/laditools[LADI Tools] is a set of programs to configure, control and monitor JACK.
152 It provides tray icon, Window Maker style dockapp,
153 G15 keyboard LCD display integration application,
154 configuration utility for managing JACK settings
155 and log file monitor application.
157 All tools are written in Python.
160 https://drobilla.net/software/patchage.html[Patchage], the ubiquitous canvas modular patch bay can be compiled to use
161 D-Bus instead of libjack to communicate with JACK.
163 Doing so also enables JACK server start/stop functionality in Patchage.
165 Various JACK related features are implemented:
167 ==== LADI Session handler (LADISH)
168 https://ladish.org/[LADISH], a rewrite of LASH session handler
169 uses D-Bus to communicate with JACK.
171 Various JACK related features are implemented:
173 * Saving of JACK settings as part of "studio" session.
175 * Handling of "JACK server crash" scenario: restarting JACK server,
176 notifying JACK applications that JACK server reappeared so they
177 can reconnect to it, and restoring JACK connections.
179 ==== QjackCtl JACK Audio Connection Kit - Qt GUI Interface
180 https://qjackctl.sourceforge.io/[QjackCtl] is a simple Qt application
181 to control the JACK sound server daemon, is another jackdbus frontend.
183 ==== KXStudio Cadence
184 https://kx.studio/Applications:Cadence[Cadence], a set of tools
185 useful for audio production, is another jackdbus frontend.
188 https://ovenwerks.github.io/studio-controls/[Studio Controls], a way to
189 configure your Linux-based audio installation for real-time audio, is
190 another jackdbus frontend.
195 * link:https://dl.ladish.org/jackdbus/[https://dl.ladish.org/jackdbus/ (signed) tarballs]
199 * https://gitea.ladish.org/LADI/jackdbus[Upstream development GIT repository] +
201 * https://repo.or.cz/jackdbus.git[Primary backup GIT repository at repo.or.cz] +
205 https://jackdbus.ladish.org/packaging.html[Packaging HOWTO]
209 . link:https://web.archive.org/web/20170106162202/http://lac.linuxaudio.org/2009/cdm/Thursday/01_Letz/01.pdf[What's new in JACK2?]