Local Environment Setup

Relevant source files

The following files were used as context for generating this wiki page:

• AGENTS.md
• README.md
• Scripts/check.sh
• Backend/spotty-playback/build-xcframework.sh
• Scripts/package-app.sh
• CONTRIBUTING.md

Local environment setup defines the necessary toolchains, signing identities, and build procedures required to develop and run Spotty on macOS. Because Spotty is an experimental project utilizing private interfaces and Apple Silicon native capabilities, the environment must strictly adhere to specific hardware and software versions.

Building from source serves as the primary method for running the application. You must maintain a Spotify Premium account and an Apple Silicon Mac running macOS 15 or newer to ensure compatibility with the AVFoundation and librespot playback engine.

Sources: README.md:1-10, README.md:38-42, AGENTS.md:4-8

System Requirements

The environment requires specific hardware and software configurations to support native Swift and Rust interoperation.

Requirement	Specification
Operating System	macOS 15+
Architecture	Apple Silicon (arm64)
Account	Spotify Premium
Developer Tools	Xcode 26.2+ (for actool), Clang, Swift, and optionally Rust
Signing	Apple Development identity (Xcode Personal Team is sufficient)

Sources: README.md:4-8, README.md:42-45, Backend/spotty-playback/build-xcframework.sh:37-45, Scripts/package-app.sh:42-48

Core Development Workflow

The setup process begins with cloning the repository and executing the build script. The system manages dependencies by downloading a checksum-pinned playback XCFramework via SwiftPM, meaning local Rust tools are only required if you intend to modify the playback engine.

This diagram illustrates the sequence from initial repository setup to the first authenticated launch.

Sources: README.md:47-58, Scripts/check.sh:75-80

Signing and Security Setup

Authenticated development launches require a stable TeamIdentifier to ensure the macOS Keychain can store OAuth credentials across rebuilds. Without a stable Apple-issued signing identity, you will encounter frequent password prompts.

1. Identity Selection: Set SPOTTY_DEVELOPMENT_SIGNING_IDENTITY to your Apple Development certificate name.
2. Keychain Persistence: The system validates the app anchor and Team ID to prevent credential loss.
3. Local Development Signatures: If no Apple identity is provided, the package-app.sh script generates a "Spotty Local Development" self-signed certificate for build-only purposes.

Sources: README.md:58-62, Scripts/check.sh:196-210, Scripts/package-app.sh:139-183

Build Configurations and Variables

Environment variables control the scope of local verification and build behavior.

Variable	Values	Description
SPOTTY_BUILD_CONFIGURATION	debug, release	Determines optimization levels and debug symbols.
SPOTTY_CHECK_SCOPE	full, rust, swift	Limits validation checks to specific language stacks.
SPOTTY_SIGNING_IDENTITY	Certificate Name	Used for Developer ID distribution builds.
SPOTTY_PLAYBACK_LOCAL_XCFRAMEWORK	Path	Forces the use of a source-built playback engine instead of the remote pin.

Sources: Scripts/check.sh:7-25, Scripts/report-size.sh:65-75, Scripts/package-app.sh:1-10

Playback Engine Setup (Optional)

If you are modifying the Rust/librespot leaf, you must provision a Rust toolchain. The repository includes scripts to generate C headers and package the Rust code into an XCFramework for Swift consumption.

• Rust Validation: The check.sh script runs cargo clippy and cargo test on the Backend/spotty-playback directory.
• ABI Integrity: Clang parses the C header (spotty_playback.h) to verify that exported symbols match the static library and the Swift PlaybackCore.swift adapter.
• Framework Creation: build-xcframework.sh uses xcodebuild to package the arm64 static library and headers.

This sequence represents the additional steps required when setting up for playback engine development.

Sources: Scripts/check.sh:40-60, Scripts/check.sh:82-110, Backend/spotty-playback/build-xcframework.sh:69-90

Summary

Setting up the Spotty local environment primarily involves ensuring macOS 15+ compatibility and establishing a stable Apple Development signing identity. While the Swift application build is automated via build_and_run.sh, manual configuration of signing is critical for a functional authentication lifecycle and Keychain access. Development of the playback engine requires additional Rust tools and strict ABI validation against the Swift core.

Sources: README.md:38-45, AGENTS.md:37-43, Scripts/check.sh:230-240