Release RealtimeSTT 1.1.2 early RMS preview

Author: KoljaB

.github/workflows/release-checks.yml

@@ -42,7 +42,7 @@ jobs:
     name: build and clean distribution smoke
     runs-on: ubuntu-latest
     env:
-      PACKAGE_VERSION: "1.1.1"
+      PACKAGE_VERSION: "1.1.2"
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-python@v5

RELEASE_NOTES.md

@@ -1,5 +1,32 @@
 # Release Notes
 
+## 1.1.2 - 2026-08-30
+
+This patch release reduces advisory early-RMS Preview latency while preserving
+the authoritative transcription retry and full-turn accuracy contract. See
+[the release-readiness checklist](docs/release-1.1.2-readiness.md) for the
+required build, deployment, attestation, and publication evidence.
+
+### Added
+
+- Production capabilities now advertise the exact `preview.earlyRms` contract:
+  request mode, 25 ms first-attempt decoder flush, one-attempt limit, and no
+  advisory empty-result retry.
+
+### Changed
+
+- The exact advisory `previewMode = "early_rms"` appends 25 ms of zero PCM to
+  its first and only decode and publishes an empty result immediately.
+- Authoritative, missing, unknown, and malformed Preview modes retain the
+  existing conditional 500 ms empty-result retry unchanged.
+
+### Release boundaries
+
+- Miep decides when an early browser RMS pause is advisory; RealtimeSTT does
+  not change endpoint detection, transcript authority, or response text.
+- LLM admission-proxy cancellation is a separate deployment component and is
+  not part of this Python distribution.
+
 ## 1.1.1 - 2026-08-28
 
 This patch release fixes stale Preview ASR work delaying newer full-turn

RealtimeSTT/install_sherpa_models.py

@@ -268,7 +268,7 @@ def _open_download(
     opener: Optional[_Urlopen],
 ):
     offset = partial.stat().st_size if partial.exists() else 0
-    headers = {"User-Agent": "RealtimeSTT/%s sherpa-model-installer" % "1.1.1"}
+    headers = {"User-Agent": "RealtimeSTT/%s sherpa-model-installer" % "1.1.2"}
     if offset:
         headers["Range"] = "bytes=%d-" % offset
     request = Request(manifest.archive_url, headers=headers)

RealtimeSTT_server/PRODUCTION_SERVER.md

@@ -119,9 +119,13 @@ At Preview request time, the complete buffered turn is transcribed immediately.
 After a correlated Resume, the complete retained logical turn is transcribed
 again; the candidate boundary fences request ownership but does not truncate
 the model input. Accurate live text is diagnostic context only; it neither
-shortens the Preview input nor replaces the Preview model result. If the first
-Preview transcription is empty, the
-server appends 500 ms of zero PCM and retries exactly once. A still-empty retry
+shortens the Preview input nor replaces the Preview model result. If an
+authoritative Preview transcription is empty, the server appends 500 ms of zero
+PCM and retries exactly once. Missing, unknown, and malformed `previewMode`
+values are authoritative. The exact advisory `previewMode = "early_rms"` adds a
+25 ms zero-PCM decoder flush to its first and only attempt, skips that second
+decode, and publishes a still-empty result immediately; endpoint and
+failure-recovery requests remain authoritative. A still-empty authoritative retry
 publishes `status = "empty"`; a model failure publishes `status = "error"`.
 Neither path substitutes `liveText` as Preview text. Preview never waits for
 either live worker and never uses `mergedText` or `ultrafastSuffix` as its
@@ -153,7 +157,9 @@ short `/v1/...` aliases:
 * `GET /api/v1/ready` returns `503` until shared model workers are ready and
   healthy.
 * `GET /api/v1/capabilities` reports final/live providers and models, active
-  languages, PCM format/sample rates, limits, and operations.
+  languages, PCM format/sample rates, limits, and operations. The
+  `preview.earlyRms` contract advertises the exact advisory request mode,
+  first-attempt decoder-flush silence, attempt limit, and empty-retry policy.
 
 `GET /health` remains available for HTTP ASR probes and includes the familiar
 `engine`, `model`, `device`, `provider`, `compute_type`, `ready`, and warmup

RealtimeSTT_server/README.md

@@ -35,7 +35,7 @@ This directory contains the server and client implementations for the RealtimeST
 Use Python 3.11 or 3.12. Install the stable server package with:
 
 ```bash
-python -m pip install "RealtimeSTT[server]==1.1.1"
+python -m pip install "RealtimeSTT[server]==1.1.2"
 ```
 
 ## Server Usage

RealtimeSTT_server/production_server.py

@@ -48,7 +48,7 @@
 API_VERSION = "v1"
 PROTOCOL_VERSION = "realtimestt.remote.v1"
 SERVER_NAME = "RealtimeSTT production server"
-_PACKAGE_VERSION_FALLBACK = "1.1.1"
+_PACKAGE_VERSION_FALLBACK = "1.1.2"
 
 
 def _package_version() -> str:
@@ -66,6 +66,7 @@ def _package_version() -> str:
 PCM_FORMAT = "pcm_s16le"
 PREVIEW_TAIL_SECONDS = 5.0
 PREVIEW_EMPTY_RETRY_SILENCE_SECONDS = 0.5
+PREVIEW_EARLY_RMS_FLUSH_SILENCE_SECONDS = 0.025
 LATE_FINAL_OPERATION = "late_full_turn_correction"
 RESUME_ACK_TYPE = "resume_ack"
 _LIVE_CANCEL = object()
@@ -514,6 +515,18 @@ def capabilities_for(settings: ProductionServerSettings) -> Dict[str, Any]:
             # realtime is retained as a descriptive alias for live/partial.
             "realtime": dict(live_contract),
         },
+        "preview": {
+            "inputCoverage": "full_turn",
+            "earlyRms": {
+                "supported": True,
+                "requestMode": "early_rms",
+                "firstAttemptSilenceMs": (
+                    PREVIEW_EARLY_RMS_FLUSH_SILENCE_SECONDS * 1000.0
+                ),
+                "maxAttempts": 1,
+                "emptyRetry": False,
+            },
+        },
         "resume": {
             "command": "resume",
             "ackType": RESUME_ACK_TYPE,
@@ -2913,6 +2926,7 @@ def _start_preview_worker(
         candidate_base_text: str,
         resume_request_id: Optional[str],
         resume_epoch: int,
+        preview_mode: str,
         preview_epoch: int,
         cancelled: threading.Event,
     ) -> None:
@@ -2936,6 +2950,7 @@ def _start_preview_worker(
             candidate_base_text,
             resume_request_id,
             resume_epoch,
+            preview_mode,
             preview_epoch,
             cancelled,
         )
@@ -3024,6 +3039,7 @@ def _run_preview_worker(
         candidate_base_text: str,
         resume_request_id: Optional[str],
         resume_epoch: int,
+        preview_mode: str,
         preview_epoch: int,
         cancelled: threading.Event,
         _release_thread: bool = True,
@@ -3043,6 +3059,7 @@ def _run_preview_worker(
             empty_retry_attempted = False
             empty_retry_recovered = False
             empty_retry_error = None
+            empty_retry_suppressed_reason = None
             matched = False
             used_fuzzy_match = False
             anchor_length = 0
@@ -3238,16 +3255,37 @@ def run_asr_attempt(
                         cancelled,
                     ):
                         return
+                    first_attempt_audio = audio
+                    first_attempt_silence_ms = 0.0
+                    if preview_mode == "early_rms":
+                        first_attempt_silence_samples = int(
+                            round(
+                                PREVIEW_EARLY_RMS_FLUSH_SILENCE_SECONDS
+                                * SERVER_SAMPLE_RATE
+                            )
+                        )
+                        first_attempt_audio = np.concatenate(
+                            (
+                                audio,
+                                np.zeros(
+                                    first_attempt_silence_samples,
+                                    dtype=np.float32,
+                                ),
+                            )
+                        )
+                        first_attempt_silence_ms = (
+                            PREVIEW_EARLY_RMS_FLUSH_SILENCE_SECONDS * 1000.0
+                        )
                     tail_text, first_attempt, first_error = run_asr_attempt(
-                        audio,
+                        first_attempt_audio,
                         attempt_index=1,
-                        added_silence_ms=0.0,
+                        added_silence_ms=first_attempt_silence_ms,
                     )
                     asr_attempts.append(first_attempt)
                     if first_error:
                         raise RuntimeError(str(first_error))
 
-                    if not tail_text:
+                    if not tail_text and preview_mode != "early_rms":
                         # The native transducer can occasionally return zero
                         # tokens when a snapshot ends directly on its final
                         # acoustic frame. Give every empty result exactly one
@@ -3300,6 +3338,13 @@ def run_asr_attempt(
                             else:
                                 tail_text = retry_text
                                 empty_retry_recovered = bool(tail_text)
+                    elif not tail_text:
+                        # An eager browser RMS probe is advisory and can be
+                        # superseded within milliseconds. Do not spend a
+                        # second native decode plus 500 ms suffix on an empty
+                        # result; authoritative and legacy Preview requests
+                        # retain the quality-preserving retry above.
+                        empty_retry_suppressed_reason = "early_rms"
 
                     queue_values = [
                         float(attempt["queueMs"])
@@ -3403,6 +3448,7 @@ def run_asr_attempt(
                 "type": "preview",
                 "turnId": turn_id,
                 "previewRequestId": request_id,
+                "previewMode": preview_mode,
                 "text": cumulative_text,
                 "cumulativeText": cumulative_text,
                 "liveText": cumulative_live_text,
@@ -3483,6 +3529,12 @@ def run_asr_attempt(
                         else 0.0
                     ),
                     "emptyRetryError": empty_retry_error,
+                    "emptyRetrySuppressedReason": empty_retry_suppressed_reason,
+                    "firstAttemptSilenceMs": (
+                        PREVIEW_EARLY_RMS_FLUSH_SILENCE_SECONDS * 1000.0
+                        if preview_mode == "early_rms"
+                        else 0.0
+                    ),
                     "requestToPublishMs": round(
                         max(0.0, publish_ready_at - requested_at) * 1000.0,
                         3,
@@ -3685,6 +3737,11 @@ async def preview(self, payload: Dict[str, Any]) -> Optional[Dict[str, Any]]:
                         "invalid_preview_request",
                         "previewRequestId must be a non-empty string of at most 128 characters",
                     )
+            preview_mode = (
+                "early_rms"
+                if payload.get("previewMode") == "early_rms"
+                else "authoritative"
+            )
             audio_revision = turn.audio_revision
             audio_frames = turn.audio_frames
             turn.preview_requested = True
@@ -3737,6 +3794,7 @@ async def preview(self, payload: Dict[str, Any]) -> Optional[Dict[str, Any]]:
                 candidate_base_text,
                 resume_request_id,
                 resume_epoch,
+                preview_mode,
                 preview_epoch,
                 cancelled,
             )
@@ -3747,6 +3805,7 @@ async def preview(self, payload: Dict[str, Any]) -> Optional[Dict[str, Any]]:
             "sessionId": self.session_id,
             "turnId": turn_id,
             "previewRequestId": request_id,
+            "previewMode": preview_mode,
             "audioPackets": packet_count,
             "audioDurationSeconds": round(audio_seconds, 6),
         }
@@ -3825,6 +3884,7 @@ async def _finalize_preview_only(self) -> Optional[Dict[str, Any]]:
                     candidate_base_text,
                     resume_request_id,
                     resume_epoch,
+                    "authoritative",
                     preview_epoch,
                     preview_cancelled,
                 )

docs/release-1.1.2-readiness.md

@@ -0,0 +1,43 @@
+# RealtimeSTT 1.1.2 release readiness
+
+Status date: 2026-08-30
+
+This checklist is evidence-conservative. An unchecked gate is not a release
+claim, and this file does not authorize publication.
+
+## Required gates
+
+- [ ] Base the candidate on current public master and review the exact commit,
+  linked worktrees, branch, tag, and remote divergence.
+- [ ] Run the focused early-RMS, authoritative Preview, production-session,
+  capabilities, package-version, and release-guard tests for the exact commit.
+- [ ] Build the wheel and sdist once from a fresh clean worktree and validate
+  their metadata, contents, filenames, and privacy checks.
+- [ ] Install that exact wheel into the declared Linux runtime, verify all three
+  import roots, restart the service, and run authenticated health,
+  capabilities, representative Preview, and 25 ms early-RMS acceptance.
+- [ ] Attest `RealtimeSTT`, `RealtimeSTT_server`, and
+  `example_fastapi_server` against the exact deployed wheel and sdist no more
+  than 30 minutes before publication.
+- [ ] Publish only through `tools/release_guard.py publish --repository pypi`,
+  proving the remote release branch and `v1.1.2` tag resolve to the attested
+  commit and confirming both uploaded hashes through PyPI.
+- [ ] Download the exact published wheel and sdist into fresh environments and
+  repeat package provenance and smoke checks.
+
+## Known boundaries
+
+The exact advisory `previewMode = "early_rms"` uses one decode with 25 ms of
+zero-PCM decoder-flush silence and no empty-result retry. Authoritative,
+missing, unknown, and malformed modes retain the quality-preserving conditional
+500 ms retry. Miep owns browser RMS timing and the decision to use the advisory
+mode. LLM admission-proxy cancellation is outside this distribution.
+
+The pinned Nemotron-live/Parakeet-final profile targets Linux x86-64. Native
+Windows remains a development target for this pair. Model weights are external
+artifacts and are not shipped in the Python distributions.
+
+## Evidence recording
+
+Exact-commit workflow URLs, deployed import paths, artifact hashes, runtime
+smoke results, and PyPI confirmation belong in the matching GitHub release.

setup.py

@@ -6,7 +6,7 @@
 from setuptools.command.build_py import build_py as _build_py
 
 
-current_version = "1.1.1"
+current_version = "1.1.2"
 
 
 INSTALL_GUIDE = """

tests/unit/test_install_sherpa_models.py

@@ -123,7 +123,8 @@ def test_resume_uses_range_and_commits_atomically(self):
 
         def opener(request, timeout=None):
             range_header = request.get_header("Range")
-            calls.append((range_header, timeout))
+            user_agent = request.get_header("User-agent")
+            calls.append((range_header, user_agent, timeout))
             if range_header is None:
                 return _Response(archive[:split], fail_after=split)
             self.assertEqual("bytes=%d-" % split, range_header)
@@ -142,6 +143,10 @@ def opener(request, timeout=None):
         destination = installer.install_model(manifest, self.root, urlopen_fn=opener)
         self.assertTrue((destination / "tokens.txt").is_file())
         self.assertEqual(2, len(calls))
+        self.assertEqual(
+            {"RealtimeSTT/1.1.2 sherpa-model-installer"},
+            {call[1] for call in calls},
+        )
         self.assertEqual("bytes=%d-" % split, calls[1][0])
         self.assertFalse(partial.exists())
         self.assertTrue(