Initial release v1.4.2

Author: AudD

.github/workflows/ci.yml

@@ -0,0 +1,32 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    name: tests + mypy + ruff
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ['3.10', '3.11', '3.12', '3.13']
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+          cache: pip
+      - name: Install
+        run: |
+          pip install --upgrade pip
+          pip install -e '.[dev]'
+      - name: Ruff
+        run: python -m ruff check src/audd/ tests/
+      - name: Mypy
+        run: python -m mypy src/audd/
+      - name: Unit tests
+        run: python -m pytest tests/unit/ -v --tb=short

.github/workflows/contract.yml

@@ -0,0 +1,49 @@
+name: Contract tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  schedule:
+    - cron: '0 6 * * *'  # daily at 06:00 UTC
+  repository_dispatch:
+    types: [openapi-updated]
+
+jobs:
+  contract:
+    name: validate parser against latest audd-openapi fixtures
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          path: audd-python
+      - name: Check out audd-openapi
+        uses: actions/checkout@v4
+        with:
+          repository: AudDMusic/audd-openapi
+          path: audd-openapi
+          ref: main
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+          cache: pip
+          cache-dependency-path: audd-python/pyproject.toml
+      - name: Install
+        working-directory: audd-python
+        run: pip install -e '.[dev]'
+      - name: Run contract tests
+        working-directory: audd-python
+        env:
+          AUDD_OPENAPI_FIXTURES: ${{ github.workspace }}/audd-openapi/fixtures
+        run: python -m pytest tests/contract/ -v --tb=short
+      - name: Open issue on failure (dispatched runs only)
+        if: failure() && github.event_name == 'repository_dispatch'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          TRIGGER_SHA: ${{ github.event.client_payload.trigger_sha }}
+        run: |
+          gh issue create \
+            --title "Contract drift: audd-openapi spec change broke parser" \
+            --body "An openapi-updated dispatch (trigger SHA: $TRIGGER_SHA) caused contract tests to fail. Investigate and update parsers." \
+            --label "contract-drift" || true

.github/workflows/release.yml

@@ -0,0 +1,36 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'audd-python/v*'
+      - 'v*'
+
+permissions:
+  contents: read
+  id-token: write
+  attestations: write
+
+jobs:
+  build-and-publish:
+    name: Build and publish to PyPI
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - name: Install build tools
+        run: |
+          pip install --upgrade pip build
+      - name: Build sdist + wheel
+        run: python -m build
+      - name: Generate Sigstore attestations
+        uses: actions/attest-build-provenance@v1
+        with:
+          subject-path: 'dist/*'
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          attestations: true

.gitignore

