Conky Lyrics Widget

This is a conky config that displays the title, artist, and lyrics (from genius.com) of a track, as well as some system data.

Installation

1. First of all you need conky (and playerctl).

# with apt
sudo apt update
sudo apt install conky-all playerctl

# with pacman
sudo pacman -Syu conky playerctl

# with dnf
sudo dnf install conky playerctl

2. Clone repository

# clone it directly into ~/.config/conky
git clone https://github.com/bvbxbv/conky-lyrics-widget.git ~/.config/conky

3. Install python requirements

cd ~/.config/conky
pip install -r requirements.txt

Pip will install:

• LyricsGenius - nice python api wrapper for getting lyrics (not only lyrics) from genius.
• tomli (or not if you have python greater than 3.11)

4. Genius api settings
   1. First of all you need an api key.
      Go to https://genius.com/developers and click on "Create API CLIENT".
      1. Enter app name (whatever)
      2. Icon url is not required
      3. App website url - i wrote http://localhost and it works
      4. Redirect url is not required
   2. Put api key into config file.
      1. Find ~/.config/conky/configs/secret.toml.copy (or where you clone this repo).
      2. Remove .copy (secret.toml.copy -> secret.toml).
      3. Paste your api key instead of YOUR GENIUS API KEY.

Usage

Running

To run conky you just need run conky and specify path to config:

conky -c ~/.config/conky/conky.conf

If you want set conky as startup app:

• GUI - just find in your system something like "Startup Applications" (in Pop!_OS)

  1. Click "Add"
  2. Write name of your task (any)
  3. In textbox "Command" write something like this:

  # if you don't want delay before launching script, then remove "sleep 5;"
  bash -c "sleep 5; conky -c /home/$USER/.config/conky/conky.conf > /home/$USER/.config/conky/conky.log 2>&1"

• Systemd service

  In this case conky may start earlier than GNOME session

  1. Create unit file with this content

  # creating
  sudo nano /etc/systemd/system/conky-music.service

  NOTE: replace $USER with your username. Systemd hate your path environment variables.

  # content
  [Unit]
  Description=Conky Music + Lyrics Widget
  After=graphical.target
  
  [Service]
  Type=simple
  User=$USER
  Environment=DISPLAY=:0
  ExecStart=/usr/bin/conky -c /home/$USER/.config/conky/conky.conf
  Restart=on-failure
  WorkingDirectory=/home/$USER/.config/conky
  
  [Install]
  WantedBy=default.target

  2. Reboot systemd and enable your service

  sudo systemctl daemon-reload
  sudo systemctl enable --now conky-music.service

  3. Check status (Optional)

  systemctl status conky-music.service
  journalctl -u conky-music.service -f

Customisation

Everything you need in config/settings.toml. If you want to remove something or add, then look at generate_conky.py. It's script which needed to make conky and toml configs best friends.

If you need more info about conky features and customisation tricks then look at:

• Official conky Github
• Official conky site

Scripts settings

Options which using only in python scripts.

• fill_lines - number of lines which returns python script.
• lyrics_area_height - number of lines of track lyrics. 38 works perfectly on 1920x1080
• skip_if_contains - lyrics may have line contributors or links. If it is, then remove that line.

LyricsGenius

Settings for LyricsGenius instance.

• verbose - better set false, because LyricsGenius write starting downloading and things like that.
• skip_non_songs - better set false, because LyricsGenius may return not only track (e.g. track list)
• excluded terms - exclude songs with these words in their title.
• remove_section_header - remove headers like [CHORUS], [VERSE] and so on

text

Settings for text formatting

• append_before - character for indentation (by default it's whitespace).
• padding_left - number of characters to indent from left.

intervals

Update time settings.

• title_update_interval - interval to update track title
• time_update_interval - interval to update track time (current and length)
• lyrics_update_interval - interval to call python script. There's no caching yet. That's a problem.

display

Output text

• empty_filler - character after indentation. ~ is pretty good.
• lyrics_not_found - script returns it when page lyrics status is 404.
• player_idle - if playerctl doesnt returns player, then conky prints it.
• timer_delimiter - delimiter between current time and track length (00:00/2:28 - timer_delimiter is /).

Conky settings

window

These configs can be found on conky website

music

• title_max_length - max number of track title characters. If length of track title greater than title_max_length then conky prints "..."

sections

Section titles

• music_section_title - title of music info block
• system_section_title - title of system info block
• memory_section_title - title of memory info sub block
• cpu_section_title - title of cpu info sub block

How it works?

• Conky config file get all data about track from playerctl (title, artist, position).
• Loads from genius with LyricsGenius api wrapper lyrics. If script didnt found lyrics its prints lyrics_not_found (you can customise it in configs/settings.toml)
• Displays system info with conky stuffs (RAM/Swap usage, uptime, CPU cores load, and simple graph)

Features

• customizable with configs/settings.toml.

Issues

• no caching yet. Conky every time launches python script which send api request
• desinc between updating track title and lyrics.
• conky freezes when script sends api request.

To do

• album cover and album name output.

Requirements

• Linux with playerctl installed
• Python 3.10.12 (just because i used them)
• Python packages (i hope you already installed them with pip (if you're not then install))
  • LyricsGenius
  • tomli (if you have python greater than 3.11 then you good)

License

MIT. Do whatever you want.

Credits

It was useful for me:

• Conky GitHub - https://github.com/brndnmtthws/conky
• Conky Website - https://conky.cc/
• Lyrics Genius python package - https://github.com/johnwmillr/LyricsGenius
• Genius - https://genius.com/
• Genius API - https://docs.genius.com/
• Linux playerctl github - https://github.com/altdesktop/playerctl
• Linux systemd github - https://github.com/systemd/systemd
• Linux systemd website - https://systemd.io/