vocalstack 1.0.0a1__tar.gz → 1.0.0a2__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: vocalstack
-Version: 1.0.0a1
+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-Expression: MIT
@@ -18,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
@@ -45,7 +47,9 @@ pip install vocalstack
 
 - [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.
@@ -65,6 +69,7 @@ pip install vocalstack
 | 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`.

{vocalstack-1.0.0a1 → 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
@@ -32,7 +34,9 @@ pip install vocalstack
 
 - [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.
@@ -52,6 +56,7 @@ pip install vocalstack
 | 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`.

{vocalstack-1.0.0a1 → 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.
@@ -94,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":
@@ -180,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`,
@@ -215,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.0a1 → vocalstack-1.0.0a2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "vocalstack"
-version = "1.0.0a1"
+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 = "MIT"
@@ -22,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", "LICENSE", "README.md", "SKILL.md", "skills", "pyproject.toml"]

{vocalstack-1.0.0a1 → 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.
@@ -94,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":
@@ -180,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`,
@@ -215,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.0a1 → 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.0a1"
+__version__ = "1.0.0a2"
 
 __all__ = [
     "DEFAULT_BASE_URL",

{vocalstack-1.0.0a1 → 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_oauth
+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
 
 
@@ -120,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
@@ -152,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: