PIPEWIRE -- audio

> **Source:** https://wiki.debian.org/PipeWire

Package `pipewire` can be used to replace `pulseaudio`.

Additionally, package `pipewire-audio-client-libraries` allow applications that access `jack` or `alsa` directly to output via the `pipewire` server!

This allows harmonious interoperability between different sound servers.

> **Attention:**
> `pipewire` on Debian 11 is not yet ready (I tested it), so we should avoid it if possible. Therefore we will only install it so that we can use web screen sharing and that is it! At this point we should not yet use it as a replacement for `pulseaudio`, `alsa`, `jack` and `bluez`.

## Installation

Install the main `pipewire` package:

```
sudo apt install pipewire libpipewire-0.3-0
```

Install the packages needed on `sway` *(`sway` is built on top of `wlroot`)*:

```
sudo apt install xdg-desktop-portal-wlr xdg-desktop-portal
```

> **Note:**
> This is considered experimental for Debian 11. It may break certain applications, lack certain functionality, or not work at all. But it needs to be done, because `pipewire` is the only way to use full screen sharing on `wayland`.

> **Note:**
> Transition to `pipewire` brings potential benefits like lower CPU usage, better support for bluetooth devices, and better integration between applications using `jack` and `pulseaudio`.

The three sub sections below are independent of each other, but you are still highly recommended to use `pipewire` to replace all of them if you intend to replace any of it, for the best integration between different applications.

### REPLACE `pulseaudio`

After this section is completed `pipewire` will run as audio service and replaces `pulseaudio` completely.

Create this empty file:

```
sudo touch /etc/pipewire/media-session.d/with-pulseaudio
```

Create the `pipewire-pulse` service by copying example files:

```
sudo cp /usr/share/doc/pipewire/examples/systemd/user/pipewire-pulse.* /etc/systemd/user/
```

Run these three commands as a regular user *(not as `root`)*:

```
systemctl --user daemon-reload
systemctl --user --now disable pulseaudio.service pulseaudio.socket
systemctl --user --now enable pipewire pipewire-pulse
```

Check which server is in use:

```
pactl info | grep '^Server Name'
```

If it's using `pipewire` the response will be:

```
"PulseAudio (On PipeWire 0.3.19)"
```

Mask the `pulsaudio` service so that it will not start itself again after reboot:

```
systemctl --user mask pulseaudio
```

> **Note:**
> Here we don't use `sudo`.

Now reboot:

```
sudo systemctl reboot
```

> **Note:**
> If we want to restore previous functionality i.e. enable `pulseaudio` instead of `pipewire`:
>
> ```
> systemctl --user unmask pulseaudio
> ```

> **Attention**:
> I am afraid that `pipewire` must run in order for screen sharing to work, but I am not 100$ sure on this one!

### REROUTE OUTPUTS FROM `alsa` CLIENTS

Programs that talk directly with `alsa` i.e. *"`alsa` clients"* can be configured to output via `pipewire`. Install the `pipewire-audio-client-libraries`:

```
sudo apt install pipewire-audio-client-libraries
```

Create an empty file:

```
sudo touch /etc/pipewire/media-session.d/with-alsa
```

Copy configuration file from `pipewire` examples into the `alsa` configuration directory:

```
# cp /usr/share/doc/pipewire/examples/alsa.conf.d/99-pipewire-default.conf /etc/alsa/conf.d/
```

### REROUTE OUTPUTS FROM `jack` CLIENTS

Programs that talk directly with `jack` i.e. *"`jack` clients"* can be configured to output via `pipewire`. Install the `pipewire-audio-client-libraries` and `libspa-0.2-jack`:

```
sudo apt install pipewire-audio-client-libraries libspa-0.2-jack
```

Create an empty file:

```
sudo touch /etc/pipewire/media-session.d/with-jack
```

Copy the configuration files:

```
sudo cp /usr/share/doc/pipewire/examples/ld.so.conf.d/pipewire-jack-*.conf /etc/ld.so.conf.d/
```

Run:

```
sudo ldconfig
```

