Skip to content
enrychPublic

Repository files navigation

Verse

Your Lyrics, Your Way.

The song you're playing, word by word, on your Mac's lock screen or any display. Free and open source.

Lock screen lyrics · Spotify and Apple Music · macOS 14+ · Apple silicon and Intel

Download the latest release

What's new: see CHANGELOG.md.

Install

With Homebrew (no security prompt, easy updates):

brew install --cask enrych/tap/verse

Or download the DMG:

  1. Open Verse.dmg and drag Verse into Applications.
  2. Verse is ad-hoc signed but not notarised, so the first time right-click → Open (or run xattr -dr com.apple.quarantine /Applications/Verse.app).
  3. Play something in Spotify or Apple Music, allow Verse to read it when macOS asks, then lock your Mac, or pick a display for the full-screen stage.

Build from source

./scripts/setup.sh
open Verse.xcodeproj

Run the Verse scheme (⌘R). setup.sh installs XcodeGen, generates the project from project.yml, and enables git hooks that regenerate it after git pull or a branch switch. Edit project.yml, not the .xcodeproj.

Releasing

GitHub Actions builds a universal, ad-hoc signed Verse.dmg and publishes it as a release. Either run Actions → Release → Run workflow with a version (e.g. 0.2.0), or push a tag:

git tag v0.2.0 && git push origin v0.2.0

Leave the version empty to build a test DMG without publishing (it's attached to the run). The site's download links always point at the latest release.

Website

site/ is a static homepage (no build step), deployed on Cloudflare Pages with output directory site. functions/download.js serves /download: the latest release's DMG, fetched from GitHub once per version and then served from Cloudflare (Workers KV binding DOWNLOADS).

Features

  • Styles: Constellation (words land as stars joined in sung order) and Focus (one big line, each word lighting up as it's sung).
  • Backgrounds: Night (default: near-black, faint dust stars, grain), Black, Album art (the song's cover, blurred), or your Wallpaper on the lock screen.
  • Quiet moments: during intros and long breaks the next line is previewed as faint stars and the sky gently comes alive; pausing dims the lyrics.
  • Sync: a global offset plus a per-song nudge that's remembered.
  • Lyrics: word-synced where available, line-synced otherwise, and plain lyrics spread across the song as a last resort.
  • Full-screen stage on any display; ⌃⌥⌘L toggles it on the display under the pointer.
  • Edge glow: ambient light around the screen edges in your colours that moves with the beat (system audio, never the microphone) or with every sung word, or breathes, or holds still. Two-colour balance, thickness, glow, display choice, notch-aware, on the desktop and the lock screen.
  • Now-playing card on the lock screen.
  • Open at login, keeps the display awake while music plays, and tells you in the menu when a new version is out.

How it works

Verse/
  App/        Menu bar app, AppModel (wires everything), menu UI
  Playback/   AppleScript polling of Spotify/Music, smooth playback clock,
              lock state, keep-display-awake
  Lyrics/     Model, YRC/LRC parsers, providers, disk cache
  Display/    Lock-screen layer, full-screen stage window, root StageView
  Styles/     Display styles (v0.1: ConstellationStyle)
  Support/    Settings, palettes, album-art colour extraction
  • Now playing: polls the player every 0.5 s via AppleScript and interpolates between samples so stars land on the beat.
  • Lyrics: NetEase Cloud Music first (per-word timings), then LRCLIB (line timings; words are estimated). Cached in ~/Library/Caches/com.enrych.verse.
  • Styles: v0.1 ships Constellation: words gather into verse-sized groups placed as points in a wide band, joined in sung order; each group clears before the next.
  • Lock screen: SkyLightWindow (MIT, © Lakr Aream) places a window in a private SkyLight space above the lock screen.

Caveats

  • The NetEase API is unofficial and may change or be rate-limited.
  • The lock-screen layer uses private macOS APIs; a macOS update can break it. The full-screen stage keeps working either way.

Inspiration

I saw a reel of Verci, lyrics drifting across a Mac's lock screen, and loved it. It was paid, and I'm a developer, so I made my own, from scratch. If you want the polished version, buy Verci. It's lovely.

Edge glow was inspired by Lumn, from the same developer, which does ambient, music-synced screen lighting beautifully.

License

MIT. See LICENSE.

Releases

Packages

Contributors

Languages