Initial release: stemsplit-python v0.1.0

Synchronous Python SDK for the StemSplit stem-separation API.

- Resources: jobs, youtube_jobs, account, webhooks, uploads
- Stripe-style error hierarchy with documented error codes
- Webhook signature verification (verify_and_parse)
- BPM and key detection on Job.audio_metadata
- pydantic v2 models, mypy --strict clean, py.typed shipped
- Three runtime dependencies: httpx, pydantic, typing-extensions
- 62 tests, ~92 percent line coverage on the SDK code

Author: StemSplit

.github/workflows/release.yml

@@ -0,0 +1,36 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Build sdist + wheel
+        run: uv build
+
+      - name: Publish to PyPI
+        run: uv publish
+        env:
+          UV_PUBLISH_TOKEN: ${{ secrets.UV_PUBLISH_TOKEN }}
+
+      - name: Upload distribution artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/

.github/workflows/test.yml

@@ -0,0 +1,40 @@
+name: Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    name: ${{ matrix.python-version }} on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dev dependencies
+        run: uv sync --extra dev
+
+      - name: Lint (ruff)
+        run: |
+          uv run ruff check src tests
+          uv run ruff format --check src tests
+
+      - name: Type-check (mypy)
+        run: uv run mypy src/stemsplit_python
+
+      - name: Run tests
+        run: uv run pytest -q

.gitignore

@@ -0,0 +1,18 @@
+.venv/
+__pycache__/
+*.pyc
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+build/
+dist/
+.coverage
+htmlcov/
+.env
+.env.local
+
+out/
+artifacts/
+
+.tmp_*.py

.python-version

@@ -0,0 +1 @@
+3.11

CHANGELOG.md

@@ -0,0 +1,85 @@
+# Changelog
+
+All notable changes to `stemsplit-python` are documented here. 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/).
+
+## [0.1.0] - 2026-05-21 — Initial release: sync SDK for the StemSplit API
+
+First public release. Synchronous Python client for the official
+[StemSplit](https://stemsplit.io) hosted stem-separation API.
+
+### Added
+
+- **`StemSplit` sync client** (`AsyncStemSplit` placeholder pointing at
+  v0.2). Bearer-auth, env-var key default (`STEMSPLIT_API_KEY`),
+  configurable base URL, soft `sk_live_` prefix validation.
+- **Resources for every public endpoint:**
+  - `client.jobs` — create (file / bytes / file-like / `source_url` /
+    `upload_key`), get, list, `iter_all`, with the killer ergonomic
+    layer: `JobHandle.wait()`, `.iter_progress()`, `.refresh()`,
+    `.download_all()`.
+  - `client.youtube_jobs` — create from YouTube URL, get, list,
+    `iter_all`, same `wait()` / `download_all()` ergonomics. Surfaces
+    video metadata (`video_title`, `video_duration`, `channel_name`,
+    `youtube_url`) and the YouTube-specific `full_audio` output.
+  - `client.uploads` — presigned-URL helpers (`create_ticket`,
+    `upload_bytes`) for the rare case where you want to manage uploads
+    yourself.
+  - `client.account` — `balance()` / `get()` returning typed `Balance`.
+  - `client.webhooks` — `create`, `list`, `delete`. Capture `secret`
+    from `create()`; the API never returns it again.
+- **Webhook signature verification** (`stemsplit_python.webhooks`):
+  `verify_signature` for raw-bytes verification and `verify_and_parse`
+  that returns a typed `WebhookEvent`. Constant-time HMAC-SHA256
+  comparison, accepts both `sha256=<hex>` and bare hex.
+- **Stripe-style error hierarchy** mapping API responses 1:1 to typed
+  exceptions: `BadRequestError` (400), `AuthenticationError` (401),
+  `InsufficientCreditsError` (402, with `.required_seconds` /
+  `.purchase_url`), `PermissionDeniedError` (403), `NotFoundError`
+  (404), `ConflictError` (409), `UnprocessableEntityError` (422),
+  `RateLimitError` (429, with `.retry_after` / `.limit` /
+  `.remaining` / `.reset_at`), `InternalServerError` (5xx). Plus
+  logical errors `JobFailedError`, `JobExpiredError`,
+  `SignatureVerificationError`.
+- **Retries with backoff** on `429` and `5xx` for safe-to-replay verbs
+  (default `max_retries=3`). Honors `Retry-After` when present.
+- **Rate-limit awareness:** parses `X-RateLimit-*` headers on every
+  response, exposed as `client.last_rate_limit`.
+- **Idempotency-Key passthrough** on `jobs.create`, `youtube_jobs.create`,
+  `webhooks.create`. Forwarded as a header today; lights up
+  automatically when the API ships server-side support.
+- **Audio metadata (BPM / key)** on completed jobs: `Job.audio_metadata`
+  and `YouTubeJob.audio_metadata` typed as `AudioMetadata { bpm, key }`.
+  Both fields are optional and degrade gracefully if the analysis
+  doesn't run.
+- **Pydantic v2 models** with `frozen=True`, `extra="allow"` (forward-
+  compatible against new server fields), snake_case Python attributes
+  aliased to the camelCase wire fields, and `Literal[...]` unions for
+  every status / quality / format value (no `enum.Enum`).
+- **Typing:** `py.typed` marker shipped, `mypy --strict` clean.
+- **Three runtime dependencies only:** `httpx`, `pydantic`,
+  `typing-extensions` (Python 3.10 backport only). No PyTorch, no
+  numpy, no native code.
+- **Snapshot of the live OpenAPI 3.1 spec** at
+  `openapi/openapi.json` so future versions can diff API drift.
+
+### Tested
+
+- 62 tests, ~92 % line coverage, all `respx`-backed mocks. Full status-
+  code → exception matrix, retry behavior, end-to-end
+  `jobs.create(audio=Path)` chain, `wait()` happy / failed / timeout
+  paths, webhook signature round-trip + tamper detection, and YouTube
+  job lifecycle.
+
+### Deferred
+
+- **`AsyncStemSplit`** — lands in v0.2. Constructing it today raises
+  `NotImplementedError` with a pointer at the tracking issue.
+- **`job.cancel()`** — the API does not yet expose `DELETE /jobs/{id}`;
+  honest omission rather than a no-op stub. Will land alongside the
+  endpoint.
+- **CLI** — a separate `stemsplit-cli` add-on is planned for v0.2 so
+  the SDK stays dependency-light.
+
+[0.1.0]: https://github.com/StemSplit/stemsplit-python/releases/tag/v0.1.0

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 StemSplit
+
+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.