{"id":51854216,"url":"https://github.com/denyherianto/spotifylyrics","last_synced_at":"2026-07-23T23:02:40.244Z","repository":{"id":370468553,"uuid":"1279945879","full_name":"denyherianto/SpotifyLyrics","owner":"denyherianto","description":"SpotifyLyrics is a lightweight macOS menu bar app that puts synced lyrics on top of Spotify as a polished, always-available overlay. It feels like karaoke mode for your desktop: live scrolling, word-level fill, translations, romanization, music controls, shareable lyric cards, and a tiny subtitle mode when you want your screen back.","archived":false,"fork":false,"pushed_at":"2026-07-09T10:38:06.000Z","size":4259,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-09T11:10:42.854Z","etag":null,"topics":["ai","apple","appleintelligence","lyrics","macos","spotify"],"latest_commit_sha":null,"homepage":"","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/denyherianto.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-06-25T06:23:04.000Z","updated_at":"2026-07-09T09:35:13.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/denyherianto/SpotifyLyrics","commit_stats":null,"previous_names":["denyherianto/spotifylyrics"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/denyherianto/SpotifyLyrics","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/denyherianto%2FSpotifyLyrics","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/denyherianto%2FSpotifyLyrics/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/denyherianto%2FSpotifyLyrics/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/denyherianto%2FSpotifyLyrics/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/denyherianto","download_url":"https://codeload.github.com/denyherianto/SpotifyLyrics/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/denyherianto%2FSpotifyLyrics/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35819442,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-07-20T02:08:10.276Z","status":"online","status_checked_at":"2026-07-23T02:00:06.683Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","apple","appleintelligence","lyrics","macos","spotify"],"created_at":"2026-07-23T23:02:39.577Z","updated_at":"2026-07-23T23:02:40.236Z","avatar_url":"https://github.com/denyherianto.png","language":"Swift","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"Assets/spotify-lyrics-avatar.png\" width=\"180\" alt=\"SpotifyLyrics mascot\"/\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eSpotifyLyrics\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eSpotify lyrics, but native. A floating karaoke overlay for macOS.\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/platform-macOS%2013%2B-blue\" alt=\"macOS 13+\"/\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Swift-6.0-orange\" alt=\"Swift 6.0 toolchain\"/\u003e\n  \u003cimg src=\"https://img.shields.io/badge/license-MIT-green\" alt=\"MIT License\"/\u003e\n\u003c/p\u003e\n\n---\n\n\u003cimg width=\"860\" height=\"825\" alt=\"SCR-20260710-jpwq\" src=\"https://github.com/user-attachments/assets/995b7c89-42a2-4031-b628-16d239fc4c9d\" /\u003e\n\nhttps://github.com/user-attachments/assets/9b579c50-f9ef-4d36-8304-79a0a795a289\n\nhttps://github.com/user-attachments/assets/99dc5c35-069d-4a24-8eff-bfd220ca7fa8\n\n---\n\nSpotifyLyrics is a lightweight macOS menu bar app that puts synced lyrics on top of Spotify as a polished, always-available overlay. It feels like karaoke mode for your desktop: live scrolling, word-level fill, translations, romanization, music controls, shareable lyric cards, and a tiny subtitle mode when you want your screen back.\n\nNo Spotify login. No Spotify Web API. No external dependencies. Just Swift, Apple frameworks, LRCLIB, and the Spotify desktop app.\n\n## Why It Exists\n\nSpotify's built-in lyrics are locked inside the player. SpotifyLyrics makes lyrics part of the operating system experience:\n\n- keep lyrics visible while coding, writing, designing, gaming, or presenting\n- learn songs in Japanese, Korean, Chinese, Arabic, Russian, Hindi, and more with romanization and translation\n- jump through a track by clicking lyric lines instead of scrubbing blindly\n- turn a single lyric into a social-ready card with album art in one click\n- run everything as a quiet menu bar utility instead of another big window\n\n## Feature Highlights\n\n### Karaoke Overlay\n\n- **Full lyrics overlay** with frosted glass styling, smooth auto-scroll, and current-line focus\n- **Mini subtitle mode** for a compact one-line lyric bar\n- **Word-level karaoke fill** when enhanced LRC word timestamps are available\n- **Four animation modes**: Karaoke, Smooth, Spring, and Glow\n- **Instrumental break view** with countdown and next-line preview\n- **Click-to-seek lyrics**: click any line to jump Spotify to that timestamp\n- **Manual scrolling** with a one-click return to the current lyric\n- **Resizable layouts**: Mini, Small, Medium, and Large\n- **Opacity control** and **Always on Top** toggle\n- **Hover controls** for play, pause, next, previous, shuffle, repeat, and seek\n\n### Lyrics Sources\n\n- **LRCLIB integration** for free synced and plain lyrics\n- **Multiple candidate picker** when LRCLIB has several matches for a track\n- **Duration-aware ranking** so the best synced match usually wins first\n- **Per-track source memory** so your selected lyric version stays selected\n- **Three-level cache**: in-memory, disk, then network\n- **Cache clearing** from the menu bar\n- **Speech recognition fallback** path for last-resort lyrics generation through Apple's Speech framework\n\n### Translation, Romanization, and AI\n\n- **Automatic language detection** with Apple's NaturalLanguage framework\n- **Romanization** for non-Latin scripts using ICU and CFStringTokenizer\n- **On-device translation** via Apple's Translation framework where available\n- **14 target languages**: Indonesian, English, Japanese, Korean, Chinese, Spanish, French, German, Portuguese, Thai, Vietnamese, Arabic, Russian, and Hindi\n- **Mixed-language handling** for lyrics that switch languages inside the same song\n- **Apple Intelligence modes** on supported macOS versions:\n  - Primary: AI translates directly for quality\n  - Refine: fast translation first, AI improves in the background\n  - Off: standard translation only\n- **AI song summary**: a short one-line theme shown in the overlay when Foundation Models are available\n\n### Menu Bar Player\n\n- **300 x 300 album-art mini player** in the menu bar popover\n- **Blurred artwork hover state** with playback controls\n- **Dominant-color accenting** extracted from album art\n- **Seek bar with timestamps**\n- **Current mood indicator** when SoundAnalysis detects a known mood\n- **Version display**, settings, cache controls, and quit action in one compact popover\n\n### Sharing\n\n- **Lyrics card generator** for quote-style lyric images\n- **Album-art background blur** with the lyric, title, artist, romanization, and translation\n- **1080 x 1080 square cards** by default, with landscape support in the generator\n- **Clipboard export** from the in-app preview\n\n### System Integration\n\n- **macOS menu bar app** with no Dock icon\n- **App Shortcuts support**:\n  - Show, hide, or toggle the lyrics overlay\n  - Ask what song is playing\n  - Toggle translation and choose a target language\n  - Set overlay size and animation mode from App Intents\n- **AppleScript control** for Spotify playback and seeking\n- **Accessibility polling** for faster play/pause, progress, shuffle, repeat, and liked-state reads\n- **Predictive line switching**: the app schedules exact timers for upcoming lyric timestamps instead of relying only on polling\n\n### Analysis and Native Intelligence\n\n- **SoundAnalysis** for lightweight mood and audio-state classification\n- **Vision** for album-art color extraction, OCR, and saliency analysis\n- **Vocal activity detection** infrastructure for vocal vs instrumental sections\n- **Drift correction** using Spotify-reported position and Accessibility progress\n- **Render-friendly SwiftUI behavior** that avoids unnecessary published-state churn and per-frame work in idle states\n\n## Requirements\n\n- macOS 13 Ventura or later\n- Spotify desktop app\n- Swift 6.0 toolchain / Xcode Command Line Tools for building from source\n- macOS 26+ and supported Apple Intelligence hardware for Foundation Models features\n- Translation availability depends on Apple's Translation framework support on the machine\n\nPermissions you may be asked for:\n\n- **Automation**: required to control Spotify through AppleScript\n- **Accessibility**: recommended for faster state/progress detection\n- **Speech Recognition / Microphone**: only needed if using speech-recognition fallback workflows\n\n## Installation\n\n### Download\n\nGrab the latest build from [Releases](https://github.com/denyherianto/SpotifyLyrics/releases), open it, and drag SpotifyLyrics to Applications.\n\nIf macOS blocks the unsigned app, remove quarantine:\n\n```bash\nxattr -cr /Applications/SpotifyLyrics.app\n```\n\nThen open SpotifyLyrics normally and allow the requested Spotify Automation permission.\n\n### Build From Source\n\n```bash\ngit clone https://github.com/denyherianto/SpotifyLyrics.git\ncd SpotifyLyrics\nswift build -c release --product SpotifyLyrics\n```\n\n### Run\n\n```bash\n./run.sh\n```\n\nOr manually:\n\n```bash\nswift build -c release --product SpotifyLyrics\n.build/release/SpotifyLyrics\n```\n\n## Usage\n\n1. Open Spotify and play a song.\n2. Launch SpotifyLyrics.\n3. The lyrics overlay appears at the bottom of the screen.\n4. Use the menu bar music icon to control visibility, lyrics source, translation, romanization, overlay size, animation, opacity, and cache.\n\nIn the overlay:\n\n- hover to reveal controls\n- click a lyric line to seek\n- scroll manually to browse the song\n- click **Current** to return to the active line\n- switch to **Mini** when you only want a subtitle bar\n- right-click a lyric line to copy it or share it as a card\n\n## Architecture\n\n```text\nSpotify desktop app\n  -\u003e AppleScriptBridge\n       track metadata, playback state, controls, seek\n  -\u003e AccessibilityBridge\n       fast UI state, progress cross-check, shuffle/repeat/liked reads\n  -\u003e SpotifyPlayerManager\n       polling, interpolation, drift correction, predictive line timers\n\nLRCLIB / cache / speech fallback\n  -\u003e LyricsManager\n       candidate ranking, per-track source selection, memory + disk cache\n  -\u003e LRCParser\n       line timestamps and inline word timestamps\n  -\u003e EnrichmentCoordinator\n       language detection, romanization, translation, AI refinement, summaries\n\nSwiftUI + AppKit\n  -\u003e LyricsOverlayWindow\n       transparent non-activating NSPanel\n  -\u003e LyricsOverlayView / MiniOverlayView\n       karaoke rendering, controls, seek bar, instrumental breaks, share cards\n  -\u003e MenuBarView\n       album-art mini player, settings, source picker, cache, mood indicator\n```\n\n## Project Layout\n\n```text\nSources/SpotifyLyricsCore/\n  Analysis/      SoundAnalysis, Vision, vocal activity helpers\n  Controls/      playback controls and seek bar\n  Lyrics/        LRCLIB provider, LRC parser, cache, enrichment pipeline\n  Models/        track, lyric, language, animation, and overlay models\n  Overlay/       full and mini overlay views, lyric line rendering, break view\n  Sharing/       lyrics card rendering and clipboard export\n  Spotify/       AppleScript and Accessibility bridges\n\nSources/App/\n  Intents/       App Shortcuts and App Intents\n  MenuBarView    menu bar popover mini player and settings\n  SpotifyLyricsApp\n                 app lifecycle, overlay controller, state wiring\n\nTests/\n  Custom executable test harness, not XCTest\n```\n\n## Build and Test\n\n```bash\n# Debug build\nswift build\n\n# Release build\nswift build -c release --product SpotifyLyrics\n\n# Run the custom test harness\nswift run SpotifyLyricsTests\n```\n\n## Apple Frameworks Used\n\n| Framework | Purpose |\n| --- | --- |\n| AppKit | menu bar app, NSPanel overlay, image handling |\n| SwiftUI | overlay, menu bar popover, controls, card rendering |\n| AppIntents | Shortcuts support |\n| Accessibility | fast Spotify UI state and progress reads |\n| NaturalLanguage | language detection and text classification |\n| Translation | on-device lyrics translation where available |\n| FoundationModels | Apple Intelligence summaries and AI translation refinement where available |\n| Speech | fallback lyric recognition workflow |\n| SoundAnalysis | audio and mood classification |\n| Vision | album-art palette extraction, OCR, saliency |\n| CreateML | vocal activity infrastructure |\n| CoreFoundation | ICU-backed romanization |\n\n## Privacy and Constraints\n\nSpotifyLyrics is intentionally local-first:\n\n- It does **not** use the Spotify Web API.\n- It does **not** ask for your Spotify account or OAuth token.\n- It reads the Spotify desktop app through AppleScript and Accessibility.\n- Lyrics searches go to LRCLIB.\n- Translation, romanization, analysis, and AI features use Apple frameworks where available.\n- Cached lyrics are stored locally in the user's caches directory.\n\nKnown constraints:\n\n- Spotify desktop app is required.\n- Queue, playlist, and library management are out of scope because there is no Spotify Web API integration.\n- Lyrics quality depends on available LRCLIB matches unless a fallback workflow is used.\n- AI features require supported macOS, hardware, and Apple Intelligence settings.\n\n## Contributing\n\nThe project is deliberately dependency-free and split into a reusable core target plus a small app target. Keep changes native, testable, and focused.\n\nBefore opening a PR:\n\n```bash\nswift build\nswift run SpotifyLyricsTests\n```\n\nNew tests live in `Tests/` and should be registered in `Tests/TestRunner.swift`.\n\n## License\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdenyherianto%2Fspotifylyrics","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdenyherianto%2Fspotifylyrics","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdenyherianto%2Fspotifylyrics/lists"}