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.

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 or a YouTube video, then transcribes it like a file. Asynchronous, with a fetch phase first.
  • 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.0a1

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

Built distribution (wheel)

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

Total release size: 81.4 kB

Release files / vocalstack-1.0.0a1.tar.gz

Download URL vocalstack-1.0.0a1.tar.gz
Size 38.8 kB
Tags Source
SHA-256 checksum
How to use checksums
1cdd86e44c462c5eca3a10eb647b9f67486e508a88ccdefb2079d947932019c6
BLAKE2b-256 checksum
How to use checksums
8962ef31aae59adc5e25144c9a7933d9b0e1458500017013ae6eb18b21418004
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

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 Oct 20, 2026.

Transparency log

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

Download URL vocalstack-1.0.0a1-py3-none-any.whl
Size 42.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
8fc7086cd2e92c35051e3b7e8458dcfa15108711e4539746357ded4a107d3396
BLAKE2b-256 checksum
How to use checksums
72793334146b38b0907563fe6abf6347150b7e143abe4054581054df8901102b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

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 Oct 20, 2026.

Transparency log

Security for vocalstack 1.0.0a1

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.0a1.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 Oct 20, 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