Skip to main content
Pre-release

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.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, voices.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.draft frames fully replace the live tail; never append them.
  • transcript.committed segments are immutable, gapless by segment.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.0a3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for vocalstack 1.0.0a3
File Size Uploaded Provenance Actions
vocalstack-1.0.0a3.tar.gz 44.5 kB With provenance Details for vocalstack-1.0.0a3.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for vocalstack 1.0.0a3
File Interpreter ABI Platform Actions
vocalstack-1.0.0a3-py3-none-any.whl Python 3 none any Details for vocalstack-1.0.0a3-py3-none-any.whl

Total release size: 93.0 kB

Release files / vocalstack-1.0.0a3.tar.gz

Download URL vocalstack-1.0.0a3.tar.gz
Size 44.5 kB
Tags Source
SHA-256 checksum
How to use checksums
f71b1306025eadb2a79b22ef5cddd8c9b290d5012def7a61a05bff0234617f57
BLAKE2b-256 checksum
How to use checksums
218f4b5918ae9d40f481ba61bbcf5ccc4a708a837fee0e9452e6b1e3f48bb01e
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 7, 2026.

Transparency log

Release files / vocalstack-1.0.0a3-py3-none-any.whl

Download URL vocalstack-1.0.0a3-py3-none-any.whl
Size 48.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
1e20423ce5632686fcf8c9fc4c2fdfed8ad30be63323cc494cbc39c9cc2c05da
BLAKE2b-256 checksum
How to use checksums
dcf714336e885e297f2fb1d07ed58a73abad513b64a45d5750314858e288d393
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 7, 2026.

Transparency log

Security for vocalstack 1.0.0a3

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.

Select from 2 files

Attestation for vocalstack-1.0.0a3.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 7, 2026.

Transparency log

A 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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page