RealtimeSTT

https://github.com/koljab/realtimestt
Admin
RealtimeSTT is an easy-to-use, low-latency speech-to-text library that listens to the microphone and...
Tokens:100,048
Snippets:822
Trust Score:9.5
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install RealtimeSTT in a virtual environment (bash)

Source: https://github.com/koljab/realtimestt/blob/master/docs/installation.md

Recommended setup: create a virtual environment and install the faster-whisper extra.

```bash
python -m venv .venv
source .venv/bin/activate
python -m pip install -U pip setuptools wheel
python -m pip install "RealtimeSTT[faster-whisper]"
```

--------------------------------

### Install RealtimeSTT in a virtual environment (PowerShell)

Source: https://github.com/koljab/realtimestt/blob/master/docs/installation.md

Alternative setup on Windows PowerShell: create a virtual environment and install with the faster-whisper extra.

```powershell
python -m venv .venv
.\ .venv\Scripts\Activate.ps1
python -m pip install -U pip setuptools wheel
python -m pip install "RealtimeSTT[faster-whisper]"
```

--------------------------------

### Install and run production server

Source: https://github.com/koljab/realtimestt/blob/master/README.md

Installs the RealtimeSTT server extra with faster-whisper and starts the production server on loopback at port 8010. The server binds to loopback by default; direct non-loopback binds require a bearer token and Uvicorn TLS certificate/key files.

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

--------------------------------

### Install RealtimeSTT[faster-whisper] on Linux

Source: https://github.com/koljab/realtimestt/blob/master/docs/installation.md

Install PortAudio and Python headers on Linux, then install RealtimeSTT with the faster-whisper extra. Optionally install ffmpeg and libsndfile for examples and tests that use them.

```bash
sudo apt-get update
sudo apt-get install python3-dev portaudio19-dev
python -m pip install "RealtimeSTT[faster-whisper]"
```

```bash
sudo apt-get install ffmpeg libsndfile1
```

--------------------------------

### Install and run the FastAPI browser server

Source: https://github.com/koljab/realtimestt/blob/master/docs/fastapi-server.md

These commands set up a virtual environment into install the fastapi browser server dependencies mirror. The bash commands apply to Unix shells with options equivalent to Windows PowerShell commands activating the virtual environment script and installing project files. Adjust the activation script in the install step. After the dependencies, the server starts on host and port. Access the browser UI by opening the URL.

```bash
python -m venv .venv-fastapi
source .venv-fastapi/bin/activate
python -m pip install -U pip setuptools wheel
python -m pip install -r requirements.txt
python -m pip install -r example_fastapi_server/requirements.txt

```

```powershell
python -m venv .venv-fastapi
.\ .venv-fastapi\Scripts\Activate.ps1
python -m pip install -U pip setuptools wheel
python -m pip install -r requirements.txt
python -m pip install -r example_fastapi_server\requirements.txt

```

```bash
python example_fastapi_server/server.py --host 0.0.0.0 --port 8010

```

```text
http://localhost:8010

```

--------------------------------

### Start Server with Default Settings

Source: https://github.com/koljab/realtimestt/blob/master/RealtimeSTT_server/README.md

Starts the server with default settings. Must be running before starting the client.

```bash
stt-server
```

--------------------------------

### Start Moonshine FastAPI example server

Source: https://github.com/koljab/realtimestt/blob/master/docs/engines/moonshine.md

Command to run the FastAPI example server with the Moonshine engine. It sets the engine and real-time engine to Moonshine, using a CUDA device. For CPU, consider the sherpa-onnx Moonshine recipes.

```bash
python example_fastapi_server/server.py \
  --engine moonshine \
  --model UsefulSensors/moonshine-streaming-medium \
  --realtime-engine moonshine \
  --realtime-model UsefulSensors/moonshine-streaming-medium \
  --language en \
  --device cuda

```

--------------------------------

### Start Client with Default Settings

Source: https://github.com/koljab/realtimestt/blob/master/RealtimeSTT_server/README.md

Starts the client with default settings. The client checks if the server is running and can prompt to start it if necessary.

```bash
stt
```

--------------------------------

### Start FastAPI server with Kroko-ONNX engine

Source: https://github.com/koljab/realtimestt/blob/master/docs/engines/kroko-onnx.md

PowerShell command to launch the FastAPI example server with the Kroko-ONNX engine. Sets host, port, engine, model, device, language, and engine options. Uses a local model file path.

```powershell
$model = "test-model-cache\kroko-onnx\Kroko-EN-Community-64-L-Streaming-001.data"
python example_fastapi_server\server.py `
  --host 0.0.0.0 `
  --port 8010 `
  --engine kroko_onnx `
  --model $model `
  --realtime-engine kroko_onnx `
  --realtime-model $model `
  --device cpu `
  --language en `
  --engine-options '{"provider":"cpu","num_threads":2}' `
  --realtime-engine-options '{"provider":"cpu","num_threads":1}'
```

--------------------------------

### Install FunASR in existing environment

Source: https://github.com/koljab/realtimestt/blob/master/docs/engines/funasr.md

Installs FunASR directly in an environment where RealtimeSTT is already installed.

```bash
pip install funasr
```

--------------------------------

### Install dependencies (pip)

Source: https://github.com/koljab/realtimestt/blob/master/docs/engines/hf-transformers.md

Installation commands for the supported engines. The first installs core Transformers and torch required by Granite Speech and Moonshine. The second installs the Qwen3-ASR package. The third adds the optional vLLM backend; vLLM is Linux-oriented and on Windows you should use WSL2 for real vLLM testing.

```bash
python -m pip install transformers torch
```

```bash
python -m pip install -U qwen-asr
```

```bash
python -m pip install -U "qwen-asr[vllm]"
```

--------------------------------

### Run FastAPI server with whisper.cpp CPU

