SyncLyrics

A real-time synced lyrics server that can run on multiple platforms and serves beautiful lyrics to any device with a web-browser.

The app's philosophy is simple: configure it once and let it run in the background all the time. When you're not listening to music; it does nothing. When you are; it activates and shows you lyrics + album art + rich metadata.

This started as a hobby project where I just wanted real-time lyrics on any of my tablet devices, but has grown to be a feature-rich self-hosted lyrics server. SyncLyrics is a visual companion to all music, anywhere.

Supported Platforms: Windows, Home Assistant, Docker, Linux, macOS (unsigned)

Supported Audio Sources: Spotify, Windows Media (SMTC), Music Assistant, Audio Recognition (Shazam), Linux, macOS, and Spicetify.

Main UI

Minimal Mode can be accessed by adding ?minimal=true to the URL

https://github.com/user-attachments/assets/7a2f5456-1618-4532-9d77-46dfd9bfbafa

Video demo showcasing the app's main features

More Screenshots

✨ Features

🎵 Lyrics

• 5 Providers: Spotify, LRCLib, Musixmatch, NetEase, QQ Music
• Word-Sync (Karaoke): Highlights each word as it's sung
• Parallel Search: Queries all providers simultaneously for fastest results
• Local Caching: Saves lyrics offline for instant future access
• Provider Selection: Manually choose your preferred provider per song
• Instrumental Detection: Automatically detects and marks instrumental tracks

🎨 Visual Modes

• Background Styles: Sharp, Soft, and Blur modes for album art display
• Visual Mode: Activates during instrumentals with optional artist image slideshow
• Album Art Database: Caches high-quality art from iTunes, Spotify and LastFM (requires API key)
• Artist Images: Fetches from Deezer, FanArt.tv, TheAudioDB, Spotify

🎤 Audio Recognition

• Shazam-Powered: Identify any song playing through your speakers or microphone
• Two Capture Modes:
  • Backend: Captures system audio via loopback device
  • Frontend: Uses browser microphone (requires HTTPS)
• Reaper DAW Integration: Auto-detects Reaper and starts recognition

🎛️ Playback Controls

• Play/Pause, Next, Previous track controls
• Like/Unlike tracks (Spotify)
• View playback queue
• Seek bar with progress display
• Waveform seekbar with audio analysis visualization (Spicetify Required)
• Spectrum visualizer (Spicetify Required)
• Keyboard shortcuts: Space, arrows, and letter keys for quick control

📚 Media Browser

• Embedded library browser for Spotify and Music Assistant
• Browse playlists, albums, and artists without leaving the app
• Toggle between libraries with a single click

⚡ Spicetify Integration

• Real-time Updates: ~100ms position updates via WebSocket
• Audio Analysis: Enables waveform and spectrum features
• Queue with Autoplay: Full queue including suggested tracks
• See Spicetify Integration for setup

⚙️ Configuration

• Web Settings Page: Full configuration UI at /settings
• URL Parameters: Customize display for embedding/OBS
• Environment Variables: Docker/HASS-friendly configuration
• Modular Settings: See Configuration Reference

---

Quick Start:

1. Install the app using your preferred method.
2. Visit http://synclyrics.local:9012 or http://localhost:9012 in your browser.
3. Login to Spotify if needed (optional)
4. Play music from a supported source and watch the lyrics on screen!

Tip: Embed it as an iFrame in any existing dashboard or run it standalone inside Fully Kiosk Browser. Make sure the app is fullscreen for the best experience; and keep your device plugged-in as running it continuously can be a battery drain.

🚀 Installation

Option 1: Windows Executable

1. Go to Releases
2. Download and extract SyncLyrics-vX.X.X-windows-x64.zip anywhere on your computer. Ensure all files are within a dedicated folder.
3. Run SyncLyrics.exe
4. (Optional) Configure .env.example for Spotify API credentials and other advanced features then rename it to .env.

Updating: When updating the app, please delete these 2 folders:

_internal

resources

You can also delete SyncLyrics.exe for safety.

Then extract the new version and replace any old files. This should maintain your existing database and settings (including Spotify cache) while avoiding any conflict from previous versions.

Option 2: Linux (AppImage or Tarball)

1. Go to Releases
2. Download either:
   • SyncLyrics-vX.X.X-linux-x64.AppImage (recommended - single file, no install)
   • SyncLyrics-vX.X.X-linux-x64.tar.gz (for developers)
3. For AppImage:

   chmod +x SyncLyrics-*.AppImage
   ./SyncLyrics-*.AppImage
   

