1 files changed, 105 insertions, 0 deletions
diff --git a/debian/pipewire.README.Debian b/debian/pipewire.README.Debian
new file mode 100644
index 0000000..fe908f2
--- /dev/null
+++ b/debian/pipewire.README.Debian
@@ -0,0 +1,105 @@
+Using pipewire for audio
+========================
+
+pipewire in Debian was initially used for video (screen sharing and remote
+desktop, particularly in GNOME and KDE Wayland sessions). However, it has
+matured enough to also be used for audio.
+
+
+Using pipewire as a substitute for PulseAudio
+---------------------------------------------
+
+Install the pipewire-pulse package and log back in.
+And potentially install the new recommended session manager
+wireplumber instead of the deprecated pipewire-media-session.
+
+PipeWire project recommends [1] to remove the pulseaudio package to prevent
+conflicts in some cases [2] even if both pulseaudio and pipewire-pulse
+services are not running at the same time.
+pipewire-pulse doesn't conflict with pulseaudio at the package level to allow
+users to switch from one to the other just by disabling/enabling services.
+
+[1] https://gitlab.freedesktop.org/pipewire/pipewire/-/wikis/FAQ#should-i-uninstall-everything-pulseaudio
+[2] https://bugs.debian.org/1013276
+
+
+Using pipewire with Bluetooth
+---------------------------------------------
+
+Install the libspa-0.2-bluetooth package to add Bluetooth support to pipewire.
+
+Please note that AAC codec support is currently disabled due to license issue.
+See https://bugs.debian.org/981285
+
+Pipewire (nor any other package) does not depend or recommend libspa-0.2-bluetooth
+as not all users are interested in Bluetooth support.
+The same apply to pulseaudio and pulseaudio-module-bluetooth:
+pulseaudio does not depend or recommend pulseaudio-module-bluetooth.
+
+However, pulseaudio-module-bluetooth and libspa-0.2-bluetooth are installed on
+a system through the dependency of a Desktop Environment. For example,
+with GNOME, the bluetooth plugin is pulled by the meta package gnome-core.
+
+Moreover, both pipewire-pulse and wireplumber packages already suggest
+to install the libspa-0.2-bluetooth package.
+
+
+Using pipewire as the default ALSA output device
+------------------------------------------------
+
+Install the pipewire-alsa package.
+
+ALSA clients will output via pipewire instead of PulseAudio or directly to
+ALSA.
+
+pipewire-alsa conflicts with pulseaudio because both try to take control of
+all ALSA devices and redirect all audio streams to them. But, because of their
+respective configs files name:
+- PipeWire:	/etc/alsa/conf.d/99-pipewire-default.conf
+- PulseAudio:	/etc/alsa/conf.d/99-pulse.conf
+which make PulseAudio ordered after PipeWire. PulseAudio will take the
+final control of ALSA clients even when pipewire-alsa is installed. Thus,
+to allow ALSA clients redirecting output to pipewire, pulseaudio package
+needs to be removed.
+
+To check where streams are redirected, run the following command:
+$ aplay -L | grep -A 1 default
+
+
+Using pipewire as a substitute for JACK
+---------------------------------------
+
+Install the pipewire-jack package.
+
+JACK clients can be configured to output via pipewire instead of JACK.
+
+To enable this:
+
+* either run JACK clients using the pw-jack(1) wrapper, or copy
+  /usr/share/doc/pipewire/examples/ld.so.conf.d/pipewire-jack-*.conf
+  into /etc/ld.so.conf.d/ and run ldconfig as root.
+
+
+Setting pipewire real-time priority limits
+---------------------------------------
+
+!!!  WARNING  !!!
+Your system has real-time priority limits for a good reason. This allows it
+to remain stable in case a process goes crazy. RTKit allows limited use of
+real-time priority without the risk of locking up the system if a real-time
+task starts spinning.
+Some upstream recommendations for real-time are to increase these limits to
+bypass RTKit or to disable most of its safeguards. By following them, your
+system could be blocked if a process goes wrong.
+These performance tweaks are not needed for a normal use of pipewire, instead
+modifying pipewire configuration is enough.
+!!!  WARNING  !!!
+
+The "pipewire" package creates a system group called "pipewire".
+The upstream recommended priority limits for this group are defined in:
+
+* /etc/security/limits.d/95-pipewire.conf
+
+To enable these limits for your user, add it to the "pipewire" group.
+
+* sudo adduser yourusername pipewire