Source: https://github.com/koljab/realtimestt/blob/master/docs/fastapi-server.md

Installs the RealtimeSTT with the whisper-cpp extra and starts the server with whisper.cpp engine on CPU, using tiny.en for both final and realtime models, with beam sizes and engine options for threading and transcription settings.

```bash
python -m pip install "RealtimeSTT[whisper-cpp]"
python example_fastapi_server/server.py \
  --host 0.0.0.0 \
  --port 8010 \
  --engine whisper_cpp \
  --model tiny.en \
  --realtime-engine whisper_cpp \
  --realtime-model tiny.en \
  --device cpu \
  --beam-size 5 \
  --beam-size-realtime 1 \
  --download-root test-model-cache/pywhispercpp \
  --engine-options '{"model":{"n_threads":8,"redirect_whispercpp_logs_to":null}}' \
  --realtime-engine-options '{"model":{"n_threads":8,"redirect_whispercpp_logs_to":null},"transcribe":{"single_segment":true,"no_context":true,"print_timestamps":false}}'
```

--------------------------------

### Install RealtimeSTT with transcribe-cpp extra

Source: https://github.com/koljab/realtimestt/blob/master/docs/engines/transcribe-cpp.md

Installs RealtimeSTT with the transcribe-cpp extra to get the portable Python binding.

```bash
python -m pip install "RealtimeSTT[transcribe-cpp]"
```

--------------------------------

### CPU-Friendly Engine Example with whisper.cpp

Source: https://github.com/koljab/realtimestt/blob/master/docs/quick-start.md

Shows the CPU-friendly engine example using whisper.cpp. First install the optional dependency, then configure `transcription_engine` to `whisper_cpp` with a small CPU model and beam size of 1.

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

```

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

```

--------------------------------

### Install Kroko-ONNX with builder helper

Source: https://github.com/koljab/realtimestt/blob/master/docs/engines/kroko-onnx.md

Installs the RealtimeSTT extras for Kroko-ONNX building and Silero ONNX CPU VAD, then runs the builder to build and install Kroko-ONNX. The silero-onnx-cpu extra is needed for the standalone recorder smoke test and live microphone use; kroko-builder alone is enough if only building the wheel.

```bash
python -m pip install "RealtimeSTT[kroko-builder,silero-onnx-cpu]"
stt-install-kroko --build
```

--------------------------------

### Install RealtimeSTT Engine Extras

Source: https://github.com/koljab/realtimestt/blob/master/docs/installation.md

Install only the engine stack you plan to use. Each command installs the corresponding RealtimeSTT extra. The kroko command requires the preceding kroko-builder and silero-onnx-cpu install, and builds the engine.

```bash
python -m pip install "RealtimeSTT[faster-whisper]"
```

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

```bash
python -m pip install "RealtimeSTT[openai-whisper]"
```

```bash
python -m pip install "RealtimeSTT[moonshine]"
```

```bash
python -m pip install "RealtimeSTT[sherpa-onnx]"
```

```bash
python -m pip install -U "RealtimeSTT[parakeet]"
```

```bash
python -m pip install "RealtimeSTT[omnilingual]"
```

```bash
python -m pip install "RealtimeSTT[granite]"
```

```bash
python -m pip install -U "RealtimeSTT[qwen]"
```

```bash
python -m pip install "RealtimeSTT[cohere]"
```

```bash
python -m pip install "RealtimeSTT[kroko-builder,silero-onnx-cpu]"
```

```bash
stt-install-kroko --build
```

--------------------------------

### Run default faster-whisper server

Source: https://github.com/koljab/realtimestt/blob/master/example_fastapi_server/README.md

Starts the FastAPI server with default faster-whisper setup on host 0.0.0.0 and port 8010.

```bash
python example_fastapi_server/server.py --host 0.0.0.0 --port 8010
```

--------------------------------

### Run FastAPI server with whisper.cpp CPU engine (tiny.en)

Source: https://github.com/koljab/realtimestt/blob/master/example_fastapi_server/README.md

Starts the example FastAPI server on 0.0.0.0:8010 using whisper.cpp for both realtime and final transcription with the tiny.en model. Realtime uses greedy decoding and single-segment/no-context settings for faster interim text. Requires PYTHON_EXE to point at the active virtual environment.

```cmd
"%PYTHON_EXE%" example_fastapi_server\server.py --host 0.0.0.0 --port 8010 --engine whisper_cpp --model tiny.en --realtime-engine whisper_cpp --realtime-model tiny.en --device cpu --beam-size 5 --beam-size-realtime 1 --download-root test-model-cache\pywhispercpp --engine-options "{"model":{"n_threads":8,"redirect_whispercpp_logs_to":null}}" --realtime-engine-options "{"model":{"n_threads":8,"redirect_whispercpp_logs_to":null},"transcribe":{"single_segment":true,"no_context":true,"print_timestamps":false}}"
```

--------------------------------

### Install RealtimeSTT server and sherpa-onnx models

Source: https://github.com/koljab/realtimestt/blob/master/README.md

Install the CPU server stack and both pinned model bundles. This command installs the RealtimeSTT package with the server and sherpa-onnx extras, then downloads all sherpa-onnx models to the ./models/sherpa-onnx directory.

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

--------------------------------

### start(frames=None)

Source: https://github.com/koljab/realtimestt/blob/master/docs/api-compatibility.md

Manually starts recording without waiting for voice activity. Returns self for chaining.

```APIDOC
## start(frames=None)

### Description
Manually starts recording without waiting for voice activity. Returns `self` to enable chaining like `recorder.stop().text()`.

### Method
Callable method

### Parameters
- **frames** (optional) - Initial frames to include in the recording.

### Behavior
- Returns `self`, enabling `recorder.stop().text()` style usage.
- Respects `min_gap_between_recordings`; if called too soon, it logs and returns `self` without starting.
- Sets state to `"recording"`.
- Clears previous text/realtime state for the new recording.
- Increments the realtime recording generation and resets the realtime stabilizer.
- Resets Silero VAD state.
- Sets `is_recording=True`, clears the stop event, and sets the start event.
- Runs `on_recording_start` when provided.
- Accepts optional initial `frames`, which tests use directly.
```

