Audio and power

Pearl’s sound controls talk to PulseAudio or PipeWire’s PulseAudio-compatible service, and its power controls talk to UPower, logind and, when installed, power-profiles-daemon. The bar’s audio and battery widgets open the compact Sound and Power & battery pages in the control center, and Settings carries the same pages in full. The battery widget hides itself when no battery is reported, and a missing service leaves the shell and its panels usable with an explicit unavailable state.

Sound

The Sound page lists output and input devices with their volume, mute and default selection, plus a row per application stream:

• Device volume covers 0 to 100% without amplification above nominal. The slider shows the loudest channel and scaling preserves the channel balance; mute is independent.
• Application playback streams can be moved to an output and recording streams to an input, including the corresponding default device. Their volumes adjust live. Read-only stream controls are disabled rather than misleading.
• Changes made by other applications, and your existing media keys, update the same rows; Pearl does not own the sound server.
• With no devices or a disconnected sound server the rows are replaced by a status message, and Pearl reconnects automatically when the service returns, without ever starting a daemon itself.

Choose speakers or a microphone

1. Open Settings → Sound. Under Output, use Change device or Use by default to choose speakers or headphones. Do the same under Input for your microphone.
2. Check Mute, set a moderate volume, then start playback or recording.
3. Under Applications, check the application’s volume and mute state. Use its ••• menu to Move to default or Choose device.
4. Check the displayed route, then listen or make a short recording.

Changes take effect immediately. Applications appear only while playing or recording. For player buttons, see Media.

No sound, missing microphone or Bluetooth audio

• One application is silent: check its own controls and its row under Applications. For a microphone, check the application’s input permission and any physical mute switch.
• Sound uses the wrong device: choose the default and move the application’s stream to it. Check the route again after unplugging or reconnecting devices.
• Bluetooth headset missing: check for Connected in Bluetooth settings. Use your distribution’s audio tools to select headset profiles or codecs; Pearl does not provide those controls.
• Audio service unavailable. Reconnecting…: check your existing PipeWire or PulseAudio service. Pearl does not start a sound server.
• No devices listed: compare with the sound server’s device list. If it is empty too, check the hardware connection, driver and device profile.

pearlctl services status shows the devices and streams Pearl can see; follow next_offset for more entries.

Battery

The Power & battery page shows the aggregate battery percentage, charging state and estimated time to empty or full, and whether the machine is on AC. The bar shows charging, full or discharge-level glyphs from UPower’s state. Firmware charge thresholds can leave a plugged-in battery pending charge, without its percentage rising.

On a desktop without a system battery the battery card, source selector and automatic power-saver row are hidden, the timers edit AC settings, and your battery settings remain saved for later.

The page also keeps a session-only charge history of up to six hours, which resets when the battery identity or service changes. An unknown charge or health value is never displayed as zero or as “Good”, and UPS or peripheral batteries do not appear as laptop batteries.

Check a missing battery or charging indication

Open Settings → Power & battery and compare its state with the bar. Add a removed battery widget in Settings → Bar & dock.

If charging state does not change, compare pearlctl services status with upower -d. If UPower also misses the change, check its service and hardware reporting. Use the glyph and Power page to check charging; a charger-plug toast is not guaranteed.

Brightness

The brightness slider reads and writes the machine’s backlight. Zero maps to the smallest nonzero hardware value so the panel stays lit, and a permission denial leaves the observed state unchanged. Writes from other tools, such as brightnessctl or a brightness daemon, are detected and reflected in the page and the on-screen display. A machine without a backlight device shows an explicit unavailable state.

Pearl needs a supported backlight and a valid logind session. For an external monitor without a system backlight, use the monitor’s controls or a separate DDC/CI tool; Pearl has no monitor brightness chooser.

Power profiles

Where power-profiles-daemon is installed, the page offers its power-saver, balanced and performance profiles. Only the choices the daemon actually advertises are enabled, a degraded-performance reason is shown when the daemon reports one, and the displayed profile always follows the daemon’s authoritative state rather than the last click.

Select a mode in Settings → Power & battery. If modes are unavailable, check systemctl status power-profiles-daemon.service --no-pager and the page’s message. Performance depends on the hardware. Power modes are separate from CPU scheduler profiles.

Idle, sleep and automatic power saver

Open Settings → Power & battery → Sleep & energy saving, choose AC or battery under Settings for, then set Turn screen off after and Suspend after. Never disables a timeout. Use Session & lock settings to set the lock timer.

Brightness and power mode apply immediately. Sleep, dimming and automatic power-saver settings also save immediately, without applying unrelated changes from the shared draft.

