Initial release v1.3.0

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.9', '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

CHANGELOG.md

@@ -0,0 +1,88 @@
+# Changelog
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.3.0] - 2026-05-05
+
+Coordinated v1.3.0 stable release across the audd-sdks family. No breaking
+changes; the version bump signals API stability across all nine SDKs.
+
+The full v0.3.0 polish — env-var auto-pickup, streaming/preview helpers
+with metadata fallback, `onEvent` inspection hook, thread-safe token
+rotation, plus per-language work (JPMS module-info, Kotlin `Flow<LongpollEvent>`,
+Swift `Sendable` + DocC, .NET AOT/source-gen + `IServiceCollection`, Rust
+TLS feature flags + `Serialize`, PHP PSR-3 logger, Python `__repr__` +
+`pretty_print()`, Go `slog` example) is now the v1.3.0 baseline.
+
+## [0.3.0] - 2026-05-05
+
+### Added
+
+- **`RecognitionResult.__repr__` and `EnterpriseMatch.__repr__`** — useful one-line representations for logs / REPL: `<RecognitionResult artist='X' title='Y' timecode='00:56' song_link='https://lis.tn/abc'>`. Empty fields are omitted; `timecode` is always present (it's required server-side).
+- **`RecognitionResult.pretty_print()` / `EnterpriseMatch.pretty_print()`** — debug helper that writes the full model state (typed fields plus any forward-compat extras) as indented JSON to stdout (or a caller-supplied stream). Useful when you want to see exactly what came back over the wire.
+
+### Documentation
+
+- README opens with an explicit "thread-safe / safe for concurrent use" statement.
+
+## [0.2.1] - 2026-05-05
+
+### Improved
+
+- **`streaming_url(provider)` now falls back to the metadata block when `song_link` is non-lis.tn.** Previously returned `None` for YouTube `song_link` values; now picks the direct URL from `apple_music.url` / `spotify.external_urls.spotify` / `deezer.link` / `napster.href` when the corresponding metadata was requested via `return=`. Direct URLs are also now *preferred* over the lis.tn redirect when both paths resolve (no redirect = faster client-side load). YouTube as a provider has no metadata-block fallback (only the lis.tn redirect path).
+- `streaming_urls()` correspondingly returns more entries — every provider with either a direct URL or a lis.tn redirect available.
+
+## [0.2.0] - 2026-05-05
+
+DX polish — env-var auto-pickup, streaming/preview helpers, on_event inspection hook, thread-safe token rotation.
+
+### Added
+
+- **`AUDD_API_TOKEN` env-var fallback** (§7.11): `Audd()` / `AsyncAudd()` constructed without an explicit `api_token` now reads it from `os.environ.get("AUDD_API_TOKEN")`. Raises `ValueError` with a dashboard-link hint if both are missing.
+- **`RecognitionResult.streaming_url(provider)`** (§4.3): returns the `lis.tn` redirect URL for `spotify` / `apple_music` / `deezer` / `napster` / `youtube` (e.g. `https://lis.tn/abc?spotify` 302-redirects to the song's Spotify page). Returns `None` for non-lis.tn `song_link` values (e.g., YouTube ones).
+- **`RecognitionResult.streaming_urls()`** (§4.3): convenience dict of all five providers' redirect URLs.
+- **`RecognitionResult.preview_url()`** (§4.3): first available 30-second preview URL from `apple_music.previews[0].url` → `spotify.preview_url` → `deezer.preview`. Documented caveat about provider TOS.
+- Same `streaming_url` / `streaming_urls` / `thumbnail_url` helpers on `EnterpriseMatch`.
+- **`set_api_token(new_token)`** on `Audd` / `AsyncAudd` (§7.10): thread-safe token rotation via a `threading.Lock`. In-flight requests continue with the old token; subsequent requests use the new one. Validates non-empty.
+- **`on_event` inspection hook** on `Audd` / `AsyncAudd` (§7.7a): a callable receiving `AuddEvent` lifecycle events (kind=`request`/`response`/`exception`, method, url, request_id, http_status, elapsed_ms, error_code, extras). Off by default. Never logs the api_token or request body. Hook exceptions are swallowed at debug level so observability never breaks the request path.
+
+### Internal
+
+- 26 new regression tests (`tests/unit/test_v0_2_polish.py`) covering all four feature areas.
+
+## [0.1.1] - 2026-05-04
+
+Independent code review caught several issues. v0.1.1 fixes them before they propagate to the other 8 language SDKs being modeled on this implementation.
+
+### Fixed
+
+- **C1 — `prepare_source` now returns a per-attempt re-opener.** *Note: the reviewer flagged this as a "silent zero-byte upload on retry" bug, but verification (running the regression test against v0.1.0 source) showed that httpx auto-seeks file handles between `post()` calls, so audd-python v0.1.0 was actually correct.* The re-opener pattern is kept as **defense in depth**: it doesn't depend on the HTTP library's seeking behavior, raises cleanly on unseekable streams (rather than silently sending an empty body), and matches the mandatory pattern other SDKs need (their HTTP libraries may not auto-seek).
+- **C2 — `advanced.find_lyrics` was using READ retry policy.** Fixed to use RECOGNITION (the lyrics endpoint is metered; the spec §7.1 cost-aware retry policy explicitly groups it with `recognize`).
+- **C3 — Code 51 (deprecation warning) was raising unconditionally.** Per spec §6.5, when the server returns code 51 with a usable `result`, the SDK now emits a `DeprecationWarning` and returns the result. Only raises if `result` is absent.
+- **S2 — Non-JSON HTTP errors mapped to `AuddSerializationError`.** A 502 with an HTML body now correctly raises `AuddServerError` preserving the HTTP status; `AuddSerializationError` is reserved for 2xx-with-bad-JSON.
+- **S5 — `LongpollConsumer` silently swallowed HTTP errors.** A 401/403/500 returned `{}` and the consumer looped forever, especially painful in browsers. Now non-2xx raises `AuddServerError`; JSON decode failures raise `AuddSerializationError`.
+- **S6 — `LongpollConsumer` had no retry/timeout knobs.** Per spec §4.1 ("same retry, timeout, transport configurability as the authenticated client"), now accepts `max_retries` and `backoff_factor` and applies READ-class retries on connection failures + 5xx.
+- **S9 — Confusing `FileNotFoundError` for typo'd URLs.** A string source that's neither HTTP(S) nor an existing path now raises `TypeError` with a hint about the URL prefix.
+
+### Added
+
+- **Context-manager protocol** on `Audd`, `AsyncAudd`, `LongpollConsumer`, `AsyncLongpollConsumer` — `with Audd(...) as audd:` / `async with AsyncAudd(...) as audd:` now work.
+
+### Tests
+
+- Added 16 regression tests covering each finding (`tests/unit/test_review_fixes.py`, `tests/unit/test_review_fixes_longpoll.py`). Total: 108 unit + contract tests passing.
+
+## [0.1.0] - 2026-05-04
+
+### Added
+- Sync (`Audd`) and async (`AsyncAudd`) clients with parity for every capability.
+- `recognize(source, *, return_, market, timeout)` — auto-detects URL / path / file-like / bytes sources.
+- `recognize_enterprise(source, ...)` with 1-hour read timeout default.
+- `streams.*` namespace: `set_callback_url(url, return_metadata=...)`, `get_callback_url`, `add`, `set_url`, `delete`, `list`, `longpoll(category, *, skip_callback_check=False)` with default-on preflight, plus pure helpers `derive_longpoll_category` and `parse_callback`.
+- `custom_catalog.add(audio_id, source)` — namespaced with NOT-for-recognition warning docstring; 904 errors raise `AuddCustomCatalogAccessError`.
+- `advanced.*` namespace: `find_lyrics(query)`, `raw_request(method, params)` escape hatch.
+- Tokenless `LongpollConsumer` / `AsyncLongpollConsumer` for browser/widget contexts.
+- Forward-compatible Pydantic v2 models with `extra="allow"` on every type.
+- Full error hierarchy mapped to the 25+ AudD error codes.
+- Cost-aware retry policy: read endpoints retry 408/429/5xx; recognition endpoints don't retry post-upload read timeouts (cost protection); mutating endpoints retry only pre-upload connection failures.
+- CI: ruff + mypy strict + pytest matrix on Py 3.9–3.13 (`ci.yml`); contract tests on push/PR + daily cron + `openapi-updated` repository_dispatch (`contract.yml`); tag-triggered PyPI publishing with Sigstore attestation (`release.yml`).

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,146 @@
+# 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.
+
+`Audd` and `AsyncAudd` are **safe for concurrent use** — share one instance across threads or asyncio tasks. Token rotation via `set_api_token(...)` is thread-safe; in-flight requests continue with the old token, subsequent requests use the new one.
+
+## 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 real-time stream recognition | `audd.streams.add(url, radio_id)` etc. |
+| Long-poll for stream events | `audd.streams.longpoll(category)` |
+| Long-poll without exposing your token | `LongpollConsumer(category).iterate()` |
+
+`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.
+
+## 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.
+
+## 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 lyrics search and a generic raw-request escape hatch:
+
+```python
+hits = audd.advanced.find_lyrics("rule the world")
+raw = audd.advanced.raw_request("someNewMethod", {"q": "x"})
+```
+
+## Tokenless longpoll
+
+For browser widgets and other contexts where shipping the api_token would leak it:
+
+```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)
+```
+
+## 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,3 @@
+# Security Policy
+
+To report a vulnerability, please email **api@audd.io**. We aim to respond within 2 business days. Do not open public GitHub issues for security reports.