metadata-agregator/docs/research/minim/analysis/INTEGRATIONS.md

# minim: Service Integrations

## Overview

minim integrates with five music services, each with different authentication methods, API coverage, and capabilities:

| Service | Auth Method | API Type | Streaming | Lyrics | Credits | Rate Limit |
|---------|-------------|----------|-----------|--------|---------|------------|
| Discogs | OAuth 1.0a, Personal Token | Public | No | No | Yes | 60/min (auth), 25/min (unauth) |
| iTunes | None | Public | No | No | No | ~20/min |
| Qobuz | Password Grant | Private | Yes | No | No | Unknown |
| Spotify | OAuth 2.0 (4 flows) | Public + Private | No | Yes | No | 180/30sec |
| TIDAL | OAuth 2.0 (PKCE, Client Creds) | Public + Private | Yes | Yes | Yes | Unknown |

## Discogs Integration

### Service Overview

**Purpose:** Music database, marketplace, collection management  
**Website:** https://www.discogs.com  
**API Documentation:** https://www.discogs.com/developers  
**API Type:** Public, documented, RESTful

### Authentication

**Method 1: OAuth 1.0a**

**Setup:**
1. Create app at https://www.discogs.com/settings/developers
2. Obtain consumer key and consumer secret
3. Implement OAuth 1.0a flow (request token → user authorization → access token)

**Implementation:**
```python
from minim import discogs

api = discogs.API(
    consumer_key="Abcd1234Efgh5678",
    consumer_secret="IjklMnopQrstUvwx"
)

# OAuth flow (opens browser)
api.set_access_token()

# Tokens saved to ~/minim.cfg
```

**Method 2: Personal Access Token**

**Setup:**
1. Generate token at https://www.discogs.com/settings/developers
2. Use token directly (no OAuth flow)

**Implementation:**
```python
api = discogs.API(personal_access_token="YourPersonalToken")
```

**Comparison:**
- OAuth 1.0a: Required for write operations (collection, wantlist), higher rate limit
- Personal Token: Read-only, simpler setup, same rate limit as OAuth

### API Coverage

**Database:**
- Search releases, artists, labels, masters
- Get detailed information (tracklist, credits, images, identifiers)
- Browse by genre, style, format, year, country

**Marketplace:**
- Search listings
- Get listing details (price, condition, seller)
- Not implemented in minim (read-only marketplace access)

**Collection:**
- Get user's collection folders
- List items in folder
- Add/remove releases
- Update notes and rating

**Wantlist:**
- Get user's wantlist
- Add/remove releases
- Not implemented: Update notes

**User:**
- Get user profile
- Get user submissions (releases, artists, labels)
- Not implemented in minim

### Data Model

**Release Object:**
```json
{
  "id": 249504,
  "title": "OK Computer",
  "artists": [{"name": "Radiohead", "id": 3840}],
  "labels": [{"name": "Parlophone", "catno": "7243 8 55229 2 5"}],
  "formats": [{"name": "CD", "qty": "1", "descriptions": ["Album"]}],
  "year": 1997,
  "country": "UK",
  "genres": ["Electronic", "Rock"],
  "styles": ["Alternative Rock", "Experimental"],
  "tracklist": [
    {"position": "1", "title": "Airbag", "duration": "4:44"},
    {"position": "2", "title": "Paranoid Android", "duration": "6:23"}
  ],
  "identifiers": [
    {"type": "Barcode", "value": "724385522925"}
  ],
  "images": [
    {"type": "primary", "uri": "https://...", "width": 600, "height": 600}
  ]
}
```

**Artist Object:**
```json
{
  "id": 3840,
  "name": "Radiohead",
  "profile": "English rock band formed in 1985...",
  "members": [
    {"name": "Thom Yorke", "id": 239},
    {"name": "Jonny Greenwood", "id": 240}
  ],
  "urls": ["https://www.radiohead.com"],
  "images": [...]
}
```

### Rate Limiting

**Authenticated:** 60 requests per minute  
**Unauthenticated:** 25 requests per minute

**Headers:**
- `X-Discogs-Ratelimit`: Total requests allowed per minute
- `X-Discogs-Ratelimit-Remaining`: Requests remaining in current window
- `X-Discogs-Ratelimit-Used`: Requests used in current window

**Enforcement:** HTTP 429 (Too Many Requests) when limit exceeded.

**minim Implementation:** Does not check rate limit headers. Caller responsible for tracking.

### Use Cases

1. **Metadata Enrichment:** Get detailed release information (catalog numbers, barcodes, formats)
2. **Collection Management:** Sync local library with Discogs collection
3. **Credits Extraction:** Get producer, engineer, musician credits from tracklist
4. **Format Identification:** Determine pressing details (country, year, label, catalog number)

### Limitations

- No streaming or preview URLs
- No lyrics
- Marketplace write operations not implemented
- User-submitted data (quality varies)
- Rate limiting requires manual tracking

## iTunes Integration

### Service Overview

**Purpose:** Public music catalog search and lookup  
**Website:** https://www.apple.com/itunes  
**API Documentation:** https://developer.apple.com/library/archive/documentation/AudioVideo/Conceptual/iTuneSearchAPI  
**API Type:** Public, documented, RESTful

### Authentication

**None required.** iTunes Search API is completely public.

**Implementation:**
```python
from minim import itunes

api = itunes.SearchAPI()
results = api.search("Radiohead", media="music", entity="musicArtist")
```

### API Coverage

**Search:**
- Search by term across all media types
- Filter by media (music, movie, podcast, audiobook, etc.)
- Filter by entity (song, album, artist, etc.)
- Filter by attribute (artist name, album name, song name, etc.)

**Lookup:**
- Lookup by iTunes ID
- Lookup by UPC (album barcode)
- Lookup by ISBN (books)
- Lookup by AMG (All Music Guide) ID

**Not Available:**
- Streaming URLs
- Lyrics
- User library access
- Playlist management

### Data Model

**Track Object:**
```json
{
  "trackId": 1109731797,
  "trackName": "Creep",
  "artistName": "Radiohead",
  "collectionName": "Pablo Honey",
  "collectionId": 1109731533,
  "artistId": 657515,
  "trackNumber": 2,
  "trackCount": 12,
  "discNumber": 1,
  "discCount": 1,
  "releaseDate": "1993-02-22T08:00:00Z",
  "primaryGenreName": "Alternative",
  "trackTimeMillis": 238640,
  "country": "USA",
  "isrc": "GBAYE9200070",
  "artworkUrl30": "https://.../30x30bb.jpg",
  "artworkUrl60": "https://.../60x60bb.jpg",
  "artworkUrl100": "https://.../100x100bb.jpg",
  "previewUrl": "https://.../preview.m4a",
  "trackViewUrl": "https://music.apple.com/us/album/creep/1109731533?i=1109731797"
}
```

**Album Object:**
```json
{
  "collectionId": 1109731533,
  "collectionName": "Pablo Honey",
  "artistName": "Radiohead",
  "artistId": 657515,
  "trackCount": 12,
  "releaseDate": "1993-02-22T08:00:00Z",
  "primaryGenreName": "Alternative",
  "copyright": "℗ 1993 XL Recordings Ltd.",
  "country": "USA",
  "artworkUrl100": "https://.../100x100bb.jpg",
  "collectionViewUrl": "https://music.apple.com/us/album/pablo-honey/1109731533"
}
```

### Rate Limiting

**Limit:** Approximately 20 requests per minute (undocumented)  
**Enforcement:** HTTP 403 (Forbidden) when limit exceeded  
**Headers:** No rate limit headers provided

**Recommendation:** Implement exponential backoff on 403 errors.

### Use Cases

