Wayvibes is a Wayland-native CLI made in C++ that plays mechanical keyboard sounds (or custom sounds) globally on keypresses. It utilizes libevdev to capture keypress events and miniaudio to play sounds.
curl -fsSl https://raw.githubusercontent.com/sahaj-b/wayvibes/main/install.sh | bashInstall wayvibes-git from AUR (maintained by @justanoobcoder).
#using yay
yay -S wayvibes-gitAdd wayvibes url to your inputs:
inputs = {
nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
wayvibes = {
url = "github:sahaj-b/wayvibes";
inputs.nixpkgs.follows = "nixpkgs";
};
};Install wayvibes and enable service using home-manager:
# home.nix
{inputs, ...}: {
imports = [
inputs.wayvibes.nixosModules.default
];
services = {
wayvibes = {
enable = true;
soundpack = "/home/youruser/wayvibes/soundpacks/cherrymx-red-abs";
volume = 5;
};
};
}Ensure the following dependencies are installed:
Ubuntu/debian-based distros:
libevdev-devnlohmann-json*-dev
Install them with:
sudo apt install libevdev-dev nlohmann-json*-dev
Arch-based distros:
libevdevnlohmann-json
Install them with:
sudo pacman -S libevdev nlohmann-json
To install wayvibes, use the following commands:
git clone https://github.com/sahaj-b/wayvibes
cd wayvibes
make
sudo make installcd ~/wayvibes
sudo make uninstallNote
This step is already done if you used the one-liner install script.
- Add user to the
inputgroup by the following command:
sudo usermod -a -G input <your_username>-
Reboot or Logout and Login for the changes to take effect.
-
Run the application:
Usage: wayvibes [options] [soundpack_path]
Options:
--device Select input device
--device-name <name> Use input device by name
-v <volume> Set volume (0.0-10.0) (default: 1.0)
--background, -bg Run in background (detached from terminal)
--help, -h Show this help message;
Note: default soundpack path is `./`(current directory)
wayvibes <soundpack_path> -v <volume(0.0-10.0)>
Note
Use --background/-bg if adding the command to a startup file like .profile
Example:
wayvibes ~/wayvibes/soundpacks/akko_lavender_purples/ -v 3
wayvibes ~/wayvibes/soundpacks/nk-cream/ -v 5 --background- Default Soundpack Path:
./ - Default Volume:
1
Upon the first run, Wayvibes will prompt you to select your keyboard device if there are multiple available. This selection will be stored in:
$XDG_CONFIG_HOME/wayvibes/input_device
Typically, the input device will be something like AT Translated Set 2 keyboard or USB Keyboard. If you use a key remapper like keyd, select its virtual device (e.g., keyd virtual keyboard).
To reset and prompt for input device selection again, use:
wayvibes --deviceIf you use NixOS, you have to restart the service after changing the device.
systemctl --user restart wayvibes.serviceWarning
Do not run the program with sudo/root privileges as it will monopolize the audio device until reboot.
Wayvibes is compatible with the Mechvibes soundpack format, in both flavors:
- V1 (classic Mechvibes):
definesmaps key codes to one wav file per key. - V2 (MechvibesDX): Plays sounds on key down too.
definitionsmaps W3C key names (KeyA,Space, ...) to[start_ms, end_ms]slices inside a singleaudio_file. Pack type is auto-detected, so existing V1 packs keep working untouched.
V2 behavior notes:
timing[0]plays on key press,timing[1]on key release. Keys with a single timing play on press only.options.recommended_volumeis the base volume unless-vis passed (CLI wins).options.random_pitchjitters pitch +-10% per hit.- Mouse packs (
MouseLeft,MouseRight, ...) need the mouse event node passed as the device. Wheel events are ignored (evdev reports those asEV_REL, not key events). definition_method: multiis not sliced. Per-key audio files play whole instead.
You can find soundpacks from the following sources:
- Mechvibes Soundpacks
- MechvibesDX (V2 packs)
- Discord Community (got akko_lavender_purples soundpack from here)
Ready-to-use soundpacks are available in this repository. Just clone the repo and point wayvibes to the pack:
wayvibes ~/wayvibes/soundpacks/nk-cream/ -v 3
wayvibes ~/wayvibes/soundpacks/eg-oreo/ -v 3V1 packs in soundpacks/:
- akko_lavender_purples
- apex pro
- banana split lubed / stock
- boxjade
- cherrymx-red-pbt
- Creams
- kalih-box-white
- mx-speed-silver
- nk-cream
- Razer Green (Blackwidow Elite) - Akira
V2 packs, same directory (mouse packs live in soundpacks/mouse/):
- cherrymx-black-abs / cherrymx-black-pbt
- cherrymx-blue-abs / cherrymx-blue-pbt
- cherrymx-brown-abs / cherrymx-brown-pbt
- cherrymx-red-abs
- eg-crystal-purple
- eg-oreo
- topre-purple-hybrid-pbt
- mouse: chat / ping / vibrate / wooden
Wayvibes uses miniaudio to play sounds, which doesn't support all ogg files by default. If a pack's audio won't decode, wayvibes offers to convert it to wav with ffmpeg on first launch (one-time, updates the pack's config automatically). Or do it by hand:
Converting ogg files to wav using ffmpeg and change extensions in config.json:
cd <soundpack_path>
for f in *.ogg; do ffmpeg -i "$f" "${f%.ogg}.wav"; done && sed -i 's/\.ogg/\.wav/g' config.json
rm *.ogg # remove ogg filesUnlike mechvibes and rustyvibes, which encounter issues on Wayland, Wayvibes aims to provide a seamless integration with wayland.
- wayvibes-tui: A native Rust TUI for Wayvibes (Ratatui). Allows browsing soundpacks, selecting input and output keyboard/audio devices, and start/stop/restart Wayvibes from a nice interface.