Guide · Open source

How to use RealtimeSTT: install, record speech and transcribe

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

RealtimeSTT is a Python library that turns speech into text. It listens with voice activity detection, can wait for a wake word, and can produce optional live text updates before a final transcript. This guide shows you how to install it, transcribe from a microphone or your own audio, and where to find the configuration reference.

RealtimeSTTKoljaB/RealtimeSTT · ★ 10.2k · MIT Install options & downloads

Quick start

1Check your Python version. Use Python 3.11 or 3.12, since the README says the current CI matrix covers only those versions.
2Install PortAudio headers. On Linux run sudo apt-get install python3-dev portaudio19-dev. On macOS run brew install portaudio.
3Install the package. Run pip install "RealtimeSTT[faster-whisper]" to get the default engine.
4Run the microphone example. Save the microphone script with the __main__ guard and run it. Speak, and the final transcript prints after the utterance ends.
5Try external audio if needed. Set use_microphone=False and feed 16-bit mono 16 kHz PCM through feed_audio().
6Read the configuration reference. Open docs/configuration.md to tune VAD timing, realtime text, wake words and callbacks.

What you need before you install RealtimeSTT

RealtimeSTT is a developer library, not a ready-made app. The README documents only Python usage and a server recipe, so you should be comfortable writing a short Python script.

The current CI matrix covers Python 3.11 and 3.12. The README states that Python 3.13 and newer are not release targets yet, so use one of those two versions.

Python 3.11 or 3.12
PortAudio development headers: portaudio19-dev on Linux, or portaudio via Homebrew on macOS

Install RealtimeSTT with the faster-whisper engine

Install PortAudio headers first, then install the package with the default faster-whisper engine. The README lists these commands for each platform.

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

Linux: run sudo apt-get update, then sudo apt-get install python3-dev portaudio19-dev
macOS: run brew install portaudio

pip install "RealtimeSTT[faster-whisper]"

Transcribe speech from your microphone

The simplest script waits for speech, stops after the detected utterance and prints the final transcript. Keep the if __name__ == "__main__": guard, because the README notes RealtimeSTT uses multiprocessing for model work, which matters especially on Windows.

from RealtimeSTT import AudioToTextRecorder

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

Run continuous dictation with a callback

For continuous dictation, pass a callback to text(). The README says transcription work can then 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)

Feed your own audio instead of a microphone

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

The README example reads a raw PCM file, passes it to feed_audio with original_sample_rate=16000, prints the text and then shuts the recorder down.

Set use_microphone=False on AudioToTextRecorder
Feed 16-bit mono PCM audio with feed_audio()
Pass original_sample_rate if your audio is not already 16 kHz
Call shutdown() when you finish

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()

Choose options, wake words and engines

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

The library uses WebRTC VAD and Silero VAD for voice activity detection. Wake words are optional and go through Porcupine or OpenWakeWord, with setup in docs/wake-words.md. Other speech engines such as whisper.cpp, Moonshine, sherpa-onnx and Kroko-ONNX are available as optional installs; check each engine page for its requirements and licence notes.

Voice activity detection: WebRTC VAD and Silero VAD
Wake words: Porcupine or OpenWakeWord
Engine pages: faster-whisper, whisper.cpp, OpenAI Whisper, Moonshine, sherpa-onnx, Kroko-ONNX, Parakeet NeMo and others listed in the docs

Run the production server on a CPU Linux machine

The README describes a packaged production server as an optional install. It binds to loopback by default. For a direct non-loopback bind you need both a bearer token and Uvicorn TLS certificate and key files. For a reverse proxy, keep the server on loopback and terminate TLS at the proxy.

For CPU INT8 deployment, the README recommends pairing two sherpa-onnx model bundles and installing them into persistent storage first. Follow docs/production server guide (RealtimeSTT_server/PRODUCTION_SERVER.md) for the exact pinned model directories.

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

What people use it for

Adding voice input to a Python assistant prototype
Building a dictation tool that turns microphone speech into text
Sending audio chunks from a websocket or file into a transcriber
Running a browser streaming server for speech input

Frequently asked questions

Is RealtimeSTT free to use?

RealtimeSTT is released under the MIT licence, as listed on its repository. Optional engines and models have their own licences, so check docs/licenses.md before commercial use.

What Python version does RealtimeSTT need?

The README says the current CI matrix covers Python 3.11 and 3.12. It states that Python 3.13 and newer are not release targets until dependency and CI gates are available.

How do I install RealtimeSTT on Linux or macOS?

Install the PortAudio headers first: sudo apt-get install python3-dev portaudio19-dev on Linux, or brew install portaudio on macOS. Then run pip install "RealtimeSTT[faster-whisper]".

Can RealtimeSTT transcribe audio from a file instead of a microphone?

Yes. Set use_microphone=False and pass 16-bit mono PCM audio to feed_audio(). Pass original_sample_rate if the audio is not 16 kHz, and RealtimeSTT can resample it.

Does RealtimeSTT support wake words?

Yes, it supports optional wake word activation through Porcupine or OpenWakeWord. The setup steps are in docs/wake-words.md.

Does RealtimeSTT have commercial support?

The README gives no support or SLA information, so do not assume commercial support guarantees. Teams that need them should plan their own support arrangements.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

RealtimeSTT suits Python developers who want to add voice input to a prototype, dictation tool or streaming pipeline, and who can work from code examples and docs. It is a poor fit for non-programmers wanting a finished app, for Python 3.13 or newer, or for teams that need guaranteed commercial support. Tools such as whisper.cpp, faster-whisper or Vosk are alternatives to compare if you need a different engine or deployment style.

Install options & downloads