Cadence

A native macOS player and library manager for music you keep locally.

Interface · Features · Quick start · Documentation

Cadence imports local audio into a managed library, keeps the source files untouched, and puts playback, lyrics, tags, playlists, and smart collections in one native SwiftUI app. The library lives at ~/Music/Cadence.library.

Important

Cadence is a source-only development build. There is no signed, notarized, App Store, or GitHub binary release yet.

Interface

The screenshots below come from Cadence's production UI rendered against an isolated in-memory SwiftData fixture. Every artist, album, track, and tag is synthetic; the capture process cannot open the developer's music library.

Listen and follow lyrics	Organize without changing files

Features

Managed local library

• Import individual audio files, folders, or Finder drops.
• Review duplicates before Cadence copies anything.
• Preserve original files and store managed media under stable track IDs.
• Link a same-folder .lrc file when its normalized basename matches the audio file.
• Move tracks, albums, or artists to Cadence Trash and restore them later.

Native playback

• Play supported lossless stereo through an AVAudioEngine PCM path.
• Fall back to the system player for formats and routes that need native handling.
• Control playback from the app, media keys, Control Center, queue, and Now Playing.
• Inspect the source format, sample rate, channel count, selected backend, and output route.
• Choose Adaptive, Pure, or Immersive audio routing profiles.

Browse and organize

• Browse all tracks, albums, artists, tags, playlists, and smart collections.
• Learn the interface through a first-run welcome and replayable Help chapters.
• Sort and resize reusable track-table columns.
• Assign hierarchical tags such as genre/ambient or standalone tags such as childhood.
• Build smart collections from nested rules without changing track metadata.
• Search the library and follow contextual links between tracks, albums, artists, and tags.

Lyrics and artwork

• Read line-timed LRC lyrics and seek by selecting a line.
• Edit text and line timestamps in the built-in Lyrics Editor.
• Import, crop, replace, or remove track, album, and artist artwork.

Quick start

Requirements

• macOS 26 or later
• Xcode 27 or later with a compatible macOS SDK
• Homebrew
• Apple silicon Mac for the documented local test destination

Build from source

git clone https://github.com/QenTerra/cadence.git
cd cadence
brew bundle
xcodegen generate --spec project.yml
open Cadence.xcodeproj

Select the Cadence scheme and run it on My Mac.

Run the complete local gate before submitting a change:

bash scripts/verify.sh

GitHub Actions regenerates the project and runs SwiftFormat and SwiftLint. The hosted macOS runner currently provides Xcode 26.6, so the complete build and test gate must be run locally with Xcode 27 until GitHub adds a compatible toolchain.

project.yml is the source of truth for Xcode configuration. Regenerate the committed Cadence.xcodeproj after changing targets, files, entitlements, or build settings.

Permissions and privacy

Cadence does not contain analytics, ads, tracking, or a network client. It opens external project links only when you select one in Settings. Your music, artwork, lyrics, tags, playlists, and playback history stay on your Mac.

• Privacy
• Terms of Use
• Security
• Third-party notices

You are responsible for using audio, artwork, metadata, and lyrics you have the right to copy and play.

Development

Project structure

Sources/Cadence/
  App/             Application state and feature coordination
  Components/      Shared SwiftUI components
  DesignSystem/    Theme, surfaces, typography, and motion
  Features/        Library, playback, tags, playlists, import, and settings
  Foundation/      App configuration and shared infrastructure
  Import/          Scan, review, copy, manifest, and recovery pipeline
  ManagedLibrary/  Cadence.library paths and package operations
  Models/          Domain and presentation values
  Persistence/     SwiftData schema, repository, and paged store
  Playback/        Coordinator, audio backends, routing, and media controls
Tests/CadenceTests/ Unit and integration tests

Read the architecture, build guide, dependency policy, or the GitHub Wiki for more detail.

Current limitations

• Cadence is available as source only; there is no signed or notarized binary.
• The complete Xcode 27 build and test gate remains local while the hosted GitHub runner provides an older toolchain.
• Output-device behavior, long playback, VoiceOver, spatial audio, and large real libraries remain hardware or manual release gates.

Documentation

• Complete product and engineering Wiki
• Documentation index
• Building from source
• Architecture
• Dependencies
• Troubleshooting
• UI system
• Contributing
• Changelog
• Privacy Policy
• Terms of Use
• Security Policy
• Third-party notices
• MIT License

Support

Cadence is created and maintained by Nikita Melnychenko (QenTerra). If it saves you time, you can buy me a coffee.

Bug reports and focused pull requests are welcome. Read CONTRIBUTING.md before opening one. Report security issues through the private route in SECURITY.md.

License

Cadence source code is available under the MIT License.