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.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.0a11

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

Built distribution (wheel)

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

Total release size: 98.5 kB

Release files / vocalstack-1.0.0a11.tar.gz

Download URL vocalstack-1.0.0a11.tar.gz
Size 47.2 kB
Tags Source
SHA-256 checksum
How to use checksums
4699af8a98731c345a29a98a7472b25f9de3e8d49efb8f010ed7d4af02a2fb27
BLAKE2b-256 checksum
How to use checksums
807bc3464fb698781874060c9819d3223c633d48a75b5dc31d290fc7dfdc926a
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 11, 2026.

Transparency log

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

Download URL vocalstack-1.0.0a11-py3-none-any.whl
Size 51.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
23fe43998aaa4c8a981b3d46dd8ed04fabb817c3fec44b3599e6141d972bc040
BLAKE2b-256 checksum
How to use checksums
773b2cc7f5d5dc5a478e6238c5b67980df7a6c6262571a280cfc75cef0f60e38
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 11, 2026.

Transparency log

Security for vocalstack 1.0.0a11

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.0a11.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 11, 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