vocalstack 1.0.0a0__tar.gz → 1.0.0a2__tar.gz

vocalstack-1.0.0a2/.gitignore

@@ -0,0 +1,8 @@
+# Packaging: hatchling reads the nearest .gitignore when it builds the sdist.
+.venv/
+dist/
+build/
+__pycache__/
+*.egg-info/
+.env
+.env.*

vocalstack-1.0.0a2/LICENSE

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

{vocalstack-1.0.0a0 → vocalstack-1.0.0a2}/PKG-INFO

@@ -1,9 +1,10 @@
 Metadata-Version: 2.5
 Name: vocalstack
-Version: 1.0.0a0
+Version: 1.0.0a2
 Summary: VocalStack speech API SDK (asyncio): one client grouped by resource, typed models from the API contract, realtime WebSocket streaming.
 Project-URL: Homepage, https://vocalstack.com
-License: MIT
+License-Expression: MIT
+License-File: LICENSE
 Requires-Python: >=3.10
 Requires-Dist: httpx>=0.27
 Requires-Dist: pydantic>=2.7
@@ -17,6 +18,8 @@ The VocalStack speech API for Python (3.10 or newer, asyncio): one client,
 are pydantic models generated from the API's one OpenAPI document
 (`/v1/openapi.json`), with snake_case attributes.
 
