Provider Integrations
Relevant source files
The following files were used as context for generating this wiki page:
Provider Integrations manage connections between the local DJ Assistant environment and external music services. The system supports metadata enrichment, track discovery via buy-links, and set export capabilities. These integrations operate on a local-first basis, ensuring that external network calls only occur when you explicitly opt-in for specific tasks.
Sources: README.md:157-160, CHANGELOG.md:21-25
Provider Classification
The system categorizes integrations into three distinct functional types: Streaming Providers, Store Providers, and Enrichment Providers.
Streaming Providers
Streaming providers primarily support playlist matching and export. The architecture prioritizes metadata-only interactions to maintain a non-destructive workflow.
- Targets: Spotify, Deezer, Apple Music, YouTube Music, SoundCloud, Tidal.
- Capabilities: ISRC search and playlist writing (reference playlists only; no audio download).
Sources: packages/shared/src/index.ts:285-288, README.md:162-167
Store Providers
Store providers facilitate track acquisition through deterministic buy-links. The system generates these links based on track metadata without requiring direct API access for audio streaming.
- Targets: Beatport, Traxsource, Juno Download, Bandcamp, Discogs.
- Functionality: Construction of search URLs based on artist and title tags.
Sources: packages/shared/src/index.ts:290-291, apps/desktop/src/services/api.ts:89-92
Enrichment Providers
Enrichment providers supply missing metadata fields and high-resolution artwork.
- Targets: MusicBrainz, iTunes, Last.fm, Discogs, AcoustID.
- Data Types: Missing BPM, keys, ISRC, and cover art.
Sources: packages/shared/src/index.ts:312-313, CHANGELOG.md:33-36
Architecture and Data Flow
The provider system uses a registry-based architecture within the Rust core. The frontend communicates with this registry via typed IPC commands.
This diagram illustrates the lifecycle of a metadata enrichment request, emphasizing the local snapshotting for undo support.
Sources: README.md:204-208, apps/desktop/src-tauri/Cargo.toml:25-30
Provider Capabilities
Each provider registration includes a capability set that defines supported operations.
| Capability | Description |
|---|---|
liveMatch | Real-time matching against a provider catalog. |
isrcSearch | Exact matching using International Standard Recording Codes. |
playlistWrite | Ability to create or update remote playlists. |
needsAppId | Requires a registered application ID/secret for authentication. |
Sources: packages/shared/src/index.ts:303-309
Metadata Enrichment Workflow
Enrichment follows a non-destructive "Preview → Apply → Undo" pattern. This ensures that you retain control over all library modifications.
- Preview: The system looks up gap tracks (tracks missing specific tags) on a selected source like MusicBrainz. It generates a
TrackProposalcontaining the current value and the proposed change. - Apply: You select specific proposals to write to the local database. This process fills empty slots (e.g., missing artwork) and updates canonical fields.
- Snapshot: Before applying changes, the system creates a
run_snapshotin theenrichment_runstable, storing thebefore_state. - Undo: You can restore the previous state at any time using the
enrichment_undocommand.
Sources: CHANGELOG.md:37-43, apps/desktop/src/services/api.ts:121-149, packages/shared/src/index.ts:333-345
Technical Implementation Details
IPC Interface
The desktop application interacts with providers through several key IPC commands defined in the API service.
// apps/desktop/src/services/api.ts
export async function providerStatus(): Promise<ProviderStatusResponse> {
// Returns connected accounts and capabilities
}
export async function providerMatchTracks(
req: ProviderMatchTracksRequest
): Promise<ProviderMatchTracksResponse> {
// Performs catalog matching (e.g., Deezer ISRC lookup)
}
Sources: apps/desktop/src/services/api.ts:101-118, apps/desktop/src/services/api.ts:167-175
Security and Rate Limiting
- Authentication: OAuth 2.0 + PKCE is used for streaming services (e.g., Spotify). Tokens are stored in the OS keychain.
- Rate Limiting: The Rust core manages rate limits for external APIs (e.g., MusicBrainz allows ~1 request per second) using
tokio::time. - Transport: The
reqwestcrate handles HTTPS requests using the native OS TLS stack.
Sources: CHANGELOG.md:46-48, apps/desktop/src-tauri/Cargo.toml:31-32
Catalog Matching Logic
Matching utilizes both exact and fuzzy strategies:
- ISRC-Exact: Joins against the library using the unique recording identifier.
- Fuzzy Matching: Uses artist and title variants with confidence scoring (High, Review, Low).
- Taste Scoring: Chart snapshots (e.g., Beatport Top 100) are filtered locally using a "taste score" based on 60% tempo and 40% key compatibility with a seed track.
Sources: CHANGELOG.md:22-24, packages/shared/src/index.ts:354-366, apps/desktop/src/App.tsx:288-292
Summary
Provider Integrations enable DJ Assistant to extend its local-first intelligence with global music data. By categorizing services into Streaming, Store, and Enrichment providers, the system maintains a clean separation between discovery, acquisition, and management. The "Preview → Apply → Undo" workflow ensures that even when integrating with external cloud services, the user maintains final authority over their library metadata.
Sources: README.md:15-18, CHANGELOG.md:21-25