Skip to content

Releases: StemSplit/stemsplit-python

v0.1.0 - initial release

21 May 23:33
@ParkNorth ParkNorth
v0.1.0
3e3e894

Choose a tag to compare

View all tags
v0.1.0 - initial release Latest
Latest

stemsplit-python v0.1.0 — initial release

First public release of the official Python SDK for the StemSplit hosted stem-separation API.

pip install stemsplit-python
from pathlib import Path
from stemsplit_python import StemSplit

client = StemSplit(api_key="sk_live_...")          # or set STEMSPLIT_API_KEY
job = client.jobs.create(audio=Path("song.mp3"), output_type="BOTH").wait()
job.download_all("./out/")

What ships in v0.1.0

  • Sync StemSplit client with sub-resources for every public endpoint: jobs, youtube_jobs, uploads, account, webhooks.
  • Killer ergonomics for the job lifecycle: JobHandle.wait(), .iter_progress(), .refresh(), .download_all(). Pass a Path / bytes / file-like to jobs.create(audio=...) and the SDK runs the presigned-URL upload dance for you.
  • YouTube jobs — client.youtube_jobs.create(url=...), same lifecycle helpers, surfaces video_title, video_duration, channel_name, and the full_audio output.
  • BPM and key detection typed on Job.audio_metadata and YouTubeJob.audio_metadata.
  • Webhook signature verification in stemsplit_python.webhooks — verify_and_parse(payload=..., signature=..., secret=...) returns a typed WebhookEvent and raises SignatureVerificationError on mismatch. Constant-time HMAC-SHA256.
  • Stripe-style error hierarchy mapping the API's documented error codes 1:1: BadRequestError (400), AuthenticationError (401), InsufficientCreditsError (402, with .required_seconds / .purchase_url), PermissionDeniedError (403), NotFoundError (404), RateLimitError (429, with .retry_after / .limit / .remaining / .reset_at), InternalServerError (5xx), plus logical JobFailedError / JobExpiredError / SignatureVerificationError.
  • Retries with Retry-After-aware backoff on 429 / 5xx for safe-to-replay verbs (default max_retries=3).
  • Rate-limit awareness — every response's X-RateLimit-* headers parsed and exposed via client.last_rate_limit.
  • Idempotency-Key passthrough on jobs.create, youtube_jobs.create, webhooks.create (lights up automatically once the server ships support).
  • pydantic v2 models — frozen, snake_case attrs aliased to camelCase wire fields, Literal unions for status / quality / format, extra="allow" so unknown server fields don't crash callers.
  • Three runtime dependencies only: httpx, pydantic, typing-extensions (Python 3.10 backport only). No PyTorch, no numpy, no native code.
  • Fully typed: py.typed shipped, mypy --strict clean.
  • 62 tests, ~92% line coverage, all respx-backed mocks.

Deferred

  • AsyncStemSplit — lands in v0.2 (the placeholder raises NotImplementedError with a pointer to the tracking issue).
  • job.cancel() — the API does not yet expose DELETE /jobs/{id}; honest omission, not a stub. Will land alongside the endpoint.
  • CLI — a separate stemsplit-cli add-on is planned for v0.2 so the SDK stays dependency-light.

Companion

Want to run inference locally without an API key? Install demucs-onnx — same model family, runs in pure ONNX Runtime.

Links

Assets 2
Loading