wshowlyrics
A Wayland-native lyrics overlay with MPRIS integration
Features
Everything you need for a seamless lyrics experience on Wayland
Multi-Format Support
Supports LRCX (karaoke with word-level timing), LRC (line-level), SRT, and VTT subtitle formats. All formats support ruby text (furigana/pinyin) annotations.
Smart Lyrics Search
Automatically searches local directories first, then falls back to online sources (lrclib.net). Full Unicode path support for Korean, Japanese, and Chinese filenames.
Real-time Translation
Translate lyrics on-the-fly using OpenAI, DeepL, Google Gemini, or Anthropic Claude. Smart caching and language detection optimize API usage.
Karaoke Mode
LRCX format enables word-by-word highlighting with progressive fill animation. Visual states for past, current (filling), and future words.
System Tray Integration
Displays album art in your system tray (Waybar/Swaybar compatible). Automatic fallback chain: MPRIS metadata, iTunes API, or default icon.
MPRIS Integration
Works with all major music players: mpv, Spotify, VLC, Rhythmbox, Audacious, and any MPRIS-compatible player via playerctl.
Screenshots
See wshowlyrics in action
Installation
Choose your preferred installation method
Arch Linux (AUR)
Install stable release or development version from AUR:
# Stable release
yay -S wshowlyrics
# Development (git)
yay -S wshowlyrics-git
Ubuntu / Debian (PPA)
Add the PPA and install:
sudo add-apt-repository ppa:unstable-code/wshowlyrics
sudo apt update
sudo apt install wshowlyrics
Fedora (COPR)
Enable the COPR repository and install:
# Stable releases
sudo dnf copr enable unstable-code/wshowlyrics
sudo dnf install wshowlyrics
# Nightly builds (latest development)
sudo dnf copr enable unstable-code/wshowlyrics-nightly
sudo dnf install wshowlyrics
Build from Source
Note: This application requires Linux with Wayland.
Clone and build with Meson:
git clone https://github.com/unstable-code/lyrics.git
cd lyrics
meson setup build
meson compile -C build
# Install (optional)
sudo meson install -C build
See README for required dependencies.
Compositor Compatibility
Uses wlr-layer-shell-unstable-v1 Wayland protocol
Officially Tested
Sway and KDE Plasma (5.27+) are fully supported and tested.
Other Compositors
Hyprland, river, wayfire, and other wlr-layer-shell compositors may work, but are not officially tested and may have stability issues.
Configuration
Customize wshowlyrics to your preferences
Example Configuration
Configuration file: ~/.config/wshowlyrics/settings.ini
[display]
font = Noto Sans CJK KR 24
active_color = FFD700FF
background_color = 00000099
anchor = bottom
margin = 50
[translation]
provider = gemini-2.5-flash
target_language = en
display_mode = both