Metadata-Version: 2.4
Name: voice-stt-server
Version: 1.0.0
Summary: A fast Voice Activity Detection and Transcription System
Home-page: https://github.com/marcosudau-vps/voice-stt-server
Author: Kolja Beigel
Author-email: kolja.beigel@web.de
License: MIT
Keywords: real-time,audio,transcription,speech-to-text,voice-activity-detection,VAD,real-time-transcription,ambient-noise-detection,microphone-input,faster_whisper,speech-recognition,voice-assistants,audio-processing,buffered-transcription,pyaudio,ambient-noise-level,voice-deactivity
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: PyAudio==0.2.14
Requires-Dist: webrtcvad-wheels==2.0.14
Requires-Dist: halo==0.0.31
Requires-Dist: torch
Requires-Dist: torchaudio
Requires-Dist: scipy==1.17.1
Requires-Dist: websockets==16.0
Requires-Dist: websocket-client==1.9.0
Requires-Dist: soundfile==0.13.1
Provides-Extra: minimal
Provides-Extra: faster-whisper
Requires-Dist: faster-whisper==1.2.1; extra == "faster-whisper"
Provides-Extra: whisper-cpp
Requires-Dist: pywhispercpp; extra == "whisper-cpp"
Provides-Extra: whispercpp
Requires-Dist: pywhispercpp; extra == "whispercpp"
Provides-Extra: openai-whisper
Requires-Dist: openai-whisper; extra == "openai-whisper"
Provides-Extra: sherpa-onnx
Requires-Dist: sherpa-onnx; extra == "sherpa-onnx"
Provides-Extra: sherpa
Requires-Dist: sherpa-onnx; extra == "sherpa"
Provides-Extra: silero-vad
Requires-Dist: silero-vad>=6.2.1; python_version >= "3.8" and extra == "silero-vad"
Provides-Extra: silero
Requires-Dist: silero-vad>=6.2.1; python_version >= "3.8" and extra == "silero"
Provides-Extra: silero-onnx
Requires-Dist: silero-vad[onnx-cpu]>=6.2.1; python_version >= "3.8" and extra == "silero-onnx"
Provides-Extra: silero-onnx-cpu
Requires-Dist: silero-vad[onnx-cpu]>=6.2.1; python_version >= "3.8" and extra == "silero-onnx-cpu"
Provides-Extra: vad-onnx
Requires-Dist: silero-vad[onnx-cpu]>=6.2.1; python_version >= "3.8" and extra == "vad-onnx"
Provides-Extra: transformers
Requires-Dist: transformers; extra == "transformers"
Provides-Extra: moonshine
Requires-Dist: transformers; extra == "moonshine"
Provides-Extra: granite
Requires-Dist: transformers; extra == "granite"
Provides-Extra: cohere
Requires-Dist: transformers; extra == "cohere"
Provides-Extra: omnilingual-asr
Requires-Dist: torch==2.8.0; (python_version >= "3.10" and python_version < "3.12" and platform_system != "Windows") and extra == "omnilingual-asr"
Requires-Dist: torchaudio==2.8.0; (python_version >= "3.10" and python_version < "3.12" and platform_system != "Windows") and extra == "omnilingual-asr"
Requires-Dist: omnilingual-asr>=0.2.0; (python_version >= "3.10" and python_version < "3.12" and platform_system != "Windows") and extra == "omnilingual-asr"
Provides-Extra: omnilingual
Requires-Dist: torch==2.8.0; (python_version >= "3.10" and python_version < "3.12" and platform_system != "Windows") and extra == "omnilingual"
Requires-Dist: torchaudio==2.8.0; (python_version >= "3.10" and python_version < "3.12" and platform_system != "Windows") and extra == "omnilingual"
Requires-Dist: omnilingual-asr>=0.2.0; (python_version >= "3.10" and python_version < "3.12" and platform_system != "Windows") and extra == "omnilingual"
Provides-Extra: meta-omnilingual-asr
Requires-Dist: torch==2.8.0; (python_version >= "3.10" and python_version < "3.12" and platform_system != "Windows") and extra == "meta-omnilingual-asr"
Requires-Dist: torchaudio==2.8.0; (python_version >= "3.10" and python_version < "3.12" and platform_system != "Windows") and extra == "meta-omnilingual-asr"
Requires-Dist: omnilingual-asr>=0.2.0; (python_version >= "3.10" and python_version < "3.12" and platform_system != "Windows") and extra == "meta-omnilingual-asr"
Provides-Extra: qwen
Requires-Dist: qwen-asr; extra == "qwen"
Provides-Extra: qwen3-asr
Requires-Dist: qwen-asr; extra == "qwen3-asr"
Provides-Extra: kroko-builder
Requires-Dist: huggingface_hub; extra == "kroko-builder"
Provides-Extra: porcupine
Requires-Dist: pvporcupine==1.9.5; extra == "porcupine"
Provides-Extra: pvporcupine
Requires-Dist: pvporcupine==1.9.5; extra == "pvporcupine"
Provides-Extra: pvp
Requires-Dist: pvporcupine==1.9.5; extra == "pvp"
Provides-Extra: openwakeword
Requires-Dist: openwakeword>=0.6.0; extra == "openwakeword"
Provides-Extra: oww
Requires-Dist: openwakeword>=0.6.0; extra == "oww"
Provides-Extra: wakewords
Requires-Dist: pvporcupine==1.9.5; extra == "wakewords"
Requires-Dist: openwakeword>=0.6.0; extra == "wakewords"
Provides-Extra: wake-words
Requires-Dist: pvporcupine==1.9.5; extra == "wake-words"
Requires-Dist: openwakeword>=0.6.0; extra == "wake-words"
Provides-Extra: server
Requires-Dist: fastapi>=0.115; extra == "server"
Requires-Dist: uvicorn[standard]>=0.30; extra == "server"
Requires-Dist: python-multipart; extra == "server"
Requires-Dist: sse-starlette; extra == "server"
Requires-Dist: httpx; extra == "server"
Requires-Dist: PyYAML>=6.0; extra == "server"
Requires-Dist: tzdata; extra == "server"
Provides-Extra: example-app
Requires-Dist: RealtimeTTS[edge,system]==0.7.3; extra == "example-app"
Requires-Dist: PyQt5==5.15.11; extra == "example-app"
Requires-Dist: openai==2.41.1; extra == "example-app"
Requires-Dist: PyYAML>=6.0; extra == "example-app"
Requires-Dist: sounddevice==0.5.5; extra == "example-app"
Requires-Dist: wavio==0.0.9; extra == "example-app"
Requires-Dist: keyboard==0.13.5; extra == "example-app"
Provides-Extra: recommended
Requires-Dist: faster-whisper==1.2.1; extra == "recommended"
Requires-Dist: silero-vad[onnx-cpu]>=6.2.1; python_version >= "3.8" and extra == "recommended"
Provides-Extra: default
Requires-Dist: faster-whisper==1.2.1; extra == "default"
Requires-Dist: silero-vad[onnx-cpu]>=6.2.1; python_version >= "3.8" and extra == "default"
Provides-Extra: all
Requires-Dist: faster-whisper==1.2.1; extra == "all"
Requires-Dist: silero-vad[onnx-cpu]>=6.2.1; python_version >= "3.8" and extra == "all"
Requires-Dist: huggingface_hub; extra == "all"
Requires-Dist: pvporcupine==1.9.5; extra == "all"
Requires-Dist: openwakeword>=0.6.0; extra == "all"
Requires-Dist: fastapi>=0.115; extra == "all"
Requires-Dist: uvicorn[standard]>=0.30; extra == "all"
Requires-Dist: python-multipart; extra == "all"
Requires-Dist: sse-starlette; extra == "all"
Requires-Dist: httpx; extra == "all"
Requires-Dist: PyYAML>=6.0; extra == "all"
Requires-Dist: tzdata; extra == "all"
Requires-Dist: RealtimeTTS[edge,system]==0.7.3; extra == "all"
Requires-Dist: PyQt5==5.15.11; extra == "all"
Requires-Dist: openai==2.41.1; extra == "all"
Requires-Dist: sounddevice==0.5.5; extra == "all"
Requires-Dist: wavio==0.0.9; extra == "all"
Requires-Dist: keyboard==0.13.5; extra == "all"
Dynamic: author
Dynamic: author-email
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary
Requires-Dist: fastapi>=0.115
Requires-Dist: uvicorn[standard]>=0.30
Requires-Dist: python-multipart
Requires-Dist: sse-starlette
Requires-Dist: httpx
Requires-Dist: PyYAML>=6.0
Requires-Dist: tzdata
Requires-Dist: numpy


