vocalstack 1.0.0a0__py3-none-any.whl

vocalstack/SKILL.md

@@ -0,0 +1,235 @@
+---
+name: vocalstack
+description: Use when writing Python code that calls the VocalStack speech API with the vocalstack package, for example to transcribe an audio or video URL or a local file, stream live audio for realtime transcription, fetch or export a transcript (JSON, SRT, XLSX, PDF), or search transcripts. Covers installing, API keys, base URLs, five copy-paste programs and error handling (401, 402, 403, 429).
+---
+
+# VocalStack Python SDK
+
+The VocalStack API transcribes speech (files, links, live audio), with speaker
+labels and translation. The `vocalstack` package has one asyncio client,
+`VocalStack`, with one group per resource: `vs.transcriptions`, `vs.jobs`,
+`vs.recordings`, `vs.broadcasts`, `vs.search`, `vs.realtime` and a few more
+(listed at the end). Answers are pydantic models with snake_case attributes.
+
+## What is what
+
+- A **transcription** is a file, a link, a microphone or a stream, transcribed
+  and stored. Create one with `await vs.transcriptions.create(...)`.
+- A **recording** is one take inside it. Its id (`recording_id`) is what you
+  read the transcript and exports with: `await vs.recordings.transcript(recording_id)`.
+- 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 **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.
+
+## Install
+
+```sh
+python3 -m venv .venv && . .venv/bin/activate   # system Pythons refuse a bare pip install
+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
+for that transcription, so print the text without a speaker.
+
+## Auth and base URL
+
+- Read the key from `VOCALSTACK_API_KEY` and pass it as `api_key`. It goes
+  out as `Authorization: Bearer <key>`, also on sockets.
+- An API key starts with `vs_key_`. There is one kind of key: every call is
+  real usage on the account's tier and quotas.
+- Keys are for servers. Never put a key in browser code or in a URL. The API
+  refuses a key sent from a web page (`Origin` header) or in a query string.
+- 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.
+
+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):
+
+```python
+async with VocalStack(os.environ.get("VOCALSTACK_BASE_URL"), api_key=os.environ["VOCALSTACK_API_KEY"]) as vs:
+    ...
+```
+
+## 1. Transcribe a URL and wait for the result
+
+The server fetches the link itself, so it must be a public http(s) address.
+Private, loopback and cloud-metadata addresses are refused.
+
+```python
+import asyncio, os
+from vocalstack import VocalStack
+
+async def main():
+    async with VocalStack(os.environ.get("VOCALSTACK_BASE_URL"), api_key=os.environ["VOCALSTACK_API_KEY"]) as vs:
+        tx = await vs.transcriptions.create(
+            url="https://raw.githubusercontent.com/openai/whisper/main/tests/jfk.flac",
+            name="JFK sample",
+        )
+        rec = tx.job.recording_id
+        job = await vs.jobs.wait(rec)  # queued -> fetching -> transcribing -> done | failed
+        if job.state != "done":
+            raise SystemExit(f"transcription {job.state}: {job.error}")
+        snap = await vs.recordings.transcript(rec)
+        for s in snap.sentences:
+            print(f"[speaker {s.speaker}] {s.text}" if s.speaker >= 0 else s.text)
+        print("recording_id", rec)
+
+asyncio.run(main())
+```
+
+## 2. Transcribe a local file
+
+```python
+import asyncio, os, sys
+from vocalstack import VocalStack
+
+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"
+        )
+        job = await vs.jobs.wait(tx.job.recording_id)
+        if job.state != "done":
+            raise SystemExit(f"transcription {job.state}: {job.error}")
+        snap = await vs.recordings.transcript(job.recording_id)
+        print(" ".join(s.text for s in snap.sentences))
+
+asyncio.run(main(sys.argv[1]))
+```
+
+## 3. Fetch a transcript or an export file
+
+The transcript holds segments (with word timings), sentences and speakers.
+Export formats are `json`, `srt`, `xlsx` and `pdf`; add `lang="<code>"` for a
+translated file. `export` returns the file's bytes.
+
+```python
+import asyncio, os, sys
+from vocalstack import VocalStack
+
+async def main(rec):
+    async with VocalStack(os.environ.get("VOCALSTACK_BASE_URL"), api_key=os.environ["VOCALSTACK_API_KEY"]) as vs:
+        snap = await vs.recordings.transcript(rec)
+        print(len(snap.segments), "segments,", len(snap.sentences), "sentences, state", snap.state)
+        with open("transcript.srt", "wb") as f:
+            f.write(await vs.recordings.export(rec, "srt"))
+
+asyncio.run(main(sys.argv[1]))
+```
+
+## 4. Live transcription from a microphone or a file
+
+A live transcription takes raw PCM: 32-bit float little-endian, 16 kHz, mono.
+Create it, start a recording, and open the publisher socket the grant names.
+Here ffmpeg decodes a file, and `pace_realtime` sends it at realtime speed and
+then calls `eof()`. For a microphone, read ffmpeg's stdout as it arrives
+(`-f avfoundation -i :0` on macOS, `-f pulse -i default` on Linux) and call
+`await stream.send_audio(chunk)` for each chunk.
+
+```python
+import asyncio, os, subprocess, sys
+from vocalstack import VocalStack, pace_realtime
+
+async def main(path):
+    async with VocalStack(os.environ.get("VOCALSTACK_BASE_URL"), api_key=os.environ["VOCALSTACK_API_KEY"]) as vs:
+        tx = await vs.transcriptions.create_live(name="Live demo", settings={"spokenLanguage": "en"})
+        grant = await vs.transcriptions.start_recording(tx.id)
+
+        pcm = subprocess.run(["ffmpeg", "-loglevel", "error", "-i", path,
+                              "-f", "f32le", "-ac", "1", "-ar", "16000", "-"],
+                             check=True, capture_output=True).stdout
+
+        # A cold engine can take a while to load, so allow a long ready deadline.
+        async with await vs.recordings.publish(grant, ready_deadline_s=180) as stream:
+            feeder = asyncio.create_task(pace_realtime(stream, pcm))  # then eof(), which ends the recording
+            async for event in stream:
+                if event.type == "transcript.committed":
+                    print(f"[speaker {event.segment.speaker}] {event.segment.text}", flush=True)
+            await feeder
+
+        # To end a recording without eof(): vs.recordings.pause(id), then vs.recordings.stop(id).
+        snap = await vs.recordings.transcript(grant.recording.id)
+        print("final:", " ".join(s.text for s in snap.sentences))
+
+asyncio.run(main(sys.argv[1]))
+```
+
+To transcribe without storing anything, use a realtime session instead:
+`(await vs.realtime.transcribe_file("talk.mp3")).text`.
+
+## 5. Search transcripts
+
+```python
+import asyncio, os, sys
+from vocalstack import VocalStack
+
+async def main(q):  # 2+ characters
+    async with VocalStack(os.environ.get("VOCALSTACK_BASE_URL"), api_key=os.environ["VOCALSTACK_API_KEY"]) as vs:
+        res = await vs.search.query(q, limit=5)
+        for h in res.hits:
+            print(f"{h.link_name} @ {h.media_start:.1f}s [speaker {h.speaker}]: {h.text} (recording {h.recording_id})")
+
+asyncio.run(main(sys.argv[1]))
+```
+
+## Errors
+
+A failed call raises `vocalstack.VocalStackError` with `.code`, `.message`,
+`.status`, `.retryable`, `.details` (the body's `data.details`), `.headers`
+and `.retry_after` (seconds, from `Retry-After`). A `429`, and a
+`503 unavailable` on a call that is safe to repeat, is retried for you after
+its `Retry-After`, twice by default (`max_retries` on the client).
+
+| Status | `code` | What to do |
+|---|---|---|
+| 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). |
+| 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`. |
+
+```python
+from vocalstack import VocalStackError
+try:
+    await vs.search.query("country")
+except VocalStackError as e:
+    if e.code in ("insufficient_credit", "quota_exceeded"):
+        print("billing:", e.message, e.details)
+    else:
+        print(e.status, e.code, e.message)
+```
+
+## More
+
+- 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.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`).
+- `<base>/llms.txt` lists every operation in a form written for agents.
+  `<base>/llms-full.txt` adds parameters, auth mode, tier and scopes.
+- `<base>/docs` is the interactive reference. `<base>/v1/openapi.json` is
+  the OpenAPI document; the SDK's models are generated from it.

vocalstack/__init__.py

@@ -0,0 +1,63 @@
+"""VocalStack speech API SDK (asyncio): one client, ``VocalStack``, grouped
+by resource, with models generated from the API's one contract."""
+
+from . import _models as models
+from ._models import (
+    Broadcast,
+    Capabilities,
+    CommittedSegment,
+    CreateSessionResponse,
+    DraftSegment,
+    Health,
+    PublishGrant,
+    Recording,
+    SearchResults,
+    ServerFrame,
+    SessionOptions,
+    SessionStats,
+    Transcription,
+    TranscriptionJob,
+    TranscriptCommitted,
+    TranscriptDraft,
+    TranscriptProgress,
+    TranscriptSnapshot,
+    TranscriptWords,
+    Word,
+)
+from ._http import DEFAULT_BASE_URL
+from .client import VocalStack
+from .errors import VocalStackError
+from .realtime import RealtimeTranscript
+from .realtime import RealtimeSession, pace_realtime
+
+__version__ = "1.0.0a0"
+
+__all__ = [
+    "DEFAULT_BASE_URL",
+    "Broadcast",
+    "Capabilities",
+    "CommittedSegment",
+    "CreateSessionResponse",
+    "DraftSegment",
+    "Health",
+    "PublishGrant",
+    "RealtimeTranscript",
+    "Recording",
+    "SearchResults",
+    "ServerFrame",
+    "SessionOptions",
+    "SessionStats",
+    "RealtimeSession",
+    "Transcription",
+    "TranscriptionJob",
+    "TranscriptCommitted",
+    "TranscriptDraft",
+    "TranscriptProgress",
+    "TranscriptSnapshot",
+    "TranscriptWords",
+    "VocalStack",
+    "VocalStackError",
+    "Word",
+    "models",
+    "pace_realtime",
+]

vocalstack/_http.py

@@ -0,0 +1,157 @@
+"""The one HTTP path every resource method goes through."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from typing import Any, Callable, Dict, Mapping, Optional, Union
+
+import httpx
+
+from .errors import from_envelope
+
+DEFAULT_BASE_URL = "https://api.vocalstack.com"
+
+Query = Mapping[str, Any]
+
+
+def _clean(q: Optional[Query]) -> Dict[str, str]:
+    out: Dict[str, str] = {}
+    for k, v in (q or {}).items():
+        if v is None or v == "":
+            continue
+        out[k] = ("true" if v else "false") if isinstance(v, bool) else str(v)
+    return out
+
+
+def listener_query(listener_token: Optional[str], share_code: Optional[str]) -> Dict[str, Any]:
+    """The query of a listener-side read (a private broadcast's listener
+    token, or a share link's code), named as on the wire."""
+    return {"listenerToken": listener_token, "shareCode": share_code}
+
+
+#: The wait before retrying ``503 unavailable`` when it names none.
+UNAVAILABLE_WAIT_S = 2.0
+
+
+def retries(status: int, code: str, method: str, idempotency_key: Optional[str] = None) -> bool:
+    """Whether a failed call is retried after its ``Retry-After`` (up to
+    ``max_retries`` times): ``429 rate_limited`` always (nothing ran), and
+    ``503 unavailable`` (the database is waking) only when repeating the call
+    cannot do the work twice: GET, HEAD and DELETE, or a call carrying an
+    ``Idempotency-Key``."""
+    if status == 429:
+        return True
+    if status != 503 or code != "unavailable":
+        return False
+    return method.upper() in ("GET", "HEAD", "DELETE") or bool(idempotency_key)
+
+
+class Transport:
+    def __init__(
+        self,
+        base_url: Optional[str],
+        api_key: Optional[str],
+        token: Union[None, str, Callable[[], Optional[str]]],
+        *,
+        http: Optional[httpx.AsyncClient],
+        acting_principal: Optional[str],
+        device_id: Optional[str],
+        max_retries: int,
+        timeout: float,
+    ) -> None:
+        self.base_url = (base_url or DEFAULT_BASE_URL).rstrip("/")
+        if api_key and token:
+            raise TypeError("VocalStack: pass api_key (a server) or token (a browser), not both")
+        self._api_key = api_key
+        self._token = token
+        self.own_http = http is None
+        self.http = http or httpx.AsyncClient(timeout=timeout)
+        self.acting_principal = acting_principal
+        self.device_id = device_id
+        self.max_retries = max_retries
+
+    def bearer(self) -> Optional[str]:
+        """What goes in ``Authorization: Bearer``: the API key, else the token."""
+        if self._api_key:
+            return self._api_key
+        t = self._token
+        return t() if callable(t) else t
+
+    def auth_headers(self) -> Dict[str, str]:
+        """The credential as a header (sockets too: a key is refused in a URL)."""
+        key = self.bearer()
+        return {"authorization": f"Bearer {key}"} if key else {}
+
+    def url(self, path: str) -> str:
+        return self.base_url + path
+
+    def ws_url(self, path: str, query: Optional[Query] = None) -> str:
+        base = "ws" + self.base_url[4:] if self.base_url.startswith("http") else self.base_url
+        q = _clean(query)
+        return base + path + (("?" + str(httpx.QueryParams(q))) if q else "")
+
+    async def raw(
+        self,
+        method: str,
+        path: str,
+        *,
+        query: Optional[Query] = None,
+        json_body: Any = None,
+        files: Any = None,
+        data: Any = None,
+        headers: Optional[Mapping[str, str]] = None,
+        idempotency_key: Optional[str] = None,
+        anonymous: bool = False,
+    ) -> httpx.Response:
+        h: Dict[str, str] = {"accept": "application/json"}
+        if headers:
+            h.update(headers)
+        key = None if anonymous else self.bearer()
+        if key:
+            h["authorization"] = f"Bearer {key}"
+        if self.acting_principal:
+            h["x-acting-principal"] = self.acting_principal
+        if self.device_id:
+            h["x-device-id"] = self.device_id
+        if idempotency_key:
+            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,
+            )
+            if resp.status_code < 400:
+                return resp
+            body = None
+            try:
+                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:
+                wait = err.retry_after
+                if wait is None and err.code == "unavailable":
+                    wait = UNAVAILABLE_WAIT_S
+                if wait is not None and wait <= 60:
+                    attempt += 1
+                    await asyncio.sleep(wait)
+                    continue
+            raise err
+
+    async def json(self, method: str, path: str, **kw: Any) -> Any:
+        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
+
+    async def aclose(self) -> None:
+        if self.own_http:
+            await self.http.aclose()