hyprwave - v1.1 (STABLE)

A sleek, modern music control bar for Wayland compositors (Hyprland, Niri, Sway, etc.) with MPRIS integration, 14 built-in themes, and dynamic customization.

hyprwave is officially complete!

NEW in v1.0: Dynamic position switching, theme system with 14 pre-made themes, smooth animations for all changes!

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 with 14 built-in themes, or create your own!

Built-in Themes

HyprWave v1.0 includes 14 stunning themes:

mystic-portal - Purple/pink portal with blue depths (default)
nebula - Deep space with orange stars and teal nebulae
octane - Pure black and white minimalist (shown below)
noir-esque - Dark backdrop with cream and gold accents
emerald-splash - Dark forest with bright emerald and mint
pink-europa - Dark silhouettes with pink and peach sunset
glacier - Icy white with glacier blue accents
midnight-city - Dark cityscape with bright blue accents
prismarine-wave - Turquoise ocean waves
pink-punk - Soft pink clouds with hot pink accents
love-sick - Rainy night with hot pink and orange neon
lucid-dreaming - Dark base with vibrant pink/purple/cyan retro
neo-lights - Dark base with multi-color neon accents
deathstar - Dark smoky with silver/cyan racing aesthetic

Switch instantly with hyprwave-toggle set-theme <name>!

OCTANE THEME

Check out THEMES.md to see all 14 themes with previews!

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)

hyprwave-v0.9-update.online-video-cutter.com.mp4

Layout Examples

Right

Top

Bottom

Left

Features

14 Built-in Themes - From minimalist to vibrant, switch themes instantly (NEW in v1.0)
Dynamic Position Switching - Move HyprWave to any edge on-the-fly (NEW in v1.0)
Custom Theme Support - Create and share your own themes easily (NEW in v1.0)
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
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
Dot Matrix Display - 8-bit style scrolling text for vertical layouts
Idle Mode - Automatically morphs into visualizer/display after inactivity
Now Playing Notifications - Elegant slide-in notifications for track changes
Configurable Layout - Position on any screen edge (left, right, top, bottom)
Layer & Exclusive Zone Control - Choose which layer to render on and whether to overlap other surfaces like waybar
Gaming Support - Control music during gameplay without moving mouse
Minimal Resource Usage - ~80-95MB RAM, <0.3% CPU, drops to 20-30MB in idle mode
Dynamic Island Inspired Animation - Smooth morphing transitions between modes

Theme System (NEW in v1.0)

Switch between 14 beautiful pre-made themes instantly:

hyprwave-toggle set-theme nebula      # Deep space theme
hyprwave-toggle set-theme octane      # Minimalist black/white
hyprwave-toggle set-theme glacier     # Icy blue and white
hyprwave-toggle set-theme love-sick   # Hot pink neon

HyprWave will smoothly slide out, apply the new theme, and slide back in with the new colors!

Theme Features:

Instant switching with smooth animations
14 carefully designed color palettes
User themes take priority over system themes
Easy to create your own (see Customization section)
Share themes with the community

Example:-

hyprwave-themeswitch-v0.9.3.mp4

Dynamic Position Switching (NEW in v1.0)

Move HyprWave to any edge without editing config files:

hyprwave-toggle set-position left     # Move to left edge
hyprwave-toggle set-position right    # Move to right edge
hyprwave-toggle set-position top      # Move to top edge
hyprwave-toggle set-position bottom   # Move to bottom edge

Perfect for:

Multi-monitor setups - Move between screens on the fly
Different workflows - Vertical for music focus, horizontal for minimal
Experimenting - Try all positions to find your favorite
Live streaming - Reposition without restarting

Example:-

hyprwave-v0.9.3.mp4

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 Dynamic Island-style morph animations
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 with vertical mode! Features a minimalistic idle mode with:

Scrolling song and artist names
Animated PAUSE and PLAY indicators
Retro 8-bit dot matrix aesthetic
Mouse hover restores control bar
Customizable font (replace VT323 with your own)

Media Control Keybinds

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 media control commands to your preferred keys!

Now Playing Notifications

Smooth slide-in notifications appear in the top-right corner when tracks change, showing album art, song title, and artist.

recording.mp4

Volume Control

Double-click the album cover to reveal the volume slider. Auto-hides after 3 seconds of inactivity.

Installation

Dependencies

# Arch Linux / Manjaro
sudo pacman -S gtk4 gtk4-layer-shell pulseaudio glib-networking

# Ubuntu / Debian
sudo apt install libgtk-4-dev gtk4-layer-shell libpulse-dev glib-networking

# Fedora
sudo dnf install gtk4-devel gtk4-layer-shell-devel pulseaudio-libs-devel glib-networking

Arch(-based)

HyprWave is available on the AUR! Install with:

yay -S hyprwave

The AUR package includes all 14 themes and the latest stable release.

NixOS

Installing the package:

Download the default.nix File.
Add the package to your configuration.nix or flake.nix:

let
  hyprwave = pkgs.callPackage ./path/to/default.nix { };
in
...
environment.systemPackages = with pkgs; [
  hyprwave
];

Rebuild.

Testing the package without installing:

nix run github:shantanubaddar/hyprwave

Building from Source

# 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 all 14 themes to ~/.local/share/hyprwave/themes/
Install hyprwave-toggle script for keybinds
Create config at ~/.config/hyprwave/config.conf

Usage

Quick Start

Install and run HyprWave: hyprwave
Start a music player (Spotify, VLC, etc.)
Control your music with on-screen controls or keybinds
Try different themes: hyprwave-toggle set-theme octane
Change position: hyprwave-toggle set-position bottom

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:

# HyprWave Configuration File

[General]
# Edge to anchor HyprWave to
# Options: right, left, top, bottom
# Note: You can also change this on-the-fly with: hyprwave-toggle set-position <edge>
edge = right

# Margin from the screen edge (in pixels)
margin = 10

# Layer to render on (works on any wlr-layer-shell compositor)
# Options: background, bottom, top, overlay
# Use "top" to stay below fullscreen windows (same layer as waybar)
# Use "overlay" to render above everything including fullscreen
layer = top

# Exclusive zone controls surface overlap behavior
# 0 = respect other surfaces' reserved space (e.g. waybar)
# -1 = overlap everything, ignore other surfaces' exclusive zones
exclusive_zone = 0

[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,firefox,brave

Note: Position and themes can be changed on-the-fly without editing config!

Note: The layer and exclusive_zone options use the wlr-layer-shell protocol and work on any compatible Wayland compositor (Hyprland, Sway, river, wayfire, Niri, etc.) — they are not Hyprland-specific.

Customization

Switching Themes

Change themes instantly:

# Try any of the 14 built-in themes
hyprwave-toggle set-theme nebula
hyprwave-toggle set-theme octane
hyprwave-toggle set-theme midnight-city
hyprwave-toggle set-theme glacier

# List all available themes
hyprwave-toggle set-theme invalid  # Shows theme list

Creating Custom Themes

Create themes directory (AUR users):
```
mkdir -p ~/.local/share/hyprwave/themes
```

Copy a template:

# AUR users
cp /usr/share/hyprwave/themes/mystic-portal.css ~/.local/share/hyprwave/themes/my-theme.css

# Local install users
cd ~/.local/share/hyprwave/themes
cp mystic-portal.css my-theme.css

Edit the CSS variables:
```
nano ~/.local/share/hyprwave/themes/my-theme.css
```
Customize the :root variables:
- Background colors
- Button colors (play, expand, default)
- Progress bar gradients
- Text colors
- Border and shadow effects
- Visualizer bar gradients
Apply your theme:
```
hyprwave-toggle set-theme my-theme
```

Sharing Themes

Share your custom themes with the community!

Upload your .css file to r/hyprwave
Others can download and copy to their themes folder
Popular themes may be included in future releases!

Keybinds

Hyprland

Add to ~/.config/hypr/hyprland.conf:

# HyprWave - Window Controls
bind = SUPER_SHIFT, M, exec, hyprwave-toggle visibility
bind = SUPER, M, exec, hyprwave-toggle expand

# HyprWave - Media Controls
bind = SUPER, P, exec, hyprwave-toggle play
bind = SUPER, PERIOD, exec, hyprwave-toggle next
bind = SUPER, COMMA, exec, hyprwave-toggle prev

# HyprWave - Theme Switching (v1.0)
bind = SUPER_SHIFT, T, exec, hyprwave-toggle set-theme nebula
bind = SUPER_CTRL, T, exec, hyprwave-toggle set-theme octane

# HyprWave - Position Switching (v1.0)
bind = SUPER_SHIFT, LEFT, exec, hyprwave-toggle set-position left
bind = SUPER_SHIFT, RIGHT, exec, hyprwave-toggle set-position right
bind = SUPER_SHIFT, UP, exec, hyprwave-toggle set-position top
bind = SUPER_SHIFT, DOWN, exec, hyprwave-toggle set-position bottom

Reload: hyprctl reload

Niri

Add to ~/.config/niri/config.kdl:

binds {
    // Window Controls
    MOD+SHIFT+M { spawn-sh "hyprwave-toggle visibility"; }
    MOD+M { spawn-sh "hyprwave-toggle expand"; }
    
    // Media Controls
    MOD+P { spawn-sh "hyprwave-toggle play"; }
    MOD+PERIOD { spawn-sh "hyprwave-toggle next"; }
    MOD+COMMA { spawn-sh "hyprwave-toggle prev"; }
    
    // Theme Switching (v1.0)
    MOD+SHIFT+T { spawn-sh "hyprwave-toggle set-theme nebula"; }
    
    // Position Switching (v1.0)
    MOD+SHIFT+LEFT { spawn-sh "hyprwave-toggle set-position left"; }
    MOD+SHIFT+RIGHT { spawn-sh "hyprwave-toggle set-position right"; }
    MOD+SHIFT+UP { spawn-sh "hyprwave-toggle set-position top"; }
    MOD+SHIFT+DOWN { spawn-sh "hyprwave-toggle set-position bottom"; }
}

Reload: niri msg action reload-config

Sway

Add to ~/.config/sway/config:

# Window Controls
bindsym $mod+Shift+M exec hyprwave-toggle visibility
bindsym $mod+M exec hyprwave-toggle expand

# Media Controls
bindsym $mod+P exec hyprwave-toggle play
bindsym $mod+period exec hyprwave-toggle next
bindsym $mod+comma exec hyprwave-toggle prev

# Theme Switching (v1.0)
bindsym $mod+Shift+T exec hyprwave-toggle set-theme nebula

# Position Switching (v1.0)
bindsym $mod+Shift+Left exec hyprwave-toggle set-position left
bindsym $mod+Shift+Right exec hyprwave-toggle set-position right
bindsym $mod+Shift+Up exec hyprwave-toggle set-position top
bindsym $mod+Shift+Down exec hyprwave-toggle set-position bottom

Reload: swaymsg reload

Keybind Demo

4ba1-e63f-425b-bed3-cab944fb7947.mp4

Auto-start

Hyprland:

exec-once = hyprwave

Niri:

spawn-at-startup "hyprwave"

Gaming Support

Control your music during gameplay without touching the mouse!

✅ Works during active gameplay
✅ No mouse needed
✅ Works when hidden
✅ Instant response

Tested Games: Terraria, Cuphead, Fallout New Vegas

Troubleshooting

Black box around HyprWave (Hyprland)

Add to hyprland.conf:

layerrule = noblur, hyprwave
layerrule = noblur, hyprwave-notification

Theme/Position changes not working

Ensure HyprWave is running
Test manually: hyprwave-toggle set-theme nebula
For AUR users: First theme change creates ~/.local/share/hyprwave/

Other Issues

See GitHub Issues for common problems and solutions.

Technical Details

Language: C
GUI: GTK4
Layer Shell: gtk4-layer-shell
Audio: PulseAudio
IPC: D-Bus (MPRIS2)
Memory: ~80-95MB RAM (base), ~100-110MB with visualizer
CPU: <0.3% idle, <2% with visualizer

File Paths

System Install (AUR):

Binary: /usr/bin/hyprwave
System resources: /usr/share/hyprwave/
System themes: /usr/share/hyprwave/themes/
User themes: ~/.local/share/hyprwave/themes/
User CSS: ~/.local/share/hyprwave/style.css

Local Install:

Binary: ~/.local/bin/hyprwave
Resources: ~/.local/share/hyprwave/
Themes: ~/.local/share/hyprwave/themes/

Config: ~/.config/hyprwave/config.conf

Changelog

v1.0 (STABLE - Latest)

NEW: Theme system with 14 pre-made themes
NEW: Dynamic position switching
NEW: Custom theme support
NEW: Smooth animations for all changes
NEW: set-theme and set-position commands
Improved path handling for AUR/local installs
User themes override system themes
STABLE RELEASE - Production ready!

Contributing

Contributions welcome!

GitHub Issues - Report bugs
GitHub Discussions - Feature requests
r/hyprwave - Share themes and rices

License

Open source. Free to use, modify, and distribute.

Acknowledgments

Built with GTK4
Uses gtk4-layer-shell
Audio via PulseAudio
Inspired by waybar

Support

Issues: GitHub Issues
Discussions: GitHub Discussions
Subreddit: r/hyprwave

Name		Name	Last commit message	Last commit date
Latest commit History 77 Commits
.github		.github
fonts		fonts
icons		icons
themes		themes
.gitignore		.gitignore
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
THEMES.md		THEMES.md
art.c		art.c
art.h		art.h
config.conf		config.conf
default.nix		default.nix
flake.lock		flake.lock
flake.nix		flake.nix
hyprwave-toggle.sh		hyprwave-toggle.sh
layout.c		layout.c
layout.h		layout.h
main.c		main.c
morph-animation-system.c		morph-animation-system.c
morph-animation-system.h		morph-animation-system.h
notification.c		notification.c
notification.h		notification.h
paths.c		paths.c
paths.h		paths.h
style-layout.css		style-layout.css
style.css		style.css
vertical_display.c		vertical_display.c
vertical_display.h		vertical_display.h
visualizer.c		visualizer.c
visualizer.h		visualizer.h
volume.c		volume.c
volume.h		volume.h

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

hyprwave - v1.1 (STABLE)

Your Control Bar, Your Imagination

Built-in Themes

OCTANE THEME

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)

Layout Examples

Right

Top

Bottom

Left

Features

Theme System (NEW in v1.0)

Dynamic Position Switching (NEW in v1.0)

Audio Visualizer

Dot Matrix Display

Media Control Keybinds

Now Playing Notifications

Volume Control

Installation

Dependencies

Arch(-based)

NixOS

Building from Source

Usage

Quick Start

Supported Music Players

Configuration

Config File

Customization

Switching Themes

Creating Custom Themes

Sharing Themes

Keybinds

Hyprland

Niri

Sway

Keybind Demo

Auto-start

Gaming Support

Troubleshooting

Black box around HyprWave (Hyprland)

Theme/Position changes not working

Other Issues

Technical Details

File Paths

Changelog

v1.0 (STABLE - Latest)

Contributing

License

Acknowledgments

Support

Stargazers

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 12

Sponsor this project

Uh oh!

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Packages