RealtimeSTT README

The project's README from github.com/KoljaB/RealtimeSTT. As one markdown file: README.md.

RealtimeSTT

RealtimeSTT is a Python speech-to-text library for applications that need voice activity detection, fast transcription, optional realtime text updates, wake words, and direct access to audio streams. It is designed for assistants, dictation tools, browser streaming servers, and prototypes that need to turn speech into text with only a few lines of code.

The general-purpose default path uses faster_whisper. Other engines are available through install extras when their optional dependencies and models are present.

Install the CPU server stack and both pinned model bundles with:

python -m pip install "RealtimeSTT[server,sherpa-onnx]"
stt-install-sherpa-models --root ./models/sherpa-onnx --model all

See the production server guide for the authenticated HTTP/WebSocket deployment recipe and exact pinned model directories.

Support RealtimeSTT

If RealtimeSTT saved you time, one GitHub star is a simple way to help make it more stable.

Stars improve visibility and visibility brings more users, more real-world testing, more bug reports, more fixes, and better releases for everyone.

Demo

https://github.com/user-attachments/assets/797e6552-27cd-41b1-a7f3-e5cbc72094f5

CLI demo code (reproduces the video above)

RealtimeSTT includes native support for kroko_onnx, the local streaming ASR engine from the Kroko/Banafo team.

This integration has been on my wishlist for a long time. Kroko is a strong fit for RealtimeSTT's goals: fast, accurate local speech recognition.

Start with the public Community models for local testing, or see Kroko/Banafo's commercial model options if you need production licensing and higher-end models.

pip install "RealtimeSTT[kroko-builder,silero-onnx-cpu]"
stt-install-kroko --build

The silero-onnx-cpu extra gives AudioToTextRecorder a local VAD backend for recorder-based smoke tests and live microphone use.

See the Kroko-ONNX engine guide, Kroko ASR docs, and kroko-onnx on GitHub.

Install

The current CI matrix covers Python 3.11 and 3.12. Python 3.13 and newer are not release targets until dependency and CI gates are available.

pip install "RealtimeSTT[faster-whisper]"

On Linux, install PortAudio headers before installing the package:

sudo apt-get update
sudo apt-get install python3-dev portaudio19-dev

On macOS:

brew install portaudio

For CUDA, platform notes, and optional engine stacks, see docs/installation.md.

Microphone Example

This waits for speech, stops after the detected utterance, and prints the final transcript:

from RealtimeSTT import AudioToTextRecorder

if __name__ == "__main__":
    with AudioToTextRecorder() as recorder:
        print("Speak now")
        print(recorder.text())

Use the if __name__ == "__main__": guard when running scripts, especially on Windows, because RealtimeSTT uses multiprocessing for model work.

Automatic Recording Loop

For continuous dictation, pass a callback to text() so transcription work can complete asynchronously while your loop keeps listening:

from RealtimeSTT import AudioToTextRecorder


def process_text(text):
    print(text)


if __name__ == "__main__":
    recorder = AudioToTextRecorder()

    while True:
        recorder.text(process_text)

External Audio

Set use_microphone=False when audio comes from a file, stream, websocket, or another process. Feed 16-bit mono PCM chunks at 16 kHz, or pass the original sample rate so RealtimeSTT can resample:

from RealtimeSTT import AudioToTextRecorder

if __name__ == "__main__":
    recorder = AudioToTextRecorder(use_microphone=False)

    with open("audio_chunk.pcm", "rb") as audio_file:
        recorder.feed_audio(audio_file.read(), original_sample_rate=16000)

    print(recorder.text())
    recorder.shutdown()

More examples are in docs/quick-start.md and docs/external-audio.md.

Configuration Reference

Every AudioToTextRecorder constructor parameter is documented in docs/configuration.md, including model/engine selection, realtime transcription, VAD timing, wake words, callbacks, external audio, logging, and executor injection.

Features

Documentation

Engine-specific references:

Production Server

The supported remote server is packaged as an optional install. It binds to loopback by default and exposes versioned health, readiness, capabilities, raw-PCM final transcription, and ordered streaming WebSocket endpoints. Direct non-loopback binds require both a bearer token and Uvicorn TLS certificate/key files; for a reverse-proxy deployment, keep the server on loopback and terminate TLS at the proxy.

python -m pip install "RealtimeSTT[server,faster-whisper]"
stt-server-production --host 127.0.0.1 --port 8010

For CPU INT8 deployment, the recommended pairing is sherpa-onnx-nemotron-3.5-asr-streaming-0.6b-560ms-int8 for live hypotheses and sherpa-onnx-nemo-parakeet-tdt-0.6b-v3-int8 for authoritative final transcription. Install RealtimeSTT[server,sherpa-onnx] and both pinned model bundles into persistent storage before following the server recipe. The server extra includes the local Silero ONNX VAD runtime used by legacy recorder-backed server paths. The versioned production WebSocket path owns its turn state and does not derive finalization from recorder VAD, so production startup does not need an interactive Torch Hub download:

stt-install-sherpa-models --root ./models/sherpa-onnx --model all

See PRODUCTION_SERVER.md.

The interactive browser reference app remains in example_fastapi_server for source checkouts. See docs/fastapi-server.md for its UI, engine recipes, protocol details, and metrics.

Contributing

Focused tests and small changes are easiest to review. The project keeps fast unit tests separate from opt-in real-model tests; see docs/testing.md.

License

MIT

Author

Kolja Beigel

RealtimeSTT (KoljaB/RealtimeSTT)

Searching Database…

10.2K ·GitHub
RealtimeSTT
What is this?A Python speech-to-text library that turns microphone or streamed audio into text with low latency: voice activity detection, optional wake words, live partial text, and final transcripts in a few lines of code.
Am I coding against a library, or installing a finished app?A library built around an AudioToTextRecorder class you call from your Python code. There is also an optional packaged FastAPI server that exposes HTTP and WebSocket endpoints for remote use.
Any gotchas before I run my first transcription?Wrap your script in an if __name__ == '__main__': guard — RealtimeSTT uses multiprocessing for model work and breaks without it, especially on Windows. Python 3.13 and newer are not supported release targets yet.
Does my audio leave my machine?With the default engines it does not — fasterwhisper, sherpa-onnx and Kroko-ONNX all run locally on your hardware. Cloud services like Cohere Transcribe exist only as opt-in extras.
What is Kroko-ONNX?A local streaming speech-recognition engine from the Kroko/Banafo team with native support in RealtimeSTT. Free Community models work for local testing, and the team sells commercial licensing and higher-end models for production.
What does the recommended CPU production stack look like?The sherpa-onnx Nemotron 0.6b INT8 streaming model produces fast live text during each turn, while the Parakeet TDT 0.6b INT8 model writes the authoritative final transcript once the turn ends. Install RealtimeSTT[server,sherpa-onnx] plus the two pinned model bundles.
What are similar projects?WhisperLiveKit, FunASR, faster-whisper, whisper, buzz, Whisper, pyvideotrans, omarchy-meeting-recorder
Which topics is it in?voice-activity-detection, assistant, transcription, realtime, whisper, onnx, speech-to-text, speech-recognition, fastapi, websocket, audio, gpu
Creator
KoljaB
Size
6.2 MB
Stars
10.2K
Updated
CommitOct 16Releasev1.1.2Aug 30
Age
3y
Commits · 90 Days