bitzdots

1# Waybar Modules
2 
3Complete documentation for all waybar modules in bitzdots.
4 
5## Layout
6 
7```
8Left:    custom/workspaces | custom/runcat | custom/media
9Center:  clock
10Right:   tray | custom/recording | custom/brightness | pulseaudio |
11         cpu | memory | custom/power-profiles | custom/notification |
12         network | bluetooth | custom/power
13```
14 
15## Custom Modules
16 
17### custom/workspaces
18 
19Batch-based workspace display showing 5 workspaces at a time, centered on the active one.
20 
21- **Script**: `waybar/scripts/workspaces.sh`
22- **Poll interval**: 3 seconds
23- **Icons**: `[N]` = active, `|N|` = occupied, `N` = empty
24- **Click**: Focus workspace (via `workspace-click.sh`)
25- **Scroll**: Cycle workspaces (prev/next)
26 
27### custom/runcat
28 
29CPU activity animation — a running cat that speeds up when CPU is busy.
30 
31- **Script**: `waybar/modules/runcat-text/main.py` (Python)
32- **Output**: JSON with emoji/text animation based on CPU usage
33- **Disable**: Remove from `modules-left` in config.jsonc for low-end systems
34 
35### custom/media
36 
37Now-playing media display with playerctl integration.
38 
39- **Script**: `waybar/scripts/media.sh`
40- **Format**: `icon artist - title` (truncated to 20 chars)
41- **Artists with ": "**: Artist ignored (shows only title for podcast-style metadata)
42- **On startup**: Kills any stale `playerctl metadata --follow` processes to prevent CPU leaks
43- **Click**: Play/Pause
44- **Right click**: Stop
45- **Scroll**: Next/Previous track
46 
47### custom/recording
48 
49Screen recording indicator — blinks when `wf-recorder` is active.
50 
51- **Script**: `waybar/scripts/recording-indicator.sh`
52- **Poll interval**: 10 seconds
53- **Output**: Empty string normally, blinking icon (alternates) when recording
54 
55### custom/brightness
56 
57Display backlight control.
58 
59- **Script**: `waybar/scripts/brightness.sh`
60- **Poll interval**: 5 seconds
61- **Timeout**: 2 seconds on `brightnessctl` calls (prevents hangs)
62- **Icons**: 4 levels (full, high, low, off) + percentage
63- **Scroll**: Adjust brightness by ±5%
64 
65### custom/power-profiles
66 
67UPower power profile management (power-saver / balanced / performance).
68 
69- **Script**: `waybar/scripts/power-profile.sh`
70- **Poll interval**: 30 seconds
71- **Implementation**: Uses `busctl` directly on the UPower D-Bus interface (avoids `powerprofilesctl` which can hang at 100% CPU)
72- **Icons**: 3 levels (performance, balanced, power-saver)
73- **Click**: Cycle to next profile via `power-profile-switch.sh`
74 
75### custom/notification
76 
77Notification center toggle.
78 
79- **Script**: `waybar/scripts/notification.sh`
80- **Poll interval**: 10 seconds
81- **Click**: Toggle notification panel (`swaync-client -t`)
82- **Right click**: Toggle Do Not Disturb (`swaync-client -d`)
83 
84### custom/power
85 
86Power menu trigger.
87 
88- **No script** — uses format + `on-click` directly
89- **Click**: Opens rofi power menu (`system-power.sh`)
90- **Options**: Lock, Logout, Sleep, Reboot, Shutdown, Cancel
91 
92## Built-in Modules
93 
94### clock
95 
96- **Format**: `{:%a %b %d  %I:%M %p}`
97- **Interval**: 30 seconds
98- **Tooltip**: Calendar with date
99 
100### network
101 
102- **Icons**: 󰤨 (WiFi), 󰈀 (ethernet), 󰤮 (disconnected), 󰤭 (no connection)
103- **Format**: `{icon}  {bandwidthDownBits}` / `{bandwidthUpBits}`
104- **Click**: opens `impala` WiFi TUI via `tui-wifi.sh`
105- **Interval**: 10 seconds
106 
107### bluetooth
108 
109- **Icons**: 󰂯 (off), 󰂱 (on, no connection), 󰂲 (connected)
110- **Click**: opens `bluetui` via `tui-bluetooth.sh`
111- **Format**: `{icon}`
112 
113### pulseaudio
114 
115- **Icons**: 󰕾 (high), 󰖀 (mid), 󰕿 (low), 󰝟 (muted)
116- **Format**: `{icon} {volume}%`
117- **Click**: opens `pulsemixer` via `tui-audio.sh`
118- **Scroll**: Volume ±5%
119 
120### cpu
121 
122- **Format**: ` {usage}%`
123- **Click**: opens `btop` via `tui-cpu.sh`
124- **Interval**: 5 seconds
125 
126### memory
127 
128- **Format**: ` {percentage}%`
129- **Click**: opens `btop`
130- **Interval**: 10 seconds
131 
132### tray
133 
134- Standard system tray for background apps
135- Spacing between items: 8px
136 
137## Adding a Custom Module
138 
139```jsonc
140"custom/my-module": {
141  "exec": "~/.config/waybar/scripts/my-script.sh",
142  "interval": 10,
143  "return-type": "json",
144  "on-click": "some-command",
145  "on-scroll-up": "command-up",
146  "on-scroll-down": "command-down"
147}
148```
149 
150The script should output JSON:
151```json
152{"text": "display text", "tooltip": "hover text", "class": "optional-css-class", "alt": "alt-text"}
153```
154 
155## Troubleshooting
156 
157### Module not updating
158 
159```bash
160pkill -x waybar && waybar &
161```
162 
163### Script errors
164 
165Check the waybar logs:
166```bash
167journalctl --user -u waybar -f
168```
169