repositories / dotfiles

dotfiles

bugabingas dorkfiles

owned by bugabinga

feat(quickshell): add osd action ipc wrappers

d7eb6371c693ec8ac653040e1d87e59704839be2

Oliver Jan Krylow <oliver@bugabinga.net> ·

unsigned

Browse filesCompare with HEAD

Changed files (4)

docs/super/inventory/2026-06-17-quickshell-phase-4e-osd-actions-verification.md

Added
new file mode 100644
1 +# Quickshell Phase 4E OSD Action Verification — 2026-06-17
3 +## Scope
5 +Added Quickshell IPC wrappers for the current `hypr/modules/hypr_osd.lua` actions. Hypr binds are not migrated yet; this creates the replacement target for later simplification.
7 +## Implemented files
9 +- `quickshell/nugu/Commands.qml` action wrappers and `osdRequested` signal
10 +- `quickshell/nugu/shell.qml` IPC methods and command-to-OSD connection
11 +- `quickshell/nugu/README.md` usage notes
13 +## New IPC surface
15 +Controls:
17 +```sh
18 +qs ipc -c nugu call nugu osdVolumeUp
19 +qs ipc -c nugu call nugu osdVolumeDown
20 +qs ipc -c nugu call nugu osdMuteAudio
21 +qs ipc -c nugu call nugu osdMuteMic
22 +qs ipc -c nugu call nugu osdBrightnessUp
23 +qs ipc -c nugu call nugu osdBrightnessDown
24 +```
26 +Media/session/capture:
28 +```sh
29 +qs ipc -c nugu call nugu osdMediaNext
30 +qs ipc -c nugu call nugu osdMediaToggle
31 +qs ipc -c nugu call nugu osdMediaPrev
32 +qs ipc -c nugu call nugu osdReloadHypr
33 +qs ipc -c nugu call nugu osdSessionLock
34 +qs ipc -c nugu call nugu osdSessionSuspendDryRun
35 +qs ipc -c nugu call nugu osdCaptureRegion
36 +qs ipc -c nugu call nugu osdCaptureWindow
37 +qs ipc -c nugu call nugu osdCaptureOutput
38 +qs ipc -c nugu call nugu osdCaptureAnnotate
39 +qs ipc -c nugu call nugu osdPickColor
40 +```
42 +## Verification run
44 +Temporary `XDG_CONFIG_HOME` named config was used; no live home symlink mutation.
46 +State saved/restored:
48 +- Sink volume restored to original value.
49 +- Sink mute state restored to original value.
50 +- Backlight raw value restored to original value.
52 +Tested IPC:
54 +```text
55 +osdVolumeUp
56 +osdVolumeDown
57 +osdBrightnessDown
58 +osdBrightnessUp
59 +osdReloadHypr
60 +lastOsdAction
61 +```
63 +Observed output:
65 +```text
66 +vol_up=<command string>
67 +last1=Volume 0.32 [MUTED]
68 +vol_down=<command string>
69 +last2=Volume 0.30 [MUTED]
70 +bright_down=<command string>
71 +last3=Brightness 78%
72 +bright_up=<command string>
73 +last4=Brightness 96%
74 +reload=Hyprland reloaded
75 +last=Hyprland reloaded
76 +```
78 +After the first reload test, `hyprctl reload` stdout (`ok`) overwrote the intended OSD message. Fixed `shellOsd()` to suppress command stdout and only print the fixed OSD label on success. Retest passed:
80 +```text
81 +reload=Hyprland reloaded
82 +last=Hyprland reloaded
83 +```
85 +Runtime output:
87 +```text
88 +INFO: Configuration Loaded
89 +```
91 +No QML errors, binding loops, reference errors, annotation warnings, or lingering `qs` process were observed.
93 +## Screenshots
95 +- `/tmp/nugu-qs-osdcmd-volume.png`
96 +- `/tmp/nugu-qs-osdcmd-brightness.png`
97 +- `/tmp/nugu-qs-osdcmd-reload-fixed.png`
99 +Vision checks confirmed:
101 +- Volume OSD is compact and Nugu-styled.
102 +- Brightness OSD is compact with warning/yellow border.
103 +- Reload OSD says `Hyprland reloaded` and is readable.
105 +## Not yet accepted for bind migration
107 +- Real hardware key events not tested yet.
108 +- Media wrappers need a live MPRIS player for parity proof.
109 +- Capture/color wrappers use interactive tools and need manual/interactive validation.
110 +- `osdSessionLock` would start `hyprlock`; not run in this verification.
111 +- `osdSessionSuspendDryRun` intentionally does not suspend.

quickshell/nugu/Commands.qml