1. **Quick Metadata Lookup:** Get basic track/album info without authentication
2. **UPC Lookup:** Find albums by barcode
3. **Preview URLs:** Get 30-second preview clips (M4A format)
4. **Artwork:** Get album artwork in multiple sizes (30x30, 60x60, 100x100)

### Limitations

- No high-resolution artwork (max 100x100 pixels, can be scaled to 600x600 by changing URL)
- No streaming URLs (only 30-second previews)
- No lyrics
- No user-specific data
- Rate limit is undocumented and may change
- Search results limited to 200 items

## Qobuz Integration

### Service Overview

**Purpose:** High-resolution music streaming and downloads  
**Website:** https://www.qobuz.com  
**API Documentation:** None (private API)  
**API Type:** Private, undocumented, reverse-engineered

### Authentication

**Method:** Password Grant OAuth 2.0

**Setup:**
1. Qobuz account with active subscription
2. App ID and secret auto-extracted from web player JavaScript
3. Email and password for authentication

**Implementation:**
```python
from minim import qobuz

api = qobuz.PrivateAPI(
    email="user@example.com",
    password="YourPassword"
)

# Automatic app_id/secret extraction and token acquisition
api.set_access_token()
```

**App ID/Secret Extraction:**
```python
def _get_app_credentials(self):
    # Fetch Qobuz web player
    response = requests.get("https://play.qobuz.com")
    html = response.text
    
    # Extract bundle URL from HTML
    bundle_url_match = re.search(r'<script src="(/resources/\d+\.\d+\.\d+-[a-z]\d+/bundle\.js)"', html)
    bundle_url = "https://play.qobuz.com" + bundle_url_match.group(1)
    
    # Fetch bundle JavaScript
    bundle_js = requests.get(bundle_url).text
    
    # Extract app_id and secrets array
    app_id = re.search(r'production:{api:{appId:"(\d+)"', bundle_js).group(1)
    secrets = re.findall(r'[a-f0-9]{32}', bundle_js)
    
    # Test secrets to find valid one
    for secret in secrets:
        if self._test_secret(app_id, secret):
            return app_id, secret
```

**Security Note:** This method violates Qobuz terms of service. Use at your own risk.

### API Coverage

**Catalog:**
- Search tracks, albums, artists, playlists
- Get detailed information
- Browse by genre, new releases, charts

**Streaming:**
- Get streaming URLs with quality selection
- Quality levels: MP3 320kbps, FLAC 16/44.1, FLAC 24/96, FLAC Hi-Res (up to 24/192)
- Download tracks (within subscription terms)

**User Library:**
- Get user playlists
- Create, update, delete playlists
- Add/remove tracks from playlists
- Get favorites (tracks, albums, artists)
- Add/remove favorites

**Not Available:**
- Lyrics
- Credits (producer, engineer, etc.)
- User playback history

### Data Model

**Track Object:**
```json
{
  "id": 12345678,
  "title": "Creep",
  "duration": 238,
  "track_number": 2,
  "media_number": 1,
  "isrc": "GBAYE9200070",
  "performer": {"name": "Radiohead", "id": 12345},
  "album": {
    "id": "0060254734729",
    "title": "Pablo Honey",
    "release_date_original": "1993-02-22",
    "upc": "0060254734729",
    "image": {
      "small": "https://.../230x230.jpg",
      "large": "https://.../600x600.jpg"
    },
    "label": {"name": "XL Recordings"}
  },
  "maximum_bit_depth": 16,
  "maximum_sampling_rate": 44.1
}
```

**Streaming URL Response:**
```json
{
  "url": "https://streaming.qobuz.com/...",
  "format_id": 27,
  "mime_type": "audio/flac",
  "sampling_rate": 44.1,
  "bit_depth": 16,
  "restrictions": []
}
```

### Quality Levels