+Read more about the [VocalStack Python SDK](https://vocalstack.com/#developers) and our other SDKs on the [VocalStack website](https://vocalstack.com/).
+
 ```python
 import asyncio, os
 from vocalstack import VocalStack
@@ -32,22 +35,27 @@ async def main():
 asyncio.run(main())
 ```
 
-<!-- sdk-docs: generated by `make sdk-docs` from the guides; edit those, not this -->
+<!-- sdk-docs: generated from the VocalStack API guides; edits here are overwritten -->
 
 ## Install
 
-Not on PyPI yet. The API serves its own builds to every account: [https://api.vocalstack.com/docs/guides/quickstart.md](https://api.vocalstack.com/docs/guides/quickstart.md) has the install command for the current build (it sends your API key to that host only).
+```sh
+pip install vocalstack
+```
 
 ## Guides
 
 - [Quickstart](https://github.com/vocalstack/python-sdk/blob/main/docs/quickstart.md): An API key, the SDK, and your first transcript in a dozen lines.
 - [Transcribe a file](https://github.com/vocalstack/python-sdk/blob/main/docs/transcribe-a-file.md): Upload a file, wait for its job, read the transcript and export it. Asynchronous; nothing to keep open.
-- [Transcribe a link](https://github.com/vocalstack/python-sdk/blob/main/docs/transcribe-a-link.md): The server fetches a public URL or a YouTube video, then transcribes it like a file. Asynchronous, with a fetch phase first.
+- [Transcribe a link](https://github.com/vocalstack/python-sdk/blob/main/docs/transcribe-a-link.md): The server fetches a public URL, a YouTube video or a recording on a video or audio site, then transcribes it like a file. Asynchronous, with a fetch phase first.
+- [Transcribe a batch of files](https://github.com/vocalstack/python-sdk/blob/main/docs/transcribe-a-batch.md): Send many files or links as one batch, start it once, and read every transcript when it is done. Cheaper than one transcription per file.
+- [Search your transcriptions](https://github.com/vocalstack/python-sdk/blob/main/docs/search-transcriptions.md): Find transcriptions by words in their name or link, site, language, kind, tag and date, keep the shared ones, and play each with its share code.
 - [Stream a microphone](https://github.com/vocalstack/python-sdk/blob/main/docs/stream-a-microphone.md): Live audio in, transcript events out, over one WebSocket. Drafts replace the live tail; commits append.
 - [Stream a file at full speed](https://github.com/vocalstack/python-sdk/blob/main/docs/stream-a-file.md): Send a file's bytes through a realtime session and read the transcript as fast as the server makes it. Nothing is stored.
 - [Go live](https://github.com/vocalstack/python-sdk/blob/main/docs/go-live.md): Publish live audio to a stored transcription, and put it on a broadcast link listeners open. Control is HTTP; audio is one WebSocket.
 - [Listen](https://github.com/vocalstack/python-sdk/blob/main/docs/listen.md): Follow a recording as it happens, in any language: subscribe, catch up from a snapshot, then apply live frames in order.
 - [Live translation and spoken translations](https://github.com/vocalstack/python-sdk/blob/main/docs/translation-and-voices.md): Translate a stream as it is spoken, and have each translated sentence spoken back in a voice. Text frames and audio clips, over the same socket.
+- [Connect an app with one click](https://github.com/vocalstack/python-sdk/blob/main/docs/connect-an-app.md): Let the people who use your app connect their VocalStack account with one Authenticate click — OAuth 2.0 authorization code with PKCE, where the access token is an API key — instead of pasting a key.
 - [Errors, retries and limits](https://github.com/vocalstack/python-sdk/blob/main/docs/errors-and-limits.md): One error envelope everywhere; what to retry (429, 503 unavailable) and how to make a retry safe (Idempotency-Key); credit, plan limits and the 402s.
 
 <!-- /sdk-docs -->
@@ -61,6 +69,7 @@ Not on PyPI yet. The API serves its own builds to every account: [https://api.vo
 | transcription | a file, link, microphone or stream, transcribed and stored | `vs.transcriptions` |
 | recording | one take inside a broadcast or a transcription | `vs.recordings` |
 | job | a file or link recording's transcription work | `vs.jobs` |
+| batch | many files transcribed together, for less than one transcription each | `vs.batches` |
 
 The other groups: `vs.corrections`, `vs.share_links`, `vs.voices`,
 `vs.search`, `vs.me`, `vs.languages`, `vs.rtmp`, `vs.events`, `vs.meta`.
@@ -113,5 +122,5 @@ async with VocalStack(api_key=key) as vs:
 `status`, `retryable`, `details` (quota numbers, code suggestions), `headers`
 and `retry_after`.
 
-Verified against the language-agnostic conformance suite (`make conformance`)
-and against a running API (`make sdk-e2e`). For agents: `SKILL.md`.
+Verified against a language-agnostic conformance suite shared by every
+VocalStack SDK and against a running API. For agents: `SKILL.md`.

{vocalstack-1.0.0a0 → vocalstack-1.0.0a2}/README.md

@@ -5,6 +5,8 @@ The VocalStack speech API for Python (3.10 or newer, asyncio): one client,
 are pydantic models generated from the API's one OpenAPI document
 (`/v1/openapi.json`), with snake_case attributes.
 
+Read more about the [VocalStack Python SDK](https://vocalstack.com/#developers) and our other SDKs on the [VocalStack website](https://vocalstack.com/).
+
 ```python
 import asyncio, os
 from vocalstack import VocalStack
@@ -20,22 +22,27 @@ async def main():
 asyncio.run(main())
 ```
 
-<!-- sdk-docs: generated by `make sdk-docs` from the guides; edit those, not this -->
+<!-- sdk-docs: generated from the VocalStack API guides; edits here are overwritten -->
 
 ## Install
 
-Not on PyPI yet. The API serves its own builds to every account: [https://api.vocalstack.com/docs/guides/quickstart.md](https://api.vocalstack.com/docs/guides/quickstart.md) has the install command for the current build (it sends your API key to that host only).
+```sh
+pip install vocalstack
+```
 
 ## Guides
 
 - [Quickstart](https://github.com/vocalstack/python-sdk/blob/main/docs/quickstart.md): An API key, the SDK, and your first transcript in a dozen lines.
 - [Transcribe a file](https://github.com/vocalstack/python-sdk/blob/main/docs/transcribe-a-file.md): Upload a file, wait for its job, read the transcript and export it. Asynchronous; nothing to keep open.
-- [Transcribe a link](https://github.com/vocalstack/python-sdk/blob/main/docs/transcribe-a-link.md): The server fetches a public URL or a YouTube video, then transcribes it like a file. Asynchronous, with a fetch phase first.
+- [Transcribe a link](https://github.com/vocalstack/python-sdk/blob/main/docs/transcribe-a-link.md): The server fetches a public URL, a YouTube video or a recording on a video or audio site, then transcribes it like a file. Asynchronous, with a fetch phase first.
+- [Transcribe a batch of files](https://github.com/vocalstack/python-sdk/blob/main/docs/transcribe-a-batch.md): Send many files or links as one batch, start it once, and read every transcript when it is done. Cheaper than one transcription per file.
+- [Search your transcriptions](https://github.com/vocalstack/python-sdk/blob/main/docs/search-transcriptions.md): Find transcriptions by words in their name or link, site, language, kind, tag and date, keep the shared ones, and play each with its share code.
 - [Stream a microphone](https://github.com/vocalstack/python-sdk/blob/main/docs/stream-a-microphone.md): Live audio in, transcript events out, over one WebSocket. Drafts replace the live tail; commits append.
 - [Stream a file at full speed](https://github.com/vocalstack/python-sdk/blob/main/docs/stream-a-file.md): Send a file's bytes through a realtime session and read the transcript as fast as the server makes it. Nothing is stored.
 - [Go live](https://github.com/vocalstack/python-sdk/blob/main/docs/go-live.md): Publish live audio to a stored transcription, and put it on a broadcast link listeners open. Control is HTTP; audio is one WebSocket.
 - [Listen](https://github.com/vocalstack/python-sdk/blob/main/docs/listen.md): Follow a recording as it happens, in any language: subscribe, catch up from a snapshot, then apply live frames in order.
 - [Live translation and spoken translations](https://github.com/vocalstack/python-sdk/blob/main/docs/translation-and-voices.md): Translate a stream as it is spoken, and have each translated sentence spoken back in a voice. Text frames and audio clips, over the same socket.
+- [Connect an app with one click](https://github.com/vocalstack/python-sdk/blob/main/docs/connect-an-app.md): Let the people who use your app connect their VocalStack account with one Authenticate click — OAuth 2.0 authorization code with PKCE, where the access token is an API key — instead of pasting a key.
 - [Errors, retries and limits](https://github.com/vocalstack/python-sdk/blob/main/docs/errors-and-limits.md): One error envelope everywhere; what to retry (429, 503 unavailable) and how to make a retry safe (Idempotency-Key); credit, plan limits and the 402s.
 
 <!-- /sdk-docs -->
@@ -49,6 +56,7 @@ Not on PyPI yet. The API serves its own builds to every account: [https://api.vo
 | transcription | a file, link, microphone or stream, transcribed and stored | `vs.transcriptions` |
 | recording | one take inside a broadcast or a transcription | `vs.recordings` |
 | job | a file or link recording's transcription work | `vs.jobs` |
+| batch | many files transcribed together, for less than one transcription each | `vs.batches` |
 
 The other groups: `vs.corrections`, `vs.share_links`, `vs.voices`,
 `vs.search`, `vs.me`, `vs.languages`, `vs.rtmp`, `vs.events`, `vs.meta`.
@@ -101,5 +109,5 @@ async with VocalStack(api_key=key) as vs:
 `status`, `retryable`, `details` (quota numbers, code suggestions), `headers`
 and `retry_after`.
 
-Verified against the language-agnostic conformance suite (`make conformance`)
-and against a running API (`make sdk-e2e`). For agents: `SKILL.md`.
+Verified against a language-agnostic conformance suite shared by every
+VocalStack SDK and against a running API. For agents: `SKILL.md`.

{vocalstack-1.0.0a0/skills/vocalstack → vocalstack-1.0.0a2}/SKILL.md

@@ -20,6 +20,9 @@ labels and translation. The `vocalstack` package has one asyncio client,
 - A **job** is a file or link recording's transcription work:
   `await vs.jobs.wait(recording_id)` polls it until it is `done` or `failed`
   (`on_progress=lambda job: ...` sees each read: `job.state`, `job.progress.pct`).
+- A **batch** is many files transcribed together for less than one
+  transcription each: `vs.batches.create()`, `add_file`/`add_url` per file,
+  `start`, then `wait` (section 6).
 - A **broadcast** is a link listeners open to follow a live recording.
 - A **realtime session** (`vs.realtime`) is a socket you stream audio into and
   read the transcript from. Nothing is stored. "Session" means only this.
@@ -31,16 +34,6 @@ python3 -m venv .venv && . .venv/bin/activate   # system Pythons refuse a bare p
 pip install vocalstack                           # Python 3.10 or newer
 ```
 
-Before the package is published, any account installs
-the private build its environment serves: the API reference's Install section
-(`<base>/docs`, or Developers -> API reference in the app) and `<base>/sdk/latest`
-give the exact commands, which send `VOCALSTACK_API_KEY` to that host only.
-Or install it from a local checkout of the repository:
-
-```sh
-pip install -e /absolute/path/to/transcribe/sdks/python
-```
-
 Live transcription (program 4) also needs `ffmpeg` on PATH.
 
 Speaker numbers start at 0. A speaker of `-1` means speaker labels were off
@@ -57,8 +50,7 @@ for that transcription, so print the text without a speaker.
 - Scopes: `read` (read transcripts, search, export), `write` and
   `recordings:publish` (create transcriptions, stream live audio), or `*`.
 - Base URL: `https://api.vocalstack.com` (the default). Override it with
-  `VOCALSTACK_BASE_URL`: `http://127.0.0.1:8090` for a local server,
-  `https://api.e2e.vocalstack.com` for e2e.
+  `VOCALSTACK_BASE_URL` (for example, a local or staging server).
 
 Every program below opens the client the same way, inside `async def main()`
 run with `asyncio.run(main())` (a `None` base URL means the default):
@@ -105,7 +97,9 @@ async def main(path):  # mp3, wav, flac, ogg, m4a, mp4 ...
     async with VocalStack(os.environ.get("VOCALSTACK_BASE_URL"), api_key=os.environ["VOCALSTACK_API_KEY"]) as vs:
         tx = await vs.transcriptions.create(
             file=path,  # a path, bytes, or an open binary file
-            settings={"spokenLanguage": "en", "speakerLabels": "on"},  # both optional; "auto" | "on" | "off"
+            settings={"spokenLanguage": "en", "speakerLabels": "on"},  # both optional; "auto" (default) | "on" | "off"
+            # Off unless asked for: settings summary, title, summaryTranslations,
+            # voice (spoken translations), and share_link=True (a public share link).
         )
         job = await vs.jobs.wait(tx.job.recording_id)
         if job.state != "done":
@@ -191,6 +185,43 @@ async def main(q):  # 2+ characters
 asyncio.run(main(sys.argv[1]))
 ```
 
+By meaning, in any language, even with none of the words (vector search). Each
+hit's `passage` is its whole paragraph: give the passages to your own model as
+context to answer questions about what was said (RAG). Pay as you go counts 60
+an hour (`allowance`); Premium and Enterprise have no limit.
+
+```python
+res = await vs.search.vector("how much does housing cost")
+for h in res.hits:
+    print(f"{h.similarity:.2f}", h.passage.media_start, h.passage.text)
+```
+
+## 6. A batch of files
+
+Many files at once cost less as a batch: one create, one minimum charge for
+the whole batch. Its files get transcripts, exports and speaker labels (when
+`settings.speakerLabels` asks), never a summary, title, share link or voices.
+
+```python
+import asyncio, os, sys
+from vocalstack import VocalStack
+
+async def main(paths):
+    async with VocalStack(os.environ.get("VOCALSTACK_BASE_URL"), api_key=os.environ["VOCALSTACK_API_KEY"]) as vs:
+        batch = await vs.batches.create(name="Interviews", settings={"spokenLanguage": "en"})
+        for path in paths:
+            await vs.batches.add_file(batch.id, file=path)  # or add_url(batch.id, url)
+        await vs.batches.start(batch.id)
+        done = await vs.batches.wait(batch.id)  # done (or stopped); check done.counts.failed
+        for tx in done.files or []:
+            if tx.job and tx.job.state == "done":
+                snap = await vs.recordings.transcript(tx.job.recording_id)
+                print(tx.name, " ".join(s.text for s in snap.sentences))
+        # vs.batches.export(batch.id, "srt") is every finished transcript in one zip.
+
+asyncio.run(main(sys.argv[1:]))
+```
+
 ## Errors
 
 A failed call raises `vocalstack.VocalStackError` with `.code`, `.message`,
@@ -203,8 +234,9 @@ its `Retry-After`, twice by default (`max_retries` on the client).
 |---|---|---|
 | 401 | `invalid_token`, `key_expired`, `key_revoked` | Check `VOCALSTACK_API_KEY`. Use the replacement key, or create a new one. |
 | 403 | `forbidden` | Usually a missing scope: the message names it, and `e.headers["www-authenticate"]` lists the scopes the route needs. A suspended key or account gets `suspended`. |
-| 402 | `insufficient_credit` | The account's credit is out. `details`: `balance`, `plan`, `topUpUrl`, and `required` when the cost was known up front. Add credit; `await vs.billing.get()` shows the balance. |
-| 409 | `payment_method_required` | Auto top-up (`vs.billing.set_auto_top_up`) and the portal (`vs.billing.portal()`) need a payment first (`vs.billing.create_checkout(kind="topup", amount=25, accept_terms=True, waive_withdrawal=True)` opens one; a signed-in person's token, never an API key). |
+| 403 | `terms_acceptance_required` | The account has not accepted the current Terms of Service and Privacy Policy: someone signs in to the Dashboard and accepts them (an organisation's keys work once an owner or admin has). Not retryable until then. |
+| 402 | `insufficient_credit` | The account's credit is out, or does not cover the transcription: every transcription is billed at least the plan's minimum (`rates.minimumSeconds`, 5 minutes). `details`: `balance`, `plan`, `topUpUrl`, and `required` when the cost was known up front. Add credit; `await vs.billing.get()` shows the balance. |
+| 409 | `payment_method_required` | Auto top-up (`vs.billing.set_auto_top_up`) and the portal (`vs.billing.portal()`) need a payment first (`vs.billing.create_checkout(kind="topup", amount=25, accept_terms=True)` opens one; a signed-in person's token, never an API key). |
 | 402 | `quota_exceeded` | The plan's transcriptions-at-once limit is reached. `details`: `metric` (`concurrent_transcriptions`), `limit`, `used`, `plan`, `topUpUrl`. |
 | 429 | `rate_limited` | Retried automatically; if it still fails, wait `e.retry_after` seconds. Every response carries `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset`. |
 | 503 | `unavailable` | The service is waking (its database was asleep). Retried automatically after `Retry-After` (2 s) on calls that are safe to repeat: GET, HEAD, DELETE, or any call with `idempotency_key=`. A create without a key is not retried: retry it yourself, with an `idempotency_key` so it cannot run twice. A realtime socket refused this way raises `unavailable`; a bare 503 there is `capacity_exceeded`. |
@@ -225,7 +257,8 @@ except VocalStackError as e:
 - The other groups: `vs.transcriptions` (`list`, `get`, `update`, `archive`,
   `restore`, `purge`, `list_share_links`, `create_share_link`), `vs.recordings`
   (`get`, `summarize`, `summary`, `translation`, `audio_url`, `subscribe`),
-  `vs.corrections`, `vs.share_links`, `vs.voices`, `vs.broadcasts`,
+  `vs.batches` (`create`, `add_file`, `add_url`, `start`, `wait`, `get`, `list`,
+  `export`, `stop`, `delete`), `vs.corrections`, `vs.share_links`, `vs.voices`, `vs.broadcasts`,
   `vs.me` (`get`, `usage`), `vs.languages`, `vs.rtmp`, `vs.events`, `vs.meta`.
   Each method is its operation's name in the OpenAPI document, in snake_case
   (`transcriptions.create` is `POST /v1/transcriptions`).

{vocalstack-1.0.0a0 → vocalstack-1.0.0a2}/pyproject.toml

@@ -1,13 +1,14 @@
 [build-system]
-requires = ["hatchling"]
+requires = ["hatchling>=1.27"]
 build-backend = "hatchling.build"
 
 [project]
 name = "vocalstack"
-version = "1.0.0a0"
+version = "1.0.0a2"
 description = "VocalStack speech API SDK (asyncio): one client grouped by resource, typed models from the API contract, realtime WebSocket streaming."
 readme = "README.md"
-license = { text = "MIT" }
+license = "MIT"
+license-files = ["LICENSE"]
 requires-python = ">=3.10"
 dependencies = [
     "httpx>=0.27",
@@ -21,11 +22,8 @@ Homepage = "https://vocalstack.com"
 [tool.hatch.build.targets.wheel]
 packages = ["src/vocalstack"]
 
-# The Agent Skill ships inside the package (site-packages/vocalstack/SKILL.md)
-# so an agent can find it next to the code.
 [tool.hatch.build.targets.wheel.force-include]
 "SKILL.md" = "vocalstack/SKILL.md"
 
-# An explicit list: nothing else from the repository goes into the sdist.
 [tool.hatch.build.targets.sdist]
-only-include = ["src/vocalstack", "README.md", "SKILL.md", "skills", "pyproject.toml"]
+only-include = ["src/vocalstack", "LICENSE", "README.md", "SKILL.md", "skills", "pyproject.toml"]

{vocalstack-1.0.0a0 → vocalstack-1.0.0a2/skills/vocalstack}/SKILL.md

@@ -20,6 +20,9 @@ labels and translation. The `vocalstack` package has one asyncio client,
 - A **job** is a file or link recording's transcription work:
   `await vs.jobs.wait(recording_id)` polls it until it is `done` or `failed`
   (`on_progress=lambda job: ...` sees each read: `job.state`, `job.progress.pct`).
+- A **batch** is many files transcribed together for less than one
+  transcription each: `vs.batches.create()`, `add_file`/`add_url` per file,
+  `start`, then `wait` (section 6).
 - A **broadcast** is a link listeners open to follow a live recording.
 - A **realtime session** (`vs.realtime`) is a socket you stream audio into and
   read the transcript from. Nothing is stored. "Session" means only this.
@@ -31,16 +34,6 @@ python3 -m venv .venv && . .venv/bin/activate   # system Pythons refuse a bare p
 pip install vocalstack                           # Python 3.10 or newer
 ```
 
-Before the package is published, any account installs
-the private build its environment serves: the API reference's Install section
-(`<base>/docs`, or Developers -> API reference in the app) and `<base>/sdk/latest`
-give the exact commands, which send `VOCALSTACK_API_KEY` to that host only.
-Or install it from a local checkout of the repository:
-
-```sh
-pip install -e /absolute/path/to/transcribe/sdks/python
-```
-
 Live transcription (program 4) also needs `ffmpeg` on PATH.
 
 Speaker numbers start at 0. A speaker of `-1` means speaker labels were off
@@ -57,8 +50,7 @@ for that transcription, so print the text without a speaker.
 - Scopes: `read` (read transcripts, search, export), `write` and
   `recordings:publish` (create transcriptions, stream live audio), or `*`.
 - Base URL: `https://api.vocalstack.com` (the default). Override it with
-  `VOCALSTACK_BASE_URL`: `http://127.0.0.1:8090` for a local server,
-  `https://api.e2e.vocalstack.com` for e2e.
+  `VOCALSTACK_BASE_URL` (for example, a local or staging server).
 
 Every program below opens the client the same way, inside `async def main()`
 run with `asyncio.run(main())` (a `None` base URL means the default):
@@ -105,7 +97,9 @@ async def main(path):  # mp3, wav, flac, ogg, m4a, mp4 ...
     async with VocalStack(os.environ.get("VOCALSTACK_BASE_URL"), api_key=os.environ["VOCALSTACK_API_KEY"]) as vs:
         tx = await vs.transcriptions.create(
             file=path,  # a path, bytes, or an open binary file
-            settings={"spokenLanguage": "en", "speakerLabels": "on"},  # both optional; "auto" | "on" | "off"
+            settings={"spokenLanguage": "en", "speakerLabels": "on"},  # both optional; "auto" (default) | "on" | "off"
+            # Off unless asked for: settings summary, title, summaryTranslations,
+            # voice (spoken translations), and share_link=True (a public share link).
         )
         job = await vs.jobs.wait(tx.job.recording_id)
         if job.state != "done":
@@ -191,6 +185,43 @@ async def main(q):  # 2+ characters
 asyncio.run(main(sys.argv[1]))
 ```
 
+By meaning, in any language, even with none of the words (vector search). Each
+hit's `passage` is its whole paragraph: give the passages to your own model as
+context to answer questions about what was said (RAG). Pay as you go counts 60
+an hour (`allowance`); Premium and Enterprise have no limit.
+
+```python
+res = await vs.search.vector("how much does housing cost")
+for h in res.hits:
+    print(f"{h.similarity:.2f}", h.passage.media_start, h.passage.text)
+```
+
+## 6. A batch of files
+
+Many files at once cost less as a batch: one create, one minimum charge for
+the whole batch. Its files get transcripts, exports and speaker labels (when
+`settings.speakerLabels` asks), never a summary, title, share link or voices.
+
+```python
+import asyncio, os, sys
+from vocalstack import VocalStack
+
+async def main(paths):
+    async with VocalStack(os.environ.get("VOCALSTACK_BASE_URL"), api_key=os.environ["VOCALSTACK_API_KEY"]) as vs:
+        batch = await vs.batches.create(name="Interviews", settings={"spokenLanguage": "en"})
+        for path in paths:
+            await vs.batches.add_file(batch.id, file=path)  # or add_url(batch.id, url)
+        await vs.batches.start(batch.id)
+        done = await vs.batches.wait(batch.id)  # done (or stopped); check done.counts.failed
+        for tx in done.files or []:
+            if tx.job and tx.job.state == "done":
+                snap = await vs.recordings.transcript(tx.job.recording_id)
+                print(tx.name, " ".join(s.text for s in snap.sentences))
+        # vs.batches.export(batch.id, "srt") is every finished transcript in one zip.
+
+asyncio.run(main(sys.argv[1:]))
+```
+
 ## Errors
 
 A failed call raises `vocalstack.VocalStackError` with `.code`, `.message`,
@@ -203,8 +234,9 @@ its `Retry-After`, twice by default (`max_retries` on the client).
 |---|---|---|
 | 401 | `invalid_token`, `key_expired`, `key_revoked` | Check `VOCALSTACK_API_KEY`. Use the replacement key, or create a new one. |
 | 403 | `forbidden` | Usually a missing scope: the message names it, and `e.headers["www-authenticate"]` lists the scopes the route needs. A suspended key or account gets `suspended`. |
-| 402 | `insufficient_credit` | The account's credit is out. `details`: `balance`, `plan`, `topUpUrl`, and `required` when the cost was known up front. Add credit; `await vs.billing.get()` shows the balance. |
-| 409 | `payment_method_required` | Auto top-up (`vs.billing.set_auto_top_up`) and the portal (`vs.billing.portal()`) need a payment first (`vs.billing.create_checkout(kind="topup", amount=25, accept_terms=True, waive_withdrawal=True)` opens one; a signed-in person's token, never an API key). |
+| 403 | `terms_acceptance_required` | The account has not accepted the current Terms of Service and Privacy Policy: someone signs in to the Dashboard and accepts them (an organisation's keys work once an owner or admin has). Not retryable until then. |
+| 402 | `insufficient_credit` | The account's credit is out, or does not cover the transcription: every transcription is billed at least the plan's minimum (`rates.minimumSeconds`, 5 minutes). `details`: `balance`, `plan`, `topUpUrl`, and `required` when the cost was known up front. Add credit; `await vs.billing.get()` shows the balance. |
+| 409 | `payment_method_required` | Auto top-up (`vs.billing.set_auto_top_up`) and the portal (`vs.billing.portal()`) need a payment first (`vs.billing.create_checkout(kind="topup", amount=25, accept_terms=True)` opens one; a signed-in person's token, never an API key). |
 | 402 | `quota_exceeded` | The plan's transcriptions-at-once limit is reached. `details`: `metric` (`concurrent_transcriptions`), `limit`, `used`, `plan`, `topUpUrl`. |
 | 429 | `rate_limited` | Retried automatically; if it still fails, wait `e.retry_after` seconds. Every response carries `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset`. |
 | 503 | `unavailable` | The service is waking (its database was asleep). Retried automatically after `Retry-After` (2 s) on calls that are safe to repeat: GET, HEAD, DELETE, or any call with `idempotency_key=`. A create without a key is not retried: retry it yourself, with an `idempotency_key` so it cannot run twice. A realtime socket refused this way raises `unavailable`; a bare 503 there is `capacity_exceeded`. |
@@ -225,7 +257,8 @@ except VocalStackError as e:
 - The other groups: `vs.transcriptions` (`list`, `get`, `update`, `archive`,
   `restore`, `purge`, `list_share_links`, `create_share_link`), `vs.recordings`
   (`get`, `summarize`, `summary`, `translation`, `audio_url`, `subscribe`),
-  `vs.corrections`, `vs.share_links`, `vs.voices`, `vs.broadcasts`,
+  `vs.batches` (`create`, `add_file`, `add_url`, `start`, `wait`, `get`, `list`,
+  `export`, `stop`, `delete`), `vs.corrections`, `vs.share_links`, `vs.voices`, `vs.broadcasts`,
   `vs.me` (`get`, `usage`), `vs.languages`, `vs.rtmp`, `vs.events`, `vs.meta`.
   Each method is its operation's name in the OpenAPI document, in snake_case
   (`transcriptions.create` is `POST /v1/transcriptions`).

{vocalstack-1.0.0a0 → vocalstack-1.0.0a2}/src/vocalstack/__init__.py

@@ -30,7 +30,7 @@ from .errors import VocalStackError
 from .realtime import RealtimeTranscript
 from .realtime import RealtimeSession, pace_realtime
 
-__version__ = "1.0.0a0"
+__version__ = "1.0.0a2"
 
 __all__ = [
     "DEFAULT_BASE_URL",

{vocalstack-1.0.0a0 → vocalstack-1.0.0a2}/src/vocalstack/_http.py

@@ -8,7 +8,7 @@ from typing import Any, Callable, Dict, Mapping, Optional, Union
 
 import httpx
 
-from .errors import from_envelope
+from .errors import VocalStackError, from_envelope, from_oauth
 
 DEFAULT_BASE_URL = "https://api.vocalstack.com"
 
@@ -30,7 +30,6 @@ def listener_query(listener_token: Optional[str], share_code: Optional[str]) ->
     return {"listenerToken": listener_token, "shareCode": share_code}
 
 
-#: The wait before retrying ``503 unavailable`` when it names none.
 UNAVAILABLE_WAIT_S = 2.0
 
 
@@ -103,6 +102,8 @@ class Transport:
         headers: Optional[Mapping[str, str]] = None,
         idempotency_key: Optional[str] = None,
         anonymous: bool = False,
+        no_retry: bool = False,
+        oauth_errors: bool = False,
     ) -> httpx.Response:
         h: Dict[str, str] = {"accept": "application/json"}
         if headers:
@@ -118,16 +119,19 @@ class Transport:
             h["idempotency-key"] = idempotency_key
         attempt = 0
         while True:
-            resp = await self.http.request(
-                method,
-                self.url(path),
-                params=_clean(query),
-                json=json_body,
-                files=files,
-                data=data,
-                headers=h,
-                follow_redirects=False,
-            )
+            try:
+                resp = await self.http.request(
+                    method,
+                    self.url(path),
+                    params=_clean(query),
+                    json=json_body,
+                    files=files,
+                    data=data,
+                    headers=h,
+                    follow_redirects=False,
+                )
+            except httpx.TransportError as e:
+                raise VocalStackError("unavailable", "could not reach the VocalStack API", retryable=True) from e
             if resp.status_code < 400:
                 return resp
             body = None
@@ -135,8 +139,8 @@ class Transport:
                 body = resp.json()
             except (json.JSONDecodeError, ValueError):
                 pass
-            err = from_envelope(body, resp.status_code, resp.headers)
-            if retries(resp.status_code, err.code, method, idempotency_key) and attempt < self.max_retries:
+            err = (from_oauth if oauth_errors else from_envelope)(body, resp.status_code, resp.headers)
+            if not no_retry and retries(resp.status_code, err.code, method, idempotency_key) and attempt < self.max_retries:
                 wait = err.retry_after
                 if wait is None and err.code == "unavailable":
                     wait = UNAVAILABLE_WAIT_S
@@ -150,7 +154,12 @@ class Transport:
         resp = await self.raw(method, path, **kw)
         if 300 <= resp.status_code < 400:
             return {"location": resp.headers.get("location")}
-        return resp.json() if resp.content else None
+        if not resp.content:
+            return None
+        try:
+            return resp.json()
+        except (json.JSONDecodeError, ValueError) as e:
+            raise VocalStackError("internal", "the API answered with a body that is not JSON", status=resp.status_code, headers=resp.headers) from e
 
     async def aclose(self) -> None:
         if self.own_http: