https://github.com/shantanubaddar/hyprwave
A music control bar for hyprland
https://github.com/shantanubaddar/hyprwave
dotfile gtk4 hyprland linux mango mpris music niri setup setup-shell spotify unix unixporn waybar
Last synced: 4 months ago
JSON representation
A music control bar for hyprland
- Host: GitHub
- URL: https://github.com/shantanubaddar/hyprwave
- Owner: shantanubaddar
- Created: 2026-01-01T07:48:53.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2026-01-05T18:02:01.000Z (5 months ago)
- Last Synced: 2026-01-08T00:56:47.232Z (5 months ago)
- Topics: dotfile, gtk4, hyprland, linux, mango, mpris, music, niri, setup, setup-shell, spotify, unix, unixporn, waybar
- Language: C
- Homepage:
- Size: 88.9 KB
- Stars: 17
- Watchers: 0
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# hyprwave - v0.9.2 (latest release)
A sleek, modern music control bar for Wayland compositors (Hyprland, Niri, Sway, etc.) with MPRIS integration.
Updates till now: Multi-Anchor support, Notifications, Music Controls, CSS Styling (control bar, expanded section and notifications), launching it as an application, huge UI bug fixing, ability to seek to different song parts via click or drag and click, volume controls, audio visualizer with idle mode animation (for horizontal mode), 8-bit dot matrix info bar with idle mode animation (for vertical layouts).
Dynamic Island Inspired Animation added between visualizer and control bar transformations. All visual bugs fixed. Direct media control keybinds for keyboard-only/gaming use.
Built and primarily tested on Niri, for all Wayland compositors that support GTK4 and GTK4-layer-shell.
Check out the subreddit for posting your rices, themes, favorite albums -> https://www.reddit.com/r/hyprwave/
# Your Control Bar, Your Imagination
Style hyprwave to your taste via the style.css!
## OCTANE THEME
Check out THEMES.md to get the theme, and more!
## Screenshots & GIFs
### Vertical Layout
### Horizontal Layout
### Audio Visualizer (Idle Mode - Horizontal)
#### Top Bar
#### Bottom Bar
#### Transition from control bar to visualizer bar
### Dot Matrix Display (Idle Mode - Vertical)
https://github.com/user-attachments/assets/c4e84d3c-c93f-4bfe-b5e9-f7888b3b8b53
### Layout Examples
#### Right
#### Top
#### Bottom
#### Left
## Features
- **Elegant Design** - Glassmorphic UI with smooth animations
- **MPRIS Integration** - Works with Spotify, VLC, and any MPRIS-compatible player
- **Album Art Display** - Fetches and displays album artwork
- **Live Progress Tracking** - Real-time progress bar with countdown timer
- **Full Playback Controls** - Play/Pause, Next, Previous buttons
- **Media Control Keybinds** - Direct keyboard shortcuts for play/pause, next, previous (NEW in v0.9.2)
- **Expandable Panel** - Toggle to reveal detailed track information
- **Volume Control** - Double-click album cover to show/hide volume slider
- **Audio Visualizer** - Real-time audio visualization with idle mode animation
- **Idle Mode** - Automatically morphs into visualizer after inactivity
- **Now Playing Notifications** - Elegant slide-in notifications for track changes
- **Configurable Layout** - Position on any screen edge (left, right, top, bottom)
- **Keybind Support** - Hide/show, expand, and media controls with keyboard shortcuts
- **Gaming Support** - Control music during gameplay without moving mouse (NEW in v0.9.2)
- **Minimal Resource Usage** - ~80-95MB RAM, <0.3% CPU, on idle mode, drops to 20-30MB RAM.
- **Dynamic Island inspired animation** - Control bar morphs into idle mode bars via smooth animations
### Audio Visualizer
The visualizer captures your system audio playback and displays real-time frequency bars. After a configurable period of inactivity (default: 5 seconds), HyprWave automatically transitions from the control bar to an animated visualizer. Mouse movement restores the control buttons.
Features:
- Real-time audio frequency visualization
- Smooth fade animations between modes
- Configurable idle timeout
- Option to disable visualizer completely
- Works only in horizontal layouts (top/bottom edges)
### Dot Matrix Display
Ever felt nostalgic about old mp3 players? Revive it back with vertical mode, with a minimalistic idle mode, scrolling name of song and artist name, PAUSE animations and PLAY animations. Mouse hover restores it back to the control bar. Also, if you don't want the dot matrix font, you are free to replace it with any other font, just place it in the same place as the VT323 font where it is placed after install, and fix the size of font in style.css if needed.
### Media Control Keybinds (NEW in v0.9.2)
Control your music without touching the mouse! Perfect for:
- **Gaming** - Skip tracks during gameplay without interrupting
- **Keyboard-only workflows** - No need to move your hand to the mouse
- **Quick access** - Instant play/pause, next, previous from any app
Simply bind the new media control commands to your preferred keys and control music from anywhere!
### Collapsed State
The control bar sits on your chosen screen edge with essential controls.
### Expanded State
Shows album cover, track title, artist, progress bar, and time remaining.
### Now Playing Notifications
Smooth slide-in notifications appear in the top-right corner when tracks change, showing album art, song title, and artist.
### Volume Control
Double-click the album cover to reveal the volume bar. The volume bar auto-hides after 3 seconds of inactivity or when you collapse the expanded state.
## Installation
### Dependencies
```bash
# Arch Linux / Manjaro
sudo pacman -S gtk4 gtk4-layer-shell pulseaudio
# Ubuntu / Debian
sudo apt install libgtk-4-dev gtk4-layer-shell libpulse-dev
# Fedora
sudo dnf install gtk4-devel gtk4-layer-shell-devel pulseaudio-libs-devel
```
### Arch(-based)
Also, Massive update - hyprwave is now on AUR.
Simply install it with:
```bash
yay -S hyprwave
```
It will not give you the bleeding new updates, but the latest releases.
### NixOS
Installing the package:
1. Download the `default.nix` File.
2. Add the package to your `configuration.nix` or `flake.nix`:
```nix
let
hyprwave = pkgs.callPackage ./path/to/default.nix { };
in
...
environment.systemPackages = with pkgs; [
hyprwave
];
```
3. Rebuild.
Testing the package without installing:
1. Run `nix run github:shantanubaddar/hyprwave`.
### Building from Source
```bash
# Clone the repository
git clone https://github.com/shantanubaddar/hyprwave.git
cd hyprwave
# Build and install
make
make install
```
The installer will:
- Copy binary to `~/.local/bin/hyprwave`
- Install resources to `~/.local/share/hyprwave/`
- Install `hyprwave-toggle` script for keybinds
- Create config at `~/.config/hyprwave/config.conf`
## Usage
### Quick Start
1. **Install and run HyprWave**: `hyprwave`
2. **Start a music player** (Spotify, VLC, etc.)
3. **Control your music** with the on-screen controls or keybinds
4. **Use keybinds** for quick access (see configuration below)
### Supported Music Players
Fully Supported:
- Spotify (Desktop app)
- VLC Media Player
- Any MPRIS2-compatible player (Rhythmbox, Audacious, MPD with mpDris2, etc.)
Limited Support:
- Web browsers - Basic controls only, limited metadata
## Configuration
### Config File
Edit `~/.config/hyprwave/config.conf`:
```conf
# HyprWave Configuration File
[General]
# Edge to anchor HyprWave to
# Options: right, left, top, bottom
edge = right
# Margin from the screen edge (in pixels)
margin = 10
[Notifications]
enabled = true
now_playing = true
[Visualizer]
# Enable/disable visualizer (horizontal layout only)
enabled = true
# Idle timeout in seconds before visualizer appears
# Set to 0 to disable auto-activation
idle_timeout = 5
[VerticalDisplay]
enabled=true
idle_timeout=5
[MusicPlayer]
preference = spotify,vlc
```
**Layout Options:**
- **`edge = right`** - Vertical layout on right edge (default)
- **`edge = left`** - Vertical layout on left edge
- **`edge = top`** - Horizontal layout on top edge
- **`edge = bottom`** - Horizontal layout on bottom edge
**Notification Options:**
- **`enabled = true`** - Master switch for all notifications
- **`now_playing = true`** - Show "Now Playing" notifications when tracks change
**Visualizer Options:**
- **`enabled = true`** - Enable audio visualizer (horizontal layouts only)
- **`idle_timeout = 5`** - Seconds of inactivity before visualizer appears (0 to disable)
**Dot Matrix Display Options:**
- **`enabled = true`** - Enable audio visualizer (vertical layouts only)
- **`idle_timeout = 5`** - Seconds of inactivity before display appears (0 to disable)
**Music Player:**
Still being developed, however, if you are a spotify user, don't worry about it. Your experience will be smooth all around.
### How Notifications Will Appear
https://github.com/user-attachments/assets/7328c91b-c9fa-43ac-a8fd-8c63c9b676d3
### Keybinds
HyprWave supports keybinds for toggling visibility, expanding details, and controlling media playback. Add these to your compositor config:
#### Hyprland
Add to `~/.config/hypr/hyprland.conf`:
```conf
# HyprWave - Window Controls
bind = SUPER_SHIFT, M, exec, hyprwave-toggle visibility
bind = SUPER, M, exec, hyprwave-toggle expand
# HyprWave - Media Controls (NEW in v0.9.2)
bind = SUPER, P, exec, hyprwave-toggle play
bind = SUPER, PERIOD, exec, hyprwave-toggle next
bind = SUPER, COMMA, exec, hyprwave-toggle prev
```
Then reload: `hyprctl reload`
#### Niri
Add to `~/.config/niri/config.kdl`:
```kdl
binds {
// HyprWave - Window Controls
MOD+SHIFT+M { spawn-sh "hyprwave-toggle visibility"; }
MOD+M { spawn-sh "hyprwave-toggle expand"; }
// HyprWave - Media Controls (NEW in v0.9.2)
MOD+P { spawn-sh "hyprwave-toggle play"; }
MOD+PERIOD { spawn-sh "hyprwave-toggle next"; }
MOD+COMMA { spawn-sh "hyprwave-toggle prev"; }
}
```
Then reload: `niri msg action reload-config`
#### Sway
Add to `~/.config/sway/config`:
```conf
# HyprWave - Window Controls
bindsym $mod+Shift+M exec hyprwave-toggle visibility
bindsym $mod+M exec hyprwave-toggle expand
# HyprWave - Media Controls (NEW in v0.9.2)
bindsym $mod+P exec hyprwave-toggle play
bindsym $mod+period exec hyprwave-toggle next
bindsym $mod+comma exec hyprwave-toggle prev
```
Then reload: `swaymsg reload`
#### Alternative: Media Keys
If you have dedicated media keys, you can map them directly:
**Hyprland:**
```conf
bind = , XF86AudioPlay, exec, hyprwave-toggle play
bind = , XF86AudioNext, exec, hyprwave-toggle next
bind = , XF86AudioPrev, exec, hyprwave-toggle prev
```
**Niri:**
```kdl
XF86AUDIOPLAY { spawn-sh "hyprwave-toggle play"; }
XF86AUDIONEXT { spawn-sh "hyprwave-toggle next"; }
XF86AUDIOPREV { spawn-sh "hyprwave-toggle prev"; }
```
#### What the Keybinds Do:
**Window Controls:**
- **Toggle Visibility** (`Super+Shift+M`) - Smoothly hides/shows entire HyprWave with slide animation
- **Toggle Expand** (`Super+M`) - Shows/hides album details
- Works even in visualizer mode - expanded section appears without exiting idle mode
- If HyprWave is hidden, this will show it AND expand in one smooth motion
**Media Controls (NEW in v0.9.2):**
- **Play/Pause** (`Super+P`) - Toggle playback
- **Next Track** (`Super+Period`) - Skip to next track
- **Previous Track** (`Super+Comma`) - Go to previous track
These media controls work from anywhere - even during gameplay or when HyprWave is hidden!
### Keybind Demo
https://github.com/user-attachments/assets/5bd27ec4-6b51-46fb-bf6e-fcb3cb3252b1
### Auto-start
#### Hyprland
Add to `~/.config/hypr/hyprland.conf`:
```conf
exec-once = hyprwave
```
#### Niri
Add to `~/.config/niri/config.kdl`:
```kdl
spawn-at-startup "hyprwave"
```
## Gaming Support
HyprWave v0.9.2 adds perfect gaming integration! Control your music during gameplay without touching the mouse:
- ✅ **Works during active gameplay** - Media keybinds function even when games have focus
- ✅ **No mouse needed** - Keep hands on keyboard/controller
- ✅ **Works when hidden** - Control music even if HyprWave is minimized
- ✅ **Instant response** - Direct MPRIS control with no lag
Simply set up the media control keybinds (see Keybinds section above) and press them during gameplay to skip tracks, pause music, or go back!
**Tested Games:**
- Terraria
- Cuphead
- Fallout New Vegas
## Troubleshooting
### Black box around HyprWave (Hyprland)
If you see a black box around HyprWave, disable blur for the overlay:
Add to `hyprland.conf`:
```conf
layerrule = noblur, hyprwave
layerrule = noblur, hyprwave-notification
```
If that doesn't work, it's most probably a broken gtk4 or gtk4-layer-shell package - just remove them, reinstall them, and try again.
Refer to Issues for a more precise explanation.
### Visualizer not working
1. Ensure PulseAudio is running: `pulseaudio --check`
2. Check that visualizer is enabled in config: `enabled = true` under `[Visualizer]`
3. Visualizer only works in horizontal layouts (top/bottom edges)
4. Check console output for PulseAudio connection errors
### Notifications not appearing
1. Check that notifications are enabled in `~/.config/hyprwave/config.conf`
2. Verify both `enabled = true` and `now_playing = true` under `[Notifications]`
3. Restart HyprWave after config changes
### Keybinds not working
1. Verify `hyprwave-toggle` is installed: `which hyprwave-toggle`
2. Test manually: `hyprwave-toggle play` (with HyprWave running and music playing)
3. Check your compositor config for syntax errors
4. Reload your compositor config after adding keybinds
5. For media keybinds: Ensure HyprWave is running and connected to a music player
### Album art not loading
HyprWave requires the music player to provide album art URLs via MPRIS. Desktop apps work better than web browsers for this.
## Technical Details
- **Language:** C
- **GUI Framework:** GTK4
- **Layer Shell:** gtk4-layer-shell (Wayland overlay)
- **Audio:** PulseAudio (for visualizer)
- **IPC:** D-Bus (MPRIS2 protocol)
- **Memory:** ~80-95MB RAM (base), ~100-110MB with visualizer active
- **CPU:** <0.3% idle, <1% during updates, <2% with visualizer
### File Paths
Resources are searched in this order:
1. Local directory: `./icons/`, `./style.css` (for development)
2. User install: `~/.local/share/hyprwave/`
3. System install: `/usr/share/hyprwave/`
Config: `~/.config/hyprwave/config.conf`
## Changelog
### v0.9.2 (Latest)
- **NEW:** Media control keybinds (play/pause, next, previous)
- **NEW:** Gaming support - control music during gameplay
- **NEW:** Direct MPRIS control via keyboard shortcuts
- Improved keyboard-only workflow support
## Roadmap
### v1.0.0 (Goals)
- Theming system with pre-built themes
- Custom dimensions and colors via config
## Contributing
Contributions welcome! Feel free to:
- Report bugs via [GitHub Issues](https://github.com/shantanubaddar/hyprwave/issues)
- Submit feature requests
- Create pull requests
- Share your custom themes/icons
## License
Open source. Free to use, modify, and distribute.
## Acknowledgments
- Built with [GTK4](https://gtk.org/)
- Uses [gtk4-layer-shell](https://github.com/wmww/gtk-layer-shell)
- Audio capture via [PulseAudio](https://www.freedesktop.org/wiki/Software/PulseAudio/)
- Inspired by [waybar](https://github.com/Alexays/Waybar)
- MPRIS specification by [freedesktop.org](https://www.freedesktop.org/)
## Support
- **Issues:** [GitHub Issues](https://github.com/shantanubaddar/hyprwave/issues)
- **Discussions:** [GitHub Discussions](https://github.com/shantanubaddar/hyprwave/discussions)
- **Subreddit:** [r/hyprwave](https://www.reddit.com/r/hyprwave/)
## Stargazers
[](https://star-history.com/#shantanubaddar/hyprwave&Timeline)