VoiceSTT V1.0.0 preservation release has two alternative published products:

    pip install voice-stt-server
    pip install voice-stt-server-pro

The public CPython 3.12 Linux/Windows product wheels already embed the matching
Kroko native runtime (Free or Pro respectively). A normal wheel consumer does
not compile Kroko and does not install a separate kroko-onnx wheel. Kroko
`.data` model files remain separate from the Python package.

The historical `stt-install-kroko --build --variant free|pro` command remains
available for developers and source builds; it is not the normal PyPI consumer
path.

Optional VoiceSTT backends can still be installed through extras, for example:

    pip install "voice-stt-server[faster-whisper]"
    pip install "voice-stt-server[silero-onnx-cpu]"

See docs/v1-preservation-release.md for the exact V1 release contract and
build/BUILD.md for source/developer build details.

# VoiceSTT

VoiceSTT 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.

This checkout is configured as a CPU-only deployment. The supported production
path uses Faster Whisper, Kroko ONNX, Silero ONNX, OpenWakeWord and Porcupine.
Model downloads are disabled in deployment. Whisper and Kroko directories are
resolved from environment variables or read-only Docker volumes; five
non-commercial OpenWakeWord models are bundled for an immediately usable Wake
Word mode.

The central build and deployment reference is
[`build/BUILD.md`](build/BUILD.md). Server-specific files for Marcos VPS are
kept separately under [`build/vps`](build/vps/README.md).