@@ -0,0 +1,14 @@
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+build/
+dist/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+.env
+.DS_Store

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AudD (https://audd.io)
+
+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.

README.md

@@ -0,0 +1,155 @@
+# audd
+
+[![CI](https://github.com/AudDMusic/audd-python/actions/workflows/ci.yml/badge.svg)](https://github.com/AudDMusic/audd-python/actions/workflows/ci.yml)
+[![Contract](https://github.com/AudDMusic/audd-python/actions/workflows/contract.yml/badge.svg)](https://github.com/AudDMusic/audd-python/actions/workflows/contract.yml)
+[![PyPI](https://img.shields.io/pypi/v/audd.svg)](https://pypi.org/project/audd/)
+[![Python versions](https://img.shields.io/pypi/pyversions/audd.svg)](https://pypi.org/project/audd/)
+
+Official Python SDK for the [AudD](https://audd.io) music recognition API.
+
+## Quickstart
+
+```bash
+pip install audd
+```
+
+```python
+from audd import AudD
+
+audd = AudD(api_token="test")  # use your token from https://dashboard.audd.io
+result = audd.recognize("https://audd.tech/example.mp3")
+if result:
+    print(f"{result.artist} — {result.title}")
+```
+
+## Capabilities
+
+| What | How |
+|---|---|
+| Recognize a short clip (≤25s) | `audd.recognize(source)` |
+| Recognize a long file (hours, days) | `audd.recognize_enterprise(source, limit=...)` |
+| Manage stream recognition (set callback, longpoll for events) | `audd.streams.*` |
+
+`source` accepts a URL, a file path, a file-like object, or raw bytes — auto-detected.
+
+## Async
+
+Use `AsyncAudD` instead — same surface:
+
+```python
+from audd import AsyncAudD
+
+async def main():
+    audd = AsyncAudD(api_token="test")
+    try:
+        result = await audd.recognize("https://audd.tech/example.mp3")
+        print(result)
+    finally:
+        await audd.aclose()
+```
+
+## Errors
+
+Every server error becomes a typed exception:
+
+```python
+from audd import AudD, AudDAuthenticationError, AudDSubscriptionError
+
+try:
+    AudD(api_token="bad").recognize("https://x.mp3")
+except AudDAuthenticationError as e:
+    print(f"check your token: {e.error_code} {e.message}")
+except AudDSubscriptionError:
+    print("this endpoint isn't enabled on your token")
+```
+
+The full hierarchy is documented in [`src/audd/errors.py`](src/audd/errors.py). Every `AudDAPIError` carries `error_code`, `message`, `http_status`, `request_id`, `requested_params`, `request_method`, `branded_message`, and `raw_response`.
+
+## Forward compatibility
+
+Models accept and round-trip unknown server fields via `model_extra`:
+
+```python
+result = audd.recognize("https://example.mp3", return_=["apple_music"])
+print(result.apple_music.url)               # typed
+print(result.model_extra)                   # any other unknown fields
+```
+
+If AudD adds a new metadata block tomorrow (e.g., `tidal`), you can read it as `result.model_extra["tidal"]` *today* — no SDK release needed. The next SDK release adds the typed `tidal` field, and both paths keep working.
+
+## Streams
+
+Manage real-time stream recognition (set callback, longpoll for events):
+
+```python
+audd.streams.set_callback_url("https://your.server/cb")
+audd.streams.add("https://your.stream.url", radio_id=42)
+for event in audd.streams.list():
+    print(event)
+```
+
+### Receiving events without exposing your token
+
+For browser widgets and other contexts where shipping the api_token would leak it,
+derive a `category` server-side and share that with the consumer:
+
+```python
+from audd import LongpollConsumer
+
+# `category` is derived server-side via AudD(...).streams.derive_longpoll_category(radio_id),
+# then shared with the browser/widget. The consumer carries no api_token.
+consumer = LongpollConsumer(category="abc123def")
+for event in consumer.iterate(timeout=30):
+    print(event)
+```
+
+## Configuration
+
+```python
+import httpx
+from audd import AudD
+
+audd = AudD(
+    api_token="...",
+    max_retries=3,           # retry budget per call
+    backoff_factor=0.5,      # initial backoff seconds (jittered)
+    httpx_client=httpx.Client(proxies="http://corp-proxy:8080"),
+)
+```
+
+Default timeouts: 30s connect / 60s read for standard endpoints, 30s connect / **1 hour** read for the enterprise endpoint. Pass `timeout=` per call to override.
+
+**Concurrency:** `AudD` and `AsyncAudD` are safe for concurrent use — share one instance across threads or asyncio tasks. `set_api_token(...)` rotates the token safely; in-flight requests continue with the old token, subsequent requests use the new one.
+
+## Custom catalog (advanced — not for music recognition)
+
+> ⚠ **The custom-catalog endpoint is NOT how you submit audio for music recognition.**
+> For recognition, use `recognize()` or `recognize_enterprise()`. The custom-catalog
+> endpoint adds songs to your private fingerprint database for *your* account.
+> Requires special access — contact api@audd.io if you need it.
+
+```python
+audd.custom_catalog.add(audio_id=42, source="https://my.song.mp3")
+```
+
+## Advanced
+
+For endpoints not yet wrapped by typed methods on this SDK, use the raw-request escape hatch:
+
+```python
+raw = audd.advanced.raw_request("someNewMethod", {"q": "x"})
+```
+
+## Spec contract
+
+This SDK builds against the [`audd-openapi`](https://github.com/AudDMusic/audd-openapi) spec. The contract tests in `tests/contract/` validate the parser against the canonical fixture set on every push, on a daily cron, and on every spec update.
+
+## License
+
+MIT — see [LICENSE](./LICENSE).
+
+## Support
+
+- Documentation: https://docs.audd.io
+- Tokens: https://dashboard.audd.io
+- Email: api@audd.io

SECURITY.md

@@ -0,0 +1,17 @@
+# Security Policy
+
+## Reporting a vulnerability
+
+If you discover a security issue in this SDK, please email **api@audd.io** privately. Do not open a public GitHub issue for security reports.
+
+We will acknowledge receipt within 2 business days and coordinate disclosure with you.
+
+## Scope
+
+- **In scope:** vulnerabilities in this SDK's source code.
+- **Out of scope:** issues in upstream dependencies (file those with the upstream maintainer), or issues in the AudD service or API itself (email **api@audd.io** with subject `AudD service: <summary>`).
+
+## Hardening practices
+
+This SDK never logs `api_token`, request bodies, or response bodies. The `onEvent` inspection hook receives request / response / exception lifecycle events with method, URL, HTTP status, elapsed time, and request_id — but never the token or payload bytes.
+

examples/custom_catalog_add.py

@@ -0,0 +1,24 @@
+"""Add a song to your private fingerprint catalog.
+
+NOTE: this is NOT music recognition — for that, use recognize() instead.
+This adds a song to YOUR private catalog so AudD can later identify it for
+YOUR account only.
+
+Run: AUDD_API_TOKEN=... python examples/custom_catalog_add.py https://my.song.mp3 42
+"""
+import os
+import sys
+
+from audd import AudD
+
+
+def main() -> None:
+    if len(sys.argv) != 3:
+        sys.exit("usage: custom_catalog_add.py <song_url> <audio_id>")
+    audd = AudD(api_token=os.environ["AUDD_API_TOKEN"])
+    audd.custom_catalog.add(audio_id=int(sys.argv[2]), source=sys.argv[1])
+    print("ok")
+
+
+if __name__ == "__main__":
+    main()

examples/recognize_enterprise.py

@@ -0,0 +1,25 @@
+"""Recognize music in a long file via the enterprise endpoint.
+
+Always pass `limit=` in dev to bound the chunk count and request cost.
+Run: AUDD_API_TOKEN=... python examples/recognize_enterprise.py https://example.mp3
+"""
+import os
+import sys
+
+from audd import AudD
+
+
+def main() -> None:
+    token = os.environ.get("AUDD_API_TOKEN")
+    if not token:
+        sys.exit("AUDD_API_TOKEN required")
+    if len(sys.argv) != 2:
+        sys.exit("usage: recognize_enterprise.py <url>")
+    audd = AudD(api_token=token)
+    matches = audd.recognize_enterprise(sys.argv[1], limit=5, accurate_offsets=True)
+    for m in matches:
+        print(f"{m.timecode}  {m.artist} — {m.title}  (score {m.score})")
+
+
+if __name__ == "__main__":
+    main()