This release is a pre-release and may not be stable for production use.
vocalstack
The VocalStack speech API for Python (3.10 or newer, asyncio): one client,
VocalStack, with one group per resource. Requests go through httpx; answers
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 and our other SDKs on the VocalStack website.
import asyncio, os
from vocalstack import VocalStack
async def main():
async with VocalStack(api_key=os.environ["VOCALSTACK_API_KEY"]) as vs: # base_url defaults to https://api.vocalstack.com
tx = await vs.transcriptions.create(url="https://example.com/talk.mp3") # or file="talk.mp3"
job = await vs.jobs.wait(tx.job.recording_id) # done | failed | cropping
snap = await vs.recordings.transcript(job.recording_id)
print(" ".join(s.text for s in snap.sentences))
open("talk.srt", "wb").write(await vs.recordings.export(job.recording_id, "srt"))
asyncio.run(main())
Install
pip install vocalstack
Guides
- Quickstart: An API key, the SDK, and your first transcript in a dozen lines.
- Transcribe a file: Upload a file, wait for its job, read the transcript and export it. Asynchronous; nothing to keep open.
- Transcribe a link: 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.
- Search your transcriptions: 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: Live audio in, transcript events out, over one WebSocket. Drafts replace the live tail; commits append.
- Stream a file at full speed: 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: Publish live audio to a stored transcription, and put it on a broadcast link listeners open. Control is HTTP; audio is one WebSocket.
- Listen: 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: 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: 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: 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.
What is what
| Name | What it is | Group |
|---|---|---|
| realtime session | a signed token plus one socket; nothing stored | vs.realtime |
| broadcast | the link listeners open | vs.broadcasts |
| 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 |
The other groups: vs.corrections, vs.share_links, vs.speakers,
vs.voices, vs.search, vs.me, vs.languages, vs.rtmp, vs.events, vs.meta.
Method names are the document's operationIds in snake_case
(broadcasts.start_recording is POST /v1/broadcasts/{id}/recordings).
Request fields are keyword arguments, in snake_case or the wire's camelCase
(settings={"spokenLanguage": "en"}); lists return lists; binary answers
(recordings.export, recordings.clip, speakers.sample, ...) return bytes.
VocalStack(
base_url=None, # default https://api.vocalstack.com
api_key=None, # an API key (vs_key_...), for a server
token=None, # or: an access token / browser token, or a callable returning one
acting_principal=None, # act for an organization (X-Acting-Principal)
device_id=None,
max_retries=2, # 429s, and 503 unavailable on safe calls, retried after Retry-After
timeout=300.0,
ready_deadline_s=30.0, # how long a socket may take to report ready
)
Realtime sessions and live recordings
async with VocalStack(api_key=key) as vs:
# Nothing stored: a file through one socket.
result = await vs.realtime.transcribe_file("meeting.mp3", spoken_language="en")
print(result.text)
# A stored live transcription: start a recording, stream raw PCM
# (f32le, 16 kHz, mono) into the publisher socket.
tx = await vs.transcriptions.create_live(name="Standup")
grant = await vs.transcriptions.start_recording(tx.id)
async with await vs.recordings.publish(grant) as stream:
asyncio.create_task(pace_realtime(stream, pcm)) # then eof()
async for event in stream:
if event.type == "transcript.committed":
print(event.segment.speaker, event.segment.text)
transcript.draftframes fully replace the live tail; never append them.transcript.committedsegments are immutable, gapless bysegment.seq, and carry word timings.- A dropped connection ends the socket (no resume): start a new one.
Errors
VocalStackError carries code (the contract's closed enum), message,
status, retryable, details (quota numbers, code suggestions), headers
and retry_after.
Verified against a language-agnostic conformance suite shared by every
VocalStack SDK and against a running API. For agents: SKILL.md.
Metadata
Release files for vocalstack 1.0.0a10
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| vocalstack-1.0.0a10.tar.gz | 47.1 kB | With provenance | Details for vocalstack-1.0.0a10.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| vocalstack-1.0.0a10-py3-none-any.whl | Python 3 | none | any | Details for vocalstack-1.0.0a10-py3-none-any.whl |
Total release size: 98.3 kB
Release files / vocalstack-1.0.0a10.tar.gz
| Download URL | vocalstack-1.0.0a10.tar.gz |
|---|---|
| Size | 47.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
d9a399c0c8d5d5dbac51b2407d1ca143dfd58d216b27cd8cef6d3bee081f3559
|
|
BLAKE2b-256 checksum How to use checksums |
d1ace8d9125823e7ca436bfff0b017b10a32c0560b7da557b1121f5116473f28
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 10, 2026.
Transparency logRelease files / vocalstack-1.0.0a10-py3-none-any.whl
| Download URL | vocalstack-1.0.0a10-py3-none-any.whl |
|---|---|
| Size | 51.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
30dfcb165f67eacc577931b128e478f8b9a03c4bcbcd50af8da852b378639c07
|
|
BLAKE2b-256 checksum How to use checksums |
c4829cc3b6b7a2e80d0a02f83d0704d9206053a7126370f18f18b5fbc7dccb2f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 10, 2026.
Transparency logSecurity for vocalstack 1.0.0a10
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for vocalstack-1.0.0a10.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 10, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.