| Format ID | Quality | Codec | Bitrate/Depth | Subscription Tier |
|-----------|---------|-------|---------------|-------------------|
| 5 | MP3 | MP3 | 320 kbps | Studio |
| 6 | CD | FLAC | 16-bit/44.1kHz | Studio |
| 7 | Hi-Res | FLAC | 24-bit/96kHz | Studio Sublime |
| 27 | Hi-Res | FLAC | Up to 24-bit/192kHz | Studio Sublime |

**Availability:** Quality depends on:
1. User's subscription tier
2. Album's available formats
3. Geographic restrictions

### Rate Limiting

**Unknown.** Private API does not document rate limits.

**Observation:** Aggressive usage (>100 requests/minute) may trigger temporary blocks.

**Recommendation:** Implement conservative rate limiting (10-20 requests/minute).

### Use Cases

1. **High-Resolution Downloads:** Get FLAC files up to 24-bit/192kHz
2. **Metadata Enrichment:** Get detailed album info (label, UPC, release date)
3. **Playlist Management:** Sync playlists between services
4. **Favorites Sync:** Export/import favorite tracks

### Limitations

- Private API (may break without notice)
- Requires active subscription
- No lyrics or credits
- Geographic restrictions on content
- Terms of service violations (use at own risk)

## Spotify Integration

### Service Overview

**Purpose:** Music streaming, discovery, and social features  
**Website:** https://www.spotify.com  
**API Documentation:** https://developer.spotify.com/documentation/web-api  
**API Type:** Public (Web API) + Private (Lyrics)

### Authentication

**Method:** OAuth 2.0 with four flow types

**Flow 1: Authorization Code**
- Full user access with refresh token
- Requires user login via browser
- Best for web applications

**Flow 2: PKCE (Proof Key for Code Exchange)**
- For mobile and desktop apps
- No client secret required
- Enhanced security for public clients

**Flow 3: Client Credentials**
- App-only access (no user context)
- No user login required
- Limited to catalog endpoints (no user library, playlists, playback)

**Flow 4: Web Player (Undocumented)**
- Extract `sp_dc` cookie from browser
- Access private endpoints (lyrics)
- Violates terms of service

**Implementation:**
```python
from minim import spotify

# Authorization Code flow
api = spotify.WebAPI(
    client_id="your_client_id",
    client_secret="your_client_secret",
    redirect_uri="http://localhost:8888"
)
api.set_flow("authorization_code", scopes=[
    "user-library-read",
    "playlist-read-private",
    "user-read-playback-state"
])
api.set_access_token()  # Opens browser

# Client Credentials flow (no user login)
api = spotify.WebAPI(client_id="...", client_secret="...")
api.set_flow("client_credentials")
api.set_access_token()
```

### API Coverage

**Catalog:**
- Search tracks, albums, artists, playlists, shows, episodes
- Get detailed information
- Get related artists
- Get artist top tracks
- Get album tracks
- Get audio features (danceability, energy, tempo, etc.)
- Get audio analysis (detailed beat/bar/section analysis)

**User Library:**
- Get saved tracks, albums, shows, episodes
- Save/remove items
- Check if items are saved

**Playlists:**
- Get user playlists
- Get playlist details and tracks
- Create, update, delete playlists
- Add/remove tracks
- Reorder tracks
- Upload custom cover image

**Playback:**
- Get current playback state
- Get available devices
- Start/pause/skip playback
- Seek to position
- Set volume
- Toggle shuffle/repeat
- Transfer playback between devices

**Personalization:**
- Get top artists and tracks
- Get recently played tracks
- Get recommendations based on seeds

**Follow:**
- Follow/unfollow artists, users, playlists
- Check if following
- Get followed artists

**Browse:**
- Get featured playlists
- Get new releases
- Get categories
- Get category playlists

**Lyrics (Private API):**
- Get synchronized lyrics via Musixmatch integration
- Requires `sp_dc` cookie

### Data Model

