MixBoard iOS — Development Summary & Architecture Guide

Project Overview

MixBoard iOS is an iOS/iPadOS music player and mix preparation tool — a companion to the existing MixBoard macOS desktop app. The user listens to their own MP3/FLAC/OGG/Opus files on their phone, builds playlists ("mixes"), and syncs the playlist metadata back to the Mac for export to Adobe Audition or other DAWs.

Repository Locations

macOS app: /Users/vdrobkov/Misc/Documents/Copilot/MixBoard/
iOS app: /Users/vdrobkov/Misc/Documents/Copilot/Mixboard iOS/

Build System

XcodeGen (project.yml → generates MixBoardiOS.xcodeproj)
Run xcodegen generate after adding/removing files or changing project settings
After regenerate, must re-set signing team in Xcode (Signing & Capabilities → Team)
Build for device: xcodebuild -scheme MixBoardiOS -destination 'generic/platform=iOS'
Build for simulator: xcodebuild -scheme MixBoardiOS -destination 'platform=iOS Simulator,name=iPhone 17 Pro'
Run tests: xcodebuild -scheme MixBoardiOSTests -destination 'platform=iOS Simulator,name=iPhone 17 Pro' test
49 unit tests as of last run, all passing

Architecture

App Entry Point

Sources/MixBoardApp.swift

Creates PlayerViewModel, PlaylistViewModel, LibraryManager, AppTheme, SyncManager
Passes them as @Environment / @EnvironmentObject to the view hierarchy
Creates ModelContainer for SwiftData (Track, CuePoint, Playlist, PlaylistEntry, PlaylistFolder)
Has a one-time database reset mechanism (dbResetV6) that nukes SQLite files on first launch after code changes — increment the version key when schema changes

Data Models (`Sources/Models/`)

Track.swift — @Model (SwiftData)

id: UUID, title, artist, album, genre, filePath (relative to Documents), fileName (just the filename for matching)
duration, bpm, musicalKey, sampleRate, bitDepth, channels, fileFormat, fileSizeBytes
year: Int? — release year extracted from the Date metadata tag
dateAdded, lastPlayed, playCount, rating, color, notes
waveformData: Data? — cached waveform
isAnalyzed: Bool — whether BPM/key detection ran
cuePoints: [CuePoint] — cascade delete relationship
fileURL — computed property that resolves Documents/ + filePath, uses .standardizedFileURL to handle /private/var vs /var iOS path discrepancy
IMPORTANT: filePath stores the path relative to the app's Documents directory (e.g., 12.1 Child Udigrudi/12.1.2 Flaviola/01.mp3). The scan uses filePath (not fileName) for duplicate detection, so same-named files in different folders are imported separately.

Playlist.swift — @Model

id, name, notes, dateCreated, dateModified, targetBPM, color (hex)
groupTemplate: String — per-playlist grouping template (e.g., {Album} ({Date}))
entries: [PlaylistEntry] — cascade delete
folder: PlaylistFolder?
WARNING: totalDuration traverses .track relationships which can crash on invalidated SwiftData models. The PlaylistRowView removed the duration display to avoid this.

PlaylistEntry.swift — @Model

position, track: Track?, crossfadeDuration, startOffset, endOffset, gainAdjustment, notes

CuePoint.swift — @Model, Comparable

timestamp, endTimestamp?, color, type: CuePointType (enum: Marker, Intro, Outro, Drop, etc.)

PlaylistFolder.swift — @Model

Groups playlists, nullify delete rule

AppTheme.swift — ObservableObject

7 skins: Winamp, foobar Light, foobar Dark, Windows Media, Obsidian, Vinyl, Tidal
Colors, sizes, cornerRadius, preferredColorScheme
Persisted to UserDefaults

AppState.swift — UserDefaults persistence for last playlist/track/playback position

GroupTemplateResolver.swift

Resolves {Artist}, {Album}, {Genre}, {Date}, {Folder}, {Format}, {BPM}, {Key} placeholders
Presets: No Grouping, Album (Date), Artist — Album, Artist, Album, Genre, Folder, Format, BPM Range

Services (`Sources/Services/`)

AudioEngine.swift — @Observable, @MainActor

AVAudioEngine + AVAudioPlayerNode + 3-band EQ
Handles three playback modes:
1. Standard files (MP3, FLAC, WAV, M4A, etc.) → AVAudioFile + scheduleSegment
2. OGG Vorbis → decoded to AVAudioPCMBuffer via stb_vorbis, played with scheduleBuffer
3. Opus → decoded via libopusfile (compiled from source), same buffer path
Audio session configured for .playback category (background audio)
Handles interruptions (phone calls) and route changes (headphone unplug)
playbackGeneration counter prevents stale completion handlers from triggering auto-advance
Node connections use nil format (auto-negotiate) — critical fix, using fixed output format broke playback for FLAC/OGG

MetadataService.swift

Reads metadata via AVURLAsset for standard formats
Special handling for OGG (via OGGDecoder.fileInfo) and Opus (via opusfile C library — reads Vorbis Comment tags: TITLE, ARTIST, ALBUM, GENRE, DATE)
Extracts year from DATE tag (all formats): checks commonKeyCreationDate, TDRC, TYER, DATE tags
Supported extensions: mp3, wav, aif, aiff, flac, m4a, aac, caf, alac, ogg, opus

OGGDecoder.swift

Uses stb_vorbis.c (public domain, single-file C decoder in Sources/OGG/)
Decodes to non-interleaved float PCM buffer
Bridging header: Sources/OGG/MixBoard-Bridging-Header.h

OpusDecoder.swift

Uses libopusfile (compiled static libraries in Sources/OpusLib/lib/)
op_open_file → op_read_float → deinterleave to AVAudioPCMBuffer
Opus always decodes at 48kHz
Libraries: libogg.a, libopus.a, libopusfile.a — compiled for iOS ARM64 (iphoneos)
Headers in Sources/OpusLib/include/ogg/ and Sources/OpusLib/include/opus/
NOTE: Simulator builds will fail to link because libs are device-only. Build simulator versions from /tmp/opus-build/install-sim/ if needed.

LibraryManager.swift — ObservableObject, @MainActor

Scan: Recursively scans entire Documents directory for audio files, creates Track models
Duplicate detection uses filePath (not fileName) — critical for same-named files in different folders
Path computation: fileURL.standardizedFileURL.path minus docsDir.path — handles /private/var vs /var
fixBadPathsIfNeeded(): One-time migration for tracks with broken paths from earlier bug
scanMusicDirectory(): Called on library view appear (once) and manually from Settings
Import from file picker copies to Documents/Music/
os.Logger with .notice level for debugging

SyncManager.swift — ObservableObject, @MainActor

Exports playlists to Documents/Sync/mixboard-playlists.json
JSON format: SyncPayload → SyncPlaylist → SyncEntry (matched by filename between devices)
Auto-exports when playlist count changes (debounced 2 seconds)
Import from JSON creates playlists, matches tracks by filename

ArtworkService.swift — actor

Cache keyed by track file path (not folder) — each track gets its own artwork
Checks embedded metadata first (most accurate), then folder images (cover.jpg, etc.)
Only accesses files within app sandbox (prevents FIGSANDBOX errors)
Callers pass URL (captured before async) to avoid SwiftData model invalidation

WaveformGenerator.swift, BPMDetector.swift, KeyDetector.swift

Accelerate framework FFT-based analysis
BPM: spectral flux onset detection + autocorrelation (60-200 BPM range)
Key: chromagram + Krumhansl-Kessler profile matching

MediaKeyHandler.swift

MPRemoteCommandCenter for lock screen / Control Center controls
MPNowPlayingInfoCenter updates

ViewModels (`Sources/ViewModels/`)

PlayerViewModel.swift — @Observable, @MainActor

Wraps AudioEngine, syncs state at 30fps via timer
Shuffle, repeat (off/all/one), seek, skip, EQ
Waveform loading with cache
os.Logger debug output for playback: logs file path, exists check, success/failure

PlaylistViewModel.swift — @Observable, @MainActor

3 mix target slots (mixTargets: [Playlist?] array, indices 0-2)
quickAddToMix(slot:track:context:) — adds track to specific mix slot
isDuplicate uses fetchCount query (not relationship traversal) — critical to avoid SwiftData model invalidation crashes
addTracks sorts by filePath with .numeric option for correct folder ordering
Persists mix targets to UserDefaults (mixTarget0ID, mixTarget1ID, mixTarget2ID)

Views (`Sources/Views/`)

ContentView.swift — Root view

No TabView — playlists are the main screen
Mini player at bottom (MiniPlayerView)
Full-screen cover for Now Playing view
Library and Settings opened as sheets from PlaylistListView toolbar

PlaylistListView.swift — Main screen

Title: "MixBoard"
Top-left: Library (music note) and Settings (gear) buttons
Top-right: + button for new playlist
List of playlists with swipe actions (delete, set as target)

PlaylistDetailView.swift

Shows playlist entries, supports grouping via groupTemplate
flatEntryList (no grouping) or groupedEntryList (by template)
Menu: Add Tracks, Set as Target, Grouping..., Export for Mac, Play All
GroupTemplateEditorSheet for editing the grouping template

LibraryView.swift

5 browse modes: Folders (default), Songs, Artists, Albums, Genres
Folders mode shows FolderBrowserView directly
Group action rows: Play, Mix 1/2/3 buttons, + (add to playlist)
Auto-scans on first appear (hasScanned flag)

FolderBrowserView.swift — Drill-down folder navigation

Shows subfolders + audio files at each level
Action row at top with Play/Mix/Add buttons for all tracks recursively
allTracksRecursive cached in @State on appear (not computed in body — performance critical)
Context menu on folders for bulk add
Folder artwork from cover images

NowPlayingView.swift — Full-screen player

Large artwork, waveform, seekbar, transport controls
3 mix buttons (red/blue/gold) with playlist names
Skip ±10s buttons
Presented as .fullScreenCover

MiniPlayerView.swift — Bottom bar

Progress bar, artwork thumbnail, track info, play/pause, next
Tap opens Now Playing
Buttons use .buttonStyle(.plain) with 44pt touch targets

TrackRow.swift — Reusable track row

Artwork, title, artist, BPM, key, duration, format badge
3 colored mix buttons (1=red, 2=blue, 3=gold)
Currently playing indicator

SettingsView.swift

Mix Targets configuration (3 slots, tap row to pick playlist)
App Icon color picker (10 variants)
Skin picker (7 skins)
Sync export/import
Library stats + Reset Library & Rescan button
About section

AddToPlaylistSheet.swift, AddGroupToPlaylistSheet.swift, GroupTemplateEditorSheet.swift, EntryNotesSheet.swift

Various action sheets for playlist management

Tests (`Tests/ModelTests.swift`)

49 tests covering: Track, Playlist, PlaylistEntry, CuePoint, PlaylistFolder, AppState, Sync encoding/decoding, MetadataService, AppTheme, Color hex parsing

Key Technical Decisions & Known Issues

SwiftData Model Invalidation (CRITICAL)

SwiftData @Model objects can become invalidated when:

The backing store is modified by a concurrent save
A scan/import runs while the UI holds model references
Relationship traversal (.track?.property) on invalidated entries

Mitigations applied:

isDuplicate uses fetchCount query instead of relationship traversal
PlaylistRowView removed formattedTotalDuration (traverses .track)
ArtworkService receives URL (captured before async), not Track model
allTracksRecursive cached in @State, not computed in body
Database reset mechanism for corrupted stores

File Path Handling (iOS-specific)

iOS resolves /var/mobile/... to /private/var/mobile/... for file URLs
Must use .standardizedFileURL before computing relative paths
Track.fileURL uses standardizedFileURL for resolution

Background Audio

Info.plist must have UIBackgroundModes: ["audio"] as an array (not string)
Configured via Info.plist file referenced in project.yml info: section
Audio session category set to .playback in AudioEngine.init()

OGG/Opus Native Libraries

stb_vorbis.c in Sources/OGG/ — single-file C decoder for OGG Vorbis
libogg.a, libopus.a, libopusfile.a in Sources/OpusLib/lib/ — compiled for iOS ARM64
Headers in Sources/OpusLib/include/
Bridging header at Sources/OGG/MixBoard-Bridging-Header.h
Simulator builds require simulator-compiled libraries (not currently included)
Build scripts at /tmp/opus-build/build_ios.sh (may need recreation)

Sync Between iOS ↔ macOS

