Introduction to Spotty
Relevant source files
The following files were used as context for generating this wiki page:
Spotty is an experimental, independent Spotify Premium client for macOS 15+ on Apple Silicon. It provides a native music experience using SwiftUI and AppKit for the interface, while delegating session management and audio streaming to a Rust-based backend. The project operates as an unofficial personal experiment and is not affiliated with Spotify AB.
Sources: README.md:1-13, AGENTS.md:1-5
The system prioritizes native macOS behavior, session safety, and small product surface area. It uses reverse-engineered interfaces and private desktop-client authorization flows. Developers must treat the project as an experimental platform where breakage and policy risks are expected.
Sources: AGENTS.md:7-10, SECURITY.md:3-7
System Architecture
Spotty separates high-level application logic from low-level playback mechanics through a clear multi-layer architecture. Swift dependencies flow from the entry point down to the domain logic.
Sources: AGENTS.md:43-45, Sources/Spotty/AGENTS.md:10-16
Architectural Layers
| Layer | Component | Responsibility |
|---|---|---|
| App | SpottyApp | Thin launcher that assembles the live object graph at the composition root. |
| Core | SpottyCore | Orchestrates top-level services and stores (e.g., PlaybackStore, PlaybackCoordinator). |
| Domain | SpottyDomain | Contains portable domain policy, state snapshots, and reducers. |
| Playback | SpottyPlaybackCore | C ABI bridge that wraps the Rust/librespot engine. |
Sources: AGENTS.md:43-45, Sources/Spotty/AGENTS.md:10-18, Sources/Spotty/Spotify/AGENTS.md:12-16
Data and Command Flow
The application follows a strict unidirectional data flow for playback state. The PlaybackStore acts as the main actor-isolated surface for state and actions.
Sources: Sources/Spotty/Spotify/AGENTS.md:12-14
This diagram illustrates how user actions trigger state mutations and engine commands, while audio flows directly from the Rust engine to the system audio framework.
Sources: AGENTS.md:52-54, Sources/Spotty/Spotify/AGENTS.md:12-15, Sources/Spotty/Spotify/AGENTS.md:39-41
Playback Engine
The playback implementation relies on a pinned librespot revision built as a Rust static library. Decoded Pulse-Code Modulation (PCM) data crosses a narrow C ABI adapter to reach the AudioRenderer in Swift.
Sources: AGENTS.md:52-54, Sources/Spotty/Spotify/AGENTS.md:9-11
FFI and ABI Surface
The SpottyPlaybackCore module provides the Swift-facing description of the Rust playback ABI. RustPlaybackEngine.swift is the exclusive caller of this bridge. The bridge handles four observation families crossing the Foreign Function Interface (FFI) as typed C snapshots.
Sources: Sources/SpottyPlaybackCore/AGENTS.md:4-10, Sources/Spotty/Spotify/AGENTS.md:31-34
The sequence shows the initialization and track loading flow across the language boundary.
Sources: Sources/SpottyPlaybackCore/AGENTS.md:4-7, Sources/Spotty/Spotify/AGENTS.md:31-33
Development and Verification
Development is exclusively performed by automated agents or contributors following the AGENTS.md instructions. The project enforces strict quality gates via a central verification script.
Sources: AGENTS.md:16-19, Scripts/check.sh:1-5
Verification Pipeline
The Scripts/check.sh script executes the following checks:
- Source Policy: Validates formatting and internal project rules.
- Rust Lane: Runs
cargo fmt,clippy, and unit tests for the backend. - C ABI Sync: Ensures the C header and Rust archive exports match exactly.
- Swift Lane: Compiles the app, runs
SpottyDomainTestsandSpottyBoundaryTests. - Packaging: Lints
Info.plistand verifies app bundle identity.
Sources: Scripts/check.sh:25-35, Scripts/check.sh:86-95, Scripts/check.sh:160-180
Build and Artifact Management
SwiftPM downloads a checksum-pinned SpottyPlaybackCore.xcframework for standard builds. Source-built engine overrides are supported via the SPOTTY_PLAYBACK_LOCAL_XCFRAMEWORK environment variable.
Sources: README.md:50-55, Scripts/check.sh:75-78
Security and Privacy
Spotty implements a direct-to-service architecture with no intermediate servers. All sensitive data stays local to the user's Mac.
Sources: README.md:60-65, PRIVACY.md:8-10
- Authentication: OAuth credentials reside in the macOS Keychain. Authenticated development requires an Apple Development signing identity with a stable Team ID.
- Logging: Operational events are recorded via Apple Unified Logging. Logs are designed to exclude tokens and raw API bodies.
- Telemetry: The application contains no analytics, advertising, or crash-reporting SDKs.
- Caching: Artwork and streaming session credentials are stored in bounded, app-scoped local directories.
Sources: README.md:60-65, PRIVACY.md:13-25, SECURITY.md:20-25
Summary
Spotty provides a native macOS interface for Spotify Premium by bridging SwiftUI with a Rust-based playback engine. It maintains a strict architecture where the Rust leaf is isolated behind a narrow C ABI. Development is governed by automated safety contracts and a comprehensive verification suite to ensure session safety and native behavior.
Sources: README.md:1-5, AGENTS.md:43-54, Scripts/check.sh:215-225