**Track Object:**
```json
{
  "id": "3n3Ppam7vgaVa1iaRUc9Lp",
  "name": "Creep",
  "artists": [
    {"name": "Radiohead", "id": "4Z8W4fKeB5YxbusRsdQVPb"}
  ],
  "album": {
    "name": "Pablo Honey",
    "id": "6AZv3m27uyRxi8KyJSfUxL",
    "release_date": "1993-02-22",
    "images": [
      {"url": "https://.../640x640.jpg", "width": 640, "height": 640}
    ]
  },
  "duration_ms": 238640,
  "track_number": 2,
  "disc_number": 1,
  "explicit": false,
  "external_ids": {"isrc": "GBAYE9200070"},
  "popularity": 82,
  "preview_url": "https://.../preview.mp3"
}
```

**Audio Features Object:**
```json
{
  "id": "3n3Ppam7vgaVa1iaRUc9Lp",
  "danceability": 0.456,
  "energy": 0.789,
  "key": 7,
  "loudness": -6.234,
  "mode": 1,
  "speechiness": 0.034,
  "acousticness": 0.123,
  "instrumentalness": 0.000012,
  "liveness": 0.089,
  "valence": 0.234,
  "tempo": 92.456,
  "duration_ms": 238640,
  "time_signature": 4
}
```

**Lyrics Object (Private API):**
```json
{
  "lyrics": {
    "syncType": "LINE_SYNCED",
    "lines": [
      {"startTimeMs": "0", "words": "When you were here before", "syllables": []},
      {"startTimeMs": "5230", "words": "Couldn't look you in the eye", "syllables": []}
    ],
    "language": "en"
  }
}
```

### Scopes

Spotify uses OAuth scopes to control API access. Common scopes:

**Library:**
- `user-library-read`: Read saved tracks/albums
- `user-library-modify`: Save/remove tracks/albums

**Playlists:**
- `playlist-read-private`: Read private playlists
- `playlist-read-collaborative`: Read collaborative playlists
- `playlist-modify-public`: Modify public playlists
- `playlist-modify-private`: Modify private playlists

**Playback:**
- `user-read-playback-state`: Read playback state
- `user-modify-playback-state`: Control playback
- `user-read-currently-playing`: Read currently playing track

**Personalization:**
- `user-top-read`: Read top artists and tracks
- `user-read-recently-played`: Read recently played tracks

**Follow:**
- `user-follow-read`: Read followed artists/users
- `user-follow-modify`: Follow/unfollow artists/users

**User:**
- `user-read-private`: Read user profile (country, product)
- `user-read-email`: Read user email

### Rate Limiting

**Limit:** Varies by endpoint, typically 180 requests per 30 seconds  
**Enforcement:** HTTP 429 (Too Many Requests)  
**Headers:**
- `Retry-After`: Seconds to wait before retrying

**Recommendation:** Implement exponential backoff and respect `Retry-After` header.

### Use Cases

1. **Comprehensive Metadata:** Get detailed track info, audio features, related artists
2. **Playlist Management:** Create, sync, and manage playlists
3. **Playback Control:** Build custom music players
4. **Music Discovery:** Get recommendations, browse new releases
5. **Lyrics Integration:** Display synchronized lyrics (via private API)

### Limitations

- No streaming URLs (only 30-second previews)
- No download capability
- Lyrics require private API (terms of service violation)
- Rate limiting varies by endpoint
- Some features require premium subscription

## TIDAL Integration

### Service Overview

**Purpose:** High-fidelity music streaming with MQA support  
**Website:** https://www.tidal.com  
**API Documentation:** Limited (mostly undocumented)  
**API Type:** Public (limited) + Private (extensive)

### Authentication

**Method:** OAuth 2.0 (PKCE or Client Credentials)

**Public API:**
- Client credentials flow
- Limited endpoints (catalog search, basic info)

**Private API:**
- PKCE flow with user login
- Full access (streaming URLs, lyrics, credits)

