|
|
[[_TOC_]]
|
|
|
|
|
|
# General
|
|
|
|
|
|
The session manager is the central part of a PipeWire setup. It is responsible for detecting, creating and configuring the devices in the system.
|
|
|
|
|
|
It is also responsible for implementing a policy that routes streams to the right destination as well as restoring their previous volume and other settings.
|
|
|
|
|
|
PipeWire ships with a simple session manager, called `pipewire-media-session`. It is a testbed for the various features in PipeWire. A more advanced session manager can be found in WirePlumber.
|
|
|
|
|
|
The session manager uses modules to activate a specific functionality. Modules are grouped into bundles. There is, for example, a 'with-audio' bundle that activates all audio related modules.
|
|
|
|
|
|
# Configuration File (`media-session.conf`)
|
|
|
|
|
|
The `pipewire-media-session` configuration template file is located in `/usr/share/pipewire/media-session.d/media-session.conf`. You can copy and edit the file to `/etc/pipewire/` or `~/.config/pipewire/media-session.d/media-session.conf`.
|
|
|
|
|
|
## `context.properties`
|
|
|
|
|
|
In addition to the generic [client](Config-client) properties, the media session has the following properties:
|
|
|
|
|
|
```
|
|
|
alsa.seq.name = "Midi-Bridge"
|
|
|
```
|
|
|
You can use this property to rename the ALSA sequencer node generated by the `alsa-seq` module. Setting this to `a2j` might improve compatibility with JACK applications at the cost of less readability for other applications.
|
|
|
|
|
|
## `context.spa-libs`
|
|
|
|
|
|
The session manager will be making most devices, so the session manager should include the spa-libs mapping for the audio, video and Bluetooth devices and nodes.
|
|
|
|
|
|
## `context.modules`
|
|
|
|
|
|
The session manager needs to include the standard [client](Config-client) modules in addition to the `libpipewire-module-client-device` and `libpipewire-module-metadata`.
|
|
|
|
|
|
## `session.modules`
|
|
|
|
|
|
The session.modules section is an object that contains the various module bundles.
|
|
|
|
|
|
Each module bundle has a name and an array of modules that it contains. There is a default bundle that is always activated. Other bundles are only activated when an (empty) file with the same name is found in the config directory.
|
|
|
|
|
|
Below is a list of modules and what they do:
|
|
|
|
|
|
### flatpak
|
|
|
|
|
|
This module manages flatpak access. It listens for new clients that are connected and configures the permissions on it when it has the `pipewire.access = flatpak` property.
|
|
|
|
|
|
The pipewire.access property is usually set by the `libpipewire-module-access` module in the pipewire daemon when a new client connects. A client will then be frozen until permissions are configured on it.
|
|
|
|
|
|
### portal
|
|
|
|
|
|
This module tracks the Portal pid on DBus and grants client created by the portal the right permissions.
|
|
|
|
|
|
### v4l2
|
|
|
|
|
|
Monitors v4l2 devices on udev and creates Device and Node objects for them.
|
|
|
|
|
|
### libcamera
|
|
|
|
|
|
Monitor libcamera devices on udev and creates Device and Node objects for them.
|
|
|
|
|
|
### suspend-node
|
|
|
|
|
|
Suspends nodes that have been in the IDLE state for a certain amount of time. By default it leaves them 3 seconds in IDLE before sending the Suspend command.
|
|
|
|
|
|
Individual nodes can have custom suspend behaviour by setting the `session.suspend-timeout-seconds` property. See [here](https://gitlab.freedesktop.org/pipewire/pipewire/-/wikis/Config-ALSA#node-properties).
|
|
|
|
|
|
### policy-node
|
|
|
|
|
|
This module tracks Node and performs the following tasks:
|
|
|
|
|
|
1. Configure the Sink/Source node adapter. This configures the Node with the right kind of ports.
|
|
|
|
|
|
2. Tracks the default Sink/Source nodes and maintains the `default.*.source` and `default.*.sink` metadata.
|
|
|
|
|
|
3. Tracks new Streams, decides where to link them to, configures them and links them.
|
|
|
|
|
|
4. Relinks streams when default nodes are changed.
|
|
|
|
|
|
5. Tracks metadata and moves streams when their metadata changes.
|
|
|
|
|
|
### metadata
|
|
|
|
|
|
Exports the `default` metadata object. It contains the default source and sink nodes as well as the place where streams can be moved.
|
|
|
|
|
|
It also contains the metadata used by the JACK API.
|
|
|
|
|
|
### default-nodes
|
|
|
|
|
|
It loads and saves the `default-nodes` session state, found in `~/.config/pipewire/media-session.d/default-nodes`. It tracks the availability of those nodes and places them in the `default` metadata with the `default.configured.*` keys.
|
|
|
|
|
|
### default-profile
|
|
|
|
|
|
Loads and saves the `default-profile` session state file found in `~/.config/pipewire/media-session.d/default-profile`.
|
|
|
|
|
|
It tracks the Profile param of Devices and tries to restore a previously saved profile or otherwise the best available profile.
|
|
|
|
|
|
When the user changes the Profile in for example pavucontrol, this module will save the new profile in the state file.
|
|
|
|
|
|
|
|
|
### default-routes
|
|
|
|
|
|
Loads and saves the `default-routes` session state file found in `~/.config/pipewire/media-session.d/default-routes`.
|
|
|
|
|
|
It tracks the Device Route param and tries to restore a previously saved setting. This includes restoring the routes associated with a profile as well as their settings such as the configured volume and mute state.
|
|
|
|
|
|
This module is responsible for detecting when jacks are plugged and unplugged and updates the route associated with this.
|
|
|
|
|
|
When the volume of a route is changed, this module will save the volume setting in the state file.
|
|
|
|
|
|
### streams-follow-default
|
|
|
|
|
|
This module simply enables the feature to make policy-node follow the default sink/source when it changes.
|
|
|
|
|
|
### alsa-seq
|
|
|
|
|
|
Loads and starts the ALSA sequencer Node that will handle midi ports and devices.
|
|
|
|
|
|
### alsa-monitor
|
|
|
|
|
|
Monitors ALSA devices on udev and creates Device and Node objects for them.
|
|
|
|
|
|
The alsa-monitor module has additional configuration options [here](https://gitlab.freedesktop.org/pipewire/pipewire/-/wikis/Config-ALSA).
|
|
|
|
|
|
### bluez5
|
|
|
|
|
|
This module loads the bluez5 module to monitor bluetooth devices. It creates Devices and Nodes for connected devices.
|
|
|
|
|
|
The bluez5 module has additional configuration options [here](https://gitlab.freedesktop.org/pipewire/pipewire/-/wikis/Config-Bluetooth).
|
|
|
|
|
|
### restore-stream
|
|
|
|
|
|
Loads and saves the `restore-stream` session state file found in `~/.config/pipewire/media-session.d/restore-stream`.
|
|
|
|
|
|
The module tracks streams and tries to restore the volume and preferred sink/source based on the name/role/application of the stream.
|
|
|
|
|
|
It also manages the `route-settings` metadata object. Any changes made to the metadata are written to the state file. This is how pavucontrol updates the volume settings of Notification sounds.
|
|
|
|
|
|
### logind
|
|
|
|
|
|
Uses systemd sd-login to track the state of the current seat.
|
|
|
|
|
|
This is mainly used by the bluez5 module to load and unload the bluetooth monitor because bluez5 only allows one user to register the bluetooth services.
|
|
|
|
|
|
# Matching Rules
|
|
|
|
|
|
Some modules can make use of the matching rules feature of `pipewire-media-session`.
|
|
|
|
|
|
Objects created by the session manager can be matched by their properties, using regular expressions. It is then possible to perform some actions on the selected object, like setting properties.
|
|
|
|
|
|
Rules are added in the various module configuration files (for example in alsa-monitor.conf and v4l2-monitor.conf) by adding a `rules = []` section to the config file. We can best show this with a simple example:
|
|
|
|
|
|
```
|
|
|
rules = [
|
|
|
{
|
|
|
matches = [
|
|
|
{
|
|
|
device.name = "my-very-special-device"
|
|
|
}
|
|
|
]
|
|
|
actions = {
|
|
|
update-props = {
|
|
|
device.nick = "My Device"
|
|
|
}
|
|
|
}
|
|
|
}
|
|
|
]
|
|
|
```
|
|
|
This array has 1 rule. It has one matches section that matches the device.name of an object to the given string "my-very-special-device".
|
|
|
|
|
|
For each object where the match is successful, the actions section is evaluated. There we have one action to update the object properties, we set device.nick to "My Device".
|
|
|
|
|
|
## AND Matching
|
|
|
|
|
|
It's possible to make more complicated match rules, for example:
|
|
|
|
|
|
```
|
|
|
matches = [
|
|
|
{
|
|
|
device.name = "my-very-special-device"
|
|
|
device.bus = pci
|
|
|
}
|
|
|
]
|
|
|
```
|
|
|
This will match objects with both device.name *AND* device.bus equal to the given values.
|
|
|
|
|
|
## OR Matching
|
|
|
|
|
|
Likewise you can add another object in the matches array :
|
|
|
```
|
|
|
matches = [
|
|
|
{
|
|
|
device.name = "my-very-special-device"
|
|
|
}
|
|
|
{
|
|
|
device.name = "my-other-device"
|
|
|
}
|
|
|
]
|
|
|
```
|
|
|
This will match any object with device.name equal to "my-very-special-device" *OR* "my-other-device".
|
|
|
|
|
|
## Regex Matching
|
|
|
|
|
|
By prefixing the match value with `~`, the object values will be matched against the regex following the `~`. For example:
|
|
|
|
|
|
```
|
|
|
matches = [
|
|
|
{
|
|
|
device.name = "~.*pci.*"
|
|
|
}
|
|
|
]
|
|
|
```
|
|
|
Matches all objects that have the string `pci` in their device.name property.
|
|
|
|
|
|
## `update-props` Action
|
|
|
|
|
|
`update-props` will simply update the properties of the object with the given properties. You can use this to mark certain objects (and make other match rules match) or to configure it in some way.
|
|
|
|
|
|
Setting a property value to `null` will remove the property from the object. |