{"id":15038127,"url":"https://github.com/nbolar/playstatus","last_synced_at":"2026-04-02T13:02:32.195Z","repository":{"id":40511512,"uuid":"183648267","full_name":"nbolar/PlayStatus","owner":"nbolar","description":"macOS app that allows the control of Spotify and AppleMusic/iTunes music playback from the menu bar.","archived":false,"fork":false,"pushed_at":"2026-03-25T04:05:54.000Z","size":13179,"stargazers_count":170,"open_issues_count":2,"forks_count":6,"subscribers_count":4,"default_branch":"master","last_synced_at":"2026-03-26T09:48:22.854Z","etag":null,"topics":["apple-music","itunes","itunes-playback","macos","menubar","music","playstatus","sparkle","sparkle-upgrade-tool","spotify","swift4"],"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/nbolar.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":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2019-04-26T15:01:19.000Z","updated_at":"2026-03-26T01:31:05.000Z","dependencies_parsed_at":"2023-10-14T17:21:42.525Z","dependency_job_id":"6c19e911-c79e-4d63-a146-e3cf2fdf4b8c","html_url":"https://github.com/nbolar/PlayStatus","commit_stats":null,"previous_names":[],"tags_count":28,"template":false,"template_full_name":null,"purl":"pkg:github/nbolar/PlayStatus","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nbolar%2FPlayStatus","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nbolar%2FPlayStatus/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nbolar%2FPlayStatus/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nbolar%2FPlayStatus/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nbolar","download_url":"https://codeload.github.com/nbolar/PlayStatus/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nbolar%2FPlayStatus/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31306710,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-02T12:59:32.332Z","status":"ssl_error","status_checked_at":"2026-04-02T12:54:48.875Z","response_time":89,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["apple-music","itunes","itunes-playback","macos","menubar","music","playstatus","sparkle","sparkle-upgrade-tool","spotify","swift4"],"created_at":"2024-09-24T20:37:13.237Z","updated_at":"2026-04-02T13:02:32.176Z","avatar_url":"https://github.com/nbolar.png","language":"Swift","readme":"#![playstatus_header](https://user-images.githubusercontent.com/45484873/56880861-09cb3980-6a67-11e9-9d45-037a9165b212.png)\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT) \n[![Version: 2.8](https://img.shields.io/badge/Version-3.0-green.svg)](https://github.com/nbolar/PlayStatus/releases) \n[![Platform](http://img.shields.io/badge/platform-macOS-black.svg?style=flat)](https://developer.apple.com/resources/)\n[![Platform](https://img.shields.io/badge/swiftUI-blue.svg?style=flat)](https://developer.apple.com/swiftui/)\n[![Open Source Love svg1](https://badges.frapsoft.com/os/v1/open-source.svg?v=103)](https://github.com/nbolar/playstatus/)\n[![GitHub All Releases](https://img.shields.io/github/downloads/nbolar/playstatus/total)](https://github.com/nbolar/PlayStatus/releases/latest/)\n\nPlayStatus is a native SwiftUI macOS menu bar app for controlling Apple Music and Spotify without living in a full desktop window all day. The current generation of the app is a full SwiftUI relaunch with a richer now-playing surface, better onboarding, customizable display themes, provider-aware search, lyrics and credits, a detached floating player, and a cleaner settings flow.\n\n## Why this version feels different\n\n- The old AppKit utility-style player has been replaced with a layered SwiftUI player that supports regular, mini, and detached modes.\n- New users get a guided walkthrough, and existing users can replay the full tour or the shorter \"What's New\" tour at any time.\n- Lyrics, credits, and provider-aware search now live inside the main player instead of feeling like separate utility flows.\n- Display tuning is much deeper: menu bar text modes, detached window sizing, theme presets, animated artwork, artwork motion styles, and progress-strip options all live in Settings.\n- The app is more efficient when closed: media caches, onboarding previews, and heavy Settings surfaces can unload when they are not visible.\n\n## What the app looks like now\n\n### Regular player\n\n\u003cimg width=\"556\" height=\"280\" alt=\"Image\" src=\"https://github.com/user-attachments/assets/a47cade8-7157-44a3-b5c8-cc6fae184ef0\" /\u003e\n\n#### Lyric View\n\u003cimg width=\"556\" height=\"521\" alt=\"Image\" src=\"https://github.com/user-attachments/assets/741a481e-7389-4282-a43b-ed0a916c4e74\" /\u003e\n\n### Mini player\n\n\u003cimg width=\"406\" height=\"406\" alt=\"Image\" src=\"https://github.com/user-attachments/assets/c90a57cc-caa3-4800-8522-b4283bddb570\" /\u003e\n\n#### Lyric View\n\u003cimg width=\"406\" height=\"586\" alt=\"Image\" src=\"https://github.com/user-attachments/assets/ace27ca0-f0b2-47d8-8981-9f59a3a616fd\" /\u003e\n\n\n### Supports Animated Album Stream (if supported/exists)\nhttps://github.com/user-attachments/assets/e12a56e8-de6e-460d-b323-5db9d491533c\n\n### Settings\n\n\u003cimg width=\"780\" height=\"742\" alt=\"Image\" src=\"https://github.com/user-attachments/assets/ed84d8a9-10c8-48ce-921d-c55404165803\" /\u003e\n\n\n## First launch\n\n1. Download the latest [release](https://github.com/nbolar/PlayStatus/releases/latest/) and move PlayStatus to `/Applications`.\n2. Launch the app and choose which providers PlayStatus should listen to: Apple Music, Spotify, or both.\n3. When macOS asks for Automation permission, allow PlayStatus to control Music and/or Spotify.\n4. If no prompt appears, retry once and then check `System Settings -\u003e Privacy \u0026 Security -\u003e Automation`.\n5. Use the walkthrough to set your preferred provider, display mode, theme, animated artwork, and launch-at-login behavior before closing the window.\n\n## How people use PlayStatus day to day\n\n### 1. Open the player from the menu bar\n\n- Click the menu bar item to open the main player.\n- Choose a menu bar display style in `Settings -\u003e Display`: `Artist`, `Song`, `Artist + Song`, or `Icon Only`.\n- Long titles can scroll, and title transitions can animate when tracks change.\n\n### 2. Pick the right player surface\n\n- `Regular mode` is the full player with artwork, inline search, progress, transport controls, lyrics, and credits.\n- `Mini mode` is a calmer, more compact surface with quick controls and optional mini lyrics/credits.\n- `Detached mode` turns the player into a floating standalone window. You can keep it always on top and choose `Small`, `Medium`, or `Large`.\n\n### 3. Control playback quickly\n\n- Use the transport controls for previous, play/pause, and next.\n- Click the track title to jump straight into the source app.\n- If Apple Music is the active source, you can favorite the current track from the player.\n- The playback progress bar is seekable, and the menu bar can show a separate progress strip.\n\n### 4. Use lyrics, credits, and search where they matter\n\n- `Lyrics` and `Credits` open from the player instead of in separate utility views.\n- Lyrics can come from Apple Music or LRCLIB depending on availability.\n- Search is provider-aware:\n  - Spotify opens the matching Spotify search.\n  - Apple Music searches your Music library and can play a matching result.\n- The mini player has its own quick lyrics and credits toggles.\n\n### 5. Personalize the visual feel\n\n- Theme presets: `Artwork Adaptive`, `Frosted`, `Midnight`, `Warm Studio`, `High Contrast`, `Graphite`.\n- Animated artwork can use static motion, and supported tracks can use animated editorial streams.\n- Artwork motion styles: `Parallax by Pointer`, `Vinyl Spin`, `Film Grain Drift`.\n- Non-adaptive themes let you blend album colors back into the surface.\n\n## Settings guide\n\n### Display\n\n- Menu bar text mode\n- Parenthetical-title cleanup\n- Scrollable titles\n- Slide animation on track change\n- Detached window always-on-top\n- Detached window size preset\n- Title width\n- Artwork color intensity\n- Theme selection\n- Album color blend\n- Animated artwork and animated artwork streams\n- Animated stream quality and preview\n- Artwork motion style preview\n\n### Playback\n\n- Preferred provider: `Auto`, `Music`, or `Spotify`\n- Automatic provider priority when the preferred app is idle\n- Enable or disable Apple Music and Spotify independently\n- Expand the details pane automatically for new tracks\n\n### Hotkeys\n\nGlobal shortcuts are configurable in `Settings -\u003e Hotkeys`. Default bindings are:\n\n| Action | Default |\n| --- | --- |\n| Play/Pause | `Ctrl+Opt+Cmd+P` |\n| Next Track | `Ctrl+Opt+Cmd+N` |\n| Previous Track | `Ctrl+Opt+Cmd+B` |\n| Toggle Popover | `Ctrl+Opt+Cmd+O` |\n| Toggle Favorite | `Ctrl+Opt+Cmd+L` |\n| Toggle Detached Mode | `Ctrl+Opt+Cmd+D` |\n\n### System\n\n- Replay the full walkthrough\n- Open the shorter `What's New` tour\n- Temporarily re-arm `Debug Coachmarks` for QA or troubleshooting\n- Launch at login\n- Check for updates through Sparkle\n- Clear the local media cache\n- Reduce hidden memory usage when all surfaces are closed\n\n### License\n\n- MIT license text\n- LRCLIB attribution and disclaimer for third-party lyrics\n\n## Walkthrough and onboarding\n\nThe new SwiftUI version includes a dedicated walkthrough window for both first-run setup and returning-user upgrades.\n\n- `Show Walkthrough` is also available from the app menu with `Cmd+Shift+/`.\n- The full walkthrough helps with provider setup, Automation permissions, personalization, and hotkeys.\n- The shorter `What's New` flow highlights the redesigned player, integrated lyrics/search, and the reorganized Settings experience.\n- Contextual coachmarks can teach the search button, mode toggle, detached mode, detail toggles, and Settings navigation.\n\n## Privacy, network use, and caching\n\n- PlayStatus uses AppleScript to control Apple Music and Spotify, so macOS Automation permission is required.\n- Lyrics may be fetched from LRCLIB, and artwork or animated artwork lookups may use public Apple/iTunes endpoints when needed.\n- The media cache stores lyrics and artwork locally on your Mac and caps itself at 50 MB.\n- Lyrics are third-party content and may be incomplete or unavailable.\n\n## Compatibility\n\n- Minimum supported macOS version: `15.0`\n- Supported providers: `Apple Music`, `Spotify`\n- Update flow: Sparkle-based in-app update checks remain supported\n- License: `MIT`\n\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnbolar%2Fplaystatus","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnbolar%2Fplaystatus","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnbolar%2Fplaystatus/lists"}