**Implementation:**
```python
from minim import tidal

# Private API (full access)
api = tidal.PrivateAPI(
    client_id="your_client_id",
    client_secret="your_client_secret"
)
api.set_flow("pkce")
api.set_access_token()  # Opens browser for login
```

**Client ID/Secret:**
- Extracted from TIDAL desktop/mobile apps
- Not officially provided by TIDAL
- Use at own risk (terms of service violation)

### API Coverage

**Catalog:**
- Search tracks, albums, artists, playlists, videos
- Get detailed information
- Get artist top tracks and albums
- Get similar artists
- Get album review and credits

**Streaming:**
- Get streaming URLs with quality selection
- Quality levels: LOW (96kbps AAC), HIGH (320kbps AAC), LOSSLESS (FLAC 16/44.1), HI_RES (FLAC 24/96+), HI_RES_LOSSLESS (MQA)
- Manifest decryption for protected streams

**Lyrics:**
- Get synchronized lyrics (LRC format)
- Get plain text lyrics

**Credits:**
- Get detailed credits (producers, engineers, musicians, composers, etc.)
- Role-based organization

**User Library:**
- Get user playlists
- Create, update, delete playlists
- Add/remove tracks
- Get favorites (tracks, albums, artists, videos)
- Add/remove favorites

**Not Available:**
- Playback control (no remote control API)
- Audio features/analysis
- Recommendations (limited)

### Data Model

**Track Object:**
```json
{
  "id": 12345678,
  "title": "Creep",
  "duration": 238,
  "trackNumber": 2,
  "volumeNumber": 1,
  "isrc": "GBAYE9200070",
  "explicit": false,
  "audioQuality": "HI_RES",
  "artists": [
    {"name": "Radiohead", "id": 4050}
  ],
  "album": {
    "id": 1234567,
    "title": "Pablo Honey",
    "releaseDate": "1993-02-22",
    "cover": "01234567-89ab-cdef-0123-456789abcdef",
    "upc": "0060254734729",
    "numberOfTracks": 12,
    "audioQuality": "HI_RES"
  },
  "streamStartDate": "1993-02-22T00:00:00.000Z"
}
```

**Streaming Manifest:**
```json
{
  "mimeType": "audio/flac",
  "codecs": "flac",
  "encryptionType": "NONE",
  "urls": ["https://streaming.tidal.com/..."],
  "soundQuality": "HI_RES",
  "bitDepth": 24,
  "sampleRate": 96000
}
```

**Lyrics Object:**
```json
{
  "trackId": 12345678,
  "lyricsProvider": "Musixmatch",
  "providerLyricsId": "12345",
  "lyrics": "When you were here before\nCouldn't look you in the eye...",
  "subtitles": "[00:00.00] When you were here before\n[00:05.23] Couldn't look you in the eye..."
}
```

**Credits Object:**
```json
{
  "credits": [
    {
      "type": "Producers",
      "contributors": [
        {"name": "Sean Slade", "id": 12345},
        {"name": "Paul Q. Kolderie", "id": 67890}
      ]
    },
    {
      "type": "Performers",
      "contributors": [
        {"name": "Thom Yorke", "id": 111, "role": "Vocals"},
        {"name": "Jonny Greenwood", "id": 222, "role": "Guitar"}
      ]
    }
  ]
}
```

### Quality Levels

| Quality | Codec | Bitrate/Depth | Subscription Tier |
|---------|-------|---------------|-------------------|
| LOW | AAC | 96 kbps | Free (trial) |
| HIGH | AAC | 320 kbps | HiFi |
| LOSSLESS | FLAC | 16-bit/44.1kHz | HiFi |
| HI_RES | FLAC | 24-bit/96kHz+ | HiFi Plus |
| HI_RES_LOSSLESS | MQA | 24-bit/96kHz+ (MQA) | HiFi Plus |

**MQA (Master Quality Authenticated):**
- Proprietary format by Meridian Audio
- Requires MQA-compatible DAC for full unfolding
- Software decoding provides 24-bit/96kHz