--------------------------------

### Install Kroko/Banafo ASR with builder and VAD extras

Source: https://github.com/koljab/realtimestt/blob/master/README.md

Installs RealtimeSTT with the kroko-builder and silero-onnx-cpu extras, then builds the Kroko engine. The silero-onnx-cpu extra provides a local VAD backend for AudioToTextRecorder, useful for smoke tests and live microphone use.

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

--------------------------------

### Install ffmpeg on Windows with Scoop

Source: https://github.com/koljab/realtimestt/blob/master/example_app/README.MD

Install ffmpeg on Windows using Scoop.

```bash
scoop install ffmpeg
```

--------------------------------

### Run FastAPI server with Omnilingual ASR engine

Source: https://github.com/koljab/realtimestt/blob/master/docs/engines/omnilingual-asr.md

Starts the FastAPI server from a source checkout in WSL2/Linux. Requires PYTHONPATH=. and the 'server' extra for FastAPI dependency. Uses example_fastapi_server/server.py, not the installed stt-server console script. Open http://localhost:8010/ from a Windows browser.

```bash
PYTHONPATH=. python example_fastapi_server/server.py \
  --host 0.0.0.0 \
  --port 8010 \
  --engine omnilingual_asr \
  --model omniASR_CTC_1B_v2 \
  --realtime-engine omnilingual_asr \
  --realtime-model omniASR_CTC_1B_v2 \
  --use-main-model-for-realtime \
  --device cuda \
  --compute-type float16 \
  --realtime-processing-pause 0.05 \
  --engine-options '{"batch_size":1,"sample_rate":16000}'
```

--------------------------------

### Install RealtimeSTT with FunASR extra

Source: https://github.com/koljab/realtimestt/blob/master/docs/engines/funasr.md

Installs RealtimeSTT with the FunASR extra. Equivalent extras 'fun-asr', 'fun_asr', and 'sensevoice' are also available.

```bash
pip install "realtimestt[funasr]"
```

--------------------------------

### Install Porcupine and use wake word 'jarvis' with AudioToTextRecorder

Source: https://github.com/koljab/realtimestt/blob/master/docs/wake-words.md

Install the Porcupine extra and configure AudioToTextRecorder with wakeword_backend='pvporcupine' and wake_words='jarvis'. The recorder waits for the 'jarvis' keyword before capturing speech; call recorder.text() to get the spoken text.

```bash
python -m pip install "RealtimeSTT[porcupine]"
```

```python
from RealtimeSTT import AudioToTextRecorder

if __name__ == "__main__":
    recorder = AudioToTextRecorder(
        wakeword_backend="pvporcupine",
        wake_words="jarvis",
    )

    print('Say "Jarvis" and then speak.')
    print(recorder.text())
    recorder.shutdown()
```

--------------------------------

### Install base RealtimeSTT package

Source: https://github.com/koljab/realtimestt/blob/master/docs/installation.md

Use this command to install the base recorder/audio runtime without a transcription engine or wake-word backend.

```bash
python -m pip install RealtimeSTT
```

--------------------------------

### Install Meta Omnilingual ASR engine

Source: https://github.com/koljab/realtimestt/blob/master/example_fastapi_server/README.md

Installs RealtimeSTT with the omnilingual extra. Use Linux or WSL2. From a source checkout, use the editable install.

```bash
python -m pip install "RealtimeSTT[omnilingual]"
```

```bash
python -m pip install -e ".[omnilingual]"
```

--------------------------------

### Install faster-whisper extra from source

Source: https://github.com/koljab/realtimestt/blob/master/docs/engines/faster-whisper.md

Installs the faster-whisper extra from a source checkout. Use this when working from the repository.

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

--------------------------------

### Verify Installation with AudioToTextRecorder

Source: https://github.com/koljab/realtimestt/blob/master/docs/installation.md

Run this script to check that the RealtimeSTT library was installed correctly. It creates an AudioToTextRecorder with the "tiny" model on CPU, prompts for speech, and prints the recognized text. Requires the RealtimeSTT package to be importable.

```python
from RealtimeSTT import AudioToTextRecorder

if __name__ == "__main__":
    with AudioToTextRecorder(model="tiny", device="cpu") as recorder:
        print("Speak now")
        print(recorder.text())
```

--------------------------------

### Install from source checkout with Omnilingual extra

Source: https://github.com/koljab/realtimestt/blob/master/docs/engines/omnilingual-asr.md

Installs RealtimeSTT from a source checkout with the Omnilingual extra. The extra is guarded with a non-Windows platform marker, so native Windows installs skip the runtime dependency.

```bash
python -m pip install -e ".[omnilingual]"
```

--------------------------------

### Install RealtimeSTT[faster-whisper] on macOS

Source: https://github.com/koljab/realtimestt/blob/master/docs/installation.md

Install PortAudio via Homebrew on macOS, then install RealtimeSTT with the faster-whisper extra.

```bash
brew install portaudio
python -m pip install "RealtimeSTT[faster-whisper]"
```

--------------------------------

### Install RealtimeSTT with faster-whisper engine

Source: https://github.com/koljab/realtimestt/blob/master/README.md

Installs the RealtimeSTT package with the faster-whisper extra, which is the default engine. This is the standard installation command for the library.

```bash
pip install "RealtimeSTT[faster-whisper]"
```

--------------------------------

### Install both wake-word backends

Source: https://github.com/koljab/realtimestt/blob/master/docs/installation.md

