waybar-timer

A high-performance, native Go timer & stopwatch custom module for Waybar.

Features

• Stopwatch Mode: Count up elapsed time in T MM:SS or T HH:MM:SS format.
• Countdown Mode: Count down in T-MM:SS format with quick presets (15 min, 30 min, 45 min, 60 min) or custom durations.
• Audio Alarm & Notification: Plays a sound alert and dispatches desktop notification when countdown finishes.
• Interactive Wofi Menu: Middle-click or run waybar-timer menu to select presets or custom times.
• Real-Time Waybar Signaling: Immediate bar updates via RTMIN+5.
• Custom CSS Classes: running, countdown-running, countdown-finished, paused, stopped.

Building & Installing

Build the binary:

go build -o waybar-timer main.go

Or install directly to $GOBIN (~/go/bin):

go install

To place the binary where Waybar can execute it (e.g. ~/.local/bin or ~/.config/waybar/scripts):

mkdir -p ~/.config/waybar/scripts ~/.local/bin
cp waybar-timer ~/.config/waybar/scripts/
cp waybar-timer ~/.local/bin/

Controls

• Left-Click: Start / Pause
• Middle-Click: Open Timer Menu (Presets & Settings)
• Right-Click: Reset

Waybar Configuration

"custom/timer": {
  "exec": "$HOME/.config/waybar/scripts/waybar-timer",
  "on-click": "$HOME/.config/waybar/scripts/waybar-timer toggle",
  "on-click-middle": "$HOME/.config/waybar/scripts/waybar-timer menu",
  "on-click-right": "$HOME/.config/waybar/scripts/waybar-timer reset",
  "return-type": "json",
  "interval": 1,
  "signal": 5,
  "tooltip": true
}

CLI Usage

waybar-timer               # Display current state JSON
waybar-timer toggle        # Toggle start/pause
waybar-timer reset         # Reset timer
waybar-timer menu          # Launch Wofi preset menu
waybar-timer mode          # Toggle between Stopwatch & Countdown mode
waybar-timer 15m           # Set 15-minute countdown
waybar-timer 30m           # Set 30-minute countdown
waybar-timer set 45        # Set 45-minute countdown
waybar-timer set 1h30m     # Set custom 1 hour 30 min countdown

Why Restructure to Go?

Originally implemented as a Python script (waybar-stopwatch), the project was restructured into native Go (waybar-timer) for several key advantages:

1. Ultra-Low Latency Execution:
   • Running Python scripts on interval polling incurs process startup and interpreter initialization overhead (~20–40ms).
   • The compiled Go binary executes natively in ~1ms, minimizing CPU and RAM footprint during continuous Waybar ticks.
2. Asynchronous & Non-Blocking Goroutines:
   • Sound playback and desktop notifications run in non-blocking background goroutines without delaying status rendering back to Waybar.
3. Single Dependency-Free Binary:
   • Compiles down to a standalone binary with zero Python environment or runtime dependencies.
4. Expanded Scope:
   • Restructured from a pure stopwatch into a unified timer module supporting both count-up stopwatches and preset/custom countdown timers.