mirrors/pipewire
1
0
Fork 0
mirror of https://gitlab.freedesktop.org/pipewire/pipewire.git synced 2025-10-29 05:40:27 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions

doc: rename pipewire-devices.7 and move stream properties into it

Browse source 
Collect the list of object properties into a single place.

Group properties in the index based on the object type. Consider
"Monitor" as a separate object type, as it's generally configured
separately.

Add something about Port, Link, and Client properties. Just explain some
of these as they're fairly technical, so just link to API docs.
This commit is contained in:
Pauli Virtanen 2024-07-23 21:36:34 +03:00 • committed by Wim Taymans
parent 3d8fb4844c
commit d7235c1dbd
5 changed files with 1107 additions and 948 deletions
Download patch file Download diff file Expand all files Collapse all files

28
doc/dox/config/index.md
View file

@ -30,7 +30,7 @@ Configuration of daemons:
Configuration of devices:
- [WirePlumber configuration](https://pipewire.pages.freedesktop.org/wireplumber/daemon/configuration.html)
- \ref page_man_pipewire-devices_7 "Device and node property reference"
- \ref page_man_pipewire-props_7 "Object property reference"
Configuration for client applications, either connecting via the
native PipeWire interface, or the emulated ALSA, JACK, or PulseAudio
@ -47,7 +47,7 @@ interfaces:
- \subpage page_man_pipewire-pulse_conf_5
- \subpage page_man_pipewire-jack_conf_5
- \subpage page_man_pipewire-filter-chain_conf_5
- \subpage page_man_pipewire-devices_7
- \subpage page_man_pipewire-props_7
- \subpage page_man_pipewire-pulse-modules_7
- \subpage page_man_libpipewire-modules_7
@ -77,6 +77,28 @@ interfaces:
@SECREF@ pipewire-env client-env jack-env pulse-env
**Object properties**
@SECREF@ props
**Monitor properties**
@SECREF@ monitor-prop
**Device properties**
@SECREF@ device-param
@SECREF@ device-prop
**Node properties**
@SECREF@ node-prop
**Port properties**
@SECREF@ port-prop
**Client properties**
@SECREF@ client-prop
\see pw_keys in API documentation.

434
doc/dox/config/pipewire-client.conf.5.md
View file

@ -101,429 +101,10 @@ Some of the properties refer to different aspects of the stream:
* How the internal processing will be done.
* Properties to configure the media format.
## Identifying Properties @IDX@ client.conf
These contain properties to identify the node or to display the node in a GUI application.
@PAR@ client.conf node.name
A (unique) name for the node. This is usually set on sink and sources to identify them
as targets for linking by the session manager.
@PAR@ client.conf node.description
A human readable description of the node or stream.
@PAR@ client.conf media.name
A user readable media name, usually the artist and title.
These are usually shown in user facing applications
to inform the user about the current playing media.
@PAR@ client.conf media.title
A user readable stream title.
@PAR@ client.conf media.artist
A user readable stream artist
@PAR@ client.conf media.copyright
User readable stream copyright information
@PAR@ client.conf media.software
User readable stream generator software information
@PAR@ client.conf media.language
Stream language in POSIX format. Ex: `en_GB`
@PAR@ client.conf media.filename
File name for the stream
@PAR@ client.conf media.icon
Icon for the media, a base64 blob with PNG image data
@PAR@ client.conf media.icon-name
An XDG icon name for the media. Ex: `audio-x-mp3`
@PAR@ client.conf media.comment
Extra stream comment
@PAR@ client.conf media.date
Date of the media
@PAR@ client.conf media.format
User readable stream format information
@PAR@ client.conf object.linger = false
If the object should outlive its creator.
## Classifying Properties @IDX@ client.conf
The classifying properties of a node are use for routing the signal to its destination and
for configuring the settings.
@PAR@ client.conf media.type
The media type contains a broad category of the media that is being processed by the node.
Possible values include "Audio", "Video", "Midi"
@PAR@ client.conf media.category
\parblock
What kind of processing is done with the media. Possible values include:
* Playback: media playback.
* Capture: media capture.
* Duplex: media capture and playback or media processing in general.
* Monitor: a media monitor application. Does not actively change media data but monitors
activity.
* Manager: Will manage the media graph.
\endparblock
@PAR@ client.conf media.role
\parblock
The Use case of the media. Possible values include:
* Movie: Movie playback with audio and video.
* Music: Music listening.
* Camera: Recording video from a camera.
* Screen: Recording or sharing the desktop screen.
* Communication: VOIP or other video chat application.
* Game: Game.
* Notification: System notification sounds.
* DSP: Audio or Video filters and effect processing.
* Production: Professional audio processing and production.
* Accessibility: Audio and Visual aid for accessibility.
* Test: Test program.
\endparblock
@PAR@ client.conf media.class
\parblock
The media class is to classify the stream function. Possible values include:
* Video/Source: a producer of video, like a webcam.
* Video/Sink: a consumer of video, like a display window.
* Audio/Source: a source of audio samples like a microphone.
* Audio/Sink: a sink for audio samples, like an audio card.
* Audio/Duplex: a node that is both a sink and a source.
* Stream/Output/Audio: a playback stream.
* Stream/Input/Audio: a capture stream.
The session manager assigns special meaning to the nodes based on the media.class. Sink or Source
classes are used as targets for Stream classes, etc..
\endparblock
## Scheduling Properties @IDX@ client.conf
@PAR@ client.conf node.latency = 1024/48000
Sets a suggested latency on the node as a fraction. This is just a suggestion, the graph will try to configure this latency or less for the graph. It is however possible that the graph is forced to a higher latency.
@PAR@ client.conf node.lock-quantum = false
\parblock
When this node is active, the quantum of the graph is locked and not allowed to change automatically.
It can still be changed forcibly with metadata or when a node forces a quantum.
JACK clients use this property to avoid unexpected quantum changes.
\endparblock
@PAR@ client.conf node.force-quantum = INTEGER
\parblock
While the node is active, force a quantum in the graph. The last node to be activated with this property wins.
A value of 0 unforces the quantum.
\endparblock
@PAR@ client.conf node.rate = RATE
Suggest a rate (samplerate) for the graph. The suggested rate will only be applied when doing so would not cause
interruptions (devices are idle) and when the rate is in the list of allowed rates in the server.
@PAR@ client.conf node.lock-rate = false
When the node is active, the rate of the graph will not change automatically. It is still possible to force a rate change with metadata or with a node property.
@PAR@ client.conf node.force-rate = RATE
\parblock
When the node is active, force a specific sample rate on the graph. The last node to activate with this property wins.
A RATE of 0 means to force the rate in `node.rate` denominator.
\endparblock
@PAR@ client.conf node.always-process = false
\parblock
When the node is active, it will always be joined with a driver node, even when nothing is linked to the node.
Setting this property to true also implies node.want-driver = true.
This is the default for JACK nodes, that always need their process callback called.
\endparblock
@PAR@ client.conf node.want-driver = true
The node wants to be linked to a driver so that it can start processing. This is the default for streams
and filters since 0.3.51. Nodes that are not linked to anything will still be set to the idle state,
unless node.always-process is set to true.
@PAR@ client.conf node.pause-on-idle = false
@PAR@ client.conf node.suspend-on-idle = false
\parblock
When the node is not linked anymore, it becomes idle. Normally idle nodes keep processing and are suspended by the session manager after some timeout. It is possible to immediately pause a node when idle with this property.
When the session manager does not suspend nodes (or when there is no session manager), the node.suspend-on-idle property can be used instead.
\endparblock
@PAR@ client.conf node.loop.name = null
@PAR@ client.conf node.loop.class = data.rt
\parblock
Add the node to a specific loop name or loop class. By default the node is added to the
data.rt loop class. You can make more specific data loops and then assign the nodes to those.
Other well known names are main-loop.0 and the main node.loop.class which runs the node data processing
in the main loop.
\endparblock
## Session Manager Properties @IDX@ client.conf
@PAR@ client.conf node.autoconnect = true
Instructs the session manager to automatically connect this node to some other node, usually
a sink or source.
@PAR@ client.conf node.exclusive = false
If this node wants to be linked exclusively to the sink/source.
@PAR@ client.conf node.target = <node.name|object.id>
Where this node should be linked to. This can be a node.name or an object.id of a node. This property is
deprecated, the target.object property should be used instead, which uses the more unique object.serial as
a possible target.
@PAR@ client.conf target.object = <node.name|object.serial>
Where the node should link to, this can be a node.name or an object.serial.
@PAR@ client.conf node.dont-reconnect = false
\parblock
When the node has a target configured and the target is destroyed, destroy the node as well.
This property also inhibits that the node is moved to another sink/source.
Note that if a stream should appear/disappear in sync with the target, a session manager (WirePlumber) script
should be written instead.
\endparblock
@PAR@ client.conf node.passive = false
\parblock
This is a passive node and so it should not keep sinks/sources busy. This property makes the session manager create passive links to the sink/sources. If the node is not otherwise linked (via a non-passive link), the node and the sink it is linked to are idle (and eventually suspended).
This is used for filter nodes that sit in front of sinks/sources and need to suspend together with the sink/source.
\endparblock
@PAR@ client.conf node.link-group = ID
Add the node to a certain link group. Nodes from the same link group are not automatically linked to each other by the session manager. And example is a coupled stream where you don't want the output to link to the input streams, making a useless loop.
@PAR@ client.conf stream.dont-remix = false
Instruct the session manager to not remix the channels of a stream. Normally the stream channel configuration is changed to match the sink/source it is connected to. With this property set to true, the stream will keep its original channel layout and the session manager will link matching channels with the sink.
## Audio Adapter Parameters @IDX@ client.conf
An audio stream (and also audio device nodes) contain an audio adapter that can perform,
sample format, sample rate and channel mixing operations.
### Merger Parameters
The merger is used as the input for a sink device node or a capture stream. It takes the various channels and merges them into a single stream for further processing.
The merger will also provide the monitor ports of the input channels and can
apply a software volume on the monitor signal.
@PAR@ client.conf monitor.channel-volumes = false
The volume of the input channels is applied to the volume of the monitor ports. Normally
the monitor ports expose the raw unmodified signal on the input ports.
### Resampler Parameters
Source, sinks, capture and playback streams contain a high quality adaptive resampler.
It uses [sinc](https://ccrma.stanford.edu/~jos/resample/resample.pdf) based resampling
with linear interpolation of filter banks to perform arbitrary
resample factors. The resampler is activated in the following cases:
* The hardware of a device node does not support the graph samplerate. Resampling will occur
from the graph samplerate to the hardware samplerate.
* The hardware clock of a device does not run at the same speed as the graph clock and adaptive
resampling is required to match the clocks.
* A stream does not have the same samplerate as the graph and needs to be resampled.
* An application wants to activate adaptive resampling in a stream to make it match some other
clock.
PipeWire performs most of the sample conversions and resampling in the client (Or in the case of the PulseAudio server, in the pipewire-pulse server that creates the streams). This ensures all the conversions are offloaded to the clients and the server can deal with one single format for performance reasons.
Below is an explanation of the options that can be tuned in the sample converter.
@PAR@ client.conf resample.quality = 4
\parblock
The quality of the resampler. from 0 to 14, the default is 4.
Increasing the quality will result in better cutoff and less aliasing at the expense of
(much) more CPU consumption. The default quality of 4 has been selected as a good compromise
between quality and performance with no artifacts that are well below the audible range.
See [Infinite Wave](https://src.infinitewave.ca/) for a comparison of the performance.
\endparblock
@PAR@ client.conf resample.disable = false
Disable the resampler entirely. The node will only be able to negotiate with the graph
when the samplerates are compatible.
### Channel Mixer Parameters
Source, sinks, capture and playback streams can apply channel mixing on the incoming signal.
Normally the channel mixer is not used for devices, the device channels are usually exposed as they are. This policy is usually enforced by the session manager, so we refer to its documentation there.
Playback and capture streams are usually configured to the channel layout of the sink/source
they connect to and will thus perform channel mixing.
The channel mixer also implements a software volume. This volume adjustment is performed on the original
channel layout. ex: A stereo playback stream that is up-mixed to 5.1 has 2 a left an right volume control.
@PAR@ client.conf channelmix.disable = false
Disables the channel mixer completely. The stream will only be able to link to compatible
sources/sinks with the exact same channel layout.
@PAR@ client.conf channelmix.min-volume = 0.0
@PAR@ client.conf channelmix.max-volume = 10.0
Gives the min and max volume values allowed. Any volume that is set will be clamped to these
values.
@PAR@ client.conf channelmix.normalize = false
\parblock
Makes sure that during such mixing & resampling original 0 dB level is preserved, so nothing sounds wildly quieter/louder.
While this options prevents clipping, it can in some cases produce too low volume. Increase the
volume in that case or disable normalization.
\endparblock
@PAR@ client.conf channelmix.lock-volumes = false
Completely disable volume or mute changes. Defaults to false.
@PAR@ client.conf channelmix.mix-lfe = true
Mixes the low frequency effect channel into the front center or stereo pair. This might enhance the dynamic range of the signal if there is no subwoofer and the speakers can reproduce the low frequency signal.
@PAR@ client.conf channelmix.upmix = true
\parblock
Enables up-mixing of the front center (FC) when the target has a FC channel.
The sum of the stereo channels is used and an optional lowpass filter can be used
(see `channelmix.fc-cutoff`).
Also enabled up-mixing of LFE when `channelmix.lfe-cutoff` is set to something else than 0 and
the target has an LFE channel. The LFE channel is produced by adding the stereo channels.
If `channelmix.upmix` is true, the up-mixing of the rear channels is also enabled and controlled
with the `channelmix-upmix-method` property.
\endparblock
@PAR@ client.conf channelmix.upmix-method = psd
\parblock
3 methods are provided to produce the rear channels in a surround sound:
1. none. No rear channels are produced.
2. simple. Front channels are copied to the rear. This is fast but can produce phasing effects.
3. psd. The rear channels as produced from the front left and right ambient sound (the
difference between the channels). A delay and optional phase shift are added to the rear signal
to make the sound bigger.
\endparblock
@PAR@ client.conf channelmix.lfe-cutoff = 150
Apply a lowpass filter to the low frequency effects. The value is expressed in Hz. Typical subwoofers have a cutoff at around 150 and 200. The default value of 0 disables the feature.
@PAR@ client.conf channelmix.fc-cutoff = 12000
\parblock
Apply a lowpass filter to the front center frequency. The value is expressed in Hz.
Since the front center contains the dialogs, a typical cutoff frequency is 12000 Hz.
This option is only active when the up-mix is enabled.
\endparblock
@PAR@ client.conf channelmix.rear-delay = 12.0
\parblock
Apply a delay in milliseconds when up-mixing the rear channels. This improves
specialization of the sound. A typical delay of 12 milliseconds is the default.
This is only active when the `psd` up-mix method is used.
\endparblock
@PAR@ client.conf channelmix.stereo-widen = 0.0
\parblock
Subtracts some of the front center signal from the stereo channels. This moves the dialogs
more to the center speaker and leaves the ambient sound in the stereo channels.
This is only active when up-mix is enabled and a Front Center channel is mixed.
\endparblock
@PAR@ client.conf channelmix.hilbert-taps = 0
\parblock
This option will apply a 90 degree phase shift to the rear channels to improve specialization.
Taps needs to be between 15 and 255 with more accurate results (and more CPU consumption)
for higher values.
This is only active when the `psd` up-mix method is used.
\endparblock
@PAR@ client.conf dither.noise = 0
\parblock
This option will add N bits of random data to the signal. When no dither.method is
specified, the random data will flip between [-(1<<(N-1)), 0] every 1024 samples. With
a dither.method, the dither noise is amplified with 1<<(N-1) bits.
This can be used to keep some amplifiers alive during silent periods. One or two bits of noise is
usually enough, otherwise the noise will become audible. This is usually used together with
`session.suspend-timeout-seconds` to disable suspend in the session manager.
Note that PipeWire uses floating point operations with 24 bits precission for all of the audio
processing. Conversion to 24 bits integer sample formats is lossless and conversion to 32 bits
integer sample formats are simply padded with 0 bits at the end. This means that the dither noise
is always only in the 24 most significant bits.
\endparblock
@PAR@ client.conf dither.method = none
\parblock
Optional [dithering](https://en.wikipedia.org/wiki/Dither) can be done on the quantized
output signal.
There are 6 modes available:
1. none No dithering is done.
2. rectangular Dithering with a rectangular noise distribution. This adds random
bits in the [-0.5, 0.5] range to the signal with even distribution.
3. triangular Dithering with a triangular noise distribution. This add random
bits in the [-1.0, 1.0] range to the signal with triangular distribution
around 0.0.
4. triangular-hf Dithering with a sloped triangular noise distribution.
5. wannamaker3 Additional noise shaping is performed on the sloped triangular
dithering to move the noise to the more inaudible range. This is using
the "F-Weighted" noise filter described by Wannamaker.
6. shaped5 Additional noise shaping is performed on the triangular dithering
to move the noise to the more inaudible range. This is using the
Lipshitz filter.
Dithering is only useful for conversion to a format with less than 24 bits and will be
disabled otherwise.
\endparblock
## Debug Parameters
@PAR@ client.conf debug.wav-path = ""
Make the stream to also write the raw samples to a WAV file for debugging purposes.
## Format Properties
Streams and also most device nodes can be configured in a certain format with properties.
@PAR@ client.conf audio.rate = RATE
Forces a samplerate on the node.
@PAR@ client.conf audio.channels = INTEGER
The number of audio channels to use. Must be a value between 1 and 64.
@PAR@ client.conf audio.format = FORMAT
\parblock
Forces an audio format on the node. This is the format used internally in the node because the graph processing format is always float 32.
Valid formats include: S16, S32, F32, F64, S16LE, S16BE, ...
\endparblock
@PAR@ client.conf audio.allowed-rates
An array of allowed samplerates for the node. ex. "[ 44100 48000 ]"
A list of object properties that can be applied to streams can be found in
\ref props__common_node_properties "pipewire-props(7) Common Node Properties"
and
\ref props__audio_converter_properties "pipewire-props(7) Audio Adapter Properties"
# STREAM RULES @IDX@ client.conf
@ -557,9 +138,10 @@ stream.rules = [
Will set the node.name of Firefox to "My Name".
# ALSA PROPERTIES @IDX@ client.conf
# ALSA CLIENT PROPERTIES @IDX@ client.conf
An `alsa.properties` section can be added to configure ALSA specific client config.
An `alsa.properties` section can be added to configure client applications
that connect via the PipeWire ALSA plugin.
```css
alsa.properties = {
@ -596,7 +178,7 @@ The number of bytes in the alsa buffer. The default is 0, which is to allow any
This controls the volume curve used on the ALSA mixer. Possible values are `cubic` and
`linear`. The default is to use `cubic`.
# ALSA RULES @IDX@ client.conf
# ALSA CLIENT RULES @IDX@ client.conf
It is possible to set ALSA client specific properties by using
\ref pipewire_conf__match_rules "Match rules, see pipewire(1)". You can

518
doc/dox/config/pipewire-devices.7.md
View file

@ -1,518 +0,0 @@
\page page_man_pipewire-devices_7 pipewire-devices
PipeWire device and node property reference.
\tableofcontents
# DESCRIPTION
Audio sinks and sources, cameras, Bluetooth endpoints, and other
objects have properties that can be set in configuration files or at
runtime.
Some of the properties are "common object properties" (e.g. such as
`node.description`) and can be set on all types of devices and
nodes. Other properties control settings of a specific type of a
device (ALSA, Bluetooth, ...).
All the properties are usually configured in the session manager configuration.
For how to configure them, see the session manager documentation.
In minimal PipeWire setups without a session manager, they can be configured via
\ref pipewire_conf__context_objects "context.objects in pipewire.conf(5)".
# RUNTIME SETTINGS @IDX@ device-param
The settings of most ALSA and virtual device parameters can be
configured also at runtime.
The settings are available in device `Props` in the `params`
field. They can be seen e.g. using `pw-dump <id>` for an ALSA device:
```json
{
...
"Props": [
{
...
"params": [
"audio.channels",
2,
"audio.rate",
0,
"audio.format",
"UNKNOWN",
"audio.position",
"[ FL, FR ]",
"audio.allowed-rates",
"[ ]",
"api.alsa.period-size",
0,
"api.alsa.period-num",
0,
"api.alsa.headroom",
0,
"api.alsa.start-delay",
0,
"api.alsa.disable-mmap",
false,
"api.alsa.disable-batch",
false,
"api.alsa.use-chmap",
false,
"api.alsa.multi-rate",
true,
"latency.internal.rate",
0,
"latency.internal.ns",
0,
"clock.name",
"api.alsa.c-1"
]
}
...
```
One or more `params` can be changed using \ref page_man_pw-cli_1 "pw-cli(1)":
```
pw-cli s <id> Props '{ params = [ "api.alsa.headroom" 1024 ] }'
```
These settings are not saved and need to be reapplied for each session manager restart.
# COMMON NODE PROPERTIES @IDX@ device-param
The properties listed in \ref client_conf__stream_properties "Stream properties"
apply also to sink or source nodes corresponding to real or virtual devices.
In addition:
@PAR@ device-param priority.driver # integer
\parblock
The priority of choosing this device as the driver in the graph. The driver is selected from all linked devices by selecting the device with the highest priority.
Normally, the session manager assigns higher priority to sources so that they become the driver in the graph. The reason for this is that adaptive resampling should be done on the sinks rather than the source to avoid signal distortion when capturing audio.
\endparblock
@PAR@ device-param priority.session # integer
The priority for selecting this device as the default device.
@PAR@ device-param clock.name # string
\parblock
The name of the clock. This name is auto generated from the card index and stream direction. Devices with the same clock name will not use a resampler to align the clocks. This can be used to link devices together with a shared word clock.
In Pro Audio mode, nodes from the same device are assumed to have the same clock and no resampling will happen when linked together. So, linking a capture port to a playback port will not use any adaptive resampling in Pro Audio mode.
In Non Pro Audio profile, no such assumption is made and adaptive resampling is done in all cases by default. This can also be disabled by setting the same clock.name on the nodes.
\endparblock
@PAR@ device-param node.param.PARAM = JSON # JSON
\parblock
Set value of a node \ref spa_param_type "Param" to a JSON value when the device is loaded.
This works similarly as \ref page_man_pw-cli_1 "pw-cli(1)" `set-param` command.
The `PARAM` should be replaced with the name of the Param to set,
ie. for example `node.param.Props = { ... }` to set `Props`.
\endparblock
@PAR@ device-param device.id
ID of the device the node belongs to.
# COMMON DEVICE PROPERTIES @IDX@ device-param
These are common properties for devices.
@PAR@ device-param device.name # string
A (unique) name for the device. It can be used by command-line and other tools to identify the device.
@PAR@ device-param device.param.PARAM = JSON # JSON
\parblock
Set value of a device \ref spa_param_type "Param" to a JSON value when the device is loaded.
This works similarly as \ref page_man_pw-cli_1 "pw-cli(1)" `set-param` command.
The `PARAM` should be replaced with the name of the Param to set,
ie. for example `device.Param.Props = { ... }` to set `Props`.
\endparblock
Other `device.*` properties: UNDOCUMENTED
# AUDIO CONVERTER PROPERTIES @IDX@ device-param
Most audio nodes (ALSA, Bluetooth, ...) have common properties for the audio
converter. See \ref client_conf__stream_properties "pipewire-client.conf(5) stream.properties"
for explanations.
## Node properties
@PAR@ device-param clock.quantum-limit
\ref pipewire_conf__default_clock_quantum-limit "See pipewire.conf(5)"
@PAR@ device-param channelmix.disable
\ref client_conf__channelmix_disable "See pipewire-client.conf(5)"
@PAR@ device-param channelmix.min-volume
\ref client_conf__channelmix_min-volume "See pipewire-client.conf(5)"
@PAR@ device-param channelmix.max-volume
\ref client_conf__channelmix_max-volume "See pipewire-client.conf(5)"
@PAR@ device-param channelmix.normalize
\ref client_conf__channelmix_normalize "See pipewire-client.conf(5)"
@PAR@ device-param channelmix.mix-lfe
\ref client_conf__channelmix_mix-lfe "See pipewire-client.conf(5)"
@PAR@ device-param channelmix.upmix
\ref client_conf__channelmix_upmix "See pipewire-client.conf(5)"
@PAR@ device-param channelmix.lfe-cutoff
\ref client_conf__channelmix_lfe-cutoff "See pipewire-client.conf(5)"
@PAR@ device-param channelmix.fc-cutoff
\ref client_conf__channelmix_fc-cutoff "See pipewire-client.conf(5)"
@PAR@ device-param channelmix.rear-delay
\ref client_conf__channelmix_rear-delay "See pipewire-client.conf(5)"
@PAR@ device-param channelmix.stereo-widen
\ref client_conf__channelmix_stereo-widen "See pipewire-client.conf(5)"
@PAR@ device-param channelmix.hilbert-taps
\ref client_conf__channelmix_hilbert-taps "See pipewire-client.conf(5)"
@PAR@ device-param channelmix.upmix-method
\ref client_conf__channelmix_upmix-method "See pipewire-client.conf(5)"
@PAR@ device-param channelmix.lock-volumes
\ref client_conf__channelmix_lock-volumes "See pipewire-client.conf(5)"
@PAR@ device-param resample.quality
\ref client_conf__resample_quality "See pipewire-client.conf(5)"
@PAR@ device-param resample.disable
\ref client_conf__resample_disable "See pipewire-client.conf(5)"
@PAR@ device-param resample.peaks = false # boolean
Instead of actually resampling, produce peak amplitude values as output.
This is used for volume monitoring, where it is set as a property
of the "recording" stream.
@PAR@ device-param resample.prefill = false # boolean
Prefill resampler buffers with silence. This affects the initial
samples produced by the resampler.
@PAR@ device-param monitor.channel-volumes
\ref client_conf__monitor_channel-volumes "See pipewire-client.conf(5)"
@PAR@ device-param dither.noise
\ref client_conf__dither_noise "See pipewire-client.conf(5)"
@PAR@ device-param dither.method
\ref client_conf__dither_method "See pipewire-client.conf(5)"
@PAR@ device-param debug.wav-path
\ref client_conf__debug_wav-path "See pipewire-client.conf(5)"
@PAR@ device-param adapter.auto-port-config = null # JSON
\parblock
If specified, configure the ports of the node when it is created, instead of
leaving that to the session manager to do. This is useful (only) for minimal
configurations without a session manager.
Value is SPA JSON of the form:
```json
{
mode = "none", # "none", "passthrough", "convert", "dsp"
monitor = false, # boolean
control = false, # boolean
position = "preserve" # "unknown", "aux", "preserve"
}
```
See \ref spa_param_port_config for the meaning.
\endparblock
# ALSA PROPERTIES @IDX@ device-param
## Monitor properties
@PAR@ device-param alsa.use-acp # boolean
Use \ref device-param__alsa_card_profiles "ALSA Card Profiles" (ACP) for device configuration.
@PAR@ device-param alsa.udev.expose-busy # boolean
Expose the ALSA card even if it is busy/in use. Default false. This can be useful when some
of the PCMs are in use by other applications but the other free PCMs should still be exposed.
## Device properties
@PAR@ device-param api.alsa.path # string
ALSA device path as can be used in snd_pcm_open() and snd_ctl_open().
@PAR@ device-param api.acp.auto-port # boolean
Select reasonable port on device startup. Available for ACP devices.
@PAR@ device-param api.acp.auto-profile # boolean
Select reasonable profile on device startup. Available for ACP devices.
## Node properties
@PAR@ device-param audio.channels # integer
The number of audio channels to open the device with. Defaults depends on the profile of the device.
@PAR@ device-param audio.rate # integer
The audio rate to open the device with. Default is 0, which means to open the device with a rate as close to the graph rate as possible.
@PAR@ device-param audio.format # string
The audio format to open the device in. By default this is "UNKNOWN", which will open the device in the best possible bits (32/24/16/8..). You can force a format like S16_LE or S32_LE.
@PAR@ device-param audio.position # JSON array of strings
The audio position of the channels in the device. This is auto detected based on the profile. You can configure an array of channel positions, like "[ FL, FR ]".
@PAR@ device-param audio.allowed-rates # JSON array of integers
\parblock
The allowed audio rates to open the device with. Default is "[ ]", which means the device can be opened in any supported rate.
Only rates from the array will be used to open the device. When the graph is running with a rate not listed in the allowed-rates, the resampler will be used to resample to the nearest allowed rate.
\endparblock
@PAR@ device-param api.alsa.period-size # integer
The period size to open the device in. By default this is 0, which will open the device in the default period size to minimize latency.
@PAR@ device-param api.alsa.period-num # integer
The amount of periods to use in the device. By default this is 0, which means to use as many as possible.
@PAR@ device-param api.alsa.headroom # integer
The amount of extra space to keep in the ringbuffer. The default is 0. Higher values can be configured when the device read and write pointers are not accurately reported.
@PAR@ device-param api.alsa.start-delay # integer
Some devices require a startup period. The default is 0. Higher values can be set to send silence samples to the device first.
@PAR@ device-param api.alsa.disable-mmap # boolean
Disable mmap operation of the device and use the ALSA read/write API instead. Default is false, mmap is preferred.
@PAR@ device-param api.alsa.disable-batch # boolean
Ignore the ALSA batch flag. If the batch flag is set, ALSA will need an extra period to update the read/write pointers. Ignore this flag from ALSA can reduce the latency. Default is false.
@PAR@ device-param api.alsa.use-chmap # boolean
Use the driver provided channel map. Default is true when using UCM, false otherwise because many driver don't report this correctly.
@PAR@ device-param api.alsa.multi-rate # boolean
Allow devices from the same card to be opened in multiple sample rates. Default is true. Some older drivers did not properly advertise the capabilities of the device and only really supported opening the device in one rate.
@PAR@ device-param api.alsa.htimestamp = false # boolean
Use ALSA htimestamps in scheduling, instead of the system clock.
Some ALSA drivers produce bad timestamps, so this is not enabled by default
and will be disabled at runtime if it looks like the ALSA timestamps are bad.
@PAR@ device-param api.alsa.htimestamp.max-errors # integer
Specify the number of consecutive errors before htimestamp is disabled.
Setting this to 0 makes htimestamp never get disabled.
@PAR@ device-param api.alsa.disable-tsched = false # boolean
Disable timer-based scheduling, and use IRQ for scheduling instead.
The "Pro Audio" profile will usually enable this setting, if it is expected it works on the hardware.
@PAR@ device-param api.alsa.auto-link = false # boolean
Link follower PCM devices to the driver PCM device when using IRQ-based scheduling.
The "Pro Audio" profile will usually enable this setting, if it is expected it works on the hardware.
@PAR@ device-param latency.internal.rate # integer
Static set the device systemic latency, in samples at playback rate.
@PAR@ device-param latency.internal.ns # integer
Static set the device systemic latency, in nanoseconds.
@PAR@ device-param api.alsa.path # string
UNDOCUMENTED
@PAR@ device-param api.alsa.open.ucm # boolean
Open device using UCM.
@PAR@ device-param api.alsa.bind-ctls # boolean
UNDOCUMENTED
@PAR@ device-param iec958.codecs # JSON array of string
Enable only specific IEC958 codecs. This can be used to disable some codecs the hardware supports.
Available values: PCM, AC3, DTS, MPEG, MPEG2-AAC, EAC3, TRUEHD, DTSHD
# BLUETOOTH PROPERTIES @IDX@ device-param
## Monitor properties
The following are settings for the Bluetooth device monitor, not device or
node properties:
@PAR@ device-param bluez5.roles # JSON array of string
\parblock
Enabled roles (default: [ a2dp_sink a2dp_source bap_sink bap_source hfp_hf hfp_ag ])
Currently some headsets (Sony WH-1000XM3) are not working with
both hsp_ag and hfp_ag enabled, so by default we enable only HFP.
Supported roles:
- hsp_hs (HSP Headset),
- hsp_ag (HSP Audio Gateway),
- hfp_hf (HFP Hands-Free),
- hfp_ag (HFP Audio Gateway)
- a2dp_sink (A2DP Audio Sink)
- a2dp_source (A2DP Audio Source)
- bap_sink (LE Audio Basic Audio Profile Sink)
- bap_source (LE Audio Basic Audio Profile Source)
\endparblock
@PAR@ device-param bluez5.codecs # JSON array of string
Enabled A2DP codecs (default: all).
Possible values: sbc sbc_xq aac aac_eld aptx aptx_hd aptx_ll aptx_ll_duplex faststream faststream_duplex lc3plus_h3 ldac opus_05 opus_05_51 opus_05_71 opus_05_duplex opus_05_pro opus_g lc3
@PAR@ device-param bluez5.default.rate # integer
Default audio rate.
@PAR@ device-param bluez5.default.channels # integer
Default audio channels.
@PAR@ device-param bluez5.hfphsp-backend # integer
HFP/HSP backend (default: native). Available values: any, none, hsphfpd, ofono, native
@PAR@ device-param bluez5.hfphsp-backend-native-modem # string
@PAR@ device-param bluez5.dummy-avrcp player # boolean
Register dummy AVRCP player. Some devices have wrongly functioning
volume or playback controls if this is not enabled. Default: false
@PAR@ device-param bluez5.enable-sbc-xq # boolean
Override device quirk list and enable SBC-XQ for devices for which it is disabled.
@PAR@ device-param bluez5.enable-msbc # boolean
Override device quirk list and enable MSBC for devices for which it is disabled.
@PAR@ device-param bluez5.enable-hw-volume # boolean
Override device quirk list and enable hardware volume fo devices for which it is disabled.
@PAR@ device-param bluez5.hw-offload-sco # boolean
\parblock
HFP/HSP hardware offload SCO support (default: false).
This feature requires a custom configuration that routes SCO audio to ALSA nodes,
in a platform-specific way. See `tests/examples/bt-pinephone.lua` in WirePlumber for an example.
Do not enable this setting if you don't know what all this means, as it won't work.
\endparblock
@PAR@ device-param bluez5.a2dp.opus.pro.channels = 3 # integer
PipeWire Opus Pro audio profile channel count.
@PAR@ device-param bluez5.a2dp.opus.pro.coupled-streams = 1 # integer
PipeWire Opus Pro audio profile coupled stream count.
@PAR@ device-param bluez5.a2dp.opus.pro.locations = "FL,FR,LFE" # string
PipeWire Opus Pro audio profile audio channel locations.
@PAR@ device-param bluez5.a2dp.opus.pro.max-bitrate = 600000 # integer
PipeWire Opus Pro audio profile max bitrate.
@PAR@ device-param bluez5.a2dp.opus.pro.frame-dms = 50 # integer
PipeWire Opus Pro audio profile frame duration (1/10 ms).
@PAR@ device-param bluez5.a2dp.opus.pro.bidi.channels = 1 # integer
PipeWire Opus Pro audio profile duplex channels.
@PAR@ device-param bluez5.a2dp.opus.pro.bidi.coupled-streams = 0 # integer
PipeWire Opus Pro audio profile duplex coupled stream count.
@PAR@ device-param bluez5.a2dp.opus.pro.bidi.locations = "FC" # string
PipeWire Opus Pro audio profile duplex coupled channel locations.
@PAR@ device-param bluez5.a2dp.opus.pro.bidi.max-bitrate = 160000 # integer
PipeWire Opus Pro audio profile duplex max bitrate.
@PAR@ device-param bluez5.a2dp.opus.pro.bidi.frame-dms = 400 # integer
PipeWire Opus Pro audio profile duplex frame duration (1/10 ms).
@PAR@ device-param bluez5.bcast_source.config # JSON
\parblock
Example:
```
bluez5.bcast_source.config = [
{
"broadcast_code": "Børne House",
"encryption: false,
"bis": [
{ # BIS configuration
"qos_preset": "16_2_1", # QOS preset name from table Table 6.4 from BAP_v1.0.1.
"audio_channel_allocation": 1, # audio channel allocation configuration for the BIS
"metadata": [ # metadata configurations for the BIS
{ "type": 1, "value": [ 1, 1 ] }
]
}
]
}
]
```
\endparblock
## Device properties
@PAR@ device-param bluez5.auto-connect # boolean
Auto-connect devices on start up. Disabled by default if
the property is not specified.
@PAR@ device-param bluez5.hw-volume = [ PROFILE1 PROFILE2... ] # JSON array of string
Profiles for which to enable hardware volume control (default: [ hfp_ag hsp_ag a2dp_source ]).
@PAR@ device-param bluez5.profile # string
Initial device profile. This usually has no effect as the session manager
overrides it.
@PAR@ device-param bluez5.a2dp.ldac.quality # string
LDAC encoding quality
Available values:
- auto (Adaptive Bitrate, default)
- hq (High Quality, 990/909kbps)
- sq (Standard Quality, 660/606kbps)
- mq (Mobile use Quality, 330/303kbps)
@PAR@ device-param bluez5.a2dp.aac.bitratemode # integer
AAC variable bitrate mode.
Available values: 0 (cbr, default), 1-5 (quality level)
@PAR@ device-param bluez5.a2dp.opus.pro.application = "audio" # string
PipeWire Opus Pro Audio encoding mode: audio, voip, lowdelay
@PAR@ device-param bluez5.a2dp.opus.pro.bidi.application = "audio" # string
PipeWire Opus Pro Audio duplex encoding mode: audio, voip, lowdelay
@PAR@ device-param bluez5.bap.cig = auto # integer, or 'auto'
Set CIG ID for BAP unicast streams of the device.
Default: "auto" (automatic).
## Node properties
@PAR@ device-param bluez5.media-source-role # string
\parblock
Media source role for Bluetooth clients connecting to
this instance. Available values:
- playback: playing stream to speakers
- input: appear as source node.
\endparblock
# ALSA CARD PROFILES @IDX@ device-param
The sound card profiles ("Analog stereo", "Analog stereo duplex", ...) except "Pro Audio" come from two sources:
- UCM: ALSA Use Case Manager: the profile configuration system from ALSA. See https://github.com/alsa-project/alsa-ucm-conf/
- ACP ("Alsa Card Profiles"): Pulseaudio's profile system ported to PipeWire. See https://www.freedesktop.org/wiki/Software/PulseAudio/Backends/ALSA/Profiles/
See the above links on how to configure these systems.
For ACP, PipeWire looks for the profile configuration files under
- ~/.config/alsa-card-profile
- /etc/alsa-card-profile
- /usr/share/alsa-card-profile/mixer`.
The `path` and `profile-set` files are in subdirectories `paths` and `profile-sets` of these directories.
It is possible to override individual files locally by putting a modified copy into the ACP directories under `~/.config` or `/etc`.
# AUTHORS
The PipeWire Developers <$(PACKAGE_BUGREPORT)>;
PipeWire is available from <$(PACKAGE_URL)>
# SEE ALSO
\ref page_man_pipewire_conf_5 "pipewire.conf(5)"

1073
doc/dox/config/pipewire-props.7.md Normal file
View file

File diff suppressed because it is too large Load diff

2
doc/meson.build
View file

@ -88,7 +88,7 @@ manpage_docs = [
'dox/config/pipewire.conf.5.md',
'dox/config/pipewire-client.conf.5.md',
'dox/config/pipewire-jack.conf.5.md',
'dox/config/pipewire-devices.7.md',
'dox/config/pipewire-props.7.md',
'dox/config/pipewire-filter-chain.conf.5.md',
'dox/config/pipewire-pulse-modules.7.md',
'dox/config/libpipewire-modules.7.md',