Modified
12 12 property string lastClipboardPreview: ""
13 13 property bool lastClipboardCopied: false
14 14 property string lastPowerAction: ""
15 + property string lastOsdAction: ""
16 + property string nextOsdTone: "info"
15 17 property bool executeConfirmedPowerActions: false
19 + signal osdRequested(string message, string tone)
17 21 function detached(args: var): void {
18 22 runner.command = args
19 23 runner.startDetached()
26 + function shellOsd(command: string, fallback: string, tone: string): string {
27 + // Shell snippets mirror the current Hypr OSD helpers. They stay behind
28 + // this boundary so Hypr Lua can later shrink to stable Quickshell IPC.
29 + lastOsdAction = fallback
30 + nextOsdTone = tone
31 + osdProcess.command = ["sh", "-c", `(${command}) >/dev/null && printf '%s' "${fallback}"`]
32 + osdProcess.running = true
33 + return fallback
34 + }
36 + function shellOsdOutput(command: string, tone: string): string {
37 + // Dynamic controls print their final status message; the collector turns
38 + // that into a Nugu OSD instead of `hyprctl notify`.
39 + lastOsdAction = command
40 + nextOsdTone = tone
41 + osdProcess.command = ["sh", "-c", command]
42 + osdProcess.running = true
43 + return lastOsdAction
44 + }
46 + function fixedOsd(message: string, tone: string): string {
47 + lastOsdAction = message
48 + osdRequested(message, tone)
49 + return message
50 + }
22 52 function uwsm(slice: string, args: var): var {
23 53 return ["uwsm", "app", "-s", slice, "--"].concat(args)
83 113 return lastPowerAction
116 + function volumeUp(): string {
117 + return shellOsdOutput("wpctl set-volume -l 1 @DEFAULT_AUDIO_SINK@ 2%+; level=$(wpctl get-volume @DEFAULT_AUDIO_SINK@ | sed 's/^Volume: //'); printf 'Volume %s' \"$level\"", "info")
120 + function volumeDown(): string {
121 + return shellOsdOutput("wpctl set-volume @DEFAULT_AUDIO_SINK@ 2%-; level=$(wpctl get-volume @DEFAULT_AUDIO_SINK@ | sed 's/^Volume: //'); printf 'Volume %s' \"$level\"", "info")
124 + function muteAudio(): string {
125 + return shellOsdOutput("wpctl set-mute @DEFAULT_AUDIO_SINK@ toggle; state=$(wpctl get-volume @DEFAULT_AUDIO_SINK@ | grep -q '\\[MUTED\\]' && echo muted || echo live); printf 'Audio %s' \"$state\"", "info")
128 + function muteMic(): string {
129 + return shellOsdOutput("wpctl set-mute @DEFAULT_AUDIO_SOURCE@ toggle; state=$(wpctl get-volume @DEFAULT_AUDIO_SOURCE@ | grep -q '\\[MUTED\\]' && echo muted || echo live); printf 'Mic %s' \"$state\"", "info")
132 + function brightnessUp(): string {
133 + return shellOsdOutput("brightnessctl -e4 -n2 set 5%+ >/dev/null; level=$(brightnessctl -m | awk -F, '{print $4}'); printf 'Brightness %s' \"$level\"", "warning")
136 + function brightnessDown(): string {
137 + return shellOsdOutput("brightnessctl -e4 -n2 set 5%- >/dev/null; level=$(brightnessctl -m | awk -F, '{print $4}'); printf 'Brightness %s' \"$level\"", "warning")
140 + function mediaNext(): string { return shellOsd("playerctl next", "Next track", "info") }
141 + function mediaToggle(): string { return shellOsd("playerctl play-pause", "Play/pause", "info") }
142 + function mediaPrev(): string { return shellOsd("playerctl previous", "Previous track", "info") }
143 + function reloadHypr(): string { return shellOsd("hyprctl reload", "Hyprland reloaded", "info") }
144 + function sessionLockOsd(): string { fixedOsd("Locking", "info"); lock(); return "Locking" }
145 + function sessionSuspendDryRun(): string { dryRunPower("sleep"); return fixedOsd("Suspending", "info") }
147 + function captureRegion(): string { return shellOsd("uwsm app -s app-graphical.slice -- hyprshot -m region -z", "Region captured", "info") }
148 + function captureWindow(): string { return shellOsd("uwsm app -s app-graphical.slice -- hyprshot -m window -z", "Window captured", "info") }
149 + function captureOutput(): string { return shellOsd("uwsm app -s app-graphical.slice -- hyprshot -m output -z", "Output captured", "info") }
150 + function captureAnnotate(): string { return shellOsd("uwsm app -s app-graphical.slice -- hyprshot -m region -z -- satty --filename", "Screenshot annotated", "info") }
151 + function pickColor(): string { return shellOsd("hyprpicker -a", "Color copied", "info") }
86 153 Process { id: runner }
155 + Process {
156 + id: osdProcess
157 + stdout: StdioCollector {
158 + onStreamFinished: {
159 + const message = this.text.trim()
160 + if (message.length > 0) {
161 + root.lastOsdAction = message
162 + root.osdRequested(message, root.nextOsdTone)
88 168 Process {
89 169 id: clipboardCopy
90 170 onExited: (exitCode, exitStatus) => { root.lastClipboardCopied = exitCode === 0 }

quickshell/nugu/README.md

Modified
151 151 qs ipc -c nugu call nugu lastPowerAction
152 152 qs ipc -c nugu call nugu closePowerMenu
155 +## Phase 4E OSD action IPC
157 +Phase 4E mirrors current `hyprctl notify` wrapper actions behind Quickshell IPC.
158 +Hypr binds are still unchanged until these commands pass live key-event tests.
160 +```sh
161 +qs ipc -c nugu call nugu osdVolumeUp
162 +qs ipc -c nugu call nugu osdVolumeDown
163 +qs ipc -c nugu call nugu osdMuteAudio
164 +qs ipc -c nugu call nugu osdMuteMic
165 +qs ipc -c nugu call nugu osdBrightnessUp
166 +qs ipc -c nugu call nugu osdBrightnessDown
167 +qs ipc -c nugu call nugu osdMediaNext
168 +qs ipc -c nugu call nugu osdMediaToggle
169 +qs ipc -c nugu call nugu osdMediaPrev
170 +qs ipc -c nugu call nugu osdReloadHypr
171 +qs ipc -c nugu call nugu osdSessionLock
172 +qs ipc -c nugu call nugu osdSessionSuspendDryRun
173 +qs ipc -c nugu call nugu osdCaptureRegion
174 +qs ipc -c nugu call nugu osdCaptureWindow
175 +qs ipc -c nugu call nugu osdCaptureOutput
176 +qs ipc -c nugu call nugu osdCaptureAnnotate
177 +qs ipc -c nugu call nugu osdPickColor
178 +qs ipc -c nugu call nugu lastOsdAction
179 +```
181 +`osdSessionSuspendDryRun` records the sleep action and shows the OSD, but does
182 +not suspend. Capture/color IPC uses the existing external tools and must be
183 +validated interactively before bind migration.

quickshell/nugu/shell.qml

Modified
68 68 function showVolumeOsd(level: string): string { return osd.showText(`Volume ${level}`, "info") }
69 69 function showBrightnessOsd(level: string): string { return osd.showText(`Brightness ${level}`, "warning") }
71 + // These IPC methods mirror the current `hyprctl notify` wrapper actions.
72 + // Hypr binds remain unchanged until each replacement is proven live.
73 + function osdVolumeUp(): string { return commandBus.volumeUp() }
74 + function osdVolumeDown(): string { return commandBus.volumeDown() }
75 + function osdMuteAudio(): string { return commandBus.muteAudio() }
76 + function osdMuteMic(): string { return commandBus.muteMic() }
77 + function osdBrightnessUp(): string { return commandBus.brightnessUp() }
78 + function osdBrightnessDown(): string { return commandBus.brightnessDown() }
79 + function osdMediaNext(): string { return commandBus.mediaNext() }
80 + function osdMediaToggle(): string { return commandBus.mediaToggle() }
81 + function osdMediaPrev(): string { return commandBus.mediaPrev() }
82 + function osdReloadHypr(): string { return commandBus.reloadHypr() }
83 + function osdSessionLock(): string { return commandBus.sessionLockOsd() }
84 + function osdSessionSuspendDryRun(): string { return commandBus.sessionSuspendDryRun() }
85 + function osdCaptureRegion(): string { return commandBus.captureRegion() }
86 + function osdCaptureWindow(): string { return commandBus.captureWindow() }
87 + function osdCaptureOutput(): string { return commandBus.captureOutput() }
88 + function osdCaptureAnnotate(): string { return commandBus.captureAnnotate() }
89 + function osdPickColor(): string { return commandBus.pickColor() }
90 + function lastOsdAction(): string { return commandBus.lastOsdAction }
71 92 // Launcher IPC is the future `SUPER+Space` target. It stays opt-in until
72 93 // desktop-entry filtering, keyboard navigation, and app launch are proven.
73 94 function openLauncher(query: string): string { return launcher.show(query) }
96 117 function lastPowerAction(): string { return commandBus.lastPowerAction }
120 + Connections {
121 + target: commandBus
122 + function onOsdRequested(message: string, tone: string): void {
123 + osd.showText(message, tone)
99 127 Loader {
100 128 id: notificationLoader
101 129 active: root.nativeNotificationsEnabled