🎵 Spotify Overlay Lyric

A premium, always-on-top desktop overlay that displays real-time synchronized lyrics for your currently playing Spotify track. Works with both Spotify Premium API and Spicetify for maximum flexibility.

---

✨ Features

• 🎤 Real-Time Synced Lyrics — Lyrics scroll and highlight in sync with your music using timestamp-based extrapolation
• 🔄 Dual Source Mode — Choose between Spotify Premium (API) or Spicetify (local) playback
• 🎯 Click-to-Sync — Click any lyric line to instantly calibrate timing offset
• 🖱️ Manual Scroll — Scroll freely through lyrics; auto-resumes after 4 seconds
• 🪟 Always on Top — Transparent, frameless overlay that stays above all windows
• ⚙️ Glassmorphism Settings — Beautiful dark-themed configuration panel
• 📦 One-Click Spicetify Setup — Automatically installs the helper extension
• 🛡️ Focus-Resilient — Lyrics persist even when focusing/minimizing Spotify

---

🚀 Quick Start

Prerequisites

• Node.js (v18+)
• Spotify Account

Installation

git clone https://github.com/aw4e/SpotifyOverlay.git
cd APP-SpotifyOverlay
npm install
npm start

---

🔧 Configuration

On first launch, the Settings panel opens. Choose your playback mode:

Mode 1: Spotify Premium (API)

1. Create an app at Spotify Developer Dashboard
2. Set Redirect URI to http://127.0.0.1:8888/callback
3. Enter your Client ID and Client Secret
4. Click Save Configuration
5. Login when prompted

Mode 2: Spicetify (Recommended)

1. Install Spicetify
2. Select Spicetify mode in Settings
3. Click Install & Apply Extension — automatically installs the helper
4. Spotify will restart with the extension active
5. Click Save Configuration

Tip: Spicetify mode provides instant lyrics from Spotify's internal API and doesn't require API credentials.

---

🎯 Lyric Sync Controls

Action	Effect
Click a lyric line	Instantly syncs offset to that line
Scroll wheel	Manually scroll through lyrics
Wait 4 seconds	Auto-resumes following current lyric

---

🏗️ Architecture

Spotify_Overlay/
├── main.js              # Electron main process, IPC handlers, HTTP server
├── renderer.js          # Overlay UI logic, lyric sync engine
├── index.html           # Overlay window layout
├── style.css            # Overlay styling with glassmorphism
├── config.html          # Settings window
├── spotifyAuth.js       # Spotify OAuth2 flow
├── spotifyApi.js        # Spotify Web API client
├── lyricsApi.js         # lrclib.net lyrics fetcher
├── spicetify-helper.js  # Spicetify extension (injected into Spotify)
└── package.json

Data Flow

┌─────────────┐     HTTP POST      ┌──────────┐     IPC      ┌──────────────┐
│  Spicetify   │ ──────────────────>│  main.js  │ ──────────> │  renderer.js  │
│   Helper     │   /local-playback  │  (cache)  │ get-playback│  (sync loop)  │
└─────────────┘                     └──────────┘              └──────────────┘
                                         │
                                    Spotify API
                                    (Premium mode)

---

📦 Building

npm run dist

Outputs a portable .exe to the dist/ folder.

---

🛠️ Tech Stack

• Electron — Desktop framework
• Spicetify API — Local Spotify data & lyrics
• Spotify Web API — Premium playback data
• lrclib.net — Fallback synced lyrics
• electron-store — Config persistence
• Outfit — Google Font