# volume-osd An on-screen display for volume, covering both output (speakers) and input (microphone). It appears at the bottom of the screen when the level or mute state changes, and fades out 1.5 seconds later. ┌────────────────────────────────────┐ │ ▪ Outside World ⏮ ⏸ ⏭ │ │ Sunbeam │ │ ──────────────────────────────── │ │ 🔊 Output 75% │ │ ████████████████░░░░░░░░░░ │ └────────────────────────────────────┘ (the track row only exists while a player does) ## Running it qs -p . From Hyprland, to start it with the session: exec-once = qs -p ~/Programming/GIT/quickshell/volume-osd ## Now playing When an MPRIS player is running, a track row sits above the volume bar: album art, title, artist, and prev/play/next. With no player the panel is exactly the volume OSD, at its original size. A track change or a play/pause shows the panel too, so the row is not something you only see by touching the volume. Hovering the panel freezes its fade so the buttons can be clicked; moving away starts the countdown again. Without a hover it behaves exactly as it did before there was anything clickable on it. It still takes no keyboard focus. Two things about MPRIS that are not obvious: **playerctld publishes a duplicate.** It proxies whichever player is active and republishes the metadata under `org.mpris.MediaPlayer2.playerctld`, so every player appears twice. `Player.qml` drops that name and talks to the real player, which works whether or not playerctld is running. **Album art can be a reused temp path.** Audacious extracts embedded art to a file in its cache and rewrites that same path on each track, so the URL repeats while the image behind it changes. The source carries the track title as a cache buster and `cache: false`, or the previous track's cover stays on screen. ## No keybinds to change The OSD watches PipeWire rather than being triggered by a hotkey, so existing volume binds keep working untouched: bind = , XF86AudioRaiseVolume, exec, wpctl set-volume @DEFAULT_AUDIO_SINK@ 5%+ Because the source of truth is PipeWire and not the keypress, the OSD also appears for volume changed from anywhere else: pavucontrol, a per-application slider, or another machine's remote control. One widget serves both directions. Whichever device changed last is the one displayed, with a speaker icon for output and a microphone for input. Icons are Nerd Font glyphs (speaker and microphone), so the font stack needs a Nerd Font available for fallback. Inconsolata Nerd Font Mono, which unified-desktop-theme already installs, covers them. ## Frosted glass The panel is drawn translucent (65% over the Macchiato base) and the blur behind it comes from the compositor, not from QML. Hyprland blurs a layer surface only when a rule says to, matched on the namespace this window sets (`quickshell-volume-osd`): hl.layer_rule({ name = "blur-volume-osd", match = { namespace = "^(quickshell-volume-osd)$" }, blur = true, xray = false, ignore_alpha = 0.1, }) `xray = false` frosts the windows actually behind the OSD rather than jumping straight to the wallpaper. `ignore_alpha = 0.1` leaves near-transparent pixels unblurred, which keeps the rounded corners from picking up a halo. Doing it this way costs nothing in the shell: no `MultiEffect`, no live blur pass in QML, no offscreen buffer. Without the rule the OSD still works, it just renders flat translucent instead of frosted. ## Theme `Theme.qml` holds no palette of its own beyond a fallback. The colours come from `~/.cache/wal/udt-palette.qml`, which `udt-accent` generates on every wallpaper change from unified-desktop-theme's `palette.rasi`, carrying the whole Macchiato palette plus the accent snapped from the wallpaper. That file is watched, so editing the palette in unified-desktop-theme and regenerating recolours a running OSD with no restart. Where the file does not exist, the hardcoded defaults in `Theme.qml` apply, which is what keeps this directory runnable on a machine without unified-desktop-theme. ## Two details worth knowing **A node's volume arrives before it is ready.** When a `PwNode` binds, its volume populates and emits a change signal, and that happens while `ready` is still false. Those first signals are state being read, not the user turning a knob, so `show()` checks `ready` and ignores them, which is why there is no OSD at login. That one check is the whole guard, and it is tempting to add a second. An earlier version also swallowed the first change per node, on the assumption that the startup values arrived *after* ready. They do not, so the extra guard ate the user's first keypress instead: the OSD only appeared from the second change onward. If this symptom comes back, trace the signal order before adding a filter. **`PwObjectTracker` is not optional.** PipeWire node properties are only kept current while something binds the node. Without the tracker the volume reads once and then goes stale, which looks like an OSD that displays a number from several changes ago. **A config with no visible window exits.** The OSD is hidden most of the time, so it holds itself open with a 1x1 transparent window with an empty mask, which is click-through and draws nothing. Without it the shell loads, reports no error, and quits, and the symptom is a keybind that appears to do nothing or a panel that never paints. This was removed once during development after misreading a process check, and the bug came straight back. **A Row sizes to its children, not to its parent.** The track row's text column originally had a fixed width, and art + text + buttons + spacing came to 356px inside a 328px content box, so the `next` button hung over the panel edge. The column now takes whatever the art and transport buttons leave, which holds at any panel width. Fixed widths inside a Row are worth distrusting. ## Volume above 100% PipeWire allows volume over 1.0. The percentage is reported as-is, so it can read above 100%, while the bar stops at full rather than overflowing its track.