Modulr

Open-source DJ companion for macOS, built with Swift and SwiftUI, that detects BPM and key, tags and renames tracks in DJ format, and manages playlists and favourites. Audio analysis runs through a Python toolkit invoked as a subprocess; playlists, favourites and recents are persisted to a local SQLite database.

Components

• Modulr.app: entry point to the system. SwiftUI interface for browsing folders, playlists and favourites, tagging tracks and playback. Calls the Python toolkit for analysis and SQLite for persistence.
• scripts/analyze.py: detects BPM and key (Essentia, madmom, librosa fallback) and measures loudness (ffmpeg volumedetect).
• TagEditor / TagService: reads and writes tags, renames files to title_KEY_BPM, fetches artwork via the iTunes API.
• PlaylistStore / RecentsStore: SQLite persistence for playlists, favourites and recents.

All app-to-toolkit communication runs through subprocess calls to analyze.py.

Storage

Local SQLite database, no server, no network calls beyond the iTunes artwork lookup:

• playlists + playlist_tracks: ordered track URLs per playlist, soft-deleted via deleted_at
• Recents and favourite folders/tracks persisted the same way

Running the Project

Stack

• Swift + SwiftUI, AVFoundation, Accelerate
• Python (essentia, madmom, librosa, ffmpeg, mutagen)
• macOS 14 (Sonoma) or later, Xcode command line tools, Homebrew

1. Set up dependencies

git clone https://github.com/johnshields/modulr.git
cd modulr
bash scripts/setup.sh

One-time brew + pip dependencies.

2. Build and install

bash scripts/run.sh --install

Builds a release binary, wraps it as Modulr.app, installs to /Applications and launches it.

3. Package a release

bash scripts/package.sh

Builds dist/Modulr-<version>.dmg and prints its sha256 for Casks/modulr.rb. Set DEVELOPER_ID and NOTARY_PROFILE to sign and notarise.

Homebrew

brew install --cask fromlost/modulr/modulr

User guide

See assets/user-guide.md for a walkthrough with screenshots.

Features

• BPM + key detection, Camelot-compatible key highlighting, search by title, key or BPM
• Tag editor with iTunes artwork finder, DJ-format rename title_KEY_BPM
• Loudness measure and match, tempo + pitch bake
• Bulk move, add and re-analyse tracks via sortable track-picker sheets
• Playlists, favourites and recents in a local SQLite database
• Rekordbox-style RGB waveform and spectrogram with cutoff quality verdict
• Open With integration (single-instance window)

License

MIT