Installs both wake-word backends (Porcupine and OpenWakeWord) via the 'wakewords' extra.

```bash
python -m pip install "RealtimeSTT[wakewords]"
```

--------------------------------

### Install Linux dependencies for RealtimeSTT

Source: https://github.com/koljab/realtimestt/blob/master/README.md

On Linux, install PortAudio headers before installing the package. These commands update the package list and install python3-dev and portaudio19-dev.

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

--------------------------------

### Run whisper.cpp interactive demo

Source: https://github.com/koljab/realtimestt/blob/master/docs/test-scripts.md

Commands to install dependencies and run the whisper.cpp interactive demo with balanced profile.

```bash
python -m pip install "RealtimeSTT[whisper-cpp]" rich pyautogui colorama
```

```bash
python tests/realtimestt_test_whispercpp.py --profile balanced
```

--------------------------------

### Install CPU whisper.cpp engine

Source: https://github.com/koljab/realtimestt/blob/master/example_fastapi_server/README.md

Installs pywhispercpp for CPU-based whisper.cpp support.

```bash
python -m pip install pywhispercpp
```

--------------------------------

### Install huggingface_hub

Source: https://github.com/koljab/realtimestt/blob/master/docs/engines/kroko-onnx.md

Installs the huggingface_hub package via pip, needed for the model download command if the kroko-builder extra was not installed.

```powershell
python -m pip install huggingface_hub
```

--------------------------------

### Run server with capacity flags

Source: https://github.com/koljab/realtimestt/blob/master/example_fastapi_server/README.md

Starts the server with configurable session and queue limits for multi-user mode.

```bash
python example_fastapi_server/server.py \
  --max-sessions 4 \
  --max-active-speakers 4 \
  --max-global-inference-queue-depth 64 \
  --max-final-queue-depth-per-session 8 \
  --max-realtime-queue-age-ms 1500 \
  --max-audio-queue-seconds-per-session 30
```

--------------------------------

### Install macOS dependency for RealtimeSTT

Source: https://github.com/koljab/realtimestt/blob/master/README.md

On macOS, install PortAudio using Homebrew before installing the package.

```bash
brew install portaudio
```

--------------------------------

### Open browser UI

Source: https://github.com/koljab/realtimestt/blob/master/example_fastapi_server/README.md

URL to open the browser UI after starting the server.

```text
http://localhost:8010
```

--------------------------------

### Install sherpa-onnx models for CPU INT8 deployment

Source: https://github.com/koljab/realtimestt/blob/master/RealtimeSTT_server/PRODUCTION_SERVER.md

Installs the server and sherpa-onnx extras, then downloads all pinned sherpa-onnx models into persistent storage with resumable downloads and atomic extraction.

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

--------------------------------

### Install CUDA PyTorch and RealtimeSTT faster-whisper

Source: https://github.com/koljab/realtimestt/blob/master/docs/installation.md

Install CUDA-enabled PyTorch and torchaudio, then install RealtimeSTT with the faster-whisper extra. Required for GPU inference with low-latency Whisper models. Use the PyTorch install selector for the exact command matching your driver and CUDA version.

```bash
python -m pip install torch torchaudio --index-url https://download.pytorch.org/whl/cu121
```

```bash
python -m pip install "RealtimeSTT[faster-whisper]"
```

--------------------------------

### Start STT Client with stt [OPTIONS]

Source: https://github.com/koljab/realtimestt/blob/master/RealtimeSTT_server/README.md

Starts the STT client, which connects to the STT server's control and data WebSocket URLs for real-time speech transcription and control.

```bash
stt [OPTIONS]
```

--------------------------------

### Install OpenWakeWord and use custom model with 'oww' backend

Source: https://github.com/koljab/realtimestt/blob/master/docs/wake-words.md

Install the OpenWakeWord extra and configure AudioToTextRecorder with wakeword_backend='oww', a custom model path, sensitivity 0.35, and a 1.0 second buffer. The model name is inferred from the file, so wake_words is not required.

```bash
python -m pip install "RealtimeSTT[openwakeword]"
```

```python
from RealtimeSTT import AudioToTextRecorder

if __name__ == "__main__":
    recorder = AudioToTextRecorder(
        wakeword_backend="oww",
        openwakeword_model_paths="models/hey_assistant.onnx",
        wake_words_sensitivity=0.35,
        wake_word_buffer_duration=1.0,
    )

    print("Say the trained wake word and then speak.")
    print(recorder.text())
    recorder.shutdown()
```

--------------------------------

### Install ffmpeg on Arch Linux

Source: https://github.com/koljab/realtimestt/blob/master/example_app/README.MD

Install ffmpeg on Arch Linux using pacman.

```bash
sudo pacman -S ffmpeg
```

--------------------------------

### Install RealtimeSTT FastAPI server dependencies

Source: https://github.com/koljab/realtimestt/blob/master/example_fastapi_server/README.md

Creates a virtual environment and installs required packages for the FastAPI server. Use on Linux for CUDA-heavy engines.

```bash
python -m venv .venv-fastapi
source .venv-fastapi/bin/activate
python -m pip install -U pip setuptools wheel
python -m pip install -r requirements.txt
python -m pip install -r example_fastapi_server/requirements.txt
```

--------------------------------

### Install Kroko-ONNX with extras

Source: https://github.com/koljab/realtimestt/blob/master/RELEASE_NOTES.md

Command to install the necessary dependencies for Kroko-ONNX and Silero VAD support.

```bash
pip install "RealtimeSTT[kroko-builder,silero-onnx-cpu]"
```

--------------------------------

### Install ffmpeg on Windows with Chocolatey

Source: https://github.com/koljab/realtimestt/blob/master/example_app/README.MD

Install ffmpeg on Windows using Chocolatey.

```bash
choco install ffmpeg
```

--------------------------------

### Install mpv on macOS for ElevenlabsEngine

