1. Download from Releases: LyricGlow-arm64.dmg (Apple Silicon) or LyricGlow-x64.dmg (Intel)
2. Open the DMG → drag to Applications
3. Open it — since v0.7.0 the app is code-signed and notarized (Developer ID: Royan AB), so macOS launches it without warnings

Old unsigned builds (v0.6.1 and earlier) need one command if macOS refuses to open them:

xattr -cr /Applications/LyricGlow.app

Automation permission: LyricGlow reads the current track with AppleScript, so macOS asks for Automation access on first run. If you dismissed the prompt, the app shows a one-time explainer with an Open Settings button, or grant it manually in System Settings → Privacy & Security → Automation → LyricGlow → enable Spotify / Music. The app detects the grant and resumes automatically — no restart needed.

The app runs as a menu bar agent (LSUIElement) — no Dock icon, no application menu.

The full lyrics view follows the current line on its own. Scrolling it yourself takes over, and a Resume auto-scroll pill appears to hand control back. Clicking a line also resumes following.

Floating Lyrics

_{Only the words — click-through, above every app, translation included}

Like a desktop lyric overlay: only the current line, large and centred, with the word-by-word glow and the translation underneath. No window, no controls, no background — clicks pass straight through to whatever is behind, and the line floats above full-screen apps on every space.

To move it, choose Move Floating Lyrics in the menu bar: the bar becomes draggable and outlines itself. Drag it where you want, then choose Lock Floating Lyrics to make it click-through again and remember the spot. Floating and normal layouts each remember their own position and size.

While no line is playing (instrumental passages, or a track with no lyrics) the overlay draws nothing at all rather than parking a status message on your desktop. Opening Settings returns the window to the normal layout, since the settings panel does not fit in the slim bar.

Menu bar menu: Show Window · Show Tray Lyrics · Floating Lyrics · Move/Lock Floating Lyrics · Settings · Check for Updates · Quit

Spotify tokens are encrypted with the macOS Keychain-backed safeStorage API before being stored.

.env is optional and read from the project root at runtime. Only two keys are used:

.env is bundled into the packaged app, so build your DMG after creating it if you need Spotify login in a self-built release.

One extra launch-time variable: LYRICGLOW_CAPTURE=1 starts the window on the normal layer instead of always-on-top, so screen recorders and Zoom/Meet window pickers can see it — macOS hides overlay windows from window capture. Used for demo recordings and screen sharing.

Releasing (maintainers): add a ## [x.y.z] section to CHANGELOG.md, then run npm run release (or -- minor / -- major). The script checks the tree is clean and in sync, bumps the version, builds both DMGs signed with the Royan AB Developer ID, notarizes and staples them with Apple, then tags, publishes the GitHub release, and updates the Homebrew cask. One-time setup: the Developer ID certificate in the Keychain, a notarytool profile named lyricglow-notary, and an authenticated gh CLI.

src/
├── main/                    # Electron main process
│   ├── index.ts             # Lifecycle, window, tray, AppleScript polling, IPC handlers
│   ├── auth/                # Spotify PKCE OAuth (token storage + refresh)
│   ├── managers/            # Lyrics, TheAudioDB, Spotify metadata, translation,
│   │                        # unified cache, image cache, update check
│   └── translation/         # Provider interface + Google Web / Lingva chain
├── preload/index.ts         # contextBridge API exposed as window.musicAPI
├── renderer/index.ts        # UI logic: sync manager, displays, metadata, settings
└── shared/utils/            # Logger, SecureFetch (verified HTTPS), LrcParser

resources/                   # index.html + styles.css loaded by the renderer
build/                       # App icon, tray icons, DMG background, entitlements
scripts/                     # install.sh (end users), release.sh (maintainers)

How it fits together: the main process runs a cached AppleScript through osascript on an adaptive interval (1.8 s while playing, 3 s paused, 5 s idle, with an immediate poll after any transport action), broadcasts track changes over IPC, and fetches lyrics/metadata in parallel. The renderer interpolates position between polls for smooth progress and word glow, and stops rendering while paused; the menu bar line is scheduled to update exactly when the next lyric line is due, so it stays correct even when the window is hidden — at near-zero idle cost.