iOS auto-exports mixboard-playlists.json to Documents/Sync/
macOS has SyncImporter.swift and SyncWatcher.swift (partially integrated)
Match tracks by filename between devices
Transfer via AirDrop, iCloud Drive, USB, or Files app

File Structure

Sources/
├── MixBoardApp.swift              # App entry point
├── Models/
│   ├── Track.swift                # Core track model
│   ├── Playlist.swift             # Playlist + PlaylistEntry models
│   ├── PlaylistFolder.swift       # Folder grouping
│   ├── CuePoint.swift             # Cue markers
│   ├── AppState.swift             # UserDefaults persistence
│   ├── AppTheme.swift             # 7 skins
│   └── GroupTemplateResolver.swift # Playlist grouping templates
├── ViewModels/
│   ├── PlayerViewModel.swift      # Playback state
│   └── PlaylistViewModel.swift    # Playlist CRUD, 3 mix targets
├── Views/
│   ├── ContentView.swift          # Root view
│   ├── PlaylistListView.swift     # Main screen (playlists)
│   ├── PlaylistDetailView.swift   # Playlist detail + grouping
│   ├── LibraryView.swift          # Library browser (5 modes)
│   ├── FolderBrowserView.swift    # Drill-down folder navigation
│   ├── NowPlayingView.swift       # Full-screen player
│   ├── MiniPlayerView.swift       # Bottom player bar
│   ├── TrackRow.swift             # Track row + 3 mix buttons
│   ├── WaveformView.swift         # Canvas waveform
│   ├── SettingsView.swift         # Settings + mix targets + icon picker
│   ├── AddToPlaylistSheet.swift   # Single track → playlist
│   ├── AddGroupToPlaylistSheet.swift # Multiple tracks → playlist
│   └── GroupTemplateEditorSheet.swift # Grouping template editor
├── Services/
│   ├── AudioEngine.swift          # AVAudioEngine playback
│   ├── MetadataService.swift      # Tag reading (all formats)
│   ├── LibraryManager.swift       # File scanning & import
│   ├── SyncManager.swift          # JSON sync export/import
│   ├── ArtworkService.swift       # Album art (embedded + folder)
│   ├── OGGDecoder.swift           # OGG Vorbis via stb_vorbis
│   ├── OpusDecoder.swift          # Opus via libopusfile
│   ├── WaveformGenerator.swift    # Accelerate-based waveform
│   ├── BPMDetector.swift          # Spectral flux BPM detection
│   ├── KeyDetector.swift          # Chromagram key detection
│   └── MediaKeyHandler.swift      # Lock screen controls
├── OGG/
│   ├── stb_vorbis.c              # C decoder (public domain)
│   ├── stb_vorbis_wrapper.h      # Header wrapper
│   └── MixBoard-Bridging-Header.h # Swift-C bridge
├── OpusLib/
│   ├── include/ogg/*.h           # libogg headers
│   ├── include/opus/*.h          # libopus + opusfile headers
│   └── lib/*.a                   # Static libraries (iOS ARM64)
└── Resources/
    └── Assets.xcassets/          # App icons (10 color variants)
Tests/
└── ModelTests.swift              # 49 unit tests
project.yml                       # XcodeGen project definition
Info.plist                        # Background audio mode
MixBoardiOS.entitlements         # App group entitlement
Package.swift                    # SPM (for library builds)

Common Operations

Adding a new file

Create the file in the appropriate Sources/ subdirectory
Run xcodegen generate to add it to the Xcode project
Re-set signing team in Xcode

Changing project settings

Edit project.yml
Run xcodegen generate
Re-set signing team

Database schema changes

Modify @Model classes
Increment the dbResetV* key in MixBoardApp.init() to force a clean database
Users will need to rescan their music library

Testing on device

Cmd+R in Xcode (must have team set)
Free Apple ID: app expires after 7 days, max 3 devices
Delete app from phone to clear corrupted database (loses music files!)
Use Settings → Reset Library & Rescan instead of deleting the app

Debugging playback

Check Xcode console for loadAndPlay: log lines
Shows file path, exists check, success/failure
scanMusicDirectory: shows how many files were found on disk

DEVELOPMENT_SUMMARY.md 17 KB Historie Surový