Source: https://github.com/koljab/realtimestt/blob/master/example_app/README.MD

Install mpv on macOS using Homebrew, required for ElevenlabsEngine streaming.

```bash
brew install mpv
```

--------------------------------

### Install OpenWakeWord dependency

Source: https://github.com/koljab/realtimestt/blob/master/docs/installation.md

Installs the OpenWakeWord dependency through the RealtimeSTT 'openwakeword' extra.

```bash
python -m pip install "RealtimeSTT[openwakeword]"
```

--------------------------------

### Run server with wake word mode

Source: https://github.com/koljab/realtimestt/blob/master/example_fastapi_server/README.md

Starts the server with wake word backend pvporcupine and wake word 'jarvis' with sensitivity and timeout settings.

```bash
python example_fastapi_server/server.py \
  --wakeword-backend pvporcupine \
  --wake-words jarvis \
  --wake-words-sensitivity 0.7 \
  --wake-word-timeout 5 \
  --wake-word-followup-window 5
```

--------------------------------

### Start the RealtimeSTT server

Source: https://github.com/koljab/realtimestt/blob/master/RealtimeSTT_server/README.md

Starts the RealtimeSTT server, which initializes and listens for WebSocket connections on the configured control and data ports. Accepts the command-line parameters listed in the server documentation.

```bash
stt-server [OPTIONS]
```

--------------------------------

### Install Moonshine dependencies with pip

Source: https://github.com/koljab/realtimestt/blob/master/docs/engines/moonshine.md

Installs the required Python packages. Install a CUDA-enabled PyTorch wheel first if you plan to run on GPU.

```bash
python -m pip install transformers torch

```

--------------------------------

### Install dependencies

Source: https://github.com/koljab/realtimestt/blob/master/tests/README.md

Upgrades pip, installs RealtimeSTT, and installs PyTorch with CUDA 12.1 support. Adjust the PyTorch index URL if a different CUDA version is required.

```bash
python -m pip install --upgrade pip
python -m pip install RealtimeSTT
python -m pip install -U torch torchaudio --index-url https://download.pytorch.org/whl/cu121
```

--------------------------------

### Install CPU sherpa-onnx Moonshine engine

Source: https://github.com/koljab/realtimestt/blob/master/example_fastapi_server/README.md

Installs sherpa-onnx for CPU-based Moonshine support.

```bash
python -m pip install sherpa-onnx
```

--------------------------------

### Install sherpa-onnx models for production server

Source: https://github.com/koljab/realtimestt/blob/master/README.md

Installs all sherpa-onnx models into the specified root directory. This is required for CPU INT8 deployment with the recommended model pairing: 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 final transcription.

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

--------------------------------

### Command: start

Source: https://github.com/koljab/realtimestt/blob/master/RealtimeSTT_server/PRODUCTION_SERVER.md

Starts a new transcription turn with an optional language specification.

```APIDOC
## Command: start

### Description
Starts a new transcription turn with an optional language specification.

### Command Type
`start`

### Parameters
- **turnId** (string) - Required - Unique identifier for the turn.
- **language** (string) - Optional - Language code for transcription.

### Request Example

{"type":"start","turnId":"turn-1","language":"en"}

```

--------------------------------

### Run production server with stt-server-production

Source: https://github.com/koljab/realtimestt/blob/master/RealtimeSTT_server/PRODUCTION_SERVER.md

Starts the production server on loopback with default settings. The default bind is loopback; a non-loopback bind requires a bearer token and TLS files.

```text
stt-server-production --host 127.0.0.1 --port 8010
```

--------------------------------

### Install RealtimeSTT with whisper-cpp extra

Source: https://github.com/koljab/realtimestt/blob/master/docs/engines/whisper-cpp.md

Installs the RealtimeSTT package with the optional whisper.cpp engine dependency.

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

--------------------------------

### Install ffmpeg on Ubuntu/Debian

Source: https://github.com/koljab/realtimestt/blob/master/example_app/README.MD

Install ffmpeg on Ubuntu or Debian using the package manager.

```bash
sudo apt update && sudo apt install ffmpeg
```

--------------------------------

### listen()

Source: https://github.com/koljab/realtimestt/blob/master/docs/api-compatibility.md

Enters listening state and arms voice activity start.

```APIDOC
## listen()

### Description
Enters listening state and arms voice activity start.

### Method
listen()

### Parameters
None

### Return Value
None
```

--------------------------------

### wakeup()

Source: https://github.com/koljab/realtimestt/blob/master/docs/api-compatibility.md

Simulates wake-word activation by setting the listen start time.

```APIDOC
## wakeup()

### Description
Simulates wake-word activation by setting the listen start time.

### Method
wakeup()

### Parameters
None

### Return Value
None
```

--------------------------------

### Install Kroko-ONNX engine

Source: https://github.com/koljab/realtimestt/blob/master/example_fastapi_server/README.md

Clones and installs Kroko-ONNX from GitHub. Note: Linux/Docker-oriented upstream; use WSL2/Linux if native Windows builds fail.

```bash
git clone https://github.com/kroko-ai/kroko-onnx.git
cd kroko-onnx
python -m pip install .
```

--------------------------------

### Install ffmpeg on macOS with Homebrew

Source: https://github.com/koljab/realtimestt/blob/master/example_app/README.MD

Install ffmpeg on macOS using Homebrew.

```bash
brew install ffmpeg
```

--------------------------------

### Install RealtimeSTT with sherpa-onnx extra

Source: https://github.com/koljab/realtimestt/blob/master/docs/engines/sherpa-onnx.md

Installs RealtimeSTT with the sherpa-onnx extra, which includes the CPU INT8 sherpa-onnx engines.

```bash
python -m pip install "RealtimeSTT[sherpa-onnx]"
```

--------------------------------

### Start and stop to get transcription

Source: https://github.com/koljab/realtimestt/blob/master/docs/api-compatibility.md

Starts recording, then stops and retrieves the transcription from the returned recorder.

```python
recorder.start()
user_text = recorder.stop().text()
```

--------------------------------

### Manual Start and Stop with start() and stop()

Source: https://github.com/koljab/realtimestt/blob/master/docs/quick-start.md

Provides manual control with `start()` and `stop()`. The application decides when recording begins and ends. After `stop()`, `text()` returns the final transcription, and `shutdown()` cleans up.

```python
from RealtimeSTT import AudioToTextRecorder

if __name__ == "__main__":
    recorder = AudioToTextRecorder()
    recorder.start()
    input("Press Enter to stop recording...")
    recorder.stop()
    print(recorder.text())
    recorder.shutdown()

```

--------------------------------

### Install RealtimeSTT with Omnilingual extra

Source: https://github.com/koljab/realtimestt/blob/master/docs/engines/omnilingual-asr.md

Installs RealtimeSTT with the Omnilingual extra. Requires Linux or WSL2 with Python 3.11.x; native Windows or Python 3.12.x are not supported.

```bash
python -m pip install "RealtimeSTT[omnilingual]"
```

--------------------------------

### Install RealtimeSTT server package

Source: https://github.com/koljab/realtimestt/blob/master/RealtimeSTT_server/README.md

Install the stable RealtimeSTT server package version 1.1.2 with its server dependencies. Requires Python 3.11 or 3.12.

```bash
python -m pip install "RealtimeSTT[server]==1.1.2"
```

--------------------------------

### Basic Parakeet recorder setup

Source: https://github.com/koljab/realtimestt/blob/master/docs/engines/parakeet-nemo.md

Initializes the recorder with the Parakeet engine, specifying the model, CUDA device, and language. This is the basic setup for using Parakeet with NeMo.

```python
from RealtimeSTT import AudioToTextRecorder

recorder = AudioToTextRecorder(
    transcription_engine="parakeet",
    model="nvidia/parakeet-tdt-0.6b-v3",
    device="cuda",
    language="en",
)
```

--------------------------------

### Install Cohere Transcribe dependencies

Source: https://github.com/koljab/realtimestt/blob/master/docs/engines/cohere.md

Installs the required Transformers and PyTorch libraries for the Cohere Transcribe adapter. Additional model-specific dependencies may be needed depending on the Transformers release.

```bash
python -m pip install transformers torch
```

--------------------------------

### Build Kroko-ONNX

Source: https://github.com/koljab/realtimestt/blob/master/RELEASE_NOTES.md

Command to build and install Kroko-ONNX for the active Python environment after installing the required extras.

```bash
stt-install-kroko --build
```

--------------------------------

### Install Parakeet engine stack

Source: https://github.com/koljab/realtimestt/blob/master/example_fastapi_server/README.md

Installs the NeMo toolkit with ASR support, soundfile, and librosa for the Parakeet engine.

```bash
python -m pip install "nemo_toolkit[asr]" soundfile librosa
```

--------------------------------

### Run standalone Kroko test script (init-only mode)

Source: https://github.com/koljab/realtimestt/blob/master/docs/engines/kroko-onnx.md

Installs the 'rich' package and runs the standalone Kroko test script in init-only mode. The script constructs AudioToTextRecorder, so it requires both Kroko-ONNX and a working recorder VAD backend. The install command includes 'silero-onnx-cpu' for that reason.

```powershell
python -m pip install rich
python .\realtimestt_kroko_test.py --model "test-model-cache\kroko-onnx\Kroko-EN-Community-64-L-Streaming-001.data" --realtime-model "test-model-cache\kroko-onnx\Kroko-EN-Community-64-L-Streaming-001.data" --provider cpu --no-keyboard --init-only
```

--------------------------------

### Run the test script

Source: https://github.com/koljab/realtimestt/blob/master/tests/README.md

Runs the openwakeword test script. On first start, some openwakeword models are downloaded.

```bash
python openwakeword_test.py
```

--------------------------------

### Install Porcupine wake word dependency

Source: https://github.com/koljab/realtimestt/blob/master/docs/installation.md

Installs the Porcupine wake word dependency through the RealtimeSTT 'porcupine' extra.

```bash
python -m pip install "RealtimeSTT[porcupine]"
```

--------------------------------

### Install Orukeet model with stt-install-sherpa-models

Source: https://github.com/koljab/realtimestt/blob/master/docs/engines/sherpa-onnx.md

Installs the Orukeet model explicitly using the pinned export. The installer downloads the release manifest and a 487 MB archive from Hugging Face, verifies SHA-256 hashes, and preserves the CC BY-SA 4.0 license and NVIDIA attribution. Extracted files occupy about 672 MB.

```sh
stt-install-sherpa-models --root ./models/sherpa-onnx --model orukeet
```

--------------------------------

### Install sherpa-onnx models for real RTF comparison

Source: https://github.com/koljab/realtimestt/blob/master/docs/testing.md

Installs the pinned Nemotron and Parakeet bundles under the persistent test-model-cache\sherpa-onnx root using the stt-install-sherpa-models command. Required before running the opt-in smoke tests.

```powershell
stt-install-sherpa-models --root test-model-cache\sherpa-onnx --model all
```

--------------------------------

### Install NeMo ASR and soundfile

Source: https://github.com/koljab/realtimestt/blob/master/docs/engines/parakeet-nemo.md

Installs the NeMo ASR toolkit and soundfile for Parakeet model support. NeMo ASR is primarily supported on Linux; on Windows, use WSL2 for real-model testing.

```bash
python -m pip install -U "nemo_toolkit[asr]" soundfile
```

--------------------------------

### Install CUDA provider wheel for transcribe.cpp 0.2.1

