Library and Import

Library and Import

Cadence uses one SwiftData-backed production catalog and one managed package. Feature views do not keep a second whole-library cache.

Supported import paths

• select individual audio files;
• select a folder;
• drag files or folders from Finder into the app.

Every entry point uses the same flow:

Scan -> Review -> Import -> Complete

Scan and Review are read-only. Cadence changes the managed package only after explicit confirmation.

Managed package layout

Cadence.library/
  Media/
  Lyrics/
  Artwork/
  Metadata/
  Staging/
  Trash/

Managed audio names use stable track identifiers instead of user-facing metadata. Titles, artists, albums, years, formats, and artwork live in the catalog and remain editable independently of the stored filename.

Transaction safety

A confirmed import uses bounded staging, SHA-256 verification, a same-volume move, one SwiftData commit, and a versioned manifest. Launch recovery can finish or roll back interrupted work. Managed paths must remain inside Cadence.library; a path that escapes the package fails closed.

Duplicates

• Exact content-hash duplicates are excluded automatically.
• Metadata-only possible duplicates remain in Review for an explicit decision.
• Ambiguous sidecar matches are not guessed.

LRC sidecars

Cadence automatically proposes an LRC link when an audio file and .lrc file share the same normalized basename in the same source folder. A linked sidecar is copied into the managed package during the same transaction as its track.

Artwork and metadata

Import inspection reads embedded title, artist, album, year, format, duration, and artwork when available. Artwork resolution follows this order:

1. custom track artwork;
2. album artwork;
3. the system placeholder.

Artists, albums, and tracks can also receive user-selected artwork without modifying the original audio file.

Trash and restore

Deleting a track, album, or artist moves its managed data into Cadence Trash. Each operation keeps a versioned manifest with catalog relationships, tags, audio, lyrics, and artwork. Restore returns those artifacts atomically. Empty Trash permanently removes only managed copies, never the original source files.