Skip to main content

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 post 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 transcription 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.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.0

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.0
File Size Uploaded Provenance Actions
vocalstack-1.0.0.tar.gz 48.7 kB With provenance Details for vocalstack-1.0.0.tar.gz

Built distribution (wheel)

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

Total release size: 101.5 kB

Release files / vocalstack-1.0.0.tar.gz

Download URL vocalstack-1.0.0.tar.gz
Size 48.7 kB
Tags Source
SHA-256 checksum
How to use checksums
131059d6d171c29dc9e1074f5f256d246c5de802a242477d65a790e79db27500
BLAKE2b-256 checksum
How to use checksums
5c57ed9f6972de8aa26f5cdc04b3a6ba8b7194fb4ebcae8b0a2477b982c52c99
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 19, 2026.

Transparency log

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

Download URL vocalstack-1.0.0-py3-none-any.whl
Size 52.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
56fc9f409413af1156b4fded55631b59e892fe5fc3becabe5e4d1b32f801fa86
BLAKE2b-256 checksum
How to use checksums
79e90a1dbc2cf7d0732e985d9a002b6e16ede7b8ddd36d59d2242b3bd3333d5e
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 19, 2026.

Transparency log

Security for vocalstack 1.0.0

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.0.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 19, 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