Speech Revolutions — Python SDK

Official Python client for the Speech Revolutions speech-to-text API.

Install

pip install speechrevolutions

For console progress bars, install the optional tqdm extra:

pip install "speechrevolutions[progress]"

Quick start

from speechrevolutions import SpeechRevolutions

client = SpeechRevolutions()  # reads SPEECHREVOLUTIONS_API_KEY
result = client.transcribe("meeting.mp3", speaker_labels=True)
print(result.text)

for u in result.utterances:
    print(f"{u.speaker}: {u.text}")  # e.g. "SPEAKER_1: Hello."

Async

import asyncio

from speechrevolutions import AsyncSpeechRevolutions


async def main():
    async with AsyncSpeechRevolutions() as client:
        result = await client.transcribe("meeting.mp3", speaker_labels=True)
        print(result.text)


asyncio.run(main())

From a URL (Deepgram-style)

result = client.transcribe_url("https://docs.speechrevolutions.com/samples/diamond-necklace.mp3")
# or, since transcribe() detects http(s) URLs:
# result = client.transcribe("https://docs.speechrevolutions.com/samples/diamond-necklace.mp3")

Options as kwargs or config object

# kwargs (ElevenLabs / Deepgram style). `diarize` is an alias for `speaker_labels`.
result = client.transcribe("meeting.mp3", diarize=True, output_type="json")

# config object (AssemblyAI style)
from speechrevolutions import TranscribeOptions
result = client.transcribe("meeting.mp3", options=TranscribeOptions(speaker_labels=True))

Defaults: output_type="json", word_timestamps, speaker_labels, nltk all True, tier="standard", custom_vocabulary=None, language=None.

language pins an ISO 639-1 code (e.g. language="ru") and skips language detection; None (or "auto") detects it automatically. Pinning the wrong language makes the model translate into it (Russian audio pinned to "en" comes back as English), and an unsupported code is rejected with HTTP 422.

Live progress

Unlike AssemblyAI/Deepgram (which give no percentage for pre-recorded audio), you get real-time progress — for both the file upload and the transcription — as a console bar, a callback, or both.

# 1. Console bars (uses tqdm if installed: pip install "speechrevolutions[progress]")
#    Shows an "Uploading" byte bar, then a "Transcribing" bar.
result = client.transcribe("meeting.mp3", progress=True)

# 2. Programmatic — read event.percent (0–100) to drive your own UI / API
def on_progress(event):        # transcription
    print(event.percent, event.step)      # e.g. 50.0 "chunk:0"

def on_upload(event):          # upload (event.step == "upload")
    print("upload", event.percent)

result = client.transcribe(
    "meeting.mp3",
    on_progress=on_progress,
    on_upload_progress=on_upload,
)

progress=True and the callbacks compose — the bars render and your callbacks still fire for every event. When the job completes, on_progress always receives a final event at 100 (event.step == "completed"), even for a short file that finished before reporting any progress.

Result shape

Default output_type is json. The SDK parses it into a transcript-first object:

from speechrevolutions import SpeechRevolutions

client = SpeechRevolutions()
result = client.transcribe("meeting.mp3")

# Deepgram's response shape; speakers are numbered from 0.
dg = result.to_deepgram()
print(dg["results"]["channels"][0]["alternatives"][0]["transcript"])

# Save raw content to disk. Appends the output type if the path has no
# extension, e.g. "output" -> "output.json". Returns the written path.
path = result.save("output")
print(f"saved {path}")

to_deepgram() numbers speakers from 0, as Deepgram does: SPEAKER_1 becomes speaker 0, SPEAKER_2 speaker 1. (Before 1.0.0 it kept our 1-based numbers.)

Webhooks & retrieving results later

submit() uploads and enqueues a job and returns its id without waiting — ideal for batch/background work. Collect the result later via a webhook (callback_url, a signed POST — verify X-SR-Signature: sha256=… against the raw bytes) or by polling:

job_id = client.submit("meeting.mp3")       # returns immediately, no waiting
# ...or have a webhook notified instead of polling:
client.submit("meeting.mp3", callback_url="https://you.example.com/hook")

status = client.get_job_status(job_id)      # .status: processing|completed|failed
if status.is_completed:
    result = client.get_transcript(job_id)  # downloads + parses
page = client.list_jobs(limit=50)           # {"jobs": [...], "next_before": ...}

The signature is HMAC-SHA256 over the raw request body, keyed with your account's own webhook signing secret — find it under API Keys in the console. Compare it with a constant-time function, and verify against the bytes you received rather than a re-serialised copy. Worked receivers for Python, Node, Go and C# are in the webhooks guide.

See examples/ for a full submit/poll/webhook walkthrough.

Robustness

SpeechRevolutions(max_retries=3, retry_backoff=0.5, proxies={"https": "..."}). Transient 429/5xx/network errors are retried (honoring Retry-After). Errors are typed (RateLimitError, AuthenticationError, …) and carry .status_code and .request_id for correlating with support.

Auth

export SPEECHREVOLUTIONS_API_KEY=stt_...

Or SpeechRevolutions(api_key="stt_...").

Other languages

Speech Revolutions also publishes SDKs for JavaScript/TypeScript, Go, and C#/.NET — see docs.speechrevolutions.com for a cross-language feature comparison.

License

MIT