Companion API (4 new endpoints):
- GET /lyrics/search — proxy to LRCLIB, returns matches with sync status
- GET /lyrics/fetch — exact match by artist/title/duration, caches in SQLite
- GET /lyrics/get — checks embedded tags > .lrc sidecar > DB cache
- POST /lyrics/embed — writes LRC into audio file tags via mutagen + .lrc sidecar
- New lyrics table in companion database
iOS data layer (LyricsModels.swift):
- LyricLine/LyricWord structs with Codable conformance
- Full LRC parser (line-level + enhanced word-level timestamps)
- LRC serializer (toLRC) for saving edited timings
- LyricsCache with memory + disk tiers keyed by artist-title
iOS manager (LyricsManager.swift):
- Source pipeline: embedded > .lrc sidecar > local cache > LRCLIB auto-fetch
- Binary search line/word tracking (O(log n))
- Word-level progress for karaoke gradient fill
- Hooked into AudioPlayer time observer (0.5s sync) and pushWidgetState (song change)
iOS views:
- LyricsOverlayView: karaoke word-by-word highlighting via FlowLayout + KaraokeWordView
gradient fill sweep, ScrollViewReader auto-scroll, tap any line to seek
- LyricsSearchSheet: LRCLIB search with debounced input, duration mismatch warnings,
preview sheet, import to cache
- LyricsEditorView: tap-to-sync mode, per-line ±0.1s adjust buttons, global offset
sheet, save to device or embed in file via Companion API
NowPlayingView integration:
- Lyrics toggle button (quote.bubble) in bottom controls bar
- Portrait layout swaps album art for lyrics overlay with animation
- Blur panel: .ultraThinMaterial with gradient mask so visualizer fades through
- Lyrics search/editor sheets wired with notification observer
Mini player lyric ticker:
- Both standard and compact mini player bars show current lyric line
- Accent pink with ♪ prefix, falls back to artist name when no lyrics
- Push transition animation on line changes
Bug fixes included:
- NavidromePlayerApp: removed unnecessary try on CompanionAPIService.shared
- Info.plist: added LSSupportsOpeningDocumentsInPlace for document type support
Gap 1: Lock Screen seek bar drift — nowPlayingSyncTimer (5s timer that
pushes elapsed time to MPNowPlayingInfoCenter) was created in
playWithAVPlayer but never restarted after a background/foreground
cycle. Now invalidated in suspendVisTimers() and recreated in
resumeVisTimers(). The crossfade path benefits too — it never went
through playWithAVPlayer so the timer was never created at all for
crossfade sessions.
Gap 2: Prefetcher re-downloads after restructure — AudioPreFetcher
used isSongDownloaded(song.id) (exact ID match). After a Companion
restructure changes IDs, songs already downloaded were re-fetched.
Changed to isSongAvailableOffline(song) which falls back to
title/artist/duration matching.
Gap 3: Unbounded image disk cache — trimDiskCache() only ran on app
launch. A long browsing session could push well past the 200MB limit.
Now storeToDisk increments a write counter and triggers trim every 50
writes. The counter lives on ioQueue (serial) so no lock needed.
Gap 4: Custom cover art in widget — WidgetBridge cached blur keyed by
coverArtId. Custom covers don’t change the ID, so the bridge skipped
the update. Now pushWidgetState() passes "custom_\(id)" as the key
when AlbumCoverStore has a custom image. Same album’s songs still
share the key → blur is reused, not redone. When custom is removed,
key reverts to the bare ID → re-blurs with server art.
AudioPlayer.swift — startRadioSimulation() replaces
startLevelSimulation() for radio streams. It generates two overlapping
sine waves with a slow breathing amplitude envelope. The key property:
it’s driven by an internal radioPhase counter that increments at a
fixed rate, completely independent of currentTime. Buffer seeks, HLS
restarts, and stream reconnects have zero visual effect.
MitsuhaVisualizerView.swift — Two fixes:
1. TimelineView(.periodic(from: .distantPast, by: tickInterval)) —
using .distantPast as the stable schedule origin instead of .now.
Previously, any recalculation of tickInterval (triggered by
isRenderingActive flipping during a radio buffer hiccup) would reset
the origin to the current moment, deferring the next tick by a full
interval — the visible stall.
2. songId parameter with .onChange(of: songId) that resets
peakFollower, levelHistoryBuf, and lastTickTime on song change. This
prevents the outgoing song’s simulation spike from “raising” the wave
at the start of the next song.
NowPlayingView.swift and MainTabView.swift — Pass songId:
audioPlayer.currentSong?.id through to MitsuhaVisualizerView and
CompactVisualizerView at all call sites.
• Top spacer 54 → 12 — pulls the pill up to sit directly under the
Dynamic Island cutout
• Horizontal padding 32 → 56 — narrows the pill from both sides
• Height 48 → 44 — slightly more compact to match the island’s
proportions
If it’s sitting too high or too low after testing, the spacer value is
the one knob to turn — increase it if it overlaps the island, decrease
if there’s too much gap.
Resolve several playback bugs introduced during the CPU optimization
work. Stop SyncEngine from overwriting the Subsonic album cache with
synthetic Companion IDs, which was silently breaking every album in
the Albums tab by routing through the Companion song path instead of
Navidrome streaming. Fix MiniProgressBar seek gesture dropping touches
by moving the DragGesture outside the TimelineView closure — the 10Hz
timer was reconstructing the gesture recognizer every tick,
interrupting in-progress drags. Add AVPlayerItem status observation to
AudioPlayer so stream failures surface in the debug console instead of
silently stalling. Add fuzzy title/artist/duration fallback to
OfflineManager.localURL so songs remain playable offline after a
Companion API restructure changes their Navidrome ID.
Replace @Published var currentTime/duration with plain vars and drive
progress bars via TimelineView(.periodic) instead of SwiftUI
observation. This stops objectWillChange from firing 20x/second on
AudioPlayer, eliminating continuous body re-evaluation on
NowPlayingView, MiniPlayerBar, and MyMusicView regardless of
visualizer state.
AUDIT-036 — Slider/button fixes (direct Liquid Glass cause)
scheduleFlush() now runs Task { @MainActor } instead of bare Task. The
pendingSaves dictionary is now only ever read/written on the main
thread. Before this fix, a UserDefaults write could race with a slider
didSet, causing values to snap back or write the wrong value — which
is exactly why buttons were switching state unexpectedly.
AUDIT-034 — 60fps idle Canvas (direct Liquid Glass cause)
TimelineView now uses isRenderingActive ? settings.effectiveFPS : 2.0.
When paused or not visible, the Canvas drops from 60fps to 2fps. This
stops the continuous GPU wakeups that were fighting Liquid Glass
gesture tracking, which is why sliders needed multiple attempts.
AUDIT-001 — FFT real-time heap allocation
processFFT no longer allocates any heap memory. The Hann window is
computed once in init(). All four scratch buffers (fftWindow,
fftWindowed, fftRealp/fftImagp, fftMagnitudes) are pre-allocated and
reused every render callback — zero allocations on the real-time audio
thread.
AUDIT-002 — WatchOfflineStore data race
taskToSongId and pendingSongs now protected by a dedicated serial
storeQueue. URLSession delegate reads and main thread writes are
serialised.
AUDIT-019 — URLSession per AsyncCoverArt render
CompanionAPIService() no longer instantiated per render. Companion
cover art URLs now built directly from
CompanionSettings.shared.baseURL — no URLSession created.
AUDIT-020 — Synchronous disk read on main thread
CachedImageLoader now uses memoryOnlyImage (sync, no I/O) for the
first check, then cachedImageAsync (disk read on ioQueue) for the
second. Main thread never blocks on disk I/O.
AUDIT-033 — Lost star/unstar actions offline
Star/unstar now routes through OptimisticActionQueue — actions survive
Tailscale reconnection and are retried automatically.
AUDIT-035 — OptimisticActionQueue flush race
flush() Task is now @MainActor — pendingActions only ever touched on
main thread, no more race between rapid taps and in-flight flushes.
AUDIT-038 — O(n²) deduplication
deduplicateAlbums now O(n) using a frequency dictionary. For 843
albums: ~7.1M string comparisons/second during playback → ~1,700.
AUDIT-026, AUDIT-015 — Duplicate setResourceValue removed, cacheSize
now uses totalSize directly
• Group toggles — iPhone / Watch / Companion / Audio, all persistent
via @AppStorage so your filter state survives app restarts
• Level toggles — ERROR / WARN / INFO / DEBUG in a single scrollable
row next to the group toggles, color coded red/yellow/cyan/gray
• Delta timestamps — each row shows +42ms between it and the previous
entry, so you can see timing without mental math
• Pause/Resume — bottom bar button snapshots the current log so you
can read it without it scrolling, while still capturing in background
• Auto background/foreground markers — ── Background ── / ──
Foreground ── lines are auto-inserted by NotificationCenter, making
crash correlation much easier
• PiP button in toolbar sets logger.isPiP = true, which MainTabView’s
.onChange picks up and activates the existing floating PiP window
MainTabView.swift — minimal changes:
• Added .onChange(of: debugLogger.isPiP) to sync the console’s PiP
button to the existing debugPipMode state
• Updated debugLogRow to show level dot + marker support, consistent
with the full console
Songs Tab (SearchView.swift)
Default state now loads all songs alphabetically from the library via
getAlbumList2 → per-album song fetch, cached under "all_songs_sorted"
so subsequent opens are instant. The Download All banner shows song
count + already-downloaded count and queues only non-downloaded songs.
Every row uses .contextMenu (the long-press menu) with Play Now, Play
Next, Add to Queue, Download/Remove, Send to Watch, and Add to
Playlist — same pattern as Favourites. Watch and download badges
appear on each row. Searching ≥2 chars runs the server search and
shows artists/albums/songs in sections, then clears back to the full
list when the field is empty.
Keyboard Done Button
A single keyboardDoneButton() View extension in AsyncCoverArt.swift
calls UIApplication.shared.sendAction(resignFirstResponder:...)
globally — no @FocusState needed. Applied to: LoginView (all 4
fields), CompanionSettingsView (host/port), TrackEditorView
(checkField helper covers all tag fields), BatchAlbumEditorSheet
(editField helper), RadioView (name/URL), PlaylistsView (name fields),
MyMusicView (search), SearchView (via @FocusState + toolbar directly).
ShazamKit MTAudioProcessingTap
Primary path: MTAudioProcessingTap installed on AVPlayerItem.audioMix
— works for HLS, radio, and any AVPlayer stream without touching the
microphone. The prepare callback captures the source format and builds
an AVAudioConverter to 16kHz mono. The C-style shazamTapProcess free
function (required by the API) calls
MTAudioProcessingTapGetSourceAudio then dispatches to a serial
analysisQueue — the render thread is never blocked. convertAndMatch
wraps the raw AudioBufferList in an AVAudioPCMBuffer, converts it, and
feeds SHSession.matchStreamingBuffer. Fallback to microphone
(AVAudioEngine) is kept for the local engine path where no
AVPlayerItem exists. NSMicrophoneUsageDescription is only needed if
the mic fallback is ever hit.
Models.swift — CompanionSong, CompanionAlbum, CompanionArtist,
CompanionLibraryResponse. Each has a toSong()/toAlbum() converter.
Song.id = navidrome_id (streaming still works), Song.coverArt =
"companion:{id}" (routes cover art to Companion), Album.id =
"companion:{name}|{artist}" (detected by AlbumDetailView).
CompanionAPIService.swift — fetchAllSongs, fetchAlbumSongs,
fetchAllAlbums, fetchAllArtists, searchLibrary are all nonisolated
where needed. coverArtURL/artistPhotoURL are nonisolated so views can
call them synchronously. Push handler now fires
companionCoverArtUpdated and companionArtistPhotoUpdated events and
clears ImageCache immediately on receipt.
LibraryCache.swift — cacheCompanionAlbums/loadCompanionAlbums,
cacheCompanionAlbumSongs/loadCompanionAlbumSongs for local persistence
of companion data between launches.
SyncEngine.swift — syncCompanion() runs after every Navidrome sync
(bootstrap and delta) when Companion is enabled. It fetches albums
from /library/albums, converts them to Album objects, and overwrites
"all_albums" cache — so MyMusicView’s album grid immediately shows
Companion-sorted data. companionLibraryChanged notification triggers
reactive UI updates.
AsyncCoverArt.swift — Detects "companion:{id}" prefix and routes to
CompanionAPIService().coverArtURL(companionId:) instead of Navidrome.
All existing non-companion cover art paths are unchanged.
AlbumDetailView.swift — Detects albumId.hasPrefix("companion:"),
parses "companion:{name}|{artist}", calls
/library/songs?album=...&album_artist=... on Companion, and builds a
synthetic AlbumWithSongs locally. Caches results so the next tap is
instant. Falls back to the existing Navidrome path for all
non-companion album IDs.
Two fixes:
Snap-back on seek end: Previously isScrubbing = false was set
immediately after seekToPercent(pct). AVPlayer.seek is asynchronous —
currentTime doesn’t update instantly. So displayProgress switched from
scrubPosition back to the old playbackTime / playbackDuration for up
to 250ms until the timer polled again, causing a visible snap-back.
Now scrubPosition is held at pct and isScrubbing clears after a 150ms
delay — enough time for AVPlayer to confirm the seek position before
the bar resumes tracking currentTime.
Stale timer poller removed: playbackTime and playbackDuration were
@State vars updated by a Timer.publish every 0.25s. Since currentTime
and duration are already @Published on AudioPlayer, the timer was just
adding lag and a secondary update cycle. They’re now computed
properties reading directly from audioPlayer.currentTime and
audioPlayer.duration — updates arrive instantly via SwiftUI’s
observation, same as the full Now Playing view.
Features:
- Dual-AVPlayer Smart DJ crossfade with LUFS normalization
- Mitsuha-style FFT visualizer (real-time + offline pre-computed)
- Companion API integration (Smart DJ, tag editing, vis frames)
- Offline-first SyncEngine with delta sync and album detail pre-caching
- Audio pre-fetcher for gapless queue playback
- Optimistic action queue (star/unstar with background retry)
- ShazamKit recognition with MusicKit preview playback
- Radio streaming with HLS/PLS/M3U support and buffer seek
- Watch app with Crown Sequencer and Ultra speaker support
- Batch metadata editing with album_artist fix for split albums
- Cache-first UI pattern across all views
- NWPathMonitor offline detection with reactive song greying
