Appendix M: CryoTunes Player (Shop Manual)
Status: Live on the App Store as of 2026-03-26. Current version 2.4 (build 2.5). App Apple ID 6761222456. Bundle ID com.Tangerine.CryoTunes-Player. GPL v3. Public repo at github.com/fluhartyml/CryoTunesPlayer. App Store: apps.apple.com/us/app/cryotunes-player/id6761222456. CryoTunes Player is a 90's-retro-inspired iPhone music player — ice-blue motif drawn from the Winamp / Napster / LimeWire visual era, MusicKit streaming underneath. It's the book's flagship music app and the host of the shared CryoKit data layer (covered in Appendix B).
What it is
An iPhone-only retro player whose look-and-feel sits firmly in the 90's: chunky transport controls, an LCD ticker, ice-blue chrome. Underneath that surface, all playback is modern Apple MusicKit. The station catalog (80+ entries) is the same one driving Tally Matrix Clock (Appendix W) — both apps share the CryoKit Swift package.
The CryoKit dependency — DIAMOND RULE
CryoTunes Player's data layer is the CryoKit Swift package, not source local to this project. Per the package's DIAMOND RULE (Appendix B): nothing in CryoKit changes without express written consent from Michael, and Claude may never remove or subtract code there. This rule exists because the same package backs Tally Matrix Clock on tvOS — an edit that makes sense for the music player can quietly break the clock.
Anything touching stations, decades, year picks, or the station catalog itself lives in CryoKit. Anything touching the iPhone-specific UI — transport controls, LCD ticker, settings — lives in this project.
Architecture overview
The project is small. SwiftUI app, MusicKit-backed, no SwiftData (CryoKit handles the data side), shared package as the engine.
File roles:
- App entry:
CryoTunes_PlayerApp.swift(the@mainscene),ContentView.swift(the player surface). - Custom controls in
Views/:CryoTransportControls.swift— the play / pause / skip / stop row plus the shuffle / repeat row and the like / dislike / share row. Three composed rows, one named view.CryoStationPicker.swift— the three-level station picker (Category → Decade → Year). Built from SwiftUI buttons, not Apple'sPickerprimitive — the design didn't fit a stock picker.CryoSleepTimerPicker.swift— sleep timer choices (30m / 1h / 2h / 4h), again as a button tree.AlbumDetailView.swift— album-art-focused detail surface with a context menu of song / artist / share actions.
- Managers:
PlaylistManager.swift— queue construction + current-track tracking.FavoriteManager.swift— per-song favorites, locally persisted.DislikeManager.swift— per-song dislikes that the playlist manager honors when constructing the next queue.ShazamManager.swift— ShazamKit song recognition (covered in detail by NightGard Commander's hardened version — see Appendix P).StationFailureMonitor.swift— watches for stations that produce empty queues and surfaces them in a quiet failure state.
- Station model:
StationGrouping.swift— the category / decade / year grouping logic that drives the picker. - Auxiliary surfaces:
SettingsView.swift,FeedbackView.swift(segmentedPickerfor feedback type),LCDTickerView.swift(time + date + local weather via WeatherKit). - Notes:
DeveloperNotes.swift(the canonical roadmap + App Store Connect block; mirror of the wiki Developer-Notes.md).
Three-level station navigation
Stations are organized as Category → Decade → Year. Popular Hits is the spine category (decades 1958 through 2025); Big Band, Jazz Age, Ragtime, and the other genre categories sit alongside it. The user picks Category, then Decade, then Year. Each leaf builds a MusicKit query that drives the playback queue.
CryoStationPicker renders this as a button tree, not a SwiftUI Picker. The pattern matters — readers reaching Book 06 (Controls) see the "stock Picker can't carry every design" example land in this exact file.
Transport + playback
MusicKit's ApplicationMusicPlayer.shared drives playback. CryoTransportControls binds its play / pause buttons to player state and dispatches skip / stop directly. No .toolbar modifier is used here — the transport row is a hand-laid HStack because the design needed exact spacing, sizing, and pill backgrounds the system toolbar doesn't give. (Book 07 cross-references this as a worked example of when .toolbar isn't the right choice.)
LCD ticker + WeatherKit
The LCD ticker at the top of the player runs three lines on a timer: current time, current date, and local weather. WeatherKit is the source for the weather line. Permission UX is the standard one-time Core Location prompt; if denied, the line falls back to a static "−−" placeholder.
Station persistence and the silent-fail rule
The last-tuned station persists across launches, but the app never auto-plays on launch. The user re-taps the station to start playback. This is a deliberate "calm" choice — the player opens to where it was, doesn't blast audio into a quiet room.
The silent-fail-on-station-tap behavior is intentional and locked since 2026-04-29: if a station tap produces an empty queue for any reason (network, subscription state, transient MusicKit error), the app shows no error overlay. The user just sees nothing happen. The errorOverlay binding was stripped on that date because the overlay was firing on transient conditions that resolved themselves a second later; the silent failure is the better UX. StationFailureMonitor still logs the failure for the next development pass, but it doesn't surface to the user.
Build + deployment
- App name: CryoTunes Player (App Store), package shipping as
CryoTunes-Player. - Bundle ID:
com.Tangerine.CryoTunes-Player. - App Apple ID: 6761222456.
- Category: Music.
- Platforms: iPhone only at v1.0. iPad and Mac are v1.1+ items (raise iOS minimum as needed; see roadmap).
- Frameworks: MusicKit (streaming), WeatherKit (LCD weather line), ShazamKit (recognition).
- Subscription disclosure: Apple Music subscription required. Per
feedback_disclose_subscription_requirements.md, this gets stated upfront in App Store copy.
Known gotchas
- Custom background image — dropped from v1.0 canon. The PhotosPicker / persisted custom background feature was dropped 2026-05-03 because the image renders over the UI controls (z-order layering issue). The App Store description and
DeveloperNotes.swiftstill reference cleanup work pending in that area. Future revival of the feature needs a proper layer fix, not another retry of the same approach. - Station tap silent failures are by design. Don't add error overlays back. The 2026-04-29 decision was that transient MusicKit failures resolve themselves and surfacing them annoys more than it helps.
- CryoKit is read-only from this project. The package is shared with Tally Matrix Clock. Local edits to package source via Xcode's "Local" SPM mode have to be reviewed for the clock too before they ship.
- App Store screenshots can't show third-party album art. Per
feedback_app_store_screenshot_ip_rule.md, screenshots that reach App Store review must overlay generic placeholders for any branded IP. Album art shown in dev is fine; album art shown on App Store Connect is a rejection vector.
Roadmap status (from DeveloperNotes.swift)
v1.0 — "Fidget Spinner" Release (Live)
| Feature | Status |
|---|---|
| Xcode project setup | Done |
| GitHub repo (fluhartyml/CryoTunesPlayer) | Done |
| Wiki with hero icon | Done |
| App icons (light + dark variants) | Done |
| Retro 90s player UI (ice blue motif) | Done |
| MusicKit streaming playback | Done |
| 80+ music stations (Category → Decade → Year) | Done |
| Album art display with song title + artist | Done |
| LCD ticker (time / date / WeatherKit) | Done |
| Station persistence (no auto-play) | Done |
| Custom background image (PhotosPicker, persisted) | Dropped 2026-05-03 (z-order) |
| Sleep timer (30m / 1h / 2h / 4h) | Pending |
| AirPlay 2 output picker | Pending |
| Play / Pause / Skip / Stop controls | Done |
| Now Playing info on lock screen | Pending |
| Settings screen | Done |
v1.1+ — Future Enhancements
- Tally Matrix Clock leader / follower sync via CloudKit.
- iCloud sync for settings + background image across devices.
- ShazamKit song recognition (NSMicrophoneUsageDescription required).
- Dark / light automatic icon switching (iOS 18+).
- Additional color themes beyond ice blue.
- Landscape mode.
- iPad support.
- Widget for home screen.
- Easter egg (hidden tap-title-or-idle-screen interaction).
- Queue position persistence (resume exact track on relaunch).
- Custom background image with proper z-order fix.
- Graceful error messages for no-subscription and no-network cases.
Sources
- Project source: github.com/fluhartyml/CryoTunesPlayer (verified 2026-05-10).
- Live on App Store: apps.apple.com/us/app/cryotunes-player/id6761222456.
- Wiki: github.com/fluhartyml/CryoTunesPlayer/wiki.
- Canonical roadmap:
CryoTunes Player/DeveloperNotes.swiftin the project repo. - Shared data layer: Appendix B (CryoKit).
- Companion clock: Appendix W (Tally Matrix Clock).
- Hardened ShazamKit stack: Appendix P (NightGard Library Commander).