Metadata-Version: 2.4
Name: selin-vinyl-api
Version: 0.1.0
Summary: Official Python client for the Selin Vinyl API: music metadata, matching, credits and cover art.
License: MIT
Project-URL: Homepage, https://selin-ai.com/vinyl-api
Project-URL: Documentation, https://vinyl-api.selin-ai.com/docs
Keywords: music,metadata,musicbrainz,isrc,upc,api,selin,vinyl
Classifier: Programming Language :: Python :: 3
Classifier: Typing :: Typed
Classifier: License :: OSI Approved :: MIT License
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# selin-vinyl-api (Python)

Official client for the [Selin Vinyl API](https://vinyl-api.selin-ai.com/docs): artists, albums, tracklists, ISRC and barcode lookups, credits, cover art and track matching, built on MusicBrainz and Wikidata (CC0) plus Selin's own listening data.

No dependencies (standard library only). Python 3.9+.

```sh
pip install selin-vinyl-api
```

Get a free key at <https://selin-ai.com/vinyl-api>.

```python
from selin_vinyl import VinylAPI, VinylAPIError

vinyl = VinylAPI(api_key="vk_...")   # or set VINYL_API_KEY

artists = vinyl.search_artists("prince", limit=3)["artists"]
album = vinyl.get_album_tracks("<release-group id>", credits=True)

# Which recording is this? The matching tool for library imports.
match = vinyl.match_track("Purple Rain", artist="Prince", duration_ms=520000)["match"]

# Up to 50 lookups in one request.
results = vinyl.batch([
    {"id": "a", "type": "isrc", "value": "USWB11602075"},
    {"id": "b", "type": "upc", "value": "602547924139"},
])["results"]
```

Methods are the API's operations in snake_case: `search_artists`, `get_artist`, `list_artist_releases`, `list_artist_credits`, `lookup_artist`, `search_albums`, `get_album`, `get_album_tracks`, `get_album_artwork`, `lookup_album`, `list_new_releases`, `lookup_upc`, `search_tracks`, `lookup_isrc`, `get_recording`, `match_track`, `batch`, `get_artist_chart`, `get_usage`, `get_plans`. Each returns the parsed JSON; the [API reference](https://vinyl-api.selin-ai.com/docs) documents every field.

## Errors, limits and retries

```python
try:
    vinyl.get_artist(artist_id)
except VinylAPIError as e:
    print(e.status, e.code, e.retry_after)

vinyl.rate_limit   # {"limit", "remaining", "quota_limit", "quota_used"} from the last response
```

A `429` is retried automatically after the `Retry-After` wait (up to `max_retries`, default 2); gateway errors on GETs are retried with backoff. Constructor options: `base_url`, `max_retries`, `timeout`.

## Attribution

Show the `attribution` string the API returns wherever you display its data. Wikipedia biographies are CC BY-SA 4.0 (credit and link back); cover art and artist photos belong to their rights holders.

MIT licensed.