Source: https://github.com/koljab/realtimestt/blob/master/docs/engines/transcribe-cpp.md

Installs the official CUDA provider wheel from the upstream GitHub release for Linux x86-64. The wheel is not on PyPI under the matching version.

```bash
python -m pip install \
  "https://github.com/handy-computer/transcribe.cpp/releases/download/v0.2.1/transcribe_cpp_native_cu12-0.2.1-py3-none-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl"
```

--------------------------------

### Set up openwakeword test project

Source: https://github.com/koljab/realtimestt/blob/master/tests/README.md

Creates a directory and downloads the test script and two ONNX model files from Hugging Face. Requires curl; if not installed, download manually from the provided URLs.

```bash
mkdir samantha_wake_word && cd samantha_wake_word
curl -O https://raw.githubusercontent.com/KoljaB/RealtimeSTT/master/tests/openwakeword_test.py
curl -L https://huggingface.co/KoljaB/SamanthaOpenwakeword/resolve/main/suh_mahn_thuh.onnx -o suh_mahn_thuh.onnx
curl -L https://huggingface.co/KoljaB/SamanthaOpenwakeword/resolve/main/suh_man_tuh.onnx -o suh_man_tuh.onnx
```

--------------------------------

### Convert TFLite model to ONNX with tf2onnx

Source: https://github.com/koljab/realtimestt/blob/master/docs/wake-words.md

Install tf2onnx and convert a TensorFlow Lite model to ONNX format. Run these commands to produce an ONNX model for OpenWakeWord when starting from a .tflite file.

```bash
python -m pip install -U tf2onnx
python -m tf2onnx.convert --tflite my_model.tflite --output my_model.onnx
```

--------------------------------

### Install RealtimeSTT with Omnilingual extra in a virtualenv

Source: https://github.com/koljab/realtimestt/blob/master/docs/installation.md

Sets up a Python 3.11.x virtual environment and installs RealtimeSTT with the omnilingual extra. Use on Linux or WSL2; native Windows lacks a fairseq2n wheel and omnilingual-asr==0.2.0 excludes Python 3.12 patch releases such as 3.12.3.

```bash
python -m venv .venv
source .venv/bin/activate
python -m pip install -U pip setuptools wheel
python -m pip install "RealtimeSTT[omnilingual]"
```

--------------------------------

### Raise TranscriptionEngineError for missing dependency

Source: https://github.com/koljab/realtimestt/blob/master/docs/custom-transcription-engines.md

Raises TranscriptionEngineError when an optional dependency is missing, wrapping the ModuleNotFoundError with a helpful install message. Use this pattern for setup or runtime failures that should be reported as engine failures.

```python
from RealtimeSTT.engines import TranscriptionEngineError


def load_backend():
    try:
        import my_asr_package
    except ModuleNotFoundError as exc:
        raise TranscriptionEngineError(
            "The custom engine requires 'my-asr-package'. "
            "Install it with 'pip install my-asr-package'."
        ) from exc
    return my_asr_package
```

--------------------------------

### Word timestamps in transcription result

Source: https://github.com/koljab/realtimestt/blob/master/docs/custom-transcription-engines.md

Accept the word_timestamps request flag and put word timings in result metadata. The example shows the expected metadata structure with word, start, and end fields.

```python
def transcribe(self, audio, language=None, use_prompt=True, **kwargs):
    include_words = kwargs.get("word_timestamps", False)

    metadata = {}
    if include_words:
        metadata["words"] = [
            {"word": "hello", "start": 0.10, "end": 0.42},
            {"word": "world", "start": 0.50, "end": 0.86},
        ]

    return TranscriptionResult(
        text="hello world",
        metadata=metadata,
    )
```

--------------------------------

### Download and run real model smoke test for Omnilingual

Source: https://github.com/koljab/realtimestt/blob/master/docs/engines/omnilingual-asr.md

Downloads a standalone smoke test script and runs it with the Omnilingual runtime installed in WSL2/Linux. Pip-only users can use this script. Start with the omniASR_CTC_1B_v2 model.

```bash
curl -L https://raw.githubusercontent.com/KoljaB/RealtimeSTT/release/v1.0.1/tests/realtimestt_omnilingual_test.py -o realtimestt_omnilingual_test.py
python realtimestt_omnilingual_test.py --file-smoke --device cuda
```

--------------------------------

### text() usage: get final transcription or pass callback

Source: https://github.com/koljab/realtimestt/blob/master/docs/api-compatibility.md

Common external usage of text(). Without a callback, returns the final transcription string. With a callback, starts a thread that calls the callback with the final string.

```python
text = recorder.text()
recorder.text(process_text)
```

--------------------------------

### stt [OPTIONS]

Source: https://github.com/koljab/realtimestt/blob/master/RealtimeSTT_server/README.md

Starts the RealtimeSTT client, connecting to the STT server's control and data WebSocket URLs for real-time speech transcription and control.

