Music/docs/superpowers/specs/2026-05-23-music-player-design.md

Music Player — Design Spec

A high-performance macOS music player built with SwiftUI + AppKit. Reads a local music collection from disk, indexes metadata into SQLite for fast search/sort/filter, and plays audio via AVPlayer.

Constraints

• Library size: 10,000+ tracks, 100GB+, growing
• All search, sort, and filter operations must feel instant (<50ms)
• macOS 15.6+ (current project target)
• No external music service integration — local files only

Data Model

SQLite database via GRDB, stored at ~/Library/Application Support/Music/db.sqlite.

tracks table

Column	Type	Notes
id	INTEGER PRIMARY KEY	Auto-increment
fileURL	TEXT, UNIQUE	Absolute path to audio file
title	TEXT	From metadata, fallback to filename
artist	TEXT
albumArtist	TEXT
album	TEXT
genre	TEXT
year	INTEGER
trackNumber	INTEGER
discNumber	INTEGER
duration	DOUBLE	Seconds
bpm	INTEGER
composer	TEXT
fileFormat	TEXT	mp3, m4a, flac, etc.
bitrate	INTEGER	kbps
sampleRate	INTEGER	Hz
fileSize	INTEGER	Bytes
artworkData	BLOB, nullable	Embedded cover art
playCount	INTEGER DEFAULT 0	Tracked by app
lastPlayedAt	DATETIME, nullable	Tracked by app
rating	INTEGER DEFAULT 0	0–5, tracked by app
dateAdded	DATETIME	When imported
dateModified	DATETIME	File modification date
fileHash	TEXT	fileSize + modificationDate for change detection

Indexes

• Individual: artist, album, genre, year
• Compound: (albumArtist, album, discNumber, trackNumber) for album browsing order

FTS5 virtual table

• Indexed columns: title, artist, albumArtist, album, genre, composer
• Kept in sync via GRDB FTS5 triggers

Architecture

Four layers, strict downward dependency only.

UI Layer

• NSTableView wrapped in NSViewRepresentable for the track list
• SwiftUI for search bar and player controls
• No business logic in views

ViewModel Layer

LibraryViewModel (ObservableObject):

• Holds current query state: search text, sort column, sort order
• Subscribes to GRDB ValueObservation — receives [Track] on every query change
• Exposes results to the NSTableView data source

PlayerViewModel (ObservableObject):

• Current track, playback state (playing/paused/stopped), current time, duration
• Queue management: current queue (array of tracks), current index
• Shuffle state and shuffled queue

Service Layer

DatabaseService:

• Owns the GRDB DatabasePool
• Schema migrations
• Query builders for search (FTS5 MATCH), sort (ORDER BY indexed columns), filter

ScannerService:

• Background folder walking with FileManager
• Metadata extraction via AVAsset.metadata (async)
• Artwork extraction from embedded tags
• Incremental rescan via fileHash comparison
• Progress reporting

AudioService:

• AVPlayer wrapper
• Play, pause, stop, seek, next, previous, volume
• Periodic time observation for progress bar
• Updates playCount/lastPlayedAt in DB when track finishes or passes 50% played

Data Layer

• SQLite + FTS5 via GRDB
• Database file at ~/Library/Application Support/Music/db.sqlite

Data Flows

Scan: User picks folder → ScannerService walks directory on background thread → extracts metadata with AVAsset → inserts into DB → ValueObservation fires → LibraryViewModel updates → NSTableView reloads

Search: User types in search bar → LibraryViewModel updates query string → new SQL query with FTS5 MATCH → ValueObservation emits new results → table reloads

Sort: User clicks column header → LibraryViewModel updates sort column/order → new SQL ORDER BY → same reactive flow

Play: User double-clicks row → PlayerViewModel receives track → AudioService loads file URL → playback starts → controls update

UI Layout

Single window, three vertical zones.

Zone 1: Search Bar (top)

• Full-width text field with placeholder: "Search by title, artist, album, genre..."
• Track count label on the right (e.g., "10,342 tracks")
• SwiftUI TextField

Zone 2: Track List (middle, fills available space)

• NSTableView via NSViewRepresentable
• Columns: Title, Artist, Album, Genre, Duration
• Sortable by clicking column headers (ascending/descending toggle)
• Currently playing track: blue left accent bar + play indicator in title cell
• Alternating row colors (white / light gray) for readability
• Double-click to play, single-click to select
• Light theme: white backgrounds, Apple system gray text hierarchy

Zone 3: Player Controls (bottom)

Three sections in a horizontal grid:

Left — Now Playing:

• Album artwork thumbnail (44×44, rounded corners)
• Track title (bold) + "Artist — Album" subtitle

Center — Transport:

• Shuffle toggle (dimmed when off, highlighted when on)
• Previous, Play/Pause, Next buttons
• Progress bar with current time / total time

Right — Volume:

• Speaker icon + volume slider

Scanner & Import

Folder scanning (primary)

• User selects root folder via NSOpenPanel
• Recursive directory walk on background thread
• Supported extensions: .mp3, .m4a, .aac, .wav, .aiff, .alac, .flac
• Metadata extraction via AVAsset.metadata
• Artwork from embedded tags → stored as BLOB
• fileHash = file size + modification date (fast, sufficient for change detection)
• Progress reported: "Scanning... 4,231 / 10,342 tracks"
• Watched folder path stored in UserDefaults

Drag and drop (secondary)

• Files/folders dropped onto the window
• Folders recursively scanned same as above
• Duplicates detected by fileURL uniqueness constraint — silently skipped

Incremental rescan

• Triggered on app launch or manually
• New files → insert
• Changed files (different fileHash) → re-extract metadata, update row
• Missing files → remove from DB

Playback & Queue

Queue model

• Current track list (full library or filtered/searched results) acts as the play queue
• Double-click a track → starts playing from that position in the current queue
• Next/Previous navigate within the queue
• Searching/filtering while playing does not interrupt playback — queue only changes on explicit play action

Shuffle

• Toggle on → build shuffled copy of current queue, starting from current track
• Toggle off → return to original queue position
• New search/filter while shuffle is on → re-shuffle new result set

Play tracking

• playCount incremented and lastPlayedAt updated when a track finishes or passes 50% played

Not in v1

• Repeat modes (repeat-one, repeat-all)
• Crossfade
• Equalizer
• Playlists

Error Handling

• Unreadable audio file (corrupt, DRM, unsupported) → skip during scan, log to console
• File moved/deleted after import → AVPlayer fails to load → inline error in player controls ("File not found"), auto-advance to next track
• Metadata extraction fails → use filename as title, "Unknown" for artist/album, still import
• Folder permission denied → system alert, prompt to grant access in System Settings
• Database migration failure → surface error, do not launch with broken schema

Dependencies

• GRDB (Swift Package) — SQLite wrapper with reactive observation
• AVFoundation (system) — audio playback and metadata extraction
• AppKit (system) — NSTableView for high-performance track list
• SwiftUI (system) — search bar, player controls, app structure

Audio Format Support

Natively handled by AVFoundation on macOS:

• MP3, AAC/M4A, WAV, AIFF, ALAC, FLAC