sonovault 1.0.0__py3-none-any.whl

sonovault/__init__.py

@@ -0,0 +1,7 @@
+"""Python client for the SonoVault music metadata API — https://sonovault.now"""
+
+from .client import SonoVault
+from .errors import SonoVaultError
+
+__all__ = ["SonoVault", "SonoVaultError"]
+__version__ = "1.0.0"

sonovault/client.py

@@ -0,0 +1,314 @@
+"""SonoVault API client.
+
+Usage:
+    from sonovault import SonoVault
+
+    sv = SonoVault(api_key="...")
+    page = sv.tracks.search(artist="Daft Punk", title="One More Time")
+    print(page["results"][0]["isrc"])
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Any, Dict, List, Optional, Union
+
+import requests
+
+from .errors import SonoVaultError
+
+DEFAULT_BASE_URL = "https://api.sonovault.now"
+
+
+class SonoVault:
+    """Client for the SonoVault music metadata API (https://sonovault.now).
+
+    Args:
+        api_key: your API key — get a free one at https://sonovault.now
+            (1,000 requests/month, no credit card).
+        base_url: override the API base URL.
+        max_retries: retries on retryable 429/5xx responses. Default 2.
+        session: optional ``requests.Session`` (for pooling or testing).
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        max_retries: int = 2,
+        session: Optional[requests.Session] = None,
+    ):
+        if not api_key:
+            raise ValueError("SonoVault: api_key is required")
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._max_retries = max_retries
+        self._session = session or requests.Session()
+
+        self.tracks = _Tracks(self)
+        self.artists = _Artists(self)
+        self.labels = _Labels(self)
+        self.releases = _Releases(self)
+        self.genres = _Genres(self)
+        self.suggestions = _Suggestions(self)
+        self.streams = _Streams(self)
+        self.webhooks = _Webhooks(self)
+
+    # -- plumbing ---------------------------------------------------------
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Optional[Dict[str, Any]] = None,
+        json: Any = None,
+        data: Optional[bytes] = None,
+        content_type: Optional[str] = None,
+    ) -> Any:
+        url = self._base_url + path
+        clean_params = {k: v for k, v in (params or {}).items() if v is not None}
+        headers = {"x-api-key": self._api_key}
+        if content_type:
+            headers["Content-Type"] = content_type
+
+        last_error: Optional[SonoVaultError] = None
+        for attempt in range(self._max_retries + 1):
+            try:
+                res = self._session.request(
+                    method, url, params=clean_params, json=json, data=data,
+                    headers=headers, timeout=30,
+                )
+            except requests.RequestException as exc:
+                last_error = SonoVaultError(f"Network error: {exc}", 0)
+                continue
+
+            if res.ok:
+                if res.status_code == 204 or not res.content:
+                    return None
+                return res.json()
+
+            try:
+                body = res.json()
+            except ValueError:
+                body = None
+            message = None
+            if isinstance(body, dict):
+                message = body.get("error") or body.get("message")
+            last_error = SonoVaultError(message or f"HTTP {res.status_code}", res.status_code, body)
+
+            # Retry only transient failures. A 429 with Retry-After is a rate
+            # limit (retryable); a 429 without one is usually quota exhaustion.
+            retry_after = res.headers.get("Retry-After")
+            retryable = res.status_code >= 500 or (res.status_code == 429 and retry_after is not None)
+            if not retryable or attempt == self._max_retries:
+                raise last_error
+            time.sleep(float(retry_after) if retry_after else 0.5 * (2 ** attempt))
+
+        raise last_error or SonoVaultError("Request failed", 0)
+
+
+class _Namespace:
+    def __init__(self, client: SonoVault):
+        self._client = client
+
+
+class _Tracks(_Namespace):
+    def search(self, *, artist: str, title: str, limit: Optional[int] = None,
+               cursor: Optional[str] = None) -> Dict[str, Any]:
+        """Search by artist + title (both required — there is no free-text query)."""
+        return self._client._request("GET", "/v1/tracks/search", params={
+            "artist": artist, "title": title, "limit": limit, "cursor": cursor,
+        })
+
+    def get(self, track_id: int) -> Dict[str, Any]:
+        """Fetch a track by its SonoVault ID."""
+        return self._client._request("GET", f"/v1/tracks/{track_id}")
+
+    def by_isrc(self, isrc: str) -> Dict[str, Any]:
+        """Look up a track by any of its ISRCs."""
+        return self._client._request("GET", f"/v1/tracks/isrc/{isrc}")
+
+    def iswc(self, *, isrc: Optional[str] = None, track_id: Optional[int] = None) -> Dict[str, Any]:
+        """Recording → composition: the ISWC(s) behind a recording."""
+        return self._client._request("GET", "/v1/tracks/iswc",
+                                     params={"isrc": isrc, "id": track_id})
+
+    def by_iswc(self, iswc: str, *, limit: Optional[int] = None) -> Dict[str, Any]:
+        """Composition → recordings: every recording of a work, by ISWC."""
+        return self._client._request("GET", f"/v1/tracks/iswc/{iswc}", params={"limit": limit})
+
+    def links(self, **ids: Union[str, int]) -> Dict[str, Any]:
+        """Cross-platform IDs + deep links, from any platform ID or ISRC.
+
+        Keyword args: ``id``, ``isrc``, ``spotify_id``, ``beatport_id``,
+        ``discogs_id``, ``musicbrainz_id``, ``applemusic_id``, ``tidal_id``,
+        ``youtube_id``.
+        """
+        return self._client._request("GET", "/v1/tracks/links", params=dict(ids))
+
+    def resolve(self, *, input_type: str,
+                items: List[Union[str, Dict[str, str]]]) -> Dict[str, Any]:
+        """Resolve up to 100 track names, ISRCs, or platform IDs in one request."""
+        return self._client._request("POST", "/v1/tracks/resolve",
+                                     json={"input_type": input_type, "items": items})
+
+    def identify(self, *, fingerprint: List[int],
+                 fingerprint_duration: Optional[float] = None,
+                 top_n: Optional[int] = None) -> Dict[str, Any]:
+        """Identify a track from a Chromaprint fingerprint (``fpcalc -raw``). Paid tiers."""
+        body: Dict[str, Any] = {"fingerprint": fingerprint}
+        if fingerprint_duration is not None:
+            body["fingerprint_duration"] = fingerprint_duration
+        if top_n is not None:
+            body["top_n"] = top_n
+        return self._client._request("POST", "/v1/tracks/identify", json=body)
+
+    def identify_audio(self, audio: bytes, *, length: Optional[int] = None,
+                       top_n: Optional[int] = None) -> Dict[str, Any]:
+        """Identify a track from raw audio bytes (any ffmpeg-decodable format).
+
+        Send the whole track when you can — the matching section is often
+        mid-track. Paid tiers; costs 10 + ceil(MB) credits.
+        """
+        return self._client._request(
+            "POST", "/v1/tracks/identify",
+            params={"length": length, "top_n": top_n},
+            data=audio, content_type="application/octet-stream",
+        )
+
+    def browse(self, **params: Any) -> Dict[str, Any]:
+        """Browse the catalog by ``labelId``, ``artistId``, ``genre``, ``genreId``,
+        ``year``, or ``randomize``. Paid tiers."""
+        return self._client._request("GET", "/v1/tracks/browse", params=dict(params))
+
+
+class _Artists(_Namespace):
+    def search(self, *, name: str, limit: Optional[int] = None,
+               cursor: Optional[str] = None) -> Dict[str, Any]:
+        return self._client._request("GET", "/v1/artists/search",
+                                     params={"name": name, "limit": limit, "cursor": cursor})
+
+    def get(self, artist_id: int) -> Dict[str, Any]:
+        return self._client._request("GET", f"/v1/artists/{artist_id}")
+
+    def releases(self, artist_id: int, *, limit: Optional[int] = None,
+                 cursor: Optional[str] = None) -> Dict[str, Any]:
+        return self._client._request("GET", f"/v1/artists/{artist_id}/releases",
+                                     params={"limit": limit, "cursor": cursor})
+
+
+class _Labels(_Namespace):
+    def search(self, *, name: str, limit: Optional[int] = None,
+               cursor: Optional[str] = None) -> Dict[str, Any]:
+        return self._client._request("GET", "/v1/labels/search",
+                                     params={"name": name, "limit": limit, "cursor": cursor})
+
+    def get(self, label_id: int) -> Dict[str, Any]:
+        return self._client._request("GET", f"/v1/labels/{label_id}")
+
+    def releases(self, label_id: int, *, limit: Optional[int] = None,
+                 cursor: Optional[str] = None) -> Dict[str, Any]:
+        return self._client._request("GET", f"/v1/labels/{label_id}/releases",
+                                     params={"limit": limit, "cursor": cursor})
+
+    def artists(self, label_id: int, *, limit: Optional[int] = None,
+                cursor: Optional[str] = None) -> Dict[str, Any]:
+        return self._client._request("GET", f"/v1/labels/{label_id}/artists",
+                                     params={"limit": limit, "cursor": cursor})
+
+
+class _Releases(_Namespace):
+    def search(self, *, title: str, artist: Optional[str] = None,
+               limit: Optional[int] = None, cursor: Optional[str] = None) -> Dict[str, Any]:
+        return self._client._request("GET", "/v1/releases/search", params={
+            "title": title, "artist": artist, "limit": limit, "cursor": cursor,
+        })
+
+    def get(self, release_id: int) -> Dict[str, Any]:
+        return self._client._request("GET", f"/v1/releases/{release_id}")
+
+    def latest(self, *, limit: Optional[int] = None,
+               cursor: Optional[str] = None) -> Dict[str, Any]:
+        """Newly released albums (``GET /v1/releases/new``). Paid tiers."""
+        return self._client._request("GET", "/v1/releases/new",
+                                     params={"limit": limit, "cursor": cursor})
+
+
+class _Genres(_Namespace):
+    def list(self) -> Dict[str, Any]:
+        """The canonical genre/subgenre hierarchy."""
+        return self._client._request("GET", "/v1/genres")
+
+
+class _Suggestions(_Namespace):
+    def submit(self, track_id: int, body: Dict[str, Any]) -> Dict[str, Any]:
+        """Suggest a metadata correction for a track. Paid tiers."""
+        return self._client._request("POST", f"/v1/tracks/{track_id}/suggestions", json=body)
+
+    def list(self, *, limit: Optional[int] = None,
+             cursor: Optional[str] = None) -> Dict[str, Any]:
+        return self._client._request("GET", "/v1/suggestions",
+                                     params={"limit": limit, "cursor": cursor})
+
+
+class _Streams(_Namespace):
+    def create(self, body: Dict[str, Any]) -> Dict[str, Any]:
+        """Start monitoring an Icecast/Shoutcast stream. Paid tiers."""
+        return self._client._request("POST", "/v1/streams", json=body)
+
+    def list(self) -> Dict[str, Any]:
+        return self._client._request("GET", "/v1/streams")
+
+    def get(self, stream_id: str) -> Dict[str, Any]:
+        return self._client._request("GET", f"/v1/streams/{stream_id}")
+
+    def update(self, stream_id: str, body: Dict[str, Any]) -> Dict[str, Any]:
+        return self._client._request("PATCH", f"/v1/streams/{stream_id}", json=body)
+
+    def history(self, stream_id: str, *, since: Optional[str] = None) -> Dict[str, Any]:
+        return self._client._request("GET", f"/v1/streams/{stream_id}/history",
+                                     params={"since": since})
+
+    def report(self, *, from_: str, until: str,
+               stream_id: Optional[str] = None) -> Dict[str, Any]:
+        """Play report between two timestamps. ``from_`` maps to the ``from`` param."""
+        return self._client._request("GET", "/v1/streams/report", params={
+            "from": from_, "until": until, "stream_id": stream_id,
+        })
+
+    def live(self) -> Dict[str, Any]:
+        """What's playing right now across your monitored streams."""
+        return self._client._request("GET", "/v1/streams/live")
+
+    def stop(self, stream_id: str) -> None:
+        """Stop monitoring a stream."""
+        return self._client._request("DELETE", f"/v1/streams/{stream_id}")
+
+
+class _Webhooks(_Namespace):
+    def create(self, *, url: str, event_types: Optional[List[str]] = None,
+               description: Optional[str] = None) -> Dict[str, Any]:
+        """Register a webhook. The response includes ``secret`` once — store it."""
+        body: Dict[str, Any] = {"url": url}
+        if event_types is not None:
+            body["event_types"] = event_types
+        if description is not None:
+            body["description"] = description
+        return self._client._request("POST", "/v1/webhooks", json=body)
+
+    def list(self) -> Dict[str, Any]:
+        return self._client._request("GET", "/v1/webhooks")
+
+    def update(self, webhook_id: str, body: Dict[str, Any]) -> Dict[str, Any]:
+        return self._client._request("PATCH", f"/v1/webhooks/{webhook_id}", json=body)
+
+    def delete(self, webhook_id: str) -> None:
+        return self._client._request("DELETE", f"/v1/webhooks/{webhook_id}")
+
+    def test(self, webhook_id: str) -> Dict[str, Any]:
+        return self._client._request("POST", f"/v1/webhooks/{webhook_id}/test")
+
+    def deliveries(self, webhook_id: str) -> Dict[str, Any]:
+        return self._client._request("GET", f"/v1/webhooks/{webhook_id}/deliveries")

sonovault/errors.py

@@ -0,0 +1,27 @@
+class SonoVaultError(Exception):
+    """Raised for any non-2xx API response.
+
+    Attributes:
+        status: HTTP status code (0 for network errors).
+        body: parsed JSON error body, when the API returned one.
+    """
+
+    def __init__(self, message: str, status: int = 0, body=None):
+        super().__init__(message)
+        self.status = status
+        self.body = body
+
+    @property
+    def is_auth_error(self) -> bool:
+        """Missing or invalid API key."""
+        return self.status == 401
+
+    @property
+    def is_forbidden(self) -> bool:
+        """The endpoint needs a paid tier (or an admin key)."""
+        return self.status == 403
+
+    @property
+    def is_rate_limited(self) -> bool:
+        """Rate limit or monthly credit quota hit."""
+        return self.status == 429

sonovault-1.0.0.dist-info/METADATA

@@ -0,0 +1,134 @@
+Metadata-Version: 2.4
+Name: sonovault
+Version: 1.0.0
+Summary: Python client for the SonoVault music metadata API — ISRC, ISWC, genre, labels, release dates, and cross-platform IDs for 90M+ tracks.
+Project-URL: Homepage, https://sonovault.now
+Project-URL: Documentation, https://sonovault.now/docs
+Project-URL: Repository, https://github.com/rekordcloud/sonovault-python
+Project-URL: Issues, https://github.com/rekordcloud/sonovault-python/issues
+Author: Rekordcloud B.V.
+License: MIT
+License-File: LICENSE
+Keywords: apple-music,audio-recognition,beatport,discogs,isrc,iswc,metadata,music,music-api,musicbrainz,spotify,tidal
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Sound/Audio
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Requires-Dist: requests>=2.25
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# sonovault
+
+[![CI](https://github.com/rekordcloud/sonovault-python/actions/workflows/ci.yml/badge.svg)](https://github.com/rekordcloud/sonovault-python/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/sonovault)](https://pypi.org/project/sonovault/)
+
+Python client for the **[SonoVault](https://sonovault.now)** music metadata API — 90M+ tracks with ISRC, ISWC, genre, record label, canonical release dates, and cross-platform IDs for Spotify, Apple Music, Tidal, Beatport, Discogs, and MusicBrainz, resolved in a single call.
+
+- **One key, no OAuth** — a single `x-api-key` header, no approval queue.
+- **Free tier** — 1,000 requests/month, no credit card: [get an API key](https://sonovault.now).
+- **Docs** — full API reference at [sonovault.now/docs](https://sonovault.now/docs).
+
+## Install
+
+```bash
+pip install sonovault
+```
+
+Python 3.9+.
+
+## Quickstart
+
+```python
+from sonovault import SonoVault
+
+sv = SonoVault(api_key="YOUR_API_KEY")
+
+# Find a track's ISRC from artist + title
+page = sv.tracks.search(artist="Daft Punk", title="One More Time")
+track = page["results"][0]
+print(track["isrc"])   # "GBDUW0000053"
+print(track["genre"], track["releases"][0]["label"]["name"])
+
+# Resolve that ISRC to its ID on every platform
+links = sv.tracks.links(isrc=track["isrc"])
+for link in links["links"]:
+    print(link["source"], link["url"])  # spotify https://open.spotify.com/track/…
+
+# Recording → composition (ISWC), for royalty/publishing workflows
+work = sv.tracks.iswc(isrc=track["isrc"])
+```
+
+## Bulk resolve
+
+Resolve up to 100 lines — track names, ISRCs, or platform IDs — in one request (great for enriching play logs and library exports):
+
+```python
+batch = sv.tracks.resolve(
+    input_type="track_name",
+    items=[
+        {"artist": "Daft Punk", "title": "Harder, Better, Faster, Stronger"},
+        {"artist": "Daft Punk", "title": "Around the World"},
+    ],
+)
+for row in batch["results"]:
+    print(row["status"], row["track"] and row["track"]["isrc"])
+```
+
+## Pagination
+
+List endpoints return `{"results": [...], "next_cursor": ...}` — pass the cursor back for the next page (`next_cursor` is `None` on the last page):
+
+```python
+cursor = None
+while True:
+    page = sv.artists.releases(42, cursor=cursor)
+    # …use page["results"]
+    cursor = page.get("next_cursor")
+    if not cursor:
+        break
+```
+
+## Error handling
+
+Non-2xx responses raise `SonoVaultError`:
+
+```python
+from sonovault import SonoVaultError
+
+try:
+    sv.tracks.browse(genre="House")  # paid-tier endpoint
+except SonoVaultError as err:
+    print(err.status, err.is_forbidden, err)
+```
+
+Rate-limited responses that carry a `Retry-After` header are retried automatically (twice by default; configure with `max_retries`).
+
+## API coverage
+
+| Namespace | Methods |
+|---|---|
+| `sv.tracks` | `search`, `get`, `by_isrc`, `iswc`, `by_iswc`, `links`, `resolve`, `identify`, `identify_audio`, `browse` |
+| `sv.artists` | `search`, `get`, `releases` |
+| `sv.labels` | `search`, `get`, `releases`, `artists` |
+| `sv.releases` | `search`, `get`, `latest` |
+| `sv.genres` | `list` |
+| `sv.suggestions` | `submit`, `list` |
+| `sv.streams` | `create`, `list`, `get`, `update`, `history`, `report`, `live`, `stop` |
+| `sv.webhooks` | `create`, `list`, `update`, `delete`, `test`, `deliveries` |
+
+Some endpoints (audio identify, browse, charts, stream monitoring) need a paid tier — see [pricing](https://sonovault.now/pricing). Everything else works on the free tier.
+
+## Related
+
+- [SonoVault API docs](https://sonovault.now/docs) — full endpoint reference with examples in 8 languages
+- [sonovault-js](https://github.com/rekordcloud/sonovault-js) — the TypeScript/Node client
+- [Free ISRC lookup](https://sonovault.now/isrc-lookup) · [ISWC lookup](https://sonovault.now/iswc-lookup) — browser tools built on the same API
+
+## License
+
+MIT

sonovault-1.0.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+sonovault/__init__.py,sha256=DhG_Yije4saOdfP5RiM4u4xx0vG0ea8_M1UXv_4B-U4,214
+sonovault/client.py,sha256=cF86-w6H-8lWvIbcZtS87x-I5Ih1RsPOaNS6hWb48gM,13424
+sonovault/errors.py,sha256=Qm_ThqzT3wvKW4Mj_kO0oUcnDDjMHp-6ygHOCGUECto,798
+sonovault-1.0.0.dist-info/METADATA,sha256=q13e1ynBRD0RM0NMVLMd1BKYp1dRcGCUC8rxU_EdoBY,4964
+sonovault-1.0.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+sonovault-1.0.0.dist-info/licenses/LICENSE,sha256=t3zvEZpn3Mg2Txx7h2rsyGwZBlzpntW1CkBxFl0T8qw,1073
+sonovault-1.0.0.dist-info/RECORD,,

sonovault-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

sonovault-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rekordcloud B.V.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.