RealTimeSTT 1.0.2__tar.gz → 1.0.4__tar.gz

{realtimestt-1.0.2 → realtimestt-1.0.4}/MANIFEST.in

@@ -4,6 +4,7 @@ include RELEASE_NOTES.md
 include LICENSE
 prune docs/development
 prune dev-log
+prune dev-logs
 prune roadmap
 prune test-model-cache
 prune test-results

{realtimestt-1.0.2/realtimestt.egg-info → realtimestt-1.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: realtimestt
-Version: 1.0.2
+Version: 1.0.4
 Summary: A fast Voice Activity Detection and Transcription System
 Home-page: https://github.com/KoljaB/RealTimeSTT
 Author: Kolja Beigel
@@ -13,6 +13,7 @@ License-File: LICENSE
 Requires-Dist: PyAudio==0.2.14
 Requires-Dist: webrtcvad-wheels==2.0.14
 Requires-Dist: halo==0.0.31
+Requires-Dist: colorama==0.4.6
 Requires-Dist: torch
 Requires-Dist: torchaudio
 Requires-Dist: scipy==1.17.1
@@ -29,9 +30,17 @@ 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"
+Requires-Dist: sherpa-onnx==1.13.4; extra == "sherpa-onnx"
 Provides-Extra: sherpa
-Requires-Dist: sherpa-onnx; extra == "sherpa"
+Requires-Dist: sherpa-onnx==1.13.4; extra == "sherpa"
+Provides-Extra: server
+Requires-Dist: fastapi<1,>=0.115; extra == "server"
+Requires-Dist: uvicorn[standard]<1,>=0.30; extra == "server"
+Requires-Dist: silero-vad[onnx-cpu]>=6.2.1; python_version >= "3.8" and extra == "server"
+Provides-Extra: production-server
+Requires-Dist: fastapi<1,>=0.115; extra == "production-server"
+Requires-Dist: uvicorn[standard]<1,>=0.30; extra == "production-server"
+Requires-Dist: silero-vad[onnx-cpu]>=6.2.1; python_version >= "3.8" and extra == "production-server"
 Provides-Extra: silero-vad
 Requires-Dist: silero-vad>=6.2.1; python_version >= "3.8" and extra == "silero-vad"
 Provides-Extra: silero
@@ -76,6 +85,14 @@ Provides-Extra: qwen3-asr
 Requires-Dist: qwen-asr; extra == "qwen3-asr"
 Provides-Extra: qwen-vllm
 Requires-Dist: qwen-asr[vllm]; extra == "qwen-vllm"
+Provides-Extra: funasr
+Requires-Dist: funasr; extra == "funasr"
+Provides-Extra: fun-asr
+Requires-Dist: funasr; extra == "fun-asr"
+Provides-Extra: fun-asr
+Requires-Dist: funasr; extra == "fun-asr"
+Provides-Extra: sensevoice
+Requires-Dist: funasr; extra == "sensevoice"
 Provides-Extra: kroko-builder
 Requires-Dist: huggingface_hub; extra == "kroko-builder"
 Provides-Extra: porcupine
@@ -104,7 +121,9 @@ Provides-Extra: all
 Requires-Dist: faster-whisper==1.2.1; extra == "all"
 Requires-Dist: pywhispercpp; extra == "all"
 Requires-Dist: openai-whisper; extra == "all"
-Requires-Dist: sherpa-onnx; extra == "all"
+Requires-Dist: sherpa-onnx==1.13.4; extra == "all"
+Requires-Dist: fastapi<1,>=0.115; extra == "all"
+Requires-Dist: uvicorn[standard]<1,>=0.30; extra == "all"
 Requires-Dist: silero-vad[onnx-cpu]>=6.2.1; python_version >= "3.8" and extra == "all"
 Requires-Dist: transformers; extra == "all"
 Requires-Dist: nemo_toolkit[asr]; extra == "all"
@@ -112,6 +131,7 @@ Requires-Dist: torch==2.8.0; (python_version >= "3.10" and python_version < "3.1
 Requires-Dist: torchaudio==2.8.0; (python_version >= "3.10" and python_version < "3.12" and platform_system != "Windows") and extra == "all"
 Requires-Dist: omnilingual-asr>=0.2.0; (python_version >= "3.10" and python_version < "3.12" and platform_system != "Windows") and extra == "all"
 Requires-Dist: qwen-asr; extra == "all"
+Requires-Dist: funasr; extra == "all"
 Requires-Dist: huggingface_hub; extra == "all"
 Requires-Dist: pvporcupine==1.9.5; extra == "all"
 Requires-Dist: openwakeword>=0.6.0; extra == "all"
@@ -140,10 +160,16 @@ Main ASR backend only, without the faster packaged Silero ONNX Runtime VAD:
 
     pip install "realtimestt[faster-whisper]"
 
-Core package only, without a transcription engine or wake-word backend:
+Base recorder/audio runtime, without a transcription engine or wake-word
+backend:
 
     pip install realtimestt
 
+The base install still includes microphone/audio support, WebRTC VAD, recorder
+VAD logic, websocket client/server dependencies, and shared audio utilities. It
+does not install `faster-whisper`, Porcupine, OpenWakeWord, or another optional
+ASR/wake-word backend unless you request the matching extra.
+
 Install multiple extras by separating them with commas:
 
     pip install "realtimestt[faster-whisper,porcupine]"
@@ -155,6 +181,7 @@ Available extras include:
 - whisper-cpp: whisper.cpp backend through pywhispercpp
 - openai-whisper: original OpenAI Whisper Python backend
 - sherpa-onnx: sherpa-onnx CPU backends
+- server/production-server: versioned FastAPI HTTP and WebSocket ASR server
 - silero-vad: packaged Silero model assets and PyTorch wrapper
 - silero-onnx/silero-onnx-cpu: fastest Silero VAD CPU ONNX Runtime backend
 - silero-onnx-gpu: installs Silero's ONNX GPU runtime extra for experiments
@@ -164,6 +191,7 @@ Available extras include:
 - moonshine, granite, cohere: aliases for the Transformers dependency set
 - qwen: Qwen ASR backend
 - qwen-vllm: Qwen ASR with vLLM extras
+- funasr: experimental FunASR/SenseVoice backend
 - kroko-builder: helper command for building/installing Kroko-ONNX plus Hugging Face model downloads
 - porcupine: Porcupine wake-word backend
 - openwakeword: OpenWakeWord wake-word backend
@@ -171,6 +199,11 @@ Available extras include:
 - recommended/default: faster-whisper backend plus fast Silero CPU ONNX VAD
 - all: all PyPI-installable optional backends
 
+Install the pinned Nemotron live and Parakeet final model bundles into a
+persistent verified cache:
+
+    stt-install-sherpa-models --root ./models/sherpa-onnx --model all
+
 WebRTC VAD is installed with the core package. AudioToTextRecorder also
 initializes a Silero VAD path. Install the recommended/default or
 silero-onnx-cpu extra for a self-contained local Silero ONNX Runtime backend.
@@ -220,8 +253,34 @@ 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 recommended default path uses `faster_whisper`. Other engines are available
-through install extras when their optional dependencies and models are present.
+The general-purpose default path uses `faster_whisper`. Other engines are
+available through install extras when their optional dependencies and models
+are present.
+
+## Recommended Engine Profiles
+
+- **CUDA / GPU:** Keep using the established `faster_whisper` CUDA setup. It
+  remains the recommended general-purpose GPU path.
+- **CPU:** For production streaming on Linux x86-64, the strongly recommended
+  profile is
+  `sherpa-onnx-nemotron-3.5-asr-streaming-0.6b-560ms-int8` for fast,
+  replaceable realtime text together with
+  `sherpa-onnx-nemo-parakeet-tdt-0.6b-v3-int8` for the single authoritative
+  final transcript. Nemotron processes only new audio frames during the turn;
+  Parakeet then refines the complete turn once at finalization. This pairing
+  provides substantially better CPU streaming behavior than repeatedly
+  retranscribing a growing audio buffer while preserving a high-quality final.
+
+Install the CPU server stack and both pinned model bundles with:
+
+```bash
+python -m pip install "RealtimeSTT[server,sherpa-onnx]"
+stt-install-sherpa-models --root ./models/sherpa-onnx --model all
+```
+
+See the [production server guide](RealtimeSTT_server/PRODUCTION_SERVER.md) for
+the authenticated HTTP/WebSocket deployment recipe and exact pinned model
+directories.
 
 ### Support RealtimeSTT
 
@@ -356,8 +415,10 @@ audio, logging, and executor injection.
 - 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.
+- A packaged production FastAPI server with versioned HTTP/WebSocket contracts,
+  session isolation, bounded shared inference resources, authentication, and
+  readiness/capabilities endpoints.
+- A browser streaming reference app for source checkouts.
 
 ## Documentation
 
@@ -369,6 +430,8 @@ audio, logging, and executor injection.
   parameter reference.
 - [Transcription engines](docs/transcription-engines.md): engine selection and
   setup links.
+- [Custom transcription engines](docs/custom-transcription-engines.md): public
+  base class, executor integration, streaming sessions, and contribution guide.
 - [Wake words](docs/wake-words.md): Porcupine and OpenWakeWord setup.
 - [External audio](docs/external-audio.md): feeding audio without a microphone.
 - [Testing](docs/testing.md): maintained unit and opt-in golden test workflow.
@@ -376,6 +439,8 @@ audio, logging, and executor injection.
   legacy experiments under `tests/`.
 - [FastAPI server](docs/fastapi-server.md): browser server configuration,
   protocol, metrics, and deployment notes.
+- [Production server](RealtimeSTT_server/PRODUCTION_SERVER.md): packaged remote
+  HTTP/WebSocket API, authentication, limits, and deployment recipe.
 - [Troubleshooting](docs/troubleshooting.md): common install, audio, CUDA,
   model, dependency, and runtime errors.
 - [Engine licenses](docs/licenses.md): license notes for optional engine
@@ -393,24 +458,42 @@ Engine-specific references:
 - [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)
+
+## Production Server
 
-## Server Example
+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.
+
+```bash
+python -m pip install "RealtimeSTT[server,faster-whisper]"
+stt-server-production --host 127.0.0.1 --port 8010
+```
 
-The browser FastAPI reference server lives in `example_fastapi_server` and is
-intended for source checkouts. It is not installed by the PyPI wheel; keeping it
-source-only keeps the wheel lean and avoids adding web-server dependencies for
-users who only need the recorder/API library.
+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:
 
 ```bash
-python -m pip install -r example_fastapi_server/requirements.txt
-python example_fastapi_server/server.py --host 0.0.0.0 --port 8010
+stt-install-sherpa-models --root ./models/sherpa-onnx --model all
 ```
 
-For pip-only installs, use the Python recorder/API examples instead. If you
-want the FastAPI reference server, clone the repository or install from Git.
+See
+[PRODUCTION_SERVER.md](RealtimeSTT_server/PRODUCTION_SERVER.md).
 
-Open `http://localhost:8010`. See [docs/fastapi-server.md](docs/fastapi-server.md)
-for engine recipes, websocket protocol details, health checks, and metrics.
+The interactive browser reference app remains in `example_fastapi_server` for
+source checkouts. See [docs/fastapi-server.md](docs/fastapi-server.md) for its
+UI, engine recipes, protocol details, and metrics.
 
 ## Contributing
 

{realtimestt-1.0.2 → realtimestt-1.0.4}/README.md

@@ -6,8 +6,34 @@ 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 recommended default path uses `faster_whisper`. Other engines are available
-through install extras when their optional dependencies and models are present.
+The general-purpose default path uses `faster_whisper`. Other engines are
+available through install extras when their optional dependencies and models
+are present.
+
+## Recommended Engine Profiles
+
+- **CUDA / GPU:** Keep using the established `faster_whisper` CUDA setup. It
+  remains the recommended general-purpose GPU path.
+- **CPU:** For production streaming on Linux x86-64, the strongly recommended
+  profile is
+  `sherpa-onnx-nemotron-3.5-asr-streaming-0.6b-560ms-int8` for fast,
+  replaceable realtime text together with
+  `sherpa-onnx-nemo-parakeet-tdt-0.6b-v3-int8` for the single authoritative
+  final transcript. Nemotron processes only new audio frames during the turn;
+  Parakeet then refines the complete turn once at finalization. This pairing
+  provides substantially better CPU streaming behavior than repeatedly
+  retranscribing a growing audio buffer while preserving a high-quality final.
+
+Install the CPU server stack and both pinned model bundles with:
+
+```bash
+python -m pip install "RealtimeSTT[server,sherpa-onnx]"
+stt-install-sherpa-models --root ./models/sherpa-onnx --model all
+```
+
+See the [production server guide](RealtimeSTT_server/PRODUCTION_SERVER.md) for
+the authenticated HTTP/WebSocket deployment recipe and exact pinned model
+directories.
 
 ### Support RealtimeSTT
 
@@ -142,8 +168,10 @@ audio, logging, and executor injection.
 - 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.
+- A packaged production FastAPI server with versioned HTTP/WebSocket contracts,
+  session isolation, bounded shared inference resources, authentication, and
+  readiness/capabilities endpoints.
+- A browser streaming reference app for source checkouts.
 
 ## Documentation
 
@@ -155,6 +183,8 @@ audio, logging, and executor injection.
   parameter reference.
 - [Transcription engines](docs/transcription-engines.md): engine selection and
   setup links.
+- [Custom transcription engines](docs/custom-transcription-engines.md): public
+  base class, executor integration, streaming sessions, and contribution guide.
 - [Wake words](docs/wake-words.md): Porcupine and OpenWakeWord setup.
 - [External audio](docs/external-audio.md): feeding audio without a microphone.
 - [Testing](docs/testing.md): maintained unit and opt-in golden test workflow.
@@ -162,6 +192,8 @@ audio, logging, and executor injection.
   legacy experiments under `tests/`.
 - [FastAPI server](docs/fastapi-server.md): browser server configuration,
   protocol, metrics, and deployment notes.
+- [Production server](RealtimeSTT_server/PRODUCTION_SERVER.md): packaged remote
+  HTTP/WebSocket API, authentication, limits, and deployment recipe.
 - [Troubleshooting](docs/troubleshooting.md): common install, audio, CUDA,
   model, dependency, and runtime errors.
 - [Engine licenses](docs/licenses.md): license notes for optional engine
@@ -179,24 +211,42 @@ Engine-specific references:
 - [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
+## 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.
+
+```bash
+python -m pip install "RealtimeSTT[server,faster-whisper]"
+stt-server-production --host 127.0.0.1 --port 8010
+```
 
-The browser FastAPI reference server lives in `example_fastapi_server` and is
-intended for source checkouts. It is not installed by the PyPI wheel; keeping it
-source-only keeps the wheel lean and avoids adding web-server dependencies for
-users who only need the recorder/API library.
+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:
 
 ```bash
-python -m pip install -r example_fastapi_server/requirements.txt
-python example_fastapi_server/server.py --host 0.0.0.0 --port 8010
+stt-install-sherpa-models --root ./models/sherpa-onnx --model all
 ```
 
-For pip-only installs, use the Python recorder/API examples instead. If you
-want the FastAPI reference server, clone the repository or install from Git.
+See
+[PRODUCTION_SERVER.md](RealtimeSTT_server/PRODUCTION_SERVER.md).
 
-Open `http://localhost:8010`. See [docs/fastapi-server.md](docs/fastapi-server.md)
-for engine recipes, websocket protocol details, health checks, and metrics.
+The interactive browser reference app remains in `example_fastapi_server` for
+source checkouts. See [docs/fastapi-server.md](docs/fastapi-server.md) for its
+UI, engine recipes, protocol details, and metrics.
 
 ## Contributing
 

realtimestt-1.0.4/RELEASE_NOTES.md

@@ -0,0 +1,205 @@
+# Release Notes
+
+## 1.0.4 - 2026-08-21
+
+### Fixed
+
+- Replaced the production WebSocket recorder/VAD-derived final path with a
+  turn-owned state machine and authoritative canonical PCM buffer. Every
+  finalized turn now produces exactly one Parakeet final result followed by
+  exactly one completion.
+- Made accepted 16 kHz PCM invariant to 10/20/40/64/100 ms packet boundaries;
+  the WebSocket final uses the same final scheduler lane, audio normalization,
+  language, and prompt policy as raw-PCM HTTP transcription.
+- Fenced late live/final/transport callbacks across cancel, reset, disconnect,
+  and reconnect, including reconnects that reuse a session or turn id.
+- Fixed live Nemotron input scaling, removed growing full-buffer snapshots,
+  fed only new frames to one stream per logical turn, and deduplicated and
+  rate-limited changed partials.
+- Closed long-session lifecycle leaks by retiring completed final threads,
+  draining cancelled live queues, cancelling timed-out live streams, pruning
+  connection epochs, and resolving queued scheduler jobs during shutdown.
+- Moved native live-stream creation and cancellation off the ASGI event loop,
+  fenced streams returned after a turn was retired, and bounded concurrent
+  native cancellation work process-wide.
+- Made final/completion admission atomic across reset and cancel, scoped final
+  timeout cancellation to the exact scheduler request, and bounded live
+  backpressure by queued audio duration instead of client packet count.
+- Bounded terminal-event reserve for slow WebSocket readers and close the
+  connection with code 1013 instead of allowing finalized turns to grow an
+  unbounded outbound queue.
+- Removed bearer-token command-line flags; production tokens now come only
+  from `REALTIMESTT_SERVER_BEARER_TOKEN` so they cannot appear in process
+  listings or shell history.
+
+### Changed
+
+- Production WebSocket audio is explicitly canonical mono 16 kHz
+  `pcm_s16le`. HTTP final transcription retains its documented supported input
+  sample rates and performs one whole-request resample.
+- Streaming benchmark pacing now uses the absolute audio clock and validates
+  exact terminal counts, terminal/completion ordering, quiet completion tails,
+  long-run repetitions, and bounded parallel concurrency.
+- HTTP A/B and WebSocket benchmark reports redact endpoints, corpus paths,
+  clip identifiers, references, partials, and finals by default. Sensitive
+  per-record output requires an explicit protected-local opt-in.
+- The production CPU profile keeps Nemotron live hypotheses display-only;
+  Parakeet remains the sole authoritative turn final.
+
+### Notes
+
+- This release supersedes the old TestPyPI `1.0.3` artifact. PyPI
+  files are immutable, so the corrected production release uses version `1.0.4`.
+- The supported Nemotron/Parakeet production profile remains Linux x86-64.
+  Keep the server on loopback behind an authenticated TLS/WSS endpoint and
+  retain a local-live/final-server rollback path during client rollout.
+- No production-PyPI publication is implied by this release candidate.
+
+## 1.0.3 - 2026-08-20
+
+### Added
+
+- Added the experimental optional FunASR/SenseVoice transcription backend and
+  install extra.
+- Added `AudioToTextRecorder.feed_audio_file()` for feeding audio files through
+  the manual audio input path.
+- Added `TranscriptionResult.metadata` support and word timestamp plumbing for
+  backends that can return word-level timing.
+- Added public custom transcription engine interfaces through
+  `RealtimeSTT.engines`, including `BaseEngine`, `TranscriptionEngineConfig`,
+  `TranscriptionResult`, and `StreamingTranscriptionSession`.
+- Added custom engine documentation showing `transcription_executor`,
+  `realtime_transcription_executor`, and streaming-session integration.
+- Added opt-in realtime punctuation splitting through
+  `realtime_punctuation_split_marks`. The default remains `"off"`; `"sentence"`
+  is the supported production mode for `.`, `?`, and `!`.
+- Added the multilingual sherpa-onnx Nemotron 3.5 0.6B INT8 engine as a true
+  streaming engine with per-stream language selection, incremental frame
+  ingestion, final draining, reset, cancellation, and deterministic release.
+- Added pinned manifests for the exact Nemotron streaming and Parakeet v3 final
+  model archives, including source, license, archive integrity, and extracted
+  file integrity metadata.
+- Added `stt-install-sherpa-models` for resumable, verified, atomic installation
+  and offline reuse of those pinned model archives in persistent storage.
+- Added a packaged production FastAPI server with versioned liveness,
+  readiness, capabilities, raw PCM16 final transcription, and ordered remote
+  streaming WebSocket APIs. Non-loopback binds require bearer authentication
+  and TLS. The server includes bounded queues and sessions, backpressure,
+  limits, structured errors, warmup, and graceful resource cleanup.
+- Added a reproducible same-host A/B benchmark harness for the AgentTalk/raw
+  PCM16 contract and release CI for unit, distribution, and isolated wheel
+  installation checks.
+
+### Changed
+
+- Hardened realtime punctuation splitting with repeated-observation checks,
+  timestamp validation, guarded dash handling, and synchronized split-state
+  bookkeeping.
+- Expanded install-extra validation to include the FunASR extra and the `all`
+  extra.
+- Exposed the same engine authoring interfaces through lazy top-level package
+  imports while keeping existing `BaseTranscriptionEngine` imports compatible.
+- Pinned the sherpa-onnx optional dependency to the release-tested version and
+  hardened empty-output/language handling for Parakeet final transcription.
+- Made the production `server` extra install a local Silero ONNX VAD runtime,
+  avoiding interactive Torch Hub model retrieval when WebSocket sessions start.
+- Promoted the remote production server to the `stt-server-production` packaged
+  entry point while preserving the legacy `stt-server` command.
+
+### Notes
+
+- Comma, dash, ellipsis, and `all` punctuation split modes remain available for
+  experiments but are not promoted as production-supported in this release.
+- Realtime punctuation splitting requires word timestamps. Built-in support is
+  currently wired through `faster_whisper`; other built-in engines skip the
+  split path.
+- The production CPU pair uses Nemotron only for replaceable live hypotheses;
+  Parakeet transcribes the authoritative final audio once and replaces the live
+  hypothesis at turn completion.
+- The exact model weights remain external artifacts governed by their own
+  licenses. The package ships manifests and installation tooling, not weights.
+- The pinned two-model production profile targets Linux x86-64. Native Windows
+  remains suitable for development, but Parakeet can return empty output for
+  some voiced cumulative-turn audio; use the Linux server or another final
+  engine until that runtime combination is proven reliable.
+- On the same Linux CPU host and final model, the 1.0.3 server matched the
+  reference WER/CER/exact result, was at single-client latency parity, and at
+  four concurrent clients improved throughput by 7.5% and p95 latency by 33.2%.
+
+## 1.0.2 - 2026-05-31
+
+### Changed
+
+- Split the `AudioToTextRecorder` implementation behind the existing public
+  facade into focused core modules for lifecycle, recording, realtime
+  transcription, voice activity, wake-word handling, initialization, shutdown,
+  and formatting.
+- Refreshed recorder architecture and compatibility documentation so the public
+  facade, threading boundaries, and regression checks are easier to audit.
+- Normalized package docstrings and comments to use block-style summaries and
+  focused runtime explanations.
+
+### Removed
+
+- Removed an unused internal console color helper from `audio_recorder.py`.
+
+## 1.0.1 - 2026-05-20
+
+### Added
+
+- Added a generic streaming transcription session interface so engines can
+  opt in to incremental realtime decoding while existing engines keep the
+  full-buffer fallback behavior.
+- Added `kroko_onnx` transcription engine for Kroko/Banafo `.data` streaming
+  models.
+- Added Kroko realtime preview support that feeds streaming engines only newly
+  recorded audio frames through a persistent session.
+- Added `stt-install-kroko`, exposed through the `kroko-builder` extra, to help
+  build and install Kroko-ONNX for the active Python environment.
+- Added focused Kroko and realtime streaming unit coverage plus a public manual
+  `tests/realtimestt_kroko_test.py` smoke script.
+- Added `omnilingual_asr` transcription engine for Meta
+  Omnilingual ASR on Linux/WSL2 with Python 3.11.x, with support for the
+  published CTC and LLM model cards. Native Windows is not supported because
+  `fairseq2n` has no Windows wheel; Python 3.12.x is blocked by upstream
+  `omnilingual-asr` package metadata.
+- Added `docs/licenses.md` with engine and model-family license notes.
+
+### Changed
+
+- Kroko Community models with known public filenames can be auto-downloaded
+  into the RealtimeSTT cache when `auto_download_model` is enabled.
+- Kroko final transcription remains one-shot. The new streaming path is used
+  for realtime previews only when the realtime engine advertises streaming
+  support.
+- Kroko model cadence is used to choose automatic finalization tail padding.
+- Omnilingual ASR uses `omniASR_CTC_1B_v2` as the default when the
+  recorder is still configured with a Whisper default model name.
+- Omnilingual in-memory audio is passed to the backend as predecoded waveform
+  dictionaries to avoid the upstream package treating raw float arrays as
+  encoded audio bytes.
+
+### Notes
+
+- Install/build Kroko-ONNX separately with
+  `pip install "RealtimeSTT[kroko-builder,silero-onnx-cpu]"` followed by
+  `stt-install-kroko --build`, or install a compatible Kroko-ONNX wheel in the
+  same Python environment. The `silero-onnx-cpu` extra provides the local VAD
+  backend used by recorder-based Kroko smoke tests and live microphone use.
+- Licensed Pro models require a Pro-capable Kroko wheel and a key supplied at
+  runtime through configuration, CLI, or environment variables. Do not commit
+  keys, Pro models, generated logs, local wheels, or local cache contents.
+- `Pro-16-L` is the recommended realtime model for the fastest partials. Local
+  private validation observed the expected low-latency partial behavior, but
+  exact cadence depends on runtime, provider, hardware, and scheduling.
+- `suppress_native_output=True` redirects Kroko native stdout/stderr during
+  recognizer calls and sets `KROKO_ONNX_SUPPRESS_LICENSE_OUTPUT=1`. Reliable
+  suppression of asynchronous Pro license refresh messages requires a Kroko
+  wheel rebuilt with RealtimeSTT's native quiet-output patch; older Kroko wheels
+  may still print background license status text.
+- Omnilingual ASR support is optional and Linux/WSL2 Python 3.11.x-oriented.
+  Native Windows installs are not supported by the upstream dependency stack at
+  this time, and Python 3.12.x cannot resolve the current upstream package.
+- `omniASR_CTC_1B_v2` is the recommended Omnilingual starting point for local
+  realtime tests in this release. Smaller/larger CTC and LLM models are exposed
+  through model-card plumbing but require their own quality and memory checks.

realtimestt-1.0.4/RealtimeSTT/__init__.py

@@ -0,0 +1,84 @@
+"""
+Exposes the public RealtimeSTT package objects through lazy imports.
+"""
+
+__all__ = [
+    "AudioToTextRecorder",
+    "AudioToTextRecorderClient",
+    "AudioInput",
+    "BaseEngine",
+    "BaseTranscriptionEngine",
+    "RealtimeSpeechBoundaryDetector",
+    "SpeechBoundaryEvent",
+    "SpeechBoundaryResult",
+    "StreamingTranscriptionSession",
+    "TranscriptionEngineConfig",
+    "TranscriptionEngineError",
+    "TranscriptionInfo",
+    "TranscriptionResult",
+    "UnsupportedTranscriptionEngineError",
+]
+
+
+def __getattr__(name):
+    """
+    Loads exported package attributes lazily.
+    """
+
+    if name == "AudioToTextRecorder":
+        from .audio_recorder import AudioToTextRecorder
+
+        return AudioToTextRecorder
+    if name == "AudioToTextRecorderClient":
+        from .audio_recorder_client import AudioToTextRecorderClient
+
+        return AudioToTextRecorderClient
+    if name == "AudioInput":
+        from .audio_input import AudioInput
+
+        return AudioInput
+    if name == "BaseEngine":
+        from .engines import BaseEngine
+
+        return BaseEngine
+    if name == "BaseTranscriptionEngine":
+        from .engines import BaseTranscriptionEngine
+
+        return BaseTranscriptionEngine
+    if name == "StreamingTranscriptionSession":
+        from .engines import StreamingTranscriptionSession
+
+        return StreamingTranscriptionSession
+    if name == "TranscriptionEngineConfig":
+        from .engines import TranscriptionEngineConfig
+
+        return TranscriptionEngineConfig
+    if name == "TranscriptionEngineError":
+        from .engines import TranscriptionEngineError
+
+        return TranscriptionEngineError
+    if name == "TranscriptionInfo":
+        from .engines import TranscriptionInfo
+
+        return TranscriptionInfo
+    if name == "TranscriptionResult":
+        from .engines import TranscriptionResult
+
+        return TranscriptionResult
+    if name == "UnsupportedTranscriptionEngineError":
+        from .engines import UnsupportedTranscriptionEngineError
+
+        return UnsupportedTranscriptionEngineError
+    if name == "RealtimeSpeechBoundaryDetector":
+        from .core.realtime_boundary_detector import RealtimeSpeechBoundaryDetector
+
+        return RealtimeSpeechBoundaryDetector
+    if name == "SpeechBoundaryEvent":
+        from .core.realtime_boundary_detector import SpeechBoundaryEvent
+
+        return SpeechBoundaryEvent
+    if name == "SpeechBoundaryResult":
+        from .core.realtime_boundary_detector import SpeechBoundaryResult
+
+        return SpeechBoundaryResult
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

realtimestt-1.0.4/RealtimeSTT/assets/__init__.py

@@ -0,0 +1 @@
+"""Package data assets used by RealtimeSTT."""