README.adoc

   1 :title: LADI JACK Audio Connection Kit
   2 :docinfo: private-header
   3 :keywords: LADI, JACK, jack-audio-connection-kit, jackdbus, jack2
   4 :toc:
   5
   6 = (LADI) jackdbus
   7
   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"]
  10
  11 == Overview
  12 This software implements D-Bus endpoint for JACK server.
  13
  14 == Brief History
  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
  25 implementation.
  26
  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
  30
  31 IMPORTANT: Do not submit LADI specific issues to jackaudio project.
  32
  33
  34 == D-Bus access
  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.
  39
  40 Improvements over classical "jackd" approach:
  41
  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.
  59
  60 === How it works
  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
  71 applications:
  72
  73  * whether JACK server is started
  74  * whether JACK server is running in realtime mode
  75  * sample rate
  76  * DSP load
  77  * current buffer size
  78  * latency
  79  * xrun counter
  80
  81 JACK server autostart is achieved by libjack calling "jack server start" method of
  82 JACK control D-Bus interface.
  83
  84 ==== JACK settings
  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".
  92
  93 Overview of the tree of standard settings' addresses:
  94
  95  * "engine"
  96  * "engine", "driver"
  97  * "engine", "realtime"
  98  * "engine", ...more engine parameters
  99  * "driver", "device"
 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
 107
 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
 112 JACK server start.
 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.
 115
 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".
 124
 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
 128 understand.
 129
 130 ==== JACK patchbay
 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
 138 D-Bus signals.
 139
 140 === JACK D-Bus enabled applications
 141
 142 ==== jack_control
 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
 148 JACK server.
 149
 150 ==== LADI Tools
 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.
 156
 157 All tools are written in Python.
 158
 159 ==== Patchage
 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.
 162
 163 Doing so also enables JACK server start/stop functionality in Patchage.
 164
 165 Various JACK related features are implemented:
 166
 167 ==== LADI Session handler (LADISH)
 168 https://ladish.org/[LADISH], a rewrite of LASH session handler
 169 uses D-Bus to communicate with JACK.
 170
 171 Various JACK related features are implemented:
 172
 173  * Saving of JACK settings as part of "studio" session.
 174
 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.
 178
 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.
 182
 183 ==== KXStudio Cadence
 184 https://kx.studio/Applications:Cadence[Cadence], a set of tools
 185 useful for audio production, is another jackdbus frontend.
 186
 187 ==== Studio Controls
 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.
 191
 192 == Source
 193 Tarballs:
 194
 195  * link:https://dl.ladish.org/jackdbus/[https://dl.ladish.org/jackdbus/ (signed) tarballs]
 196
 197 GIT repositories:
 198
 199  * https://gitea.ladish.org/LADI/jackdbus[Upstream development GIT repository] +
 200    Self-hosted upstream
 201  * https://repo.or.cz/jackdbus.git[Primary backup GIT repository at repo.or.cz] +
 202    Cloud hosted
 203
 204 == Packaging
 205 https://jackdbus.ladish.org/packaging.html[Packaging HOWTO]
 206
 207 References
 208 ----------
 209 . link:https://web.archive.org/web/20170106162202/http://lac.linuxaudio.org/2009/cdm/Thursday/01_Letz/01.pdf[What's new in JACK2?]