{"id":23763526,"url":"https://github.com/tomashubelbauer/lyrics","last_synced_at":"2026-05-17T00:51:35.505Z","repository":{"id":107986182,"uuid":"609329935","full_name":"TomasHubelbauer/lyrics","owner":"TomasHubelbauer","description":"An Electron-based application for displaying the currently playing Spotify song synchronized lyrics","archived":false,"fork":false,"pushed_at":"2024-06-11T21:44:23.000Z","size":6947,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-06-10T13:49:06.404Z","etag":null,"topics":["electron","lrc","lyrics","spotify"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/TomasHubelbauer.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2023-03-03T22:00:07.000Z","updated_at":"2024-11-28T13:46:23.000Z","dependencies_parsed_at":"2024-06-12T00:33:30.763Z","dependency_job_id":"e413fb37-8b98-4d9a-9a2d-f200223f78e1","html_url":"https://github.com/TomasHubelbauer/lyrics","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/TomasHubelbauer/lyrics","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TomasHubelbauer%2Flyrics","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TomasHubelbauer%2Flyrics/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TomasHubelbauer%2Flyrics/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TomasHubelbauer%2Flyrics/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/TomasHubelbauer","download_url":"https://codeload.github.com/TomasHubelbauer/lyrics/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TomasHubelbauer%2Flyrics/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":272829544,"owners_count":25000251,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-30T02:00:09.474Z","response_time":77,"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":["electron","lrc","lyrics","spotify"],"created_at":"2024-12-31T22:12:53.083Z","updated_at":"2026-05-17T00:51:35.471Z","avatar_url":"https://github.com/TomasHubelbauer.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Lyrics\n\nLyrics is a macOS Electron-based application for displaying the current line of\nlyrics of the song playing in Spotify.\n\nIt is a homage to a similar application that existed for Windows when I was a\nkid and which I loved.\nI don't remember its name anymore though.\nIt might have been MiniLyrics, but a Google image search doesn't surface a UI\nsetup with transparent background and click-through behavior which I remember\nhaving and may have just configured for myself.\n\n![](lyrics.gif)\n\n## Tasks\n\n### Set up a GitHub Actions workflow for generating the GIF and screencast\n\nI might drop the GIF now that both GitHub Markdown preview and VS Code support\nvideos.\nThough that would mean losing auto-play.\n\nThe video needs to be recorded based on an automated script to be reproducible.\nI will use faked synchronized lyrics for it so that I don't need to connect to\nSpotify from the agent.\n\n### Integrate the Electron auto-update service once GitHub Actions is set up\n\nSo I do not need to replace the app but can rely on it to auto-update on start\nif a new version has been cut.\n\n### Figure out automated publishing to GitHub Actions\n\nI am manually using Electron Packager:\nhttps://github.com/electron/packager\n\n```\nbunx electron-packager . Lyrics --overwrite --ignore \"(node_modules|.gitignore|bun.lockb|README.md)\"\n```\n\nRun emulating startup initiated by the user:\n\n```\nopen Lyrics-darwin-arm64/Lyrics.app\n```\n\nRun with the ability to see console statements:\n\n```\n./Lyrics-darwin-arm64/Lyrics.app/Contents/MacOS/Lyrics\n```\n\nReplace the installed Lyrics app in Applications with the built one:\n\n```\nrm -rf /Applications/Lyrics.app \u0026\u0026 cp -R ./Lyrics-darwin-arm64/Lyrics.app /Applications/Lyrics.app\n```\n\n- `overwrite` is used to force a new build each run\n- `ignore` is used to ignore files not a part of the application bundle\n\nThe production builds require a working directory to be set to something because\nthey default to `/`.\n\nI set it to the user's home directory, create a `Lyrics` directory there and the\n`lyrics` directory and `token.json` files further go there.\n\n### Allow dragging the lyrics away or dismissing them for a song\n\nThis will require not making the window click-through, just transparent and cut\nto the exact size of the lyrics line so it fits snugly around it and can be\ndragged without stealing the pointer outside of the lyric line's hitzone.\n\n### Allow scrolling up or down while over the lyrics to adjust unsynchronized\n\nThe pace of the synchronized lyrics is linear now.\nWith the ability to hold up or rush the pace, it will be possible to correc the\ntiming issues with linear unsynchronized lyrics.\nAlso consider saving the changes to manually synchronized lyrics for reuse.\n\n## Notes\n\n- The application cannot be supported on Windows due to lack of AppleScript\n  (Windows has automations but the Spotify app doesn't have the same commands)\n- The text shadow/opacity ghost remains visible even after changing the text\n  - This is some sort of an issue with Electron because it is for the most part\n    fixable by reloading the page (vast majority of reloads clear the shadow)\n  - Clearing the text before updating it did not help\n    I tried both in a single `executeJavaScript` call and split clear and update\n  - Hiding and showing the window did not help\n  - Resizing the window to zero and back did not help\n  - Reloading the window helps for the most part so I stuck with it\n  - This is an issue for both HTML and SVG based text rendering!\n  - This might seem as the OS compositor because sometimes it lingers even after\n    the Electron process is killed but so far it has always be a stray process\n\n## Logs\n\n- Followed the Advanced Installation Instructions to add Electron without the\n  need to scaffold by cloning a sample repository\n  https://www.electronjs.org/docs/latest/tutorial/installation\n- Came up with a TLA + dynamic `import` based solution to work around the lack\n  of ESM\n- Made the window always stay on top\n- Made the window frameless, non-minimizable and non-maximizable\n- Made the window transparent\n- Made the window click-through\n- Styled the text to be big, white, with a glow and an outline for legibility\n- Implemented logic for scraping Spotify ID for artist and title from Google\n- Implemented logic for pulling lyrics using the Spotify Lyrics API on GitHub\n  (https://github.com/akashrchandran/spotify-lyrics-api)\n- Fixed most of the lingering shadow issue by reloading before every line change\n- Made the lyrics fade into view instead of flashing in aggressively\n- Swithced to SVG based rendering\n  - Allows for the text fade without ugly unsupported CSS\n  - Allows for an easy way to do a text outline\n  - Still suffers from the shadow/opacity ghosting HTML based rendering did\n- Replaced track ID web search lookup with a Spotify AppleScript command\n- Rewrote to use the Spotify API directly instead of via the Heroku app\n- Upgraded to latest Electron and started using ESM and TLA\n- Implemented a re-authorization flow for obtaining the new token after a 401\n- Switched back to CSS based rendering for the more flexible approach\n  (Not everything is supported vendorless, but it is getting better.)\n- Added a macOS Dock context menu with artist, song and token information\n- Made the Spotify web player window wait to show to prevent refresh flashes\n- Removed no longer used stuff now that the app uses the user's Home directory\n- Worked around the ghosting issue and capture a repro repository for it:\n  https://github.com/TomasHubelbauer/electron-lingering-shadow-repro\n- Fixed the Lyrics app opening up Spotify unintentionally if it was closed\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftomashubelbauer%2Flyrics","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftomashubelbauer%2Flyrics","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftomashubelbauer%2Flyrics/lists"}