The timers are constrained so the sequence stays sane: suspend requires an earlier nonzero lock timeout, and screen off cannot be later than an enabled suspend timeout. When dimming is on, brightness drops to 20% for up to 30 seconds before screen off and is restored on activity unless you changed it yourself; dimming does nothing when screen off is disabled or brightness is already at or below 20%. Screen off needs the compositor’s output power support, and automatic suspend locks the screen first and waits for the lock to be verified; see Session security for lock, sleep and inhibition behavior.

Automatic power saver accepts off or a battery threshold of 10, 20 or 30 percent. While discharging below the threshold it selects the power-saver profile, and exits after a five-point recovery margin or when AC returns. It restores only a profile it still owns: if you changed the profile manually or another tool changed it, automation stays out of the way until the low-battery episode ends. It keeps running while Settings is closed and never rewrites your saved threshold.

Check sleep and resume safely

Save your work, then check that Lock and unlock work. Choose Suspend or Hibernate in the control center’s Session & security card and confirm. Hibernate requires system storage and firmware support.

After resume, check that the session is locked, unlock it, and check brightness and networking. Lid-triggered sleep follows system policy.

For an unwanted timeout, set Never for the affected AC or battery setting. For a failed sleep or logout, keep the exact error and previous-boot logs (journalctl -b -1). Avoid repeating a freeze with unsaved work.

Power off and restart

Power off and restart are deliberate: the same button must be activated twice within ten seconds, and the confirmation resets when you cancel, close the popup or let it expire. The request goes through the system’s normal authorization, denials are shown rather than silently escalated, and an accepted request is reported as acceptance by the session manager. No power-off or restart command is exposed through the CLI.

On-screen feedback

Volume and brightness changes show a brief card centered near the bottom of the display that triggered them: an icon, the device name or caption, a percentage and a level meter. The card appears for changes to the default output from any source, including media keys and external clients, and for any successful brightness write, but not for rejected writes or unchanged values. Rapid changes coalesce into one card, a newer request replaces an older one, and the card expires shortly after its last update. It is click-through, never takes focus, and is dismissed by locking the session.

System and scheduling

Choose a CPU scheduler profile in Settings → System, or add CPU Scheduler under Settings → Bar & dock → Add widget. The widget needs an installed profile file.

Caution

Scheduler profiles apply to every user and persist across boots. Pearl’s helper uses polkit authorization to replace /etc/default/scx and enable/restart scx.service. Default disables the service and returns to the kernel scheduler. Selecting a profile replaces hand edits to that file.

Pearl v0.3.0 uses scx.service, not the older scxctl/scx_loader backend. It needs a sched_ext-capable kernel, scheduler binaries, Pearl’s helper/polkit files and a version-2 profile file. Pearl reads /etc/pearl/scheduling-profiles.json before /usr/share/pearl/scheduling-profiles.json; Git builds use pearl-git in these paths.

After selecting a profile, wait for Running and the scheduler’s identity. Custom means a scheduler is running outside these profiles. If a profile fails, Pearl reports the error and attempts to return to Default.

Profiles installed but unavailable

Check the message in Settings → System, then inspect the kernel and service:

uname -r
systemctl status scx.service --no-pager
cat /sys/kernel/sched_ext/state
cat /sys/kernel/sched_ext/root/ops
journalctl -b -u scx.service --no-pager -n 80

root/ops can be absent when no sched_ext scheduler is attached. Check the profile file and /usr/lib/pearl/pearl-scheduling-helper (Git: /usr/lib/pearl-git/). Check your distribution’s package instructions for missing profiles, binaries, helper files or scx.service. A scheduler binary alone is not enough.

When requesting help, include the Pearl, scx, scheduler and kernel versions. See the profile format and backend details for administrator setup.

Command line

pearlctl control-center show --page sound
pearlctl control-center show --page power
pearlctl services status [--offset N]
pearlctl audio set --kind sink --volume 45
pearlctl audio set --kind source --mute true
pearlctl audio set --kind sink --generation GENERATION --device INDEX --default true
pearlctl audio set --kind playback --generation GENERATION --device INDEX --target SINK_INDEX
pearlctl brightness set --percent 65
pearlctl profile set --profile balanced

services status pages through audio devices, streams, battery, profile and brightness state four entries at a time, following next_offset. Simple volume and mute changes target the current default device; targeting a specific device or moving a stream needs the --generation and --device values from a current status call. Accepted mutations return queued:true, and the real outcome appears in a later status call, the panel or the on-screen display. Audio, brightness and profile mutations are rejected while the session is locked.

Caution

The idle timers live in an idle block inside the preferences file. Older Pearl versions parse preferences strictly and reject it, so remove the block before downgrading.