Documentation

Everything you need to get OpenDJ running and making the most of your library.

Installation

macOS (recommended)

Requires Apple Silicon (an M-series Mac, 2020 or later) — there's no Intel build. Stem separation depends on ONNX Runtime, which doesn't ship a prebuilt binary for Intel Macs, so an Intel-compatible build isn't currently possible without dropping that feature entirely. Running the .dmg on an Intel Mac will fail to launch; there's no workaround short of Apple Silicon hardware.

OpenDJ isn't Apple-notarized yet (that requires a paid Developer account), so a plain browser download of the .dmg gets flagged by Gatekeeper as “damaged” on first launch — misleading, since nothing is actually corrupt. The install script sidesteps this entirely by fetching and installing the app directly, outside the browser download path that triggers the flag in the first place:

No dialog, no extra steps. yt-dlp and ffmpeg ship inside the app either way — nothing else to install.

From source

If you want to build from source, you'll need Rust, Node.js, and pnpm — plus yt-dlp and ffmpeg on your own PATH, since the bundling step only runs in release CI, not a local cargo tauri dev:

Quick Start

1. Open OpenDJ
2. Choose a download folder in Settings (or use the default)
3. Paste a link into the Queue tab — any URL from YouTube, SoundCloud, etc.
4. Tracks download automatically, convert to 320kbps MP3, and organize into your folder structure

System Requirements

Downloading Tracks

OpenDJ accepts input in three ways:

• Paste — Paste a URL directly into the Queue tab (Cmd+V)
• Drop — Drag and drop a URL or local audio file anywhere in the window
• Batch — Paste multiple URLs, one per line. Playlists are automatically expanded.

Each track goes through the pipeline:

1. Resolve — Metadata is fetched from the source (title, artist, artwork, BPM, key)
2. Download — Audio is downloaded at the highest available quality
3. Convert — ffmpeg converts to MP3 320kbps if needed
4. Tag — ID3 tags are written (title, artist, album, artwork, genre, etc.)
5. Organize — File is moved to the destination folder based on your template

Supported Sources

OpenDJ uses yt-dlp under the hood, which supports 1800+ sites. The most common for DJs:

SoundCloud Likes

The SoundCloud tab lets you fetch and download any SoundCloud user's liked tracks:

1. Enter a SoundCloud username (or paste their profile URL)
2. Click Fetch Likes — OpenDJ fetches their entire likes library via the SoundCloud API
3. Browse the results, search by title or artist
4. Click MP3 on individual tracks, or Download All MP3 for the whole list

No API key is required. OpenDJ auto-detects SoundCloud's client ID from their website — the same approach used by browser extensions and scripts.

Auto-Organization

OpenDJ organizes downloaded tracks using a configurable folder template. The default is:

Available template variables:

Batch Tagging

Select multiple tracks in the Queue and edit their tags simultaneously. Useful for:

• Fixing artist capitalization across a set
• Adding a genre to a batch of tracks
• Normalizing title formatting

Repair & Restore

Every file mutation OpenDJ makes is journaled with a checksum. The Repair tab shows:

• All modifications made to your library
• Original file backups (stored alongside or in a backup directory)
• One-click restore to revert any change

Colored Waveform & Hot Cues

Click a track's title (or the expand icon) in Library to open its enlarged waveform. Three color modes are available, switchable from the same view:

• RGB — low, mid, and high frequencies blended into one continuous color
• 3-Band — low/mid/high rendered as distinct solid bands
• Classic Blue — a single-color amplitude waveform, no frequency coloring

Click anywhere on the waveform to set the cue cursor — the track does not need to be playing. Press 1–8 to drop or jump to a hot cue at that position.

Stem Separation

From the same enlarged waveform view, Download Stems runs real source separation — not an EQ filter — splitting a track into isolated vocals, drums, bass, and other. Check the boxes for whichever stems you want to keep.

Separation runs fully on-device (CPU) via an ONNX/htdemucs model. The first split on a machine downloads the model (roughly 200MB, one time); every split after that starts immediately. A full track typically takes anywhere from several seconds to a couple of minutes depending on your machine.

Cloud Sync

Turn on Settings → Sync to sync BPM, key, hot cues, and preferences across your devices. There's no account: the first time you enable it, OpenDJ generates a random recovery key on your device and registers it anonymously.

• To use the same identity on another device, copy your recovery key from Settings and paste it into "Use on this device" there
• The recovery key is a secret, not a password — anyone with it can use your identity, and there's no way to recover it if lost
• Sync is off by default and never required to use OpenDJ

Community

The Community tab is a lightweight, anonymous feed layered on the same recovery-key identity as Sync. Setting a username (from the Community tab or the sidebar) is required to post, upvote, or comment — not to read.

• Share a Crate — posts your crate's track list (title/artist/key/BPM, plus a source link wherever OpenDJ can resolve one from your download history) as a metadata snapshot, never the audio itself
• Share a Song — paste any link with a title and optional artist
• Post — plain text, no track attached
• Upvote, reply in flat (non-threaded) comments, and @mention other usernames — typing @ suggests real usernames as you type
• A + button on song/crate shares downloads the song, or creates a local crate matched against tracks you already have

Settings Reference

Concurrency

OpenDJ downloads tracks in parallel. The default concurrency is 6, which means 6 tracks download at the same time.

• 1–2 — Conservative, good for slow connections
• 4–6 — Balanced, works well on most connections
• 8–16 — Aggressive, use on fast connections with high bandwidth

You can adjust this in Settings → Concurrency → Simultaneous network jobs.

Folder Templates

Templates use {variable} syntax. Slashes create subdirectories. Unknown variables are skipped.

Examples:

CLI Usage

OpenDJ is a GUI application, but you can use yt-dlp directly from the command line for scripting:

Troubleshooting

"yt-dlp not found" or "ffmpeg not found"

Both ship inside official OpenDJ downloads, so this shouldn't happen — if it does, your install is likely corrupted; redownload from the download page. Running from source instead? Install both yourself: brew install yt-dlp ffmpeg, and confirm they're on your PATH.

Downloads are slow

Check your network concurrency setting. Default is 6 simultaneous downloads. Increase to 8–16 on fast connections.

Spotify/Apple Music tracks not downloading

These services use DRM protection. OpenDJ searches YouTube for a matching track instead. The match quality varies.

SoundCloud client_id not detected

SoundCloud periodically rotates their JavaScript assets. If detection fails, restart OpenDJ to re-fetch the latest scripts.

macOS says OpenDJ "is damaged and can't be opened"

This is Gatekeeper, not an actually corrupt download — OpenDJ isn't Apple-notarized yet, so a fresh browser download gets quarantined and macOS shows this (misleading) message instead of the usual "unidentified developer" prompt. Two ways to fix it:

Avoid it next time: use the install script instead of the browser download — it clears the quarantine flag as part of installing, so the dialog never shows.

Already hit it? Fix it once per download from Terminal, after dragging OpenDJ.app to Applications:

Then launch it normally from Applications or Spotlight.

Downloads fail with "Failed to load Python shared library" / "different Team IDs"

Fixed in v0.3.12. Earlier builds enabled macOS Hardened Runtime on the whole app bundle, which blocked the bundled yt-dlp binary from loading its own embedded Python runtime (a code-signing Team ID mismatch between yt-dlp and its bundled framework). Update to the latest version to fix it — no other workaround needed.