This will replace `jack` server libraries with `pipewire` replacement libraries at application runtime, by pointing the dynamic linker at the `/usr/lib/x86_64-linux-gnu/pipewire-0.3/jack/` folder.

### USE FOR `bluez` AUDIO DEVICES

`pipewire` will generally work fine in conjunction with `bluez` to supply high-quality audio to bluetooth-enabled audio devices when used as a replacement for `pulseaudio` with some caveats.

Install one package:

```
sudo apt install libspa-0.2-bluetooth
```

Remove one package:

```
pulseaudio-module-bluetooth
```

Then either reboot your computer or restart the `pipewire` services, otherwise device connections will fail with:

> "Protocol not available"

`pipewire` will attempt to choose the best possible codecs by default. It is possible to override this and many other related settings globally here:

```
/etc/pipewire/media-session.d/bluez-monitor.conf
```

We can also store per-user configurations by copying the above file to:

```
~/.config/pipewire/media-session.d/bluez-monitor.conf
```

> **Note:**
> Since release of `pipewire` 0.3.19, there have been numerous bluetooth-related feature additions and bug fixes. The version in Debian 11 is not representative of the current state of `pipewire`.

# PIPEWIRE -- screen sharing on browsers using WebRTC

## Browsers

Pipewire includes WebRTC protocol which can be used for **comunication between** (!) software that also supports it. One of such software are `firefox`, `chromium`, `skype`.