## V1.0.0 preservation packages

The preserved V1.0.0 public products target **CPython 3.12** on Linux x86_64
and Windows AMD64:

```bash
pip install voice-stt-server
# or, for the licensed Pro runtime:
pip install voice-stt-server-pro
```

These published platform wheels already contain the matching Kroko native
runtime. End users do **not** compile Kroko and do not install a second Kroko
wheel. Kroko `.data` model files remain separate. The Free package uses the
Community model path; the Pro package never auto-downloads a private model and
requires a separately provisioned licensed model plus runtime credential.

See [V1 preservation release](docs/v1-preservation-release.md) for the exact
release contract. `stt-install-kroko --build` remains available for developers
and source builds only.

## Support VoiceSTT

If VoiceSTT 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)](tests/realtimestt_test.py)

## Featured Integration: Kroko/Banafo ASR

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

For normal V1.0.0 consumers, Kroko is already embedded by the public package
shown above. The builder flow below is specifically for source/developer work:

```bash
pip install "voice-stt-server[kroko-builder,silero-onnx-cpu]"
stt-install-kroko --build --variant free
```

Use `--variant pro` only when intentionally building a licensed Pro runtime;
the API/license key is supplied at runtime, not as a build input. See the
[build guide](build/BUILD.md#kroko-im-detail),
[Kroko-ONNX engine guide](docs/engines/kroko-onnx.md), and
[Kroko ASR docs](https://docs.kroko.ai/on-premise/).

## Install

For the V1 preservation release, use Python 3.12 and one of the two product
packages above. Optional backends remain available as extras, for example:

```bash
pip install "voice-stt-server[faster-whisper]"
```

On Linux, install PortAudio headers before installing the package:

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

On macOS:

```bash
brew install portaudio
```

For the tested Windows venv and Docker setup, see
[docs/windows-cpu-deployment.md](docs/windows-cpu-deployment.md).

## Microphone Example

```python
from VoiceSTT 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 VoiceSTT uses multiprocessing for model work.

## Automatic Recording Loop

```python
from VoiceSTT 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 VoiceSTT can resample:

```python
from VoiceSTT 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](docs/quick-start.md) and
[docs/external-audio.md](docs/external-audio.md).

## Configuration Reference

All project and deployment defaults live in the versioned root
[`config.yaml`](config.yaml). It is grouped into `settings`, `deployment` and
`example_app`. The only local env file is `.env`, and it contains credentials
only. It is ignored by Git.

Docker model paths are selected automatically from the existing candidates in
`deployment.model_paths`. A new machine therefore requires no change when one
of those paths exists; otherwise add one candidate in that single section.

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

## Features

- Voice activity detection with WebRTC VAD and Silero VAD.
- Final and realtime transcription with selectable engines.
- Optional wake word activation through Porcupine or OpenWakeWord, with fourteen bundled ONNX Wake Words for non-commercial use.
- Session-local OpenWakeWord selection for FastAPI WebSocket clients without changing the server baseline or other sessions.
- Direct microphone input or application-fed audio chunks.
- Event callbacks for recording, VAD, realtime text, transcription, and wake word state.
- A FastAPI browser streaming server example with multi-user session isolation, shared inference resources, metrics, and health endpoints.
- Four SQLite-first structured server event channels with calendar JSONL mirrors, indexed history, session-scoped client access, server-wide Admin history/live access, and a separate replayable log WebSocket.

## Documentation

- [V1 preservation release](docs/v1-preservation-release.md): exact V1.0.0 packaging, qualification, and publication contract.
- [Build and deployment](build/BUILD.md): canonical package, Docker and Kroko build paths, validation and rollback.
- [Marcos VPS deployment](build/vps/README.md): server-only paths, configuration and release automation.
- [Documentation overview](docs/README.md): authoritative guides, client contract, and archive process.
- [Quick start](docs/quick-start.md)
- [Windows CPU deployment](docs/windows-cpu-deployment.md)
- [Configuration](docs/configuration.md)
- [Transcription engines](docs/transcription-engines.md)
- [Wake words](docs/wake-words.md)
- [External audio](docs/external-audio.md)
- [Testing](docs/testing.md)
- [Test scripts](docs/test-scripts.md)
- [FastAPI server](docs/fastapi-server.md)
- [Structured logging](docs/structured-logging.md)
- [Session-local Wake Word](docs/session-wakeword-erweiterung.md)
- [Troubleshooting](docs/troubleshooting.md)
- [Engine licenses](docs/licenses.md)

### Process for larger changes

Larger changes to architecture, public protocols or APIs, persisted formats,
security boundaries, deployment structure, or cross-module behavior must be
registered in the [archive for larger change actions](docs/.archiv/README.md)
before implementation begins. Every action requires a dated overall plan and a
later plan-versus-implementation review. Material deviations require their own
rationale file.

Engine-specific references:

- [faster-whisper](docs/engines/faster-whisper.md)
- [whisper.cpp](docs/engines/whisper-cpp.md)
- [OpenAI Whisper](docs/engines/openai-whisper.md)
- [Moonshine](docs/engines/moonshine.md)
- [sherpa-onnx](docs/engines/sherpa-onnx.md)
- [Kroko-ONNX](docs/engines/kroko-onnx.md)
- [Parakeet NeMo](docs/engines/parakeet-nemo.md)
- [Meta Omnilingual ASR](docs/engines/omnilingual-asr.md)
- [Granite/Qwen Transformers engines](docs/engines/hf-transformers.md)
- [Cohere Transcribe](docs/engines/cohere.md)
- [FunASR](docs/engines/funasr.md)

## Server Example

The browser FastAPI server is also the installed `VoiceSTT_server` production
entry point. It provides independent multi-user WebSockets and the
OpenAI-compatible transcription route through one shared model scheduler.

```bash
.\install_windows_cpu.ps1
python .\tools\compose.py up --build -d
```

This is the portable development path. Marcos VPS uses the separate,
Pro-aware release process under [build/vps](build/vps/README.md). Open
`http://localhost:8010` for the local setup. See
[docs/fastapi-server.md](docs/fastapi-server.md) for engine recipes, websocket
protocol details, health checks, 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](docs/testing.md).

## License

MIT


V1.0.0 published-wheel install:

    pip install voice-stt-server

The matching Kroko native runtime is embedded in this platform wheel. No separate Kroko wheel/build is required for normal consumers. Kroko .data model files remain separate. Source developers may still use stt-install-kroko --build.
