Waybar Lyric

A waybar module for song lyrics

Important

🔥 Found this useful? A quick star goes a long way.

Description

waybar-lyric fetches and displays real-time lyrics on your Waybar. It provides a scrolling lyrics display that syncs with your currently playing music, enhancing your desktop music experience. Checkout the Example waybar configuration.

Supported Players

waybar-lyric will work with any player that has xesam:album and xesam:artist metadata.

Run playerctl metadata -a to check if your player has those metadata.

I've test these following player:

• Spotify
• Pear-Desktop
• Amarok
• Amberol
• TauonMB
• Firefox (Specific domains)
  • open.spotify.com
  • music.youtube.com
• Chromium with --experimental-chromium-support (Not recommended)!

Features

• Real-time display of the current song's lyrics
• Click to toggle play/pause
• Smart caching system:
  • Stores available lyrics locally to reduce API requests
  • Remembers songs without lyrics to prevent unnecessary API calls
• Custom waybar tooltip
• Configurable maximum text length
• Detailed logging options
• Profanity filter
  • Partial (badword -> b*****d)
  • Full (badword -> *******)

Installation

Prerequisites

• Any of the supported browser
• DBus connectivity
• waybar
• go

Install

AUR

• Latest stable version

yay -S waybar-lyric

• The latest git commit:

yay -S waybar-lyric-git

Nixpkgs

• NixOS:

environment.systemPackages = [
  pkgs.waybar-lyric
];

• Home-Manager:

home.packages = [
  pkgs.waybar-lyric
];

• On Non NixOS:

# without flakes:
nix-env -iA nixpkgs.waybar-lyric

Manual

You need GNU make and install

1. Build the waybar-lyric

git clone https://github.com/Nadim147c/waybar-lyric.git
cd waybar-lyric
make

2. Local install

make install PREFIX=$HOME/.local

3. Global install

sudo make install PREFIX=/usr

go install (Not recommended)

Note: You have to make sure that $GOPATH/bin/ in your system PATH before running waybar.

go install github.com/Nadim147c/waybar-lyric@latest

Configuration

Waybar Configuration

The recommended way to configure waybar-lyric is to generate the configuration snippet using the built-in command:

waybar-lyric init

This will output the proper JSON configuration snippet that you can copy directly into your Waybar config.jsonc file.

Style Example

Add to your style.css:

#custom-lyrics {
  color: #1db954;
  margin: 0 5px;
  padding: 0 10px;
}

#custom-lyrics.paused {
  color: #aaaaaa; /* Set custom color when paused */
}

Troubleshooting

If you encounter issues:

1. Check that any of the supported browser is running is running and connected
2. Run with verbose logging

waybar-lyric -v --log-file=/tmp/waybar-lyric.log

3. Verify DBus connectivity with:

dbus-send --print-reply \
    --dest=org.mpris.MediaPlayer2.spotify \
    /org/mpris/MediaPlayer2 org.freedesktop.DBus.Properties.Get \
    string:org.mpris.MediaPlayer2.Player \
    string:PlaybackStatus

Hacking

Contributions are welcome! Feel free to submit a Pull Request.

License

This repository is licensed under AGPL-3.0.

Thanks To

• SimpMusic for lyrics API.
• BetterLyrics for lyrics API.
• YouLy+ for lyrics API.
• ArchiveTune and vivi-music for providers implementations.