LordOS — a free, fast and secure GNU/Linux distribution based on Debian, with its own desktop environment: display server and Wayland compositor in C, a React UI engine on QuickJS, and private native apps.
Sound in LordOS
The sound server is PipeWire, the same one GTK, Qt and Firefox apps use. LordOS doesn't ship
another server or use libpipewire or libpulse: lord-server talks to PipeWire with its own C
client (server/src/sound/). With that client, the UI shows and changes:
- outputs and inputs;
- the volume of each channel;
- mute;
- the default device;
- each app's volume and output;
- and a microphone level meter.
![]() |
![]() |
Volume in Control Center (it changes it in PipeWire: pactl reports the same value) |
Settings → Sound: outputs, inputs, test and per-app volume (listed while an app plays sound) |
![]() |
|
With the VM's HDA card (audio0: ich9-intel-hda): output, port (Line Out ↔ Speakers, tested with pactl) and microphone with meter |
Why the PulseAudio protocol
PipeWire accepts clients over two protocols:
Its own (
pipewire-0). It is serialized as SPA PODs, which are nested structures with alignment, 64-bit types and objects with properties by id. Changing a volume there means:- binding the node;
- building a
Propsinside anSPA_PARAM_Props; - and knowing how WirePlumber stores volumes: if the node is changed directly, WirePlumber doesn't remember it.
The protocol isn't documented apart from libpipewire.
PulseAudio's (
pulse/native), served bypipewire-pulse. It has been a stable protocol for 15 years and is documented in PulseAudio's code. It is simple: a list of typed values (tagstruct). It has high-level commands ("volume of this sink", "app to this output", "default output") that PipeWire translates and WirePlumber remembers. It is what pavucontrol, the GNOME and KDE applets, andpactluse.
We chose option 2: with about 1300 lines (snd.c and pulse.c) it covers everything the UI
needs. It is still talking to PipeWire: pipewire-pulse is a PipeWire module, not a separate
server. The format was taken from PulseAudio 17's pulsecore/protocol-native.c and tagstruct.h.
That code was only read to follow the format: it isn't linked or copied.
How it works
- Connection.
snd_start()starts after dropping privileges. It connects to$PULSE_SERVER(unix:/path) or to$XDG_RUNTIME_DIR/pulse/native. IfXDG_RUNTIME_DIRisn't set, it uses/run/user/<uid>. It only connects if the socket belongs to the user. - Handshake. It sends
AUTH(protocol 32, without shared memory, so the data goes over the socket) andSET_CLIENT_NAME("LordOS",org.lordos.Server). - State. It subscribes to changes of sinks, sources, apps, server and cards, and requests the four lists. With each notification it requests only what changed.
- Notifications to JS. When something changed and all the replies have arrived, JS is
notified with a
statecarrying the full state. - Reconnection. If PipeWire crashes or restarts,
snd_fd()becomes a timer and it retries every 2 s. Meanwhile, the state saysconnected: false. - Meter. It is a recording stream of the chosen input: 1 float channel, at 25 Hz, with
PEAK_DETECT(the same thing pavucontrol does). The server sends one peak per packet. - System sounds.
pop,notifyanderrorare synthesized on the fly: sine waves with an envelope, with no files or OGG decoder. They're uploaded once to the server's sample cache and then played withPLAY_SAMPLEon the default output, withmedia.role=event. - Our own streams. LordOS's streams (the meter and the sounds) don't show up in the app lists. Otherwise, the microphone meter would make it look like someone is recording.
API: lord.sound
| Function | What it does |
|---|---|
state() |
the full state (shape below) |
setVolume(kind, index, value) |
value is a number (brings the loudest channel to that level and keeps the balance) or a per-channel list; 1 = 100 %, up to 1.5 |
setMute(kind, index, bool) |
mute |
setDefault('sink' | 'source', name) |
default output or input |
setPort('sink' | 'source', index, port) |
speakers ↔ headphones, etc. (a port from ports) |
move('input', app, sink) / move('output', app, source) |
moves an app to another output or input |
meter(sourceIndex) / meter(-1) |
turns the meter on or off; for an output, its monitor is used |
play('pop' | 'notify' | 'error') |
system sound |
kindis'sink'(output),'source'(input),'input'(app playing) or'output'(app recording).- They all return
trueif the command went out. The result shows up in the nextstate. - They validate the type, the index (32-bit integer) and the names (no control characters, less than 256 bytes). Also, the index or name must exist in the current state.
Events: globalThis.__lordSound = (type, data) => …
type === 'state':datais the same asstate().type === 'peak':datais{ source, level }(0..1), 25 times per second while the meter is on.
Shape of the state:
{
connected: true, server: 'PulseAudio (on PipeWire 1.4.2)', version: '15.0.0',
defaultSink: 'alsa_output.pci-…', defaultSource: '…', meter: -1,
sinks: [{ index, name, description, icon, formFactor, bus,
volume: [1, 1], level: 1, // per channel and the maximum; 1 = 100 %
mute, state, // 0 running, 1 idle, 2 suspended
monitor, // index of its "monitor" source (for the meter)
card, default: true,
ports: [{ name, description, priority, available }], // available: true/false/null (unknown)
activePort }],
sources: [{ …the same, with monitorOf (sink index, or -1 if it is a real input) }],
inputs: [{ index, name, app, appId, icon, binary, role, pid, sink,
volume, level, mute, corked, hasVolume, volumeWritable }], // apps playing
outputs: [{ …the same, with source instead of sink }], // apps recording
}
Inputs with monitorOf >= 0 are the "monitor" of an output, what plays through it. The UI
normally hides them from the microphone list.
Tests
make -C server testincludesbuild/sound-test: round trip of each tagstruct type, property lists, descriptors, truncated packets (none reads outside the buffer) and wrong types.build/sound-cli(make -C server build/sound-cli) is a command-line client over the samesnd.c, against the real PipeWire:list,volume,mute,default,port,move,meter,play,watch.LORD_SND_DEBUG=1shows every packet.
Tested in the VM (PipeWire 1.4.2) with two virtual outputs (module-null-sink) and one virtual
input. The results were compared with pactl and wpctl status:
| Test | Result |
|---|---|
List outputs, inputs, monitors and apps (paplay with --client-name) |
same as pactl list (name, description, channels, volume, pid, binary) |
| Volume 42 %; balance 30/70; level 90 % keeping the balance | pactl get-sink-volume: 42 %; 30 % and 70 %; 39 % and 90 % |
| Output and app mute | pactl: Mute: yes / no |
| Default output and input | pactl get-default-sink and wpctl status (the *) |
| An app's volume (25 %) and moving it to another output | pactl list sink-inputs: 25 %, Sink: 59 |
| Meter | 50 peaks in 2 s (25 Hz) with sound; level ~0 in silence |
| System sounds | pactl list samples: lordos-pop, lordos-notify and lordos-error; when played, pactl subscribe sees the stream appear and end |
Changes made by another program (pactl set-sink-volume, set-default-sink) |
a new state arrives with the value |
systemctl --user restart pipewire pipewire-pulse wireplumber |
"desconectado… reintentando" ("disconnected… retrying"), connected: false, and after 2 s it reconnects by itself |
lord.sound from JS (QuickJS with the binding, without the screen) |
changes volume and mute, turns on the meter and plays sounds; rejects invalid type, index or name |
lord-server builds with the client inside (main.c polls snd_fd()). The sound UI in Control
Center and Settings is built separately, on top of this API.
Session: where PipeWire lives
PipeWire runs as a systemd user service (pipewire, pipewire-pulse and wireplumber, with
socket activation). Those services live in the user's systemd --user, which exists while the
user has a session or "linger".
- Today in the VM: lord-server is started with
sudofrom SSH and then drops privileges tolord. So that PipeWire is there even without an open SSH session,loginctl enable-linger lordwas enabled:systemd --userstarts with the machine and leaves the sockets in/run/user/1000. lord-server finds the socket there even thoughsudoclearedXDG_RUNTIME_DIR. The Wayland compositor already fills in that variable with/run/user/<uid>. - With our own session (M8): login goes through PAM with
pam_systemd. That creates the logind session with a seat (seat0),XDG_RUNTIME_DIRand theuser@<uid>.service. That way PipeWire comes up via socket without linger. Also, logind gives the seat's user access to/dev/snd/*(uaccessACL), which today, over SSH and without a seat, it doesn't have:lordisn't in theaudiogroup.
Packages in the VM
| Package | What for |
|---|---|
pipewire, pipewire-pulse, wireplumber |
the sound server (Debian 13 ships it by default on desktops) |
pipewire-alsa |
so apps that use ALSA directly go through PipeWire |
pulseaudio-utils |
testing only: pactl and paplay |
sound-theme-freedesktop |
testing only: .oga sounds for paplay |
Configuration: sudo loginctl enable-linger lord and
systemctl --user enable --now pipewire pipewire-pulse wireplumber. To read the format,
PulseAudio's source was downloaded with apt-get source --download-only pulseaudio into
~/snd-ref: it was only used as a reference and isn't built.
Real time: PipeWire must not wait for anyone
Chromium's audio (YouTube) stuttered on the live ISO.
Cause. PipeWire ran at normal priority (SCHED_OTHER, nice 0), the same as lord-server, which
composites on the CPU, and as the browser. It asks for real time in two ways, and neither worked
in LordOS:
- Through the user's limits (
RLIMIT_RTPRIO). It didn't have them. - Through RealtimeKit (
rtkit). The ISO ships it, but rtkit asks polkit. rtkit's rule isallow_any=no: it only gives real time to processes of an active session on a logind seat.lord-sessiondsessions run inuser@<uid>.servicewithout a seat, so polkit says no. PipeWire's log shows "can't set rt prio to 83 (try increasing rlimits)".
On a PC the quantum is small (browsers ask for ~5–10 ms). With PipeWire competing for the CPU,
any delay longer than that is a dropout. In a VM you don't notice, because PipeWire raises the
minimum to 1024 (21 ms) when it detects a VM (vm.overrides).
Fix. LordOS users are in the pipewire group:
- The
pipewirepackage already ships/etc/security/limits.d/25-pw-rlimits.conf(@pipewire: rtprio 95, nice -19, memlock 4 MB). pam_limitsis in thesystemd --usersession (/usr/lib/pam.d/systemd-user).
That way PipeWire takes real time by itself, without polkit: its data-loop threads end up at
SCHED_FIFO 88/83 and the main ones at nice -11. The group is added:
- to the live ISO user (
tools/iso/build.sh); - to the installer's first user (
server/src/install/install.c); - to new users from Settings → Users (
server/src/users/users_admin.c).
A user that already existed needs to log in again, or systemctl restart user@<uid>.
Test (VM 118) with pw-top. "Dropouts" is the difference in the ERR counter, for the output
and for the stream:
| Test | Without real time | With the pipewire group |
|---|---|---|
paplay at 5 ms (PULSE_LATENCY_MSEC=5, like a browser on a PC), 30 s, dragging windows and 6 processes burning CPU |
16 dropouts on the output, 303 on the stream | 0 and 0 |
| The same without extra load, dragging | 0 and 2 | 0 and 0 |
| YouTube in Chromium, 3 minutes, dragging windows and 2 processes burning CPU | — | 0 and 0 |
For the "without real time" case, PipeWire's VM adjustment was removed with two test files in
~/.config/pipewire/*.conf.d/ (deleted afterwards).
lord-server doesn't need real time and doesn't hold PipeWire back:
- its PulseAudio client is non-blocking (
O_NONBLOCK; if the socket is full, it buffers and moves on); - it uses 2 % CPU with or without audio playing.
There was no need to change pipewire-pulse's quantum.
Virtual machines (0.8.1)
Symptom (0.8.0). On VMware (2 vCPUs, the default emulated card and later HD Audio), YouTube
in Chromium stuttered: pw-top showed ERR on the ALSA sink climbing (600 → 1600) while BUSY was
~10–30 µs, so the guest CPU wasn't the problem: the emulated card is fed by the host's timers and
on a busy host they arrive late. It was worst in the first minutes after login.
What was already there. PipeWire and WirePlumber detect a VM themselves (cpu.vm.name, from
DMI/CPUID; pw-cli info 0 shows it, qemu on Proxmox). Then PipeWire raises the minimum quantum
to 1024 (pipewire.conf, vm.overrides) and Debian's WirePlumber gives emulated PCI cards
1024-frame periods and 2048 frames of headroom (/usr/share/wireplumber/wireplumber.conf.d/alsa-vm.conf).
On the user's VMware machine those were active and the sink still ran dry (ERR 989 → 1042 in
~10 s with YouTube playing).
Fix. /etc/wireplumber/wireplumber.conf.d/lordos-vm-audio.conf (in the lordos package,
tools/iso/rootfs/) adds a rule for alsa_output.* with the same VM-only match as
alsa-vm.conf (cpu.vm.name = "~.*"): 8 periods of 1024 frames, api.alsa.headroom = 8192
(~170 ms at 48 kHz) and api.alsa.disable-tsched = true (the card's interrupts drive PipeWire,
not timers). Its name sorts after alsa-vm.conf, so its values win. On the VMware machine it
took ERR from climbing to 0 → 0 over 30 s of YouTube (sink WAIT 287 µs, BUSY 28 µs). On real
hardware cpu.vm.name is not set, the rule doesn't match and latency stays as before. No unit or
generator is needed: the match is WirePlumber's own.
Startup: helpers that do background work right after login now yield. lord-maild (its first
full sync starts at login) runs at nice 19 with the idle I/O class; the lord-media thumbnail and
probe worker runs at nice 10 with the lowest best-effort I/O level. The backup thread already ran
at nice 19, idle I/O, 5 minutes after login and never on battery. PipeWire itself runs with
real-time priority (see above), so contention inside the guest can't starve it; what the extra
headroom covers is the host.
The input level meter in Settings → Sound used pavucontrol's 25 Hz PEAK_DETECT stream, which in
PipeWire is a node at rate 25 with a quantum of 1; on the VMware machine PipeWire was seen at
36 % CPU while the page was open. It is now a plain 48 kHz mono stream read in blocks of 2048
samples (23 levels a second), opened only while the Sound page is open and closed when it
closes (apps/settings/Sound.jsx, snd_meter in server/src/sound/snd.c). The Voice Recorder computes its level from
its own recording stream and has no extra one.
Tested (VM 123, Proxmox, live ISO, emulated HD Audio with driver=none, SeaBIOS): the sink
shows the rule's values (wpctl inspect @DEFAULT_AUDIO_SINK@: api.alsa.headroom = "8192",
api.alsa.disable-tsched = "true"; /proc/asound/card1/pcm0p/sub0/hw_params: period 1024,
buffer 8192), the source keeps Debian's 2048. 30 s of playback with 4 CPU burners in the guest:
ERR 0 → 0, with and without the rule: KVM's emulated card doesn't show VMware's dropouts, so the
fix itself was measured on the user's VMware machine, and Proxmox only checks that it applies and
does no harm.
Pending
- Real speakers. The VM now has an HDA card with a codec (
audio0: ich9-intel-hda; the userlordis in theaudiogroup): WirePlumber sees the analog output and microphone andsetPort(Line Out ↔ Speakers) was tested withpactl. Whether it is actually audible can't be checked in a VM with no audio on the host (driver=none); it still needs testing on a physical machine. - Card profiles (stereo, HDMI, duplex):
GET_CARD_INFO_LISTandSET_CARD_PROFILEare missing. - Volume of virtual inputs. The volume of a virtual input
(
media.class=Audio/Source/Virtual) doesn't change, not even withpactl: that's how it is in PipeWire 1.4. - Suspended virtual outputs. A suspended virtual output (nothing playing) freshly created
after restarting PipeWire ignores the volume, also with
pactl. With something playing it works. It doesn't happen with real outputs. - System sounds from files. freedesktop themes come in OGG Vorbis and would need a decoder. Today there are 3 synthesized sounds.
- Repeated events. Changes in our own streams (meter, sounds) generate a few extra
stateevents, although they aren't shown. A few per second when turned on, not continuous.


