Debian Codegraph @

docs/rst/daemon/multi_instance.rst

raw
1 .. _daemon_multi_instance:
2
3 Running multiple instances
4 ==========================
5
6 WirePlumber has the ability to run either as a single instance daemon or as
7 multiple instances, meaning that there can be multiple processes, each one
8 doing a different task.
9
10 The most common use case for such a setup is to separate the graph orchestration
11 tasks from the device monitoring and object creation ones. This can be useful
12 for robustness and security reasons, as it allows restarting the device monitors
13 or running them in different security contexts without affecting the rest of the
14 session management functionality.
15
16 To achieve a multi-instance setup, WirePlumber can be started multiple times
17 with a different :ref:`profile<config_components_and_profiles>` loaded in each
18 instance. This can be achieved using the ``--profile`` command line option to
19 select the profile to load:
20
21 .. code-block:: console
22
23 $ wireplumber --profile=custom
24
25 When no particular profile is specified, the ``main`` profile is loaded.
26
27 For multi-instance configuration, the default ``wireplumber.conf`` specifies 4
28 profiles:
29
30 .. describe:: policy
31
32 This profile runs all the policy scripts, i.e. ones that monitor changes
33 in the graph and execute actions to link nodes, select default devices,
34 create new nodes or configure existing ones differently.
35
36 .. describe:: audio
37
38 The audio profile runs the ALSA and ALSA MIDI monitors, which make audio &
39 MIDI devices available to PipeWire.
40
41 .. describe:: bluetooth
42
43 The bluetooth profile runs the BlueZ and BlueZ MIDI monitors, which enable
44 Bluetooth audio & MIDI devices and other Bluetooth functionality tied to the
45 A2DP, HSP, HFP and BAP profiles, using BlueZ.
46
47 .. describe:: video-capture
48
49 The video-capture profile runs the V4L2 and libcamera monitors, which make
50 video capture devices, such as cameras and HDMI capture cards, available
51 to PipeWire.
52
53 .. note::
54
55 The ``main`` profile includes all the functionality of the ``policy``,
56 ``audio``, ``video-capture`` and ``bluetooth`` profiles combined (i.e. it is
57 the default for a standard single instance configuration). You should never
58 load the ``main`` profile alongside these other 4 profiles, as their
59 functionality will conflict.
60
61 .. warning::
62
63 Always ensure that the instances you load serve a different purpose and they
64 do not conflict with each other. Conflicting components executed in parallel
65 will have undefined behavior.
66
67 Systemd integration
68 -------------------
69
70 To make this easier to work with, a template systemd unit is provided, which is
71 meant to be started with the name of the profile as a template argument:
72
73 .. code-block:: console
74
75 $ systemctl --user disable wireplumber # disable the "main" profile instance
76 $ systemctl --user enable wireplumber@policy
77 $ systemctl --user enable wireplumber@audio
78 $ systemctl --user enable wireplumber@video-capture
79 $ systemctl --user enable wireplumber@bluetooth
80
81 .. note::
82
83 In WirePlumber 0.4, the template argument was the name of the configuration
84 file to load, since profiles did not exist. In WirePlumber 0.5, the template
85 argument is the name of the profile and the configuration file is always
86 ``wireplumber.conf``. To change the name of the configuration file you need
87 to craft custom systemd unit files and use the ``--config-file`` command line
88 option as needed.