4. For Tarball:

   tar -xzf SyncLyrics-*.tar.gz
   cd SyncLyrics
   ./SyncLyrics
   

Note: Linux builds require playerctl for media detection. Install via your package manager.

Option 3: macOS (Unsigned)

1. Go to Releases

2. Download:

   • SyncLyrics-vX.X.X-macos-x64.zip (Intel Macs)
   • SyncLyrics-vX.X.X-macos-arm64.zip (Apple Silicon)

3. Extract the zip - you'll get a SyncLyrics folder

4. First launch (bypass Gatekeeper):

   cd /path/to/SyncLyrics
   xattr -cr .  # Remove quarantine attributes
   ./sync_lyrics
   

   Or right-click the executable → Open → click "Open" in the warning dialog.

   You can use the included start.command file.

Note: macOS builds are unsigned, so you'll need to allow them through Gatekeeper on first run.

For full support on macOS, it is recommended to install nowplaying-cli via Homebrew. Simply run this command:

brew install nowplaying-cli

Without it, only Apple Music and Spotify are detected. With it, any app that shows in Control Center works (Firefox, VLC, etc.).

Option 4: Home Assistant Addon

1. Add https://github.com/AnshulJ999/homeassistant-addons as a repository to your Home Assistant addon store
2. Install the SyncLyrics addon
3. Configure environment variables in addon settings
4. Start the addon and access via direct URL

Option 5: Run from Source

You can use the included run.bat or 'Run SyncLyrics Hidden.vbs' to run the app directly. Install the requirements first.

Clone the repo and run directly with Python:

git clone https://github.com/AnshulJ999/SyncLyrics.git

cd SyncLyrics

pip install -r requirements.txt

# Edit with your credentials
copy .env.example .env  

python sync_lyrics.py

Option 6: Docker

Docker images are available from:

• Docker Hub: anshulj99/synclyrics
• GitHub Container Registry: ghcr.io/anshulj999/synclyrics

1. Download docker-compose.yml
2. Edit with your Spotify credentials
3. Run: docker-compose up -d
4. Open: http://localhost:9012

➡️ Docker Reference for all configuration options.

---

UI UX Shortcuts

The UI supports many gestures and shortcuts, such as:

1. Long-press: Several buttons can be long-pressed to access more features. For example: a) Visual Mode Toggle: Holding this will lead to 'Art Mode', which hides all on-screen elements to focus on the album art. Combine with Slideshow to turn your device into an art slideshow using artist images. Long-press on a screen corner or press ESC to exit it. b) Slideshow Icon: Holding this will show the Slideshow Menu, where you can configure all slideshow settings and exclude images you don't want.

2. Three-finger tap will play/pause the music. This is for touchsceen devices.

3. Four-finger tap will start/stop the slideshow.

⚙️ Configuration

The app works best with a Spotify API connection, which requires you to create a custom app in your Spotify Developer Dashboard.

Key Environment Variables

| Variable | Description | |----------|-------------| | SPOTIFY_CLIENT_ID | Spotify API client ID | | SPOTIFY_CLIENT_SECRET | Spotify API client secret | | SPOTIFY_REDIRECT_URI | OAuth callback URL (default: http://127.0.0.1:9012/callback) | | SERVER_PORT | Web server port (default: 9012) | | FANART_TV_API_KEY | FanArt.tv API key for artist images | | LASTFM_API_KEY | Last.fm API key for album art |

Note: Spotify OAuth works with localhost/127.0.0.1 over HTTP, but requires HTTPS for any other address. For remote access, use https://<YOUR_IP>:9013/callback.

URL Parameters

Append these to the URL for custom displays (e.g., http://localhost:9012/?minimal=true):

| Parameter | Values | Description | |-----------|--------|-------------| | minimal | true/false | Hide all UI except lyrics | | sharpAlbumArt | true/false | Sharp album art background | | softAlbumArt | true/false | Soft (medium blur) background | | artBackground | true/false | Blurred album art background | | hideControls | true/false | Hide playback controls | | hideProgress | true/false | Hide progress bar |

These can easily be configured via the on-screen settings panel and the URL can be copied.

HTTPS (Required for Browser Microphone)

To use the browser microphone for audio recognition, HTTPS is required.

HTTPS is enabled by default for browser microphone access:

• HTTP: http://localhost:9012 (for local use)
• HTTPS: https://localhost:9013 (for mic access on tablets/phones)

The app auto-generates a self-signed certificate. You'll need to accept the browser's security warning on first use.

---

🛠️ Build

To create a standalone Windows/Linux/macOS executable yourself:

Clone the repo and then run t