Primuse End-to-End Workflow Guide & Core Design Principles

Overview

Media Servers (Fastest Sync): If you run Navidrome, Subsonic, Jellyfin, Emby, Plex, Audiobookshelf, Ting Reader, fnMusic, or Synology Audio Station, select the dedicated server connector. Because the server already indexes your tags and playlists, syncing tens of thousands of tracks takes only seconds.
NAS Shared Folders & Cloud Drives: Connect via Synology File Station, QNAP, SMB, WebDAV, SFTP, FTP, NFS, S3, or cloud drives (OneDrive, Google Drive, Dropbox, pCloud, Drime, InfiniCLOUD, Baidu Netdisk, Aliyun Drive, 123Pan, 115). Select your music folders first; if a folder contains audiobooks or spoken-word MP3s, mark that folder as Audiobook during folder selection so it goes straight to your Audiobook shelf instead of cluttering your music artists.
Local Files & Apple Music: Use Reference Folder when importing local files on iPhone/iPad to play them in place without duplicating storage. Enable Apple Music to mix streaming catalog tracks and your own NAS/cloud lossless files in the exact same playback queue.
Dual LAN + WAN Addresses: Fill in both your local IP and external domain on a single music source so Primuse uses full-speed LAN at home and automatically switches to WAN on cellular without splitting your playlists or play counts.

File and cloud sources use two-phase scanning: Phase 1 lists audio files immediately so you can start playing right away; Phase 2 reads embedded tags, artwork, sidecar lyrics, and virtual tracks from .cue sheets, SACD ISOs, DVD-Audio ISOs, and data disc ISOs in the background.
Cloud sources enable Load Cloud Details on Wi-Fi Only by default to protect your cellular data plan and automatically resume tag reading on Wi-Fi.

Enable scraping sources in Settings → Metadata & Scraping (including Apple Music artwork/metadata, Last.fm biographies, AMLL word-by-word lyrics, or custom lyrics APIs).
Automatic and batch scraping only fills missing fields—it never overwrites existing album titles or covers from your server or files. To replace wrong existing metadata on a specific song, open Single-Track Scrape Preview, pick the match, and apply it; Primuse locks your choice as a local override across future refreshes.

Audio Effects Mode: Enables the 10-band Equalizer (with automatic per-headphone/speaker preset switching), Spatial Reverb, ReplayGain loudness normalization (displaying active dB gain in the audio quality badge), Pitch Shift, Playback Speed, Smart/Fixed Crossfade, and Music Medley (playing only the climax segment of each track).
Bit-Perfect Pass-Through Mode: Bypasses all DSP, resampling, EQ, crossfade, and ReplayGain so untouched PCM reaches your DAC (with exclusive mode and automatic hardware sample-rate switching on macOS).

Audio Cache: Automatically stores played tracks and prefetches upcoming queue items within your Audio Cache Limit. In 1.13.0+, you can batch-cache entire folders from Music Source → Folders → Cache Selected Folders with a 3-line live progress banner.
Offline Downloads: Tracks, albums, and playlists downloaded manually or marked Keep Offline are stored separately and never evicted by the cache limit. You can keep original lossless files or transcode to 128 / 192 / 256 / 320 kbps AAC on-device to save storage.
LAN Cache Sync: Transfer already-cached audio directly from your Mac to your iPhone over local Wi-Fi via Storage Management → Cache Sync without re-downloading from cloud drives.

Switch between Online Lyrics and Embedded/Sidecar Lyrics in one tap, enable offline on-device translation, Apple Intelligence, or custom AI translation, and display automatic romanization/furigana for Japanese, Korean, Cantonese, and Mandarin.
Export lyrics cards with audio as an iPhone Live Photo or video clip.
Tap the microphone icon for Karaoke Stage: Primuse runs neural vocal separation locally on your device for instant instrumental accompaniment, pitch shifting, live mic monitoring, and exporting separated vocals or instrumentals as WAV / M4A.

Why doesn't Primuse immediately delete songs when a scan returns fewer files? Sleeping NAS drives, reverse-proxy timeouts, or cloud rate limits can temporarily return an incomplete directory listing. Deleting missing entries immediately would wipe out your playlists, ratings, and play counts. Primuse holds missing tracks for confirmation; to remove intentionally deleted server files right away, open the source menu and use Songs Deleted on Server → Remove Immediately.
Why are EQ, Crossfade, Pitch Shift, and ReplayGain disabled in Bit-Perfect mode and for Apple Music streaming tracks? Bit-perfect output requires every PCM sample to match the source file; EQ, mixing, and gain scaling mathematically alter samples and are intentionally bypassed. Apple Music subscription streams are played through the system DRM pipeline, which does not expose raw PCM to third-party DSP or spectrum visualizers.
Why does background scanning pause even while music is playing? iOS enforces strict background CPU and disk I/O watchdog limits. Scanning tens of thousands of remote headers in the background while playing audio risks iOS terminating the app and cutting off playback. Primuse saves a scan checkpoint when backgrounded and resumes seamlessly when you return to the foreground.