Appendix L: Cryo Playlist Manager (Shop Manual)

Status: In submission for Mac App Store; ship dependency for the book's official release. GPL v3. Public repo at github.com/fluhartyml/Cryo-Playlist-Manager. Locked as an appendix reference per project memory. Cryo Playlist Manager is the Mac-side companion to the Cryo music apps (CryoTunes Player in Appendix M, Tally Matrix Clock in Appendix W). It manages Apple Music playlists, imports from Spotify, and provides a Playlist Locker that prevents accidental dynamic changes to the user's curated lists. Built on MusicKit on the Apple side and the Spotify Web API on the Spotify side.

What it is

A macOS app for users who keep their music library serious. Three jobs:

  1. Browse and curate Apple Music. The user's library shown in a Mac-native table, organized by station / decade / year groupings shared with the CryoTunes family.
  2. Import from Spotify. Authenticate against the user's Spotify account, list their Spotify playlists, and replicate tracks into Apple Music where possible (matching by title + artist + duration).
  3. Lock playlists. Apple Music can re-order or substitute tracks in dynamic playlists in ways that surprise the user. The Playlist Locker takes a snapshot of a playlist's contents and lets the user restore it if Apple Music drifts.

Architecture overview

SwiftUI Mac app with two service stacks (Apple Music via MusicKit, Spotify via Web API + OAuth). The project is organized into Views/ and Services/ folders for separation.

Mac-native design choices

This is a Mac-first app, not a Designed-for-iPad-on-Mac port:

The Spotify side

Spotify integration uses the Spotify Web API with OAuth 2.0 (PKCE flow):

  1. User clicks Connect Spotify.
  2. SpotifyAuthManager opens the system browser to Spotify's authorization endpoint with the PKCE challenge.
  3. User approves; Spotify redirects to the app's registered redirect URI.
  4. The app receives the authorization code, exchanges it for an access + refresh token, stores both in the system keychain.
  5. SpotifyService uses the access token for subsequent API calls. When the token expires, the refresh token mints a new one without user interaction.

The keychain storage means Spotify credentials survive restarts and reboots. The refresh-token flow means the user authenticates once.

The Playlist Locker

Apple Music has long-standing behavior where playlists can shift — tracks can be replaced with matched cloud versions, durations can change slightly, occasionally a track can drop out entirely. For a curator, that's an unwelcome surprise. The Locker takes a snapshot of a playlist's track list at lock time and stores it locally. Later, the user can compare the current Apple Music state against the snapshot and choose to restore (re-add missing tracks, re-order to match) or accept the drift (update the snapshot).

The snapshot is per-playlist, with version history. The user can roll back to any previous snapshot, not just the most recent.

Build + deployment

Subscription disclosure

This app needs two third-party subscriptions to operate at full capacity:

Per feedback_disclose_subscription_requirements.md, both requirements are stated upfront in the App Store description. The app's UI also surfaces the subscription state inline when a feature needs it (e.g., the Spotify view shows a Connect Spotify call-to-action when no account is linked).

Known gotchas

Sources