Spotiverse

A GTK lyrics companion for Spotify with synced, Spotify-style lyrics.
Report Bug · Request Feature

Table of Contents

1. About The Project
   • Built With
2. Getting Started
   • Prerequisites
   • Installation
   • API Keys
3. Usage
4. Roadmap
5. Contributing
6. License
7. Contact
8. Acknowledgments

About The Project

Spotiverse is a fork of verse, a small Linux desktop app that fetches lyrics for the song currently playing on Spotify.

This fork reshapes the experience around a Spotify-like lyric display:

• Synced lyrics when timestamped LRC lyrics are available
• Explicit lyrics visibility toggle for tracks marked explicit
• Automatic updates when the current Spotify track changes
• Spotify Web API or MPRIS playback source detection
• Playback-aware lyric highlighting and centered active lines
• Dark, full-window lyric presentation
• Keyboard zoom with Ctrl++ and Ctrl+-
• Local .env support for Spotify and Genius credentials
• Configurable Spotify callback port with SPOTIFY_REDIRECT_URI

(back to top)

Built With

• Python
• GTK 4
• libadwaita
• WebKitGTK
• Meson
• Spotipy
• lyricsgenius
• syncedlyrics

(back to top)

Getting Started

These instructions set up a local development build.

Prerequisites

On Debian, Ubuntu, Mint, or similar:

sudo apt install meson ninja-build python3-pip python3-setuptools libgtk-4-dev libadwaita-1-dev libwebkitgtk-6.0-dev libsecret-1-dev

Install Python dependencies:

python3 -m pip install --user -r requirements.txt

Some distributions protect the system Python environment. If pip reports an externally managed environment, use a virtual environment or your distribution packages instead.

Installation

Clone the fork:

git clone https://github.com/wispdevon/Spotiverse.git
cd Spotiverse

Create your local environment file:

cp .env.example .env

Build and install into a local prefix:

meson setup _build --prefix "$PWD/_install"
meson compile -C _build
meson install -C _build

Run the local build:

GSETTINGS_SCHEMA_DIR="$PWD/_install/share/glib-2.0/schemas" "$PWD/_install/bin/spotiverse"

You can also build through GNOME Builder or install through Flatpak Builder:

flatpak-builder --force-clean _flatpak/ io.github.wispdevon.Spotiverse.json --user --install
flatpak run io.github.wispdevon.Spotiverse

(back to top)

API Keys

Spotiverse needs Spotify API credentials and a Genius access token.

Add these values to .env:

SPOTIFY_CLIENT_ID=
SPOTIFY_CLIENT_SECRET=
SPOTIFY_REDIRECT_URI=http://127.0.0.1:53682
GENIUS_TOKEN=

In the Spotify Developer Dashboard, add the exact redirect URI from SPOTIFY_REDIRECT_URI.

For more detail, see wiki/README.md.

After the app starts, open Preferences with Ctrl+O and generate the Spotify refresh token.

If you prefer to detect tracks from a local media player, open Preferences and switch Playback Source to MPRIS player. You can leave the player on Automatic or choose a specific MPRIS-enabled player.

(back to top)

Usage

1. Start Spotify and play a track.
2. Launch Spotiverse.
3. If credentials are not configured yet, press Ctrl+O to open Preferences.
4. Generate the Spotify refresh token.
5. Return to the lyrics window.

Useful shortcuts:

• Ctrl+O: Open Preferences
• Ctrl+R: Refresh the current track
• Ctrl++: Increase lyric font size
• Ctrl+-: Decrease lyric font size
• Ctrl+Q: Quit

If synced lyrics are found, the active line follows the current Spotify playback position. If no synced lyrics are available, Spotiverse falls back to regular Genius lyrics.

Use the Show explicit lyrics preference to choose whether lyrics appear for tracks Spotify marks as explicit.

(back to top)

Roadmap

• Improve synced lyric provider matching and fallbacks
• Add a small in-window control surface for refresh, preferences, and zoom
• Persist lyric zoom preferences
• Add screenshots for the synced lyrics view
• Package the fork under its own app ID

See the open issues for proposed features and known issues.

(back to top)

Contributing

Contributions are welcome.

1. Fork the project
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a pull request

(back to top)

License

Distributed under the Apache-2.0 License. See COPYING for more information.

(back to top)

Contact

Project Link: https://github.com/wispdevon/Spotiverse

Upstream Project: https://github.com/TanmayPatil105/verse

(back to top)

Acknowledgments

• Tanmay Patil for the original verse project
• Spotify Web API
• Genius API
• LRCLIB
• Best-README-Template

(back to top)