Beta Notice - StarryNight is getting ready for the Spicetify Marketplace. Expect rapid updates and please report anything that feels off.
Catppuccin StarryNight turns Spotify into a living, music-reactive canvas. Built on the Catppuccin palette, it blends real-time album color harmonies, beat-synced visuals, and a performance-conscious architecture so you can enjoy the show on everything from ultrabooks to studio rigs.
- Dynamic Catppuccin palette - Album art feeds the OKLAB color pipeline for instant mood shifts across the UI.
- Music-aware visuals - The Visual Effects Coordinator keeps gradients, particles, and UI accents in sync with BPM, energy, and emotional tone.
- Performance-first - Unified animation loop, batched CSS variable updates, and adaptive quality tiers target 60 FPS while gracefully degrading when hardware or APIs fall back.
- Built-in settings - Tweak flavor, accent behavior, flow intensity, and performance modes directly inside Spotify.
- Accessible by design - Honors reduced-motion and high-contrast preferences with automatic fallbacks.
- Install the Spicetify CLI and make sure Spotify is up to date.
- Follow the detailed install instructions in
docs/BUILD_AND_DEPLOY.md(covers install scripts, manual setup, validation, and troubleshooting). - Launch Spotify, open Settings -> Catppuccin StarryNight, and dial in your vibe.
Note: The detailed guide above is the source of truth, but quick scripts are available:
# Windows PowerShell
iwr -useb "https://raw.githubusercontent.com/minipuft/catppuccin-starrynight/main/install.ps1" | iex# Linux / macOS
curl -fsSL "https://raw.githubusercontent.com/minipuft/catppuccin-starrynight/main/install.sh" | sh# Hybrid (WSL detecting Windows paths)
curl -fsSL "https://raw.githubusercontent.com/minipuft/catppuccin-starrynight/main/install-hybrid.sh" | bashScripts will rebuild/install the theme automatically. Manual steps remain documented in docs/BUILD_AND_DEPLOY.md.
 Home |
 Album |
 Favorites |
 Search |
Open Settings -> Catppuccin StarryNight in Spotify to adjust:
- Flavor (Latte, Frappe, Macchiato, Mocha)
- Dynamic accent vs. static palette
- Flow/gradient intensity and blur
- Star density/speed and UI highlight energy
- Performance profile (battery, balanced, performance, premium)
For deeper tweaks (CSS variables, override examples), see docs/STYLING_AND_TOKENS.md.
Start at the Documentation Index. Key guides:
| Document | Why you might need it |
|---|---|
docs/ARCHITECTURE.md |
Lifecycle, coordinators, and system layout. |
docs/COLOR_AND_AUDIO.md |
MusicSyncService, ColorHarmonyEngine, OKLAB pipeline. |
docs/BUILD_AND_DEPLOY.md |
Build scripts, validation, CI overview, install notes. |
docs/PERFORMANCE_OPTIMIZATION_GUIDELINES.md |
Current performance targets and quality scaling. |
docs/GRACEFUL_DEGRADATION_GUIDE.md |
How the theme handles missing APIs/hardware. |
Legacy research lives under docs/legacy/ if you want the full history.
Bugs, ideas, or pull requests are welcome:
- File issues with the appropriate template in the issue tracker.
- Before contributing code, skim the core docs above so your changes stay aligned with the architecture.
- Catppuccin for the legendary palette.
- Spicetify for making Spotify customisation possible.
- Everyone in the community providing feedback, testing, and inspiration.
Released under the MIT License. See LICENSE for details.