PHPackages the-shit/music - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Framework](/categories/framework) 4. / 5. the-shit/music ActiveProject[Framework](/categories/framework) the-shit/music ============== Spotify CLI player powered by Laravel Zero and spotifyd. v1.0.1(4mo ago)121[1 issues](https://github.com/the-shit/music/issues)MITPHPPHP ^8.2CI passing Since Aug 11Pushed 2w agoCompare [ Source](https://github.com/the-shit/music)[ Packagist](https://packagist.org/packages/the-shit/music)[ Docs](https://laravel-zero.com)[ RSS](/packages/the-shit-music/feed)WikiDiscussions master Synced 1mo ago READMEChangelog (3)Dependencies (11)Versions (50)Used By (0) Your codebase has a soundtrack ============================== [](#your-codebase-has-a-soundtrack) Every commit in this repo carries the Spotify track that was playing when the code was written. A git hook injects it. CI enforces it. **No music, no merge.** The byproduct is the [vibes page](https://the-shit.github.io/music/vibes.html) — an auto-generated, living soundtrack of the entire codebase. Every song that was playing when every line was written, regenerated on every push to master. **[Docs](https://the-shit.github.io/music/)** · **[Vibes](https://the-shit.github.io/music/vibes.html)** · **[Commands](https://the-shit.github.io/music/commands.html)** · **[MCP](https://the-shit.github.io/music/mcp.html)** How the soundtrack happens -------------------------- [](#how-the-soundtrack-happens) 1. **You listen** — Spotify plays while you code, like it already does. 2. **The hook captures** — a pre-commit hook asks the CLI what's playing and appends the track URL to your commit message. 3. **CI enforces** — the Vibe Check gate scans every commit for a Spotify URL. No music, no merge. 4. **The vibes page regenerates** — every push to master rebuilds the soundtrack of the whole repo. It's enforced by the same pipeline as PHPStan and test coverage. Music is a CI gate here, not a gimmick. Quick Start ----------- [](#quick-start) ``` composer global require the-shit/music spotify setup # Configure Spotify API credentials spotify login # Authenticate via OAuth spotify play "Killing In the Name" spotify current # See what's playing ``` That's it. The hook and CI gate are wired up per-repo — see [CONTRIBUTING.md](CONTRIBUTING.md). The Premium Player ------------------ [](#the-premium-player) `spotify player:premium` — a full php-tui player in your terminal. Album art rendered as ANSI, mood-aware theming, a search palette with play-now and queue actions, playlist browsing, and a queue peek. It's the player a vibes-enforced codebase deserves. [![Premium player demo — mood theming, lyrics, queue peek, and the search palette](docs/demo/premium-player.gif)](docs/demo/premium-player.gif) ``` spotify player:premium ``` (The classic `spotify player` TUI is still there if you want something lighter.) And it's a full Spotify CLI --------------------------- [](#and-its-a-full-spotify-cli) The soundtrack is enforced, but the day-to-day tooling carries its weight too: 30+ commands, 12 MCP tools, mood-aware autopilot, event-driven integrations. Every feature is a layer you opt into — nothing assumes anything else is running. LayerWhat it doesRequired?**CLI commands**Play, pause, skip, queue, search, volume, shuffle, repeatJust this**Premium player**php-tui player with art, mood theming, search palette`spotify player:premium` when you want it**MCP server**12 tools for AI assistants (Claude, etc.) to control SpotifyConfigure if you use AI tools**Daemon**Headless Spotify Connect speaker via spotifydInstall if you want background playback**Media bridge**macOS Control Center + media keys via native SwiftInstall if you want media key control**Autopilot**Background queue auto-refill with mood presetsInstall if you want hands-off listening**Slack integration**Share now-playing to Slack channelsSet up if you use Slack**Webhooks**Forward playback events to any URL with HMAC signingConfigure if you want event-driven automation**Event streaming**JSON Lines event bus for track changes, state transitionsEnable if you're building on top of thisSee the full [command reference](https://the-shit.github.io/music/commands.html) for all 32 commands. Why This Instead Of... ---------------------- [](#why-this-instead-of) **spotify\_player / ncspot / spotatui** — Great TUI players. But they only play music. No commit soundtrack, no MCP server, no queue intelligence, no integrations. If you just want a terminal UI, those are solid. If you want Spotify as composable infrastructure — and your git history to have a soundtrack — this is it. **Standalone MCP servers** — There are a handful on Smithery/GitHub. Most are weekend scripts with 3-5 tools and no maintenance. This is a real application with 12 MCP tools, 2 resources, battle-tested against Spotify's API deprecations, and actively maintained. **The Spotify desktop app** — 800MB Electron app. This is 30 commands in a single binary. MCP Server ---------- [](#mcp-server) This CLI doubles as an [MCP server](https://the-shit.github.io/music/mcp.html) — AI assistants like Claude can control your Spotify directly. 12 tools for playback, queue, search, and discovery. ``` { "mcpServers": { "spotify": { "command": "spotify", "args": ["mcp:start", "spotify"] } } } ``` See the [MCP setup docs](https://the-shit.github.io/music/mcp.html) for Claude Desktop, Claude Code, and OpenCode configuration. Mood-Aware Queue ---------------- [](#mood-aware-queue) Built-in mood presets that queue tracks matching an energy profile. Each uses Spotify's audio feature targeting with smart deduplication against your queue and recent history. ``` spotify chill # Lofi, acoustic, ambient spotify flow --duration=60 # Deep work focus spotify hype # High energy, workout spotify autopilot --install --mood=hype # Set it and forget it ``` Autopilot watches for track changes and auto-refills the queue when it drops below a threshold. Supports moods: `chill`, `flow`, `hype`, `focus`, `party`, `upbeat`, `melancholy`, `ambient`, `workout`, `sleep`. macOS Services -------------- [](#macos-services) Three optional background services, each managed via `launchd` with auto-restart and logging. **spotifyd** — headless Spotify Connect speaker: ``` spotify daemon:setup && spotify daemon install ``` **Swift Media Bridge** — Control Center + media keys: ``` spotify setup:media-bridge ``` **Autopilot** — background queue auto-refill: ``` spotify autopilot --install --mood=flow ``` ServiceLaunchAgentRunAtLoadKeepAliveLogsspotifyd`com.spotify-cli.spotifyd`YesYes`~/.config/spotify-cli/spotifyd.log`media-bridge`com.theshit.media-bridge`YesYes`~/.config/spotify-cli/media-bridge.log`autopilot`com.theshit.autopilot`No (on-demand)Yes`~/.config/spotify-cli/autopilot.log`Integrations ------------ [](#integrations) **Slack** — share now-playing to a channel: ``` spotify slack setup && spotify slack now ``` **Webhooks** — forward events with HMAC signing: ``` spotify webhook:configure --url=https://your.endpoint/hook --secret=your-secret ``` **Event streaming** — the `watch` command emits JSON Lines events (`track.changed`, `playback.paused`, `playback.resumed`, etc.) that you can pipe anywhere: ``` spotify watch --json | your-consumer ``` Contributing ------------ [](#contributing) PRs welcome. Pick an [issue](https://github.com/the-shit/music/issues), ship it, CI handles the rest. CI runs three automated gates on every PR — no manual review bottleneck: GateWhat it checks**PHPStan**Static analysis at level 5 (type safety, param mismatches)**Sentinel Gate**Test coverage ≥ 50%**Vibe Check**Every commit has a Spotify track URLAll must pass. See [CONTRIBUTING.md](CONTRIBUTING.md) for setup. Requirements ------------ [](#requirements) - PHP 8.2+ - Composer - Spotify Premium account - A [Spotify Developer](https://developer.spotify.com/dashboard) application License ------- [](#license) MIT ### Health Score 39 — LowBetter than 85% of packages Maintenance67 Regular maintenance activity Popularity6 Limited adoption so far Community10 Small or concentrated contributor base Maturity62 Established project with proven stability Bus Factor1 Top contributor holds 86.3% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~98 days Total 3 Last Release 130d ago Major Versions v0.0.1 → v1.0.12026-02-23 ### Community Maintainers ![](https://www.gravatar.com/avatar/a6bb27de88a541a632427686306c8fc56366d72582f6a3316d20500efe7971f3?d=identicon)[conduit-ui](/maintainers/conduit-ui) --- Top Contributors [![jordanpartridge](https://avatars.githubusercontent.com/u/9040417?v=4)](https://github.com/jordanpartridge "jordanpartridge (158 commits)")[![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4)](https://github.com/github-actions[bot] "github-actions[bot] (24 commits)")[![lamwilton](https://avatars.githubusercontent.com/u/16893989?v=4)](https://github.com/lamwilton "lamwilton (1 commits)") --- Tags aiclilaravel-zeromacosmcpmusicshit-componentspotifyspotify-cliterminalcliconsoleframeworklaravellaravel-zero ### Code Quality TestsPest Static AnalysisPHPStan, Rector Code StyleLaravel Pint Type Coverage Yes ### Embed Badge ![Health badge](/badges/the-shit-music/health.svg) ``` [![Health](https://phpackages.com/badges/the-shit-music/health.svg)](https://phpackages.com/packages/the-shit-music) ``` ### Alternatives [laravel-zero/framework The Laravel Zero Framework. 3491.6M432](/packages/laravel-zero-framework)[mehrancodes/laravel-harbor A CLI tool to Quickly create On-Demand preview environment for your apps. 10097.5k](/packages/mehrancodes-laravel-harbor) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)