... | ... | @@ -24,15 +24,237 @@ stream.properties = { |
|
|
#resample.quality = 4
|
|
|
#channelmix.normalize = true
|
|
|
#channelmix.mix-lfe = false
|
|
|
#channelmix.upmix = false
|
|
|
#channelmix.upmix = true
|
|
|
#channelmix.upmix-method = psd # none, simple
|
|
|
#channelmix.lfe-cutoff = 120
|
|
|
#channelmix.fc-cutoff = 6000
|
|
|
#channelmix.lfe-cutoff = 150
|
|
|
#channelmix.fc-cutoff = 12000
|
|
|
#channelmix.rear-delay = 12.0
|
|
|
#channelmix.stereo-widen = 0.1
|
|
|
#channelmix.stereo-widen = 0.0
|
|
|
#channelmix.hilbert-taps = 0
|
|
|
}
|
|
|
```
|
|
|
Some of the properties refer to different aspects of the stream:
|
|
|
|
|
|
* General stream properties to identify the stream
|
|
|
* General stream properties to classify the stream
|
|
|
* How it is going to be scheduled by the graph
|
|
|
* How it is going to be linked by the session manager
|
|
|
* How the internal processing will be done.
|
|
|
* Properties to configure the media format
|
|
|
|
|
|
### Identifying properties
|
|
|
|
|
|
These contain properties to identify the node or to display the node in a GUI application.
|
|
|
|
|
|
```
|
|
|
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.
|
|
|
|
|
|
|
|
|
```
|
|
|
node.description
|
|
|
```
|
|
|
A human readable description of the node or stream.
|
|
|
|
|
|
```
|
|
|
media.name
|
|
|
media.title
|
|
|
media.artist
|
|
|
```
|
|
|
A user readable media name, usually the artist and title. These are usually shown in use facing applications
|
|
|
to inform the user about the current playing media.
|
|
|
|
|
|
Other media properties exist such as copyright and icon.
|
|
|
|
|
|
### Classifying properties
|
|
|
|
|
|
The clasifying properties of a node are use for routing the signal to its destination and
|
|
|
for configuring the settings.
|
|
|
|
|
|
```
|
|
|
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"
|
|
|
|
|
|
```
|
|
|
media.category
|
|
|
```
|
|
|
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.
|
|
|
|
|
|
|
|
|
```
|
|
|
media.role
|
|
|
```
|
|
|
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
|
|
|
|
|
|
```
|
|
|
media.class
|
|
|
```
|
|
|
The media class is to clasify 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 manage assigns special meaning to the nodes based on the media.class. Sink or Source
|
|
|
classes are used as targets for Stream classes, etc..
|
|
|
|
|
|
|
|
|
### Scheduling properties
|
|
|
|
|
|
```
|
|
|
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.
|
|
|
|
|
|
|
|
|
```
|
|
|
node.lock-quantum = false
|
|
|
```
|
|
|
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.
|
|
|
|
|
|
|
|
|
```
|
|
|
node.force-quantum = <quantum>
|
|
|
```
|
|
|
While the node is active, force a quantum in the graph. The last node to be activated with this property wins.
|
|
|
|
|
|
```
|
|
|
node.rate = <rate>
|
|
|
```
|
|
|
Suggest a rate (samplerate) for the graph. The suggested rate will only be applied when doing so would not cause
|
|
|
interuptions (devices are idle) and when the rate is in the list of allowed rates in the server.
|
|
|
|
|
|
```
|
|
|
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.
|
|
|
|
|
|
```
|
|
|
node.force-rate = <rate>
|
|
|
```
|
|
|
When the node is active, force a specific sample rate on the graph. The last node to activate with this property wins.
|
|
|
|
|
|
```
|
|
|
node.always-process = false
|
|
|
```
|
|
|
When the node is active, it will always be joined with a driver node, even when nothing is linked to the node.
|
|
|
|
|
|
This is the default for JACK nodes, that always need their process callback called.
|
|
|
|
|
|
```
|
|
|
node.pause-on-idle = false
|
|
|
node.suspend-on-idle = false
|
|
|
```
|
|
|
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.
|
|
|
|
|
|
|
|
|
### Session manager properties
|
|
|
|
|
|
```
|
|
|
node.autoconnect = true
|
|
|
```
|
|
|
Instructs the session manager to automatically connect this node to some other node, usually
|
|
|
a sink or source.
|
|
|
|
|
|
```
|
|
|
node.exclusive = false
|
|
|
```
|
|
|
If this node wants to be linked exclusively to the sink/source.
|
|
|
|
|
|
```
|
|
|
node.target =
|
|
|
```
|
|
|
Where this node should be linked to. This can be a node.name or an object.id of a node.
|
|
|
|
|
|
```
|
|
|
node.dont-reconnect = false
|
|
|
```
|
|
|
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.
|
|
|
|
|
|
```
|
|
|
node.passive = false
|
|
|
```
|
|
|
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.
|
|
|
|
|
|
```
|
|
|
node.link-group = <id>
|
|
|
```
|
|
|
Add the node to a certain link group. Nodes from the same link group are not automatically linked to eachother by the session manager. And example is a coupled stream where you don't want the ouput to link to the input streams, making a useless loop.
|
|
|
|
|
|
```
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
|
|
### Adapter properties
|
|
|
|
|
|
An audio stream (and also audio device nodes) contain an audio adapter that can perform,
|
|
|
sample format, sample rate and channelmixing operations.
|
|
|
|
|
|
#### Merger properties
|
|
|
|
|
|
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.
|
|
|
|
|
|
```
|
|
|
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 properties
|
|
|
|
|
|
Source, sinks, capture and playback streams contain a high quality adaptive resampler.
|
|
|
It uses sinc 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.
|
|
|
|
... | ... | @@ -41,7 +263,9 @@ Below is an explanation of the options that can be tuned in the sample converter |
|
|
````
|
|
|
resample.quality = 4
|
|
|
````
|
|
|
The resampler quality in use. This is a value between 0 and 14 with 14 the highest quality.
|
|
|
The quality of the resampler. from 0 to 14, the default is 4.
|
|
|
|
|
|
You can check some of the resampler qualities [here](https://src.infinitewave.ca/). Note that the results for 4 and 10 are using the old filters and are significantly better in newer PipeWire versions.
|
|
|
|
|
|
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
|
... | ... | @@ -49,9 +273,37 @@ between quality and performance with no artifacts that are well below the audibl |
|
|
|
|
|
See [Infinite Wave](https://src.infinitewave.ca/) for a comparison of the performance.
|
|
|
|
|
|
````
|
|
|
resample.disable = false
|
|
|
````
|
|
|
|
|
|
Disable the resampler entirely. The node will only be able to negotiate with the graph
|
|
|
when the samplerates are compatible.
|
|
|
|
|
|
|
|
|
#### channelmixer properties
|
|
|
|
|
|
Source, sinks, capture and playback streams can apply channelmixing on the incoming signal.
|
|
|
|
|
|
Normally the channelmixer 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 channelmixing.
|
|
|
|
|
|
The channelmixer also implement a software volume. This volume adjustment is performed on the original
|
|
|
channel layout. ex: A stereo playback stream that is upmixed to 5.1 has 2 a left an right volume control.
|
|
|
|
|
|
|
|
|
````
|
|
|
channelmix.disable = false
|
|
|
````
|
|
|
|
|
|
Disables the channelmixer completely. The stream will only be able to link to compatible
|
|
|
sources/sinks with the exact same channel layout.
|
|
|
|
|
|
|
|
|
````
|
|
|
channelmix.normalize
|
|
|
channelmix.normalize = false
|
|
|
````
|
|
|
Makes sure that during such mixing & resampling original 0 dB level is preserved, so nothing sounds wildly quieter/louder.
|
|
|
|
... | ... | @@ -59,25 +311,26 @@ While this options prevents clipping, it can in some cases produce too low volum |
|
|
volume in that case or disable normalization.
|
|
|
|
|
|
````
|
|
|
channelmix.mix-lfe
|
|
|
channelmix.mix-lfe = false
|
|
|
````
|
|
|
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.
|
|
|
|
|
|
````
|
|
|
channelmix.upmix
|
|
|
channelmix.upmix = true
|
|
|
````
|
|
|
Upmixing of the front center (FC) is always performed when the target has a FC channel.
|
|
|
|
|
|
Enables upmixing 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`).
|
|
|
|
|
|
Upmixing of LFE is always done when `channelmix.lfe-cutoff` is set to something else than 0 and
|
|
|
Also enabled upmixing 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 upmixing of the rear channels is enabled and controlled
|
|
|
If `channelmix.upmix` is true, the upmixing of the rear channels is also enabled and controlled
|
|
|
with the `channelmix-upmix-method` property.
|
|
|
|
|
|
````
|
|
|
channelmix.upmix-method
|
|
|
channelmix.upmix-method = psd
|
|
|
````
|
|
|
|
|
|
3 method are provided to procude the rear channels in a surround sound:
|
... | ... | @@ -91,18 +344,18 @@ difference between the channels). A delay and optional phase shift are added to |
|
|
to make the sound bigger.
|
|
|
|
|
|
````
|
|
|
channelmix.lfe-cutoff = 120
|
|
|
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.
|
|
|
|
|
|
```
|
|
|
channelmix.fc-cutoff = 6000
|
|
|
channelmix.fc-cutoff = 12000
|
|
|
```
|
|
|
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 6000 Hz.
|
|
|
Since the front center contains the dialogs, a typical cutoff frequency is 12000 Hz.
|
|
|
|
|
|
This option is only active when the PSD upmix method is used.
|
|
|
This option is only active when the upmix is enabled.
|
|
|
|
|
|
```
|
|
|
channelmix.rear-delay = 12.0
|
... | ... | @@ -114,13 +367,13 @@ spacialization of the sound. A typical delay of 12 milliseconds is the default. |
|
|
This is only active when the psd upmix-method is used.
|
|
|
|
|
|
```
|
|
|
channelmix.stereo-widen = 0.1
|
|
|
channelmix.stereo-widen = 0.0
|
|
|
```
|
|
|
|
|
|
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 the psd upmix-method is used.
|
|
|
This is only active when upmix is enabled and a Front Center channel is mixed.
|
|
|
|
|
|
```
|
|
|
channelmix.hilbert-taps = 0
|
... | ... | @@ -131,4 +384,31 @@ for higher values. |
|
|
|
|
|
This is only active when the psd upmix-method is used.
|
|
|
|
|
|
### Format properties
|
|
|
|
|
|
Streams and also most device nodes can be configured in a certain format with properties.
|
|
|
|
|
|
```
|
|
|
audio.rate = <rate>
|
|
|
```
|
|
|
Forces a samplerate on the node.
|
|
|
|
|
|
```
|
|
|
audio.channels =
|
|
|
```
|
|
|
The number of audio channels to use. Must be a value between 1 and 64.
|
|
|
|
|
|
```
|
|
|
audio.format =
|
|
|
```
|
|
|
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, ...
|
|
|
|
|
|
```
|
|
|
audio.allowed-rates
|
|
|
```
|
|
|
An array of allowed samplerates for the node. ex. "[ 44100 48000 ]"
|
|
|
|
|
|
|
|
|
# Streams |