### Manifest Decryption

Some streaming URLs are encrypted. minim handles decryption:

```python
def _decrypt_manifest(self, manifest: dict) -> str:
    from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
    from cryptography.hazmat.backends import default_backend
    import base64
    
    # Extract encrypted URL
    encrypted_url = manifest["urls"][0]
    
    # Decrypt using AES-128-CTR
    key = base64.b64decode(manifest["encryptionKey"])
    nonce = base64.b64decode(manifest["nonce"])
    
    cipher = Cipher(
        algorithms.AES(key),
        modes.CTR(nonce),
        backend=default_backend()
    )
    decryptor = cipher.decryptor()
    
    decrypted = decryptor.update(base64.b64decode(encrypted_url)) + decryptor.finalize()
    return decrypted.decode("utf-8")
```

### Rate Limiting

**Unknown.** Private API does not document rate limits.

**Observation:** Moderate usage (<50 requests/minute) appears safe.

**Recommendation:** Implement conservative rate limiting and exponential backoff on errors.

### Use Cases

1. **High-Fidelity Streaming:** Get FLAC files up to 24-bit/192kHz and MQA
2. **Comprehensive Credits:** Get detailed production credits
3. **Synchronized Lyrics:** Display time-synced lyrics
4. **Metadata Enrichment:** Get authoritative release dates, ISRCs, UPCs
5. **Playlist Management:** Sync playlists between services

### Limitations

- Private API (may break without notice)
- Requires active subscription (HiFi or HiFi Plus for lossless)
- Client ID/secret extraction violates terms of service
- No playback control API
- No audio features/analysis
- Geographic restrictions on content

## Integration Comparison

### Authentication Complexity

**Simplest:** iTunes (no auth)  
**Simple:** Discogs (personal token), Spotify (client credentials)  
**Moderate:** Spotify (authorization code), TIDAL (PKCE)  
**Complex:** Qobuz (app_id extraction + password grant)

### API Documentation Quality

**Best:** Spotify (comprehensive, well-maintained)  
**Good:** Discogs, iTunes  
**Poor:** TIDAL (limited public docs)  
**None:** Qobuz (fully reverse-engineered)

### Streaming Capability

**High-Resolution:** Qobuz (up to 24/192 FLAC), TIDAL (up to 24/192 FLAC + MQA)  
**Lossless:** TIDAL (16/44.1 FLAC)  
**Lossy:** TIDAL (AAC), Qobuz (MP3)  
**Preview Only:** Spotify (30sec MP3), iTunes (30sec M4A)  
**None:** Discogs

### Metadata Richness

**Credits:** TIDAL (excellent), Discogs (good), others (none)  
**Lyrics:** TIDAL (synced), Spotify (synced, private API), others (none)  
**Audio Features:** Spotify (excellent), others (none)  
**Catalog Info:** All services (good)

### Terms of Service Compliance

**Compliant:** Discogs (public API), iTunes (public API), Spotify (public Web API)  
**Questionable:** Spotify (private lyrics API)  
**Violation:** Qobuz (app_id extraction, private API), TIDAL (client_id extraction, private API)

## Summary

minim provides comprehensive integration with five music services, each serving different use cases:

- **Discogs:** Best for credits, catalog numbers, and collection management
- **iTunes:** Best for quick, unauthenticated metadata lookup
- **Qobuz:** Best for high-resolution downloads (within subscription terms)
- **Spotify:** Best for comprehensive metadata, audio features, and playlist management
- **TIDAL:** Best for high-fidelity streaming, credits, and synchronized lyrics

All integrations follow consistent patterns (authentication, request handling, error raising) while exposing service-specific features. The private API usage (Qobuz, Spotify lyrics, TIDAL) provides powerful capabilities but carries legal and stability risks.

For a metadata aggregator project, prioritize public APIs (Spotify Web API, Discogs, iTunes) for production use, and use private APIs only for research or personal projects.