.TH "pipewire-jack.conf" 5 "1.6.8" "PipeWire" \" -*- nroff -*-
.ad l
.nh
.SH NAME
pipewire-jack.conf \- jack\&.conf 
.SH DESCRIPTION
.PP
The PipeWire JACK client configuration file\&.

.PP
.SH "SYNOPSIS"
.PP

.PP
\fI$XDG_CONFIG_HOME/pipewire/jack\&.conf\fP

.PP
\fI/etc/pipewire/jack\&.conf\fP

.PP
\fI/usr/share/pipewire/jack\&.conf\fP

.PP
\fI/usr/share/pipewire/jack\&.conf\&.d/\fP

.PP
\fI/etc/pipewire/jack\&.conf\&.d/\fP

.PP
\fI$XDG_CONFIG_HOME/pipewire/jack\&.conf\&.d/\fP

.PP
.SH "DESCRIPTION"
.PP

.PP
Configuration for PipeWire JACK clients\&.

.PP
The configuration file format and lookup logic is the same as for \fBpipewire\&.conf(5)\fP\&.

.PP
Drop-in configuration files \fRjack\&.conf\&.d/*\&.conf\fP can be used, and are recommended\&. See \fBpipewire\&.conf(5)\fP\&.
.SH "CONFIGURATION FILE SECTIONS"
.PP
\fBjack\&.properties\fP
.RS 4
JACK client configuration\&.
.RE
.PP
\fBjack\&.rules\fP
.RS 4
JACK client match rules\&.
.RE
.PP
In addition, the PipeWire context configuration sections may also be specified, see \fBpipewire\&.conf(5)\fP\&.
.SH "JACK PROPERTIES"
.PP
The configuration file can contain an extra JACK specific section called \fRjack\&.properties\fP like this: 
.PP
.nf
# ~/\&.config/pipewire/jack\&.conf\&.d/custom\&.conf

jack\&.properties = {
    #rt\&.prio             = 88
    #node\&.latency        = 1024/48000
    #node\&.lock\-quantum   = true
    #node\&.force\-quantum  = 0
    #jack\&.show\-monitor   = true
    #jack\&.merge\-monitor  = true
    #jack\&.show\-midi      = true
    #jack\&.short\-name     = false
    #jack\&.filter\-name    = false
    #jack\&.filter\-char    = " "
    #
    # allow:           Don't restrict self connect requests
    # fail\-external:   Fail self connect requests to external ports only
    # ignore\-external: Ignore self connect requests to external ports only
    # fail\-all:        Fail all self connect requests
    # ignore\-all:      Ignore all self connect requests
    #jack\&.self\-connect\-mode  = allow
    #jack\&.locked\-process     = true
    #jack\&.default\-as\-system  = false
    #jack\&.fix\-midi\-events    = true
    #jack\&.global\-buffer\-size = false
    #jack\&.passive\-links      = false
    #jack\&.max\-client\-ports   = 768
    #jack\&.fill\-aliases       = false
    #jack\&.writable\-input     = false
    #jack\&.flag\-midi2         = false
}

.fi
.PP

.PP
See \fRstream\&.properties\fP in \fBpipewire-client\&.conf(5)\fP for an explanation of the generic node properties\&.

.PP
It is also possible to have per-client settings, see Match Rules below\&.

.PP
\fBrt\&.prio \fP
.RS 4
To limit the realtime priority that jack clients can acquire\&.
.RE
.PP
\fBnode\&.latency \fP
.RS 4
To force a specific minimum buffer size for the JACK applications, configure: 
.PP
.nf
node\&.latency = 1024/48000

.fi
.PP
 This configures a buffer-size of 1024 samples at 48KHz\&. If the graph is running at a different sample rate, the buffer-size will be adjusted accordingly\&.
.RE
.PP
\fBnode\&.lock-quantum \fP
.RS 4
To make sure that no automatic quantum is changes while JACK applications are running, configure: 
.PP
.nf
node\&.lock\-quantum = true

.fi
.PP
 The quantum can then only be changed by metadata or when an application is started with node\&.force-quantum\&. JACK Applications will also be able to use jack_set_buffersize() to override the quantum\&.
.RE
.PP
\fBnode\&.force-quantum \fP
.RS 4
To force the quantum to a certain value and avoid changes to it: 
.PP
.nf
node\&.force\-quantum = 1024

.fi
.PP
 The quantum can then only be changed by metadata or when an application is started with node\&.force-quantum (or JACK applications that use jack_set_buffersize() to override the quantum)\&.
.RE
.PP
\fBjack\&.show-monitor \fP
.RS 4
Show the Monitor client and its ports\&.
.RE
.PP
\fBjack\&.merge-monitor \fP
.RS 4
Exposes the capture ports and monitor ports on the same JACK device client\&. This is how JACK presents monitor ports to the clients\&. The default is however \fInot\fP to merge them together because this results in more user friendly user interfaces, usually\&. An extra client with a \fRMonitor\fP suffix is created that contains the monitor ports\&.

.PP
For example, this is (part of) the output of \fRjack_lsp\fP with the default setting (\fRjack\&.merge-monitor = false\fP):

.PP
Compare:

.PP
\fRjack\&.merge-monitor = true\fP  \fRjack\&.merge-monitor = false\fP  Built-in Audio Analog Stereo:playback_FL  Built-in Audio Analog Stereo:playback_FL  Built-in Audio Analog Stereo:monitor_FL  Built-in Audio Analog Stereo Monitor:monitor_FL  Built-in Audio Analog Stereo:playback_FR  Built-in Audio Analog Stereo:playback_FR  Built-in Audio Analog Stereo:monitor_FR  Built-in Audio Analog Stereo Monitor:monitor_FR  
.RE
.PP

.PP
\fBjack\&.show-midi \fP
.RS 4
Show the MIDI clients and their ports\&.
.RE
.PP
\fBjack\&.short-name \fP
.RS 4
To use shorter names for the device client names use \fRjack\&.short-name = true\fP\&. Compare:

.PP
\fRjack\&.short-name = true\fP  \fRjack\&.short-name = false\fP  HDA Intel PCH:playback_FL  Built-in Audio Analog Stereo:playback_FL  HDA Intel PCH Monitor:monitor_FL  Built-in Audio Analog Stereo Monitor:monitor_FL  HDA Intel PCH:playback_FR  Built-in Audio Analog Stereo:playback_FR  HDA Intel PCH Monitor:monitor_FR  Built-in Audio Analog Stereo Monitor:monitor_FR  
.RE
.PP

.PP
\fBjack\&.filter-name \fP
.RS 4

.RE
.PP
\fBjack\&.filter-char \fP
.RS 4
Will replace all special characters with \fRjack\&.filter-char\fP\&. For clients the special characters are \fR ()[]\&.:*$\fP and for ports they are \fR ()[]\&.*$\fP\&. Use this option when a client is not able to deal with the special characters\&. (and older version of PortAudio was known to use the client and port names as a regex, and thus failing when there are regex special characters in the name)\&.
.RE
.PP
\fBjack\&.self-connect-mode \fP
.RS 4
Restrict a client from making connections to and from itself\&. Possible values and their meaning are summarized as:

.PP
Value  Behavior  \fRallow\fP  Don't restrict self connect requests\&.  \fRfail-external\fP  Fail self connect requests to external ports only\&.  \fRignore-external\fP  Ignore self connect requests to external ports only\&.  \fRfail-all\fP  Fail all self connect requests\&.  \fRignore-all\fP  Ignore all self connect requests\&.  
.RE
.PP

.PP
\fBjack\&.locked-process \fP
.RS 4
Make sure the process and callbacks can not be called at the same time\&. This is the normal operation but it can be disabled in case a specific client can handle this\&.
.RE
.PP
\fBjack\&.default-as-system \fP
.RS 4
Name the default source and sink as \fRsystem\fP and number the ports to maximize compatibility with JACK programs\&.

.PP
\fRjack\&.default-as-system = false\fP  \fRjack\&.default-as-system = true\fP  HDA Intel PCH:playback_FL  system:playback_1  HDA Intel PCH Monitor:monitor_FL  system:monitor_1  HDA Intel PCH:playback_FR  system:playback_2  HDA Intel PCH Monitor:monitor_FR  system:monitor_2  
.RE
.PP

.PP
\fBjack\&.fix-midi-events \fP
.RS 4
Fix NoteOn events with a 0 velocity to NoteOff\&. This is standard behaviour in JACK and is thus enabled by default to maximize compatibility\&. Especially LV2 plugins do not allow NoteOn with 0 velocity\&.
.RE
.PP
\fBjack\&.global-buffer-size \fP
.RS 4
When a client has this option, buffersize changes will be applied globally and permanently for all PipeWire clients using the metadata\&.
.RE
.PP
\fBjack\&.passive-links \fP
.RS 4
Makes JACK clients make passive links\&. This option only works when the server link-factory was configured with the \fRallow\&.link\&.passive\fP option\&.
.RE
.PP
\fBjack\&.max-client-ports \fP
.RS 4
Limit the number of allowed ports per client to this value\&.
.RE
.PP
\fBjack\&.fill-aliases \fP
.RS 4
Automatically set the port alias1 and alias2 on the ports\&.
.RE
.PP
\fBjack\&.writable-input \fP
.RS 4
Makes the input buffers writable\&. This is the default because some JACK clients write to the input buffer\&. This however can cause corruption in other clients when they are also reading from the buffer\&.

.PP
Set this to true to avoid buffer corruption if you are only dealing with non-buggy clients\&. 
.RE
.PP

.PP
\fBjack\&.flag-midi2 \fP
.RS 4
Use the new JACK MIDI2 port flag on MIDI2 (UMP) ports\&. This is disabled by default because most JACK apps don't know about this flag yet and refuse to show the port\&.

.PP
Set this to true for applications that know how to handle MIDI2 ports\&. 
.RE
.PP
.SH "MATCH RULES"
.PP
 \fRjack\&.rules\fP provides an \fRupdate-props\fP action that takes an object with properties that are updated on the client and node object of the jack client\&.

.PP
Add a \fRjack\&.rules\fP section in the config file like this:

.PP
.PP
.nf
# ~/\&.config/pipewire/jack\&.conf\&.d/custom\&.conf

jack\&.rules = [
    {
        matches = [
            {
                # all keys must match the value\&. ! negates\&. ~ starts regex\&.
                application\&.process\&.binary = "jack_simple_client"
            }
        ]
        actions = {
            update\-props = {
                node\&.latency = 512/48000
            }
        }
    }
    {
        matches = [
            {
                client\&.name = "catia"
            }
        ]
        actions = {
            update\-props = {
                jack\&.merge\-monitor = true
            }
        }
    }
]
.fi
.PP
 Will set the latency of jack_simple_client to 512/48000 and makes Catia see the monitor client merged with the playback client\&.
.SH "ENVIRONMENT VARIABLES"
.PP
See \fBpipewire(1)\fP for common environment variables\&. Many of these also apply to JACK client applications\&.

.PP
Environment variables can be used to control the behavior of the PipeWire JACK client library\&.

.PP
\fBPIPEWIRE_NOJACK \fP
.RS 4

.RE
.PP
\fBPIPEWIRE_INTERNAL \fP
.RS 4
When any of these variables is set, the JACK client library will refuse to open a client\&. The \fRPIPEWIRE_INTERNAL\fP variable is set by the PipeWire main daemon to avoid self connections\&.
.RE
.PP
\fBPIPEWIRE_PROPS \fP
.RS 4
Adds/overrides the properties specified in the \fRjack\&.conf\fP file\&. Check out the output of this: 
.PP
.nf
> PIPEWIRE_PROPS='{ jack\&.short\-name=true jack\&.merge\-monitor=true }' jack_lsp
\&.\&.\&.
HDA Intel PCH:playback_FL
HDA Intel PCH:monitor_FL
HDA Intel PCH:playback_FR
HDA Intel PCH:monitor_FR
\&.\&.\&.

.fi
.PP
.RE
.PP
\fBPIPEWIRE_LATENCY \fP
.RS 4

.PP
.nf
PIPEWIRE_LATENCY=<samples>/<rate> <application>

.fi
.PP
 A quick way to configure the maximum buffer-size for a client\&. It will run this client with the specified buffer-size (or smaller)\&.

.PP
\fRPIPEWIRE_LATENCY=256/48000 jack_lsp\fP is equivalent to \fRPIPEWIRE_PROPS='{ node\&.latency=256/48000 }' jack_lsp\fP

.PP
A better way to start a jack session in a specific buffer-size is to force it with: 
.PP
.nf
pw\-metadata \-n settings 0 clock\&.force\-quantum <quantum>

.fi
.PP
 This always works immediately and the buffer size will not change until the quantum is changed back to 0\&. 
.RE
.PP

.PP
\fBPIPEWIRE_RATE \fP
.RS 4

.PP
.nf
PIPEWIRE_RATE=1/<rate> <application>

.fi
.PP

.PP
A quick way to configure the rate of the graph\&. It will try to switch the samplerate of the graph\&. This can usually only be done with the graph is idle and the rate is part of the allowed sample rates\&.

.PP
\fRPIPEWIRE_RATE=1/48000 jack_lsp\fP is equivalent to \fRPIPEWIRE_PROPS='{ node\&.rate=1/48000 }' jack_lsp\fP

.PP
A better way to start a jack session in a specific rate is to force the rate with: 
.PP
.nf
pw\-metadata \-n settings 0 clock\&.force\-rate <rate>

.fi
.PP
 This always works and the samplerate does not need to be in the allowed rates\&. The rate will also not change until it is set back to 0\&. 
.RE
.PP

.PP
\fBPIPEWIRE_QUANTUM \fP
.RS 4

.PP
.nf
PIPEWIRE_QUANTUM=<buffersize>/<rate> <application>

.fi
.PP

.PP
Is similar to using \fRPIPEWIRE_LATENCY=<buffersize>/<rate>\fP and \fRPIPEWIRE_RATE=1/<rate>\fP (see above), except that it is not just a suggestion but it actively \fIforces\fP the graph to change the rate and quantum\&. It can be used to set both a buffersize and samplerate at the same time\&.

.PP
When 2 applications force a quantum, the last one wins\&. When the winning app is stopped, the quantum of the previous app is restored\&. 
.RE
.PP

.PP
\fBPIPEWIRE_LINK_PASSIVE \fP
.RS 4

.PP
.nf
PIPEWIRE_LINK_PASSIVE=true qjackctl

.fi
.PP
 Make this client create passive links only\&. All links created by the client will be marked passive and will not keep the sink/source busy\&.

.PP
You can use this to link filters to devices\&. When there is no client connected to the filter, only passive links remain between the filter and the device and the device will become idle and suspended\&. 
.RE
.PP

.PP
\fBPIPEWIRE_NODE \fP
.RS 4

.PP
.nf
PIPEWIRE_NODE=<id> <application>

.fi
.PP
 Will sort the ports so that only the ports of the node with <id> are listed\&. You can use this to force an application to only deal with the ports of a certain node, for example when auto connecting\&. 
.RE
.PP

.PP
.SH "AUTHORS"
.PP

.PP
The PipeWire Developers <https://gitlab.freedesktop.org/pipewire/pipewire/issues>; PipeWire is available from <https://pipewire.org>

.PP
.SH "SEE ALSO"
.PP

.PP
\fBpw-jack(1)\fP, \fBpipewire\&.conf(5)\fP 