WebRTC is supported on official packages for `firefox` and `chromium` on Debian 11 ([source](https://github.com/emersion/xdg-desktop-portal-wlr/wiki/Screencast-Compatibility#webrtc-aka-firefoxchromium)). But it is much better to upgrade to the newest versions of both browsers which can be installed.

WebRTC is enabled by default in the newest `firefox` so we don't have to do anything else except install it.

WebRTC is however not enabled by default in the newest `chromium`, but we can easily enable it. What we need to do is just to open the `chromium` browser and insert `chrome://flags/` in the search bar. Then we search for string `WebRTC` and make sure to enable the feature `WebRTC PipeWire support`. Then `chromium` will be restart and everything will also work!Note that this setting is not available on old versions.

## Sway

Sway by itself does not integrate WebRTC protocol. It needs `xdg-desktop-portal` and because it is *"Wlroort"* based application it also needs `xdg-desktop-portal-wlr` . After these packages are installed we can reboot the system and we will see that they run as `systemd` *"user"*. If they do not, we can enable and start them like any other `systemd` *"unit"*.

```
┌───┐
│ $ │ ziga > ziga--workstation > ~
└─┬─┘ /dev/pts/1
  └─> systemctl --user status xdg-desktop-portal-wlr.service
● xdg-desktop-portal-wlr.service - Portal service (wlroots implementation)
     Loaded: loaded (/usr/lib/systemd/user/xdg-desktop-portal-wlr.service; static)
     Active: active (running) since Wed 2021-12-15 15:17:31 CET; 4min 24s ago
   Main PID: 997 (xdg-desktop-por)
      Tasks: 2 (limit: 11237)
     Memory: 1.0M
        CPU: 6ms
     CGroup: /user.slice/user-1000.slice/[email protected]/app.slice/xdg-desktop-portal-wlr.service
             └─997 /usr/libexec/xdg-desktop-portal-wlr

Dec 15 15:17:31 ziga--workstation systemd[840]: Starting Portal service (wlroots implementation)...
Dec 15 15:17:31 ziga--workstation systemd[840]: Started Portal service (wlroots implementation).

┌───┐
│ $ │ ziga > ziga--workstation > ~
└─┬─┘ /dev/pts/1
  └─> systemctl --user status xdg-desktop-portal.service
● xdg-desktop-portal.service - Portal service
     Loaded: loaded (/usr/lib/systemd/user/xdg-desktop-portal.service; static)
     Active: active (running) since Wed 2021-12-15 15:17:31 CET; 1h 37min ago
   Main PID: 972 (xdg-desktop-por)
      Tasks: 4 (limit: 11237)
     Memory: 4.7M
        CPU: 54ms
     CGroup: /user.slice/user-1000.slice/[email protected]/app.slice/xdg-desktop-portal.service
             └─972 /usr/libexec/xdg-desktop-portal

Dec 15 15:17:31 ziga--workstation systemd[840]: Starting Portal service...
Dec 15 15:17:31 ziga--workstation systemd[840]: Started Portal service.
```

Note that these *"units"* are only started for the user and can't be found in the system wide *"units"*:

```
┌───┐
│ $ │ ziga > ziga--workstation > ~
└─┬─┘ /dev/pts/1
  └─> systemctl status xdg-desktop-portal-wlr.service
Unit xdg-desktop-portal-wlr.service could not be found.


┌───┐
│ $ │ ziga > ziga--workstation > ~
└─┬─┘ /dev/pts/1
  └─> systemctl status xdg-desktop-portal.service
Unit xdg-desktop-portal.service could not be found.
```

## Sway ⟷ Firefox

If we want to use WebRTC between `sway` window manager and `firefox` we have to first make sure that `firefox` uses `sway` and not `xorg`. We can do this by exporting an environmental variable `MOZ_ENABLE_WAYLAND=1` but here is the catch. We must not do this in `/etc/environment`! We will actually leave `/etc/environment` empty!

Instead we create file `~/.config/environment.d/10-environental_variables.conf` and define environmental variables inside! Along side mentioned variable we also have to define others that (a) enable styling of `sway` widgets with `qt5ct` & `lxappearance` and (b) define default display server as `wayland`for all applications. In the end this file looks like this:

```
####################################################################################################
# Force Firefox to use "wayland" graphical server.
####################################################################################################
MOZ_ENABLE_WAYLAND=1


####################################################################################################
# LINK: # https://wiki.archlinux.org/title/PipeWire#WebRTC_screen_sharing
####################################################################################################
XDG_CURRENT_DESKTOP=sway


####################################################################################################
# NOTE: https://github.com/emersion/xdg-desktop-portal-wlr/wiki/Screencast-Compatibility#webrtc-aka-firefoxchromium
####################################################################################################
XDG_SESSION_TYPE=wayland


####################################################################################################
# LINK: https://bbs.archlinux.org/viewtopic.php?id=259721
# LINK: https://github.com/FedoraQt/QGnomePlatform
####################################################################################################
QT_QPA_PLATFORMTHEME=qt5ct
# QT_QPA_PLATFORMTHEME=gnome


####################################################################################################
# NOTE: "xcb" sets "X" graphical server and "wayland" sets "Wayland" graphical server to be used by
#       all applications. When there are two options i.e. "xcb;wayland", first one is prefered over
#       the second. The last option makes sure that even "X" based native Debain packages run
#       smoothly, but it does not work for some flatpaks that come packaged and perfer to use their
#       own QT that doesn't yet supporrt Wayland QPA platform plugin.
# LINK: https://stackoverflow.com/questions/49583671/pyqt5-unable-to-find-wayland-plugin
# LINK: https://doc.qt.io/qt-5/qguiapplication.html#platformName-prop
# LINK: https://blog.martin-graesslin.com/blog/2018/03/unsetting-qt_qpa_platform-environment-variable-by-default/
####################################################################################################
QT_QPA_PLATFORM=wayland
# QT_QPA_PLATFORM=wayland
# QT_QPA_PLATFORM=xcb
# QT_QPA_PLATFORM=wayland;xcb
# QT_QPA_PLATFORM=xcb;wayland


####################################################################################################
# LINK: https://github.com/swaywm/sway/wiki#my-favorite-application-isnt-displayed-right-how-can-i-fix-this
####################################################################################################
# QT_WAYLAND_DISABLE_WINDOWDECORATION=1


####################################################################################################
# NOTE: Forcing DPI is not needed as it is set in the sway configuration file.
####################################################################################################
# QT_WAYLAND_FORCE_DPI=physical


####################################################################################################
# NOTE: If I set "QT_QPA_PLATFORM=wayland it will automatically export "WAYLAND_DISPLAY=wayland-0".
#       If I set "QT_QPA_PLATFORM=xcb;wayland it will export "WAYLAND_DISPLAY=wayland-0" and
#       "DISPLAY=:0".
# LINK: https://wiki.archlinux.org/title/PipeWire#WebRTC_screen_sharing
####################################################################################################
# DISPLAY=:0
# WAYLAND_DISPLAY=wayland-0


####################################################################################################
# LINK: https://github.com/swaywm/wlroots/blob/master/docs/env_vars.md
# LINK: https://github.com/swaywm/sway/issues/6167
####################################################################################################
# WLR_DRM_NO_MODIFIERS=1
```

> **Note**:
> There is no `export` in front of environmental variables.

After this is done we reboot and check that these environmental variables are exported in the `systemd` user session:

```
┌───┐
│ $ │ ziga > ziga--workstation > ~
└─┬─┘ /dev/pts/1
  └─> systemctl --user show-environment
HOME=/home/ziga
LANG=en_US.UTF-8
LANGUAGE=en_US:en
LOGNAME=ziga
PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
SHELL=/bin/bash
USER=ziga
XDG_DATA_DIRS=/home/ziga/.local/share/flatpak/exports/share:/var/lib/flatpak/exports/share:/usr/local/share/:/u>
XDG_RUNTIME_DIR=/run/user/1000
MOZ_ENABLE_WAYLAND=1
XDG_CURRENT_DESKTOP=sway
XDG_SESSION_TYPE=wayland
QT_QPA_PLATFORMTHEME=qt5ct
QT_QPA_PLATFORM=wayland
QT_ACCESSIBILITY=1
DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/1000/bus
DISPLAY=:0
SWAYSOCK=/run/user/1000/sway-ipc.1000.901.sock
WAYLAND_DISPLAY=wayland-0
```

These environmental variables are not exported as a standard environmental variables are:

```
┌───┐
│ $ │ ziga > ziga--workstation > ~
└─┬─┘ /dev/pts/1
  └─> printenv
SHELL=/bin/bash
COLORTERM=truecolor
LANGUAGE=en_US:en
I3SOCK=/run/user/1000/sway-ipc.1000.901.sock
XCURSOR_SIZE=24
XDG_SEAT=seat0
PWD=/home/ziga
LOGNAME=ziga
XDG_SESSION_TYPE=tty
MOTD_SHOWN=pam
HOME=/home/ziga
LANG=en_US.UTF-8
SWAYSOCK=/run/user/1000/sway-ipc.1000.901.sock
WAYLAND_DISPLAY=wayland-0
INVOCATION_ID=a9a5056db67b4f53860bebc10877b185
XDG_SESSION_CLASS=user
TERM=foot
USER=ziga
DISPLAY=:0
SHLVL=1
XDG_VTNR=1
XDG_SESSION_ID=1
XDG_RUNTIME_DIR=/run/user/1000
PS1=\n┌───┐\n│ \[\033[1;32m\]$\[\033[0m\] │ \[\033[1;32m\]\u\[\033[0m\] > \033[1m\]\h\033[0m\] > \033[1m\]\W\033[0m\]\n└─┬─┘ \033[37m\]/dev/pts/1\033[0m\]\n  └─>
JOURNAL_STREAM=8:18757
XDG_DATA_DIRS=/home/ziga/.local/share/flatpak/exports/share:/var/lib/flatpak/exports/share:/usr/local/share/:/usr/share/
HUSHLOGIN=FALSE
PATH=/usr/local/bin:/usr/bin:/bin:/usr/local/games:/usr/games
DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/1000/bus
MAIL=/var/mail/ziga
_=/usr/bin/printenv
```

But `xdg-desktop-portal.service` and `xdg-desktop-portal.service-wlr` run in `systemd` user session and they are the ones that need these variables in order to work. Like this, now they can see them!

We can now open `firefox` and navigate to it's official website where we can test screen sharing ([source](https://mozilla.github.io/webrtc-landing/gum_test.html)).

For some reason this test page will find our *"entire screen"* that it can broadcast but when we press <kbd>Start</kbd> display will be black and mouse cursor will be moving.

...