Metadata-Version: 2.4
Name: minkdb
Version: 0.2.0
Summary: A metadata-link between iTunes and MusicBrainz
Requires-Python: >=3.13
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.3.1
Requires-Dist: lidarr-py>=1.2.0
Requires-Dist: musicbrainzngs>=0.7.1
Requires-Dist: rich>=14.3.3
Provides-Extra: dev
Requires-Dist: ruff>=0.15.4; extra == "dev"
Requires-Dist: ty>=0.0.19; extra == "dev"
Dynamic: license-file

# Mink-db

A metadata-link between iTunes and MusicBrainz. A CLI tool that catalogs a music library by scanning iTunes libraries and retrieving MusicBrainz artist IDs.

## How It Works

1. **Reads iTunes XML**: Parses `iTunes Music Library.xml` for album metadata
2. **Deduplicates**: Groups tracks by (artist, album) to avoid duplicate queries
3. **Queries MusicBrainz**: Searches release groups using exact artist + album matching
4. **Caches Results**: Stores album and artist data in `.minkdb/album.json` and `.minkdb/artist.json`
5. **Outputs**: Prints matched IDs to stdout or file

On subsequent runs, Mink-db will skip already-matched albums and only query MusicBrainz for new ones.

## Installation

Mink-db requires Python 3.13 or later.

```bash
# Run directly with uvx (no installation required)
uvx minkdb --help

# Or install as a tool
git clone https://github.com/thomaseleff/minkdb.git
cd minkdb
uv tool install .
```

## Quick Start

Catalog your iTunes library and get MusicBrainz IDs:

```bash
minkdb --path "M:\Music\iTunes"
```

## Usage

```bash
# Basic usage (defaults to current directory)
minkdb

# Specify iTunes library path
minkdb --path "M:\Music\iTunes"

# Limit number of albums processed
minkdb --path "M:\Music\iTunes" --limit 10

# Save output to file
minkdb --path "M:\Music\iTunes" -o ids.json

# Retry matching for previously unmatched albums
minkdb --path "M:\Music\iTunes" --rematch

# Publish curated exact albums to Lidarr
LIDARR_API_KEY="<your-api-key>" minkdb publish --path "M:\Music\iTunes"

# Publish to a non-default Lidarr URL
LIDARR_API_KEY="<your-api-key>" minkdb publish --path "M:\Music\iTunes" --url "http://lidarr.local:8686"
```

## Output Format

Mink-db outputs a JSON array of unique matched MusicBrainz artist IDs:

```json
[
  {"MusicBrainzArtistId": "11111111-1111-1111-1111-111111111111"},
  {"MusicBrainzArtistId": "22222222-2222-2222-2222-222222222222"}
]
```

## Data Storage

- **Album database**: `<library_path>/.minkdb/album.json`
- **Artist database**: `<library_path>/.minkdb/artist.json` (unique by artist MusicBrainz ID)
- **Album FK**: Each album row includes `artist_musicbrainz_id` referencing `artist.json`

## Lidarr Publish

- Uses `lidarr-py` for API integration
- Reads curated matched album metadata from `.minkdb/album.json`
- Requires `LIDARR_API_KEY` in environment
- Adds artists with broad monitoring disabled and monitors only exact albums from Mink-db

## Requirements

- Python 3.13+
- iTunes Music Library.xml file
- Internet connection (for MusicBrainz queries)