```APIDOC
## stt [OPTIONS]

### Description
Starts the RealtimeSTT client, connecting to the STT server's control and data WebSocket URLs for real-time speech transcription and control.

### Usage
```bash
stt [OPTIONS]
```

### Parameters

#### `-i`, `--input-device`
- **Type**: `int`
- **Metavar**: `INDEX`
- **Description**: Audio input device index. Use `-L` to list available devices.

#### `-l`, `--language`
- **Type**: `str`
- **Default**: `'en'`
- **Metavar**: `LANG`
- **Description**: Language code to be used for transcription.

#### `-sed`, `--speech-end-detection`
- **Action**: `store_true`
- **Description**: Enable intelligent speech end detection for better sentence boundaries.

#### `-D`, `--debug`
- **Action**: `store_true`
- **Description**: Enable debug mode for detailed logging.

#### `-n`, `--norealtime`
- **Action**: `store_true`
- **Description**: Disable real-time transcription output.

#### `-W`, `--write`
- **Metavar**: `FILE`
- **Description**: Save recorded audio to a WAV file.

#### `-s`, `--set`
- **Type**: `list`
- **Metavar**: `('PARAM', 'VALUE')`
- **Action**: `append`
- **Description**: Set a recorder parameter. Can be used multiple times with different parameters.

#### `-m`, `--method`
- **Type**: `list`
- **Metavar**: `METHOD`
- **Action**: `append`
- **Description**: Call a recorder method with optional arguments.

#### `-g`, `--get`
- **Type**: `list`
- **Metavar**: `PARAM`
- **Action**: `append`
- **Description**: Get the value of a recorder parameter.

#### `-c`, `--continuous`
- **Action**: `store_true`
- **Description**: Run in continuous mode, transcribing speech without exiting.

#### `-L`, `--list`
- **Action**: `store_true`
- **Description**: List all available audio input devices and exit.

#### `--control`, `--control_url`
- **Type**: `str`
- **Default**: `ws://127.0.0.1:8011`
- **Description**: WebSocket URL for STT control connection.

#### `--data`, `--data_url`
- **Type**: `str`
- **Default**: `ws://127.0.0.1:8012`
- **Description**: WebSocket URL for STT data connection.

### Parameters only available when speech-end-detection is active:

#### `--post-silence`
- **Type**: `float`
- **Default**: `1.0`
- **Description**: Post speech silence duration in seconds.

#### `--unknown-pause`
- **Type**: `float`
- **Default**: `1.3`
- **Description**: Unknown sentence detection pause duration in seconds.

#### `--mid-pause`
- **Type**: `float`
- **Default**: `3.0`
- **Description**: Mid-sentence detection pause duration in seconds.

#### `--end-pause`
- **Type**: `float`
- **Default**: `0.7`
- **Description**: End of sentence detection pause duration in seconds.

#### `--hard-break`
- **Type**: `float`
- **Default**: `3.0`
- **Description**: Hard break threshold in seconds when background noise is present.

#### `--min-texts`
- **Type**: `int`
- **Default**: `3`
- **Description**: Minimum number of texts required for hard break detection.

#### `--min-similarity`
- **Type**: `float`
- **Default**: `0.99`
- **Description**: Minimum text similarity threshold for hard break detection.

#### `--min-chars`
- **Type**: `int`
- **Default**: `15`
- **Description**: Minimum number of characters required for hard break detection.

### Examples

```bash
# List available audio devices
stt -L

# Use specific input device and language
stt -i 1 -l en

# Enable intelligent speech end detection and continuous mode
stt -sed -c

# Set parameter and save audio
stt -s silero_sensitivity 0.1 -W recording.wav

# Use custom WebSocket URLs
stt --control ws://localhost:9001 --data ws://localhost:9002
```
```

--------------------------------

### Initialize AudioToTextRecorder with transformers engines

Source: https://github.com/koljab/realtimestt/blob/master/docs/engines/hf-transformers.md

Recorder setups for Transformers-backed engines. The first sets a writable download_root for predictable model file caching. The second shows Granite Speech with CUDA and generation options (max_new_tokens=200, do_sample=False). The third configures Qwen3-ASR with English and CUDA. These engines may require accepting license or gated access terms before download.

```python
recorder = AudioToTextRecorder(
    transcription_engine="granite_speech",
    model="ibm-granite/granite-speech-4.1-2b",
    download_root="models/hf",
)
```

```python
from RealtimeSTT import AudioToTextRecorder

recorder = AudioToTextRecorder(
    transcription_engine="granite_speech",
    model="ibm-granite/granite-speech-4.1-2b",
    device="cuda",
    transcription_engine_options={
        "generate": {
            "max_new_tokens": 200,
            "do_sample": False,
        },
    },
)
```

```python
recorder = AudioToTextRecorder(
    transcription_engine="qwen3_asr",
    model="Qwen/Qwen3-ASR-1.7B",
    language="en",
    device="cuda",
)
```

--------------------------------

### Basic Moonshine recorder setup

Source: https://github.com/koljab/realtimestt/blob/master/docs/engines/moonshine.md

Creates a Moonshine audio-to-text recorder using the Transformers backend. This configuration uses the CUDA device with an English model. For CPU, use a smaller model and device="cpu".

```python
from RealtimeSTT import AudioToTextRecorder

recorder = AudioToTextRecorder(
    transcription_engine="moonshine",
    model="UsefulSensors/moonshine-streaming-medium",
    language="en",
    device="cuda",
)

```

--------------------------------

### Build with pro variant

Source: https://github.com/koljab/realtimestt/blob/master/docs/engines/kroko-onnx.md

Builds and installs Kroko-ONNX with the pro variant for licensed Pro/private models. The free variant is for public Community models; the pro variant may need network access for Kroko's license check.

```bash
stt-install-kroko --build --variant pro
```

--------------------------------

### Verify local prerequisites on Windows

Source: https://github.com/koljab/realtimestt/blob/master/docs/engines/kroko-onnx.md

Checks that Python, Git, and Docker are available. docker version should print both a Client and a Server section; if only client info appears, Docker Desktop is not running. docker --version only checks the CLI, not the engine.

```powershell
python --version
git --version
docker version
```

--------------------------------

### Run boundary detector microphone visualizer

Source: https://github.com/koljab/realtimestt/blob/master/docs/test-scripts.md

Command to run the boundary detector microphone visualizer with sensitivity 0.6.

```bash
python tests/realtime_boundary_detector_microphone.py --sensitivity 0.6
```

--------------------------------

### Install openai-whisper with pip

Source: https://github.com/koljab/realtimestt/blob/master/docs/engines/openai-whisper.md

Install the openai-whisper package using pip. This is required before using the openai_whisper engine.

```bash
python -m pip install openai-whisper
```
Tokens:
Raw