RealtimeSTT

RealtimeSTT operates around a recorder-centered audio pipeline. The internal audio currency is 16 kHz mono PCM. The data flow follows this sequence:

1. Audio Input: Provided via microphone or feed_audio().
2. AudioToTextRecorder: Manages an audio queue.
3. Gating: Processes wake word, VAD (Voice Activity Detection), pre-roll, and recording state.
4. Realtime ASR: Optional realtime ASR and text stabilization.
5. Final ASR Engine: The core transcription engine.
6. Output: Dispatched via callbacks, client/server messages, or the text() return value.

The Transformers backend automatically downloads model and processor files from Hugging Face. You can specify where these are stored using the download_root parameter, which is passed as cache_dir during loading.

recorder = AudioToTextRecorder(
    transcription_engine="moonshine",
    model="UsefulSensors/moonshine-streaming-medium",
    download_root="models/hf",
    language="en",
)

For local testing on CPUs, install the whisper-cpp extra and configure the transcription_engine to "whisper_cpp".

python -m pip install "RealtimeSTT[whisper-cpp]"

from RealtimeSTT import AudioToTextRecorder

if __name__ == "__main__":
    recorder = AudioToTextRecorder(
        transcription_engine="whisper_cpp",
        model="tiny.en",
        device="cpu",
        beam_size=1,
    )
    print(recorder.text())
    recorder.shutdown()

The server provides real-time speech-to-text transcription via WebSocket interfaces. It listens on two ports: a control port for commands and a data port for audio data and transcription updates. Use the stt-server CLI to start it.

stt-server [OPTIONS]

If you are modifying the recorder API, run the following unit tests to validate compatibility across different audio fixtures and backends:

python -m pytest tests\unit\test_audio_fixtures.py
python -m pytest tests\unit\test_slow_final_transcription_audio_gap.py
python -m pytest tests\unit\test_silero_vad_backend.py
python -m pytest tests\unit\test_realtime_text_stabilizer.py
python -m pytest tests\unit\test_realtime_streaming_transcription.py
python -m pytest tests\unit\test_fastapi_server_protocol.py
python -m pytest tests\unit\test_fastapi_server_multi_user.py

To use faster_whisper (the default transcription engine) with RealtimeSTT, install the specific extra via pip.

If installing as a package:

pip install "RealtimeSTT[faster-whisper]"

If installing from a source checkout:

python -m pip install -e ".[faster-whisper]"

To reduce latency in realtime mode, use a smaller model for realtime transcription than your final model.

Recommended Configuration:

• Set enable_realtime_transcription=True.
• Use a smaller realtime_model_type (e.g., tiny.en).
• Adjust realtime_processing_pause (e.g., 0.15).

If you want to save memory, set use_main_model_for_realtime=True. This uses a single shared model, but may reduce responsiveness if the final and realtime tasks contend for the same model resources.

recorder = AudioToTextRecorder(
    model="small.en",
    enable_realtime_transcription=True,
    realtime_model_type="tiny.en",
    realtime_processing_pause=0.15,
)

The project includes unit tests and opt-in integration tests for measuring ASR performance and latency.

Unit Tests

To run fast unit tests (without loading ASR models):

python -m unittest -v \
  tests.unit.test_fastapi_server_protocol \
  tests.unit.test_fastapi_server_multi_user

ASR Integration and Performance Tests

To run tests that load real engines and compare transcripts against expected results, set the following environment variables:

• REALTIMESTT_RUN_FASTAPI_MULTI_USER_ASR=1: Runs integration tests.
• REALTIMESTT_RUN_FASTAPI_MULTI_USER_PERF=1: Runs performance tests (measures latency).

Example command:

REALTIMESTT_RUN_FASTAPI_MULTI_USER_PERF=1 \
python -m unittest -v tests.unit.test_fastapi_server_multi_user_asr_integration

To save the performance report as a JSON file, set REALTIMESTT_FASTAPI_ASR_METRICS_JSON=/path/to/report.json.