python-voiceio 0.4.1__py3-none-any.whl → 0.6.0__py3-none-any.whl

{python_voiceio-0.4.1.dist-info → python_voiceio-0.6.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-voiceio
-Version: 0.4.1
+Version: 0.6.0
 Summary: Voice dictation for Linux. Speak → text, locally, instantly.
 Author: Hugo Montenegro
 License-Expression: MIT

{python_voiceio-0.4.1.dist-info → python_voiceio-0.6.0.dist-info}/RECORD

@@ -1,15 +1,15 @@
-python_voiceio-0.4.1.dist-info/licenses/LICENSE,sha256=Gz61o8jFTAvZUZyB3nWDB3DQQVuipjfPkVu9W8hBHM0,1072
-voiceio/__init__.py,sha256=pMtTmSUht-XtbR_7Doz6bsQqopJJd8rZ8I8zy2HwwoA,22
+python_voiceio-0.6.0.dist-info/licenses/LICENSE,sha256=Gz61o8jFTAvZUZyB3nWDB3DQQVuipjfPkVu9W8hBHM0,1072
+voiceio/__init__.py,sha256=cID1jLnC_vj48GgMN6Yb1FA3JsQ95zNmCHmRYE8TFhY,22
 voiceio/__main__.py,sha256=xT5QCGGreYMisHO7Lh_Y-xAQ2TOzG2D7npKknGNcWSY,53
-voiceio/app.py,sha256=ZVuvITD76lYauIB68XvItyOsB1I3kMSqy9YISp0gl9E,60833
+voiceio/app.py,sha256=4o3nOv_Z_NCBr6KTHr1eSGT159ZE98dVBAy5wUOpzAo,64398
 voiceio/audit.py,sha256=vX3x-YAhmt6EZYRZd0_6wvTquZu5sxGMvH45BhSBnCk,14915
 voiceio/autocorrect.py,sha256=jGsglEYwAHWk2uWedeEZzyAMW2LWO_8nQGZgrWYy4Dc,26552
 voiceio/autocorrect_state.py,sha256=BNzdHP5slcOV_-OU4MlaKE7xgVJzrPncsYFK30JWTs8,6858
 voiceio/backends.py,sha256=-rs1YhPblub4NjFb6qCD7Ih9FqBRXtPuvjVv9bQoQ1w,368
 voiceio/cli.py,sha256=_HfcWQt2Jf34YfI4W1RavsyqegQy9jrg0nwLe6DvD6E,71639
-voiceio/clipboard_read.py,sha256=266u_QoJb_n3iLuy5fbccPZJfpYpPkjsNtZxjDNmqAE,2062
+voiceio/clipboard_read.py,sha256=CqbHSvOztcQ3u2I2EzFm0jdcDVKv56gl0T1YfWxNpmI,3390
 voiceio/commands.py,sha256=Vhtn8s5G5OcCbRN44YZ-_14Fa85ISXl_3Ix-KqSHs2A,4694
-voiceio/config.py,sha256=PF_G8xnzsFTFLee-tXReJiWUpACg5Li6HM9k97dWjM8,12569
+voiceio/config.py,sha256=AOFaJras9rUPRDz7xeaZd4-WbWLOPUe0f0hYcQNwdJM,14042
 voiceio/consent.py,sha256=jtdp1TkTbicUSTCDmV4qo4SdbS4kQpYzy1Kjc_7pJVw,1883
 voiceio/corrections.py,sha256=7moKhkVvo5CZU1mZobV2-MajkcHiwliKBY1dSBFh0w0,7445
 voiceio/demo.py,sha256=QRNJuNObXCsjwGD-Cz3dh81cfb21xiuSeVyyU720U9Q,8673
@@ -22,18 +22,18 @@ voiceio/llm_api.py,sha256=ex1brY10a8xNtw4cHCYC0yCth3Z02NkCQaHdB4XQPag,7497
 voiceio/numbers.py,sha256=MP8jag4_F2OqUU5H14KzOmR9L8gWg48yQhLoUbGg_YI,8376
 voiceio/pidlock.py,sha256=RInlF_8H7wR0nqkdlhUfxYs7OGzHIvb5p-XDjjQSTNg,619
 voiceio/platform.py,sha256=f_8MmC5q1sCEuEPyKjRqlVvV9FExuGmwn_aJXhkpiEk,11809
-voiceio/postcorrect.py,sha256=lxm3zxdz3yzoR6qpf0bKRycBrF5y91bVnU4DqyTRbxU,8163
+voiceio/postcorrect.py,sha256=iyO7MPIR4a4XIASEGOs9Y3iUXVTfwtVkhVOWj2vY1lk,11201
 voiceio/postprocess.py,sha256=9grkq3I6XgiQV6ZQbIw2_fOUe57tzC7GBPvLXqhhdTs,2979
 voiceio/prompt.py,sha256=9iza8KoQxvO_U9NPMJ8Ep7j-zkIs9nW8N5sacCRpsEk,2904
-voiceio/recorder.py,sha256=aWCZC8sKYnUNnrzGxFlYzJlnUVIk8PNpkahVXeAUULE,12323
-voiceio/retention.py,sha256=VrN261qL4C2_mSbjI6yPnMNiTVMxpo16wYua27TQb_Q,3330
+voiceio/recorder.py,sha256=p1r0mH_plBD3BHqBbIGV_m2N4Mj5RAF7LfMu8u6mk5I,12813
+voiceio/retention.py,sha256=i_VWPCyykT4kQ1uKilTplpiIrACTYljn09BU1vL71A0,6019
 voiceio/service.py,sha256=jqX1opZyQh_dOJMK4bVf8Aoei0zOuuk1Ogta9BXTWGY,12106
 voiceio/snapshots.py,sha256=bm-lzIeYucDUDlPBZiFiWd-jyB2I6Ft1jRANZCO6go4,2351
-voiceio/streaming.py,sha256=BBIU-Uub5z8ByYi8tXEUykdhTBgMhwvLHS87-_pZeaQ,15339
-voiceio/transcriber.py,sha256=D6_RLO8K3bGUV4CsS2q_k5rxkHTMB_6DqnzDka5mEb0,9939
+voiceio/streaming.py,sha256=XpF4fALTAgYqRB8zoDL81TuKlKLmUOc5_Cfd3auZFBI,21802
+voiceio/transcriber.py,sha256=2ev_hwdusve7ZZqht9A9wtjjT72rcr7SuhmSIW8aClk,10721
 voiceio/vad.py,sha256=72_ICk4jSuSPYvTHdHYtHzY8W5uaGEOz5FTdqkolJi8,5327
 voiceio/vocabulary.py,sha256=eGV7QZs3tN6Cw5YpyoZsVEk2M5fJvie1n2XFi9CD4hw,6321
-voiceio/wizard.py,sha256=cqNKMMzzfFy0Ncg4LJ0TWX77B84-ZvXm_1ibbarQFng,80209
+voiceio/wizard.py,sha256=AwjwrocrQp0DPSOMZ0m6z6G3hlo9VPceEwPzR9-xXe0,80227
 voiceio/wordfreq.py,sha256=2UMjW1xIFqo5EchXzsXPizUhRb9N18CVgjnXso1wsgw,2382
 voiceio/worker.py,sha256=M6e4s6P0-4UGQzw0j8Mq68nypvwZleOSwuRhjuOqlVE,2563
 voiceio/hotkeys/__init__.py,sha256=rGXSGZLD2mS_Ep2HfVdRdkUKNr4xagySlL1FM00cYgk,735
@@ -71,8 +71,8 @@ voiceio/typers/pynput_type.py,sha256=DTtkT59M-EKOAlTNkvcZrRvf_Fq52OpI8S5t_8S-QAY
 voiceio/typers/wtype.py,sha256=d1wG-HZdYDQxXIysV_Xvk9HixDpaJgl3VEoKbP5vhIs,1786
 voiceio/typers/xdotool.py,sha256=dh1zhPqUT8ihJahJ7ZKm6PtfYY087UAzADx664DvQOM,1356
 voiceio/typers/ydotool.py,sha256=dt0W9ot__W8LQG2so8vZLGIw9leK2Q6g3i-Voo0LXE4,5327
-python_voiceio-0.4.1.dist-info/METADATA,sha256=eCo6CC2sRMLl4xKLDyp0N7W7a_qVKvBf6vARmNZYJaY,15877
-python_voiceio-0.4.1.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
-python_voiceio-0.4.1.dist-info/entry_points.txt,sha256=U64fA65zxzyLoC8bgbn2ztQVWHLsc0o0H0qCk1J9DMc,218
-python_voiceio-0.4.1.dist-info/top_level.txt,sha256=piwtn309lD6uexQyXdZ-efAVBJF9y6Wfr48Z-8zkNhg,8
-python_voiceio-0.4.1.dist-info/RECORD,,
+python_voiceio-0.6.0.dist-info/METADATA,sha256=HdRa-d2IgSiL7VZxA7lcXavG0dGkqcKGf6Lmzdf9xxk,15877
+python_voiceio-0.6.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+python_voiceio-0.6.0.dist-info/entry_points.txt,sha256=U64fA65zxzyLoC8bgbn2ztQVWHLsc0o0H0qCk1J9DMc,218
+python_voiceio-0.6.0.dist-info/top_level.txt,sha256=piwtn309lD6uexQyXdZ-efAVBJF9y6Wfr48Z-8zkNhg,8
+python_voiceio-0.6.0.dist-info/RECORD,,

voiceio/__init__.py

@@ -1 +1 @@
-__version__ = "0.4.1"
+__version__ = "0.6.0"

voiceio/app.py

@@ -337,7 +337,31 @@ class VoiceIO:
                 log.exception("Cannot reopen audio stream, aborting recording")
                 return
 
-        if not self.recorder.has_signal():
+        if self.recorder.is_zombie():
+            # Full pre-buffer of digital zeros with a "healthy" stream is the
+            # post-suspend zombie signature (callbacks fire, capture node
+            # gone). Reopening fixes it; a failed reopen means no audio is
+            # possible, so abort rather than record silence.
+            log.warning("Zombie audio stream (all-zero pre-buffer) — reopening")
+            try:
+                self.recorder.reopen_stream()
+                time.sleep(0.4)  # let the new stream fill some pre-buffer
+            except Exception:
+                log.exception("Audio stream reopen failed, aborting recording")
+                from voiceio import feedback
+                feedback.notify(
+                    "VoiceIO: microphone unavailable",
+                    "Could not reopen the audio stream — check your input device.",
+                )
+                return
+            if not self.recorder.has_signal():
+                log.warning("Mic still silent after reopen — muted or wrong device?")
+                from voiceio import feedback
+                feedback.notify(
+                    "VoiceIO: microphone appears silent",
+                    "Check that your mic is unmuted and the right input device is selected.",
+                )
+        elif not self.recorder.has_signal():
             log.warning("Mic appears silent or muted (pre-buffer is all zeros)")
 
         self._state = _State.RECORDING
@@ -368,6 +392,8 @@ class VoiceIO:
                 llm=self._llm,
                 voice_input_prefix=self._voice_input_prefix,
                 on_typer_broken=self._on_typer_broken,
+                on_interim=self._on_interim_text,
+                freeze_secs=self.cfg.output.streaming_freeze_secs,
             )
             self._session.start()
         log.info("Recording... press [%s] again to stop", self.cfg.hotkey.key)
@@ -492,12 +518,19 @@ class VoiceIO:
     ) -> None:
         """Run final transcription and commit in background thread."""
         t_final = time.monotonic()
+        # Snappy clipboard: make the best-so-far text pasteable the moment
+        # the user stops, instead of after the (possibly long) final decode.
+        if (self.cfg.output.copy_to_clipboard == "live"
+                and self._typer.name != "clipboard" and session.interim_text):
+            from voiceio import clipboard_read
+            clipboard_read.copy_text(session.interim_text)
         extra = self._retention_extra(audio)
         final_text = session.stop(audio)
         if self._generation != gen:
             log.debug("Finalize cancelled (gen %d, current %d)", gen, self._generation)
             return
         if final_text:
+            self._copy_result_async(final_text)
             self._play_feedback(final_text)
             stored = self._strip_voice_prefix(final_text)
             self._prompt_builder.add_transcript(stored)
@@ -513,6 +546,16 @@ class VoiceIO:
                 duration=elapsed,
                 extra=extra,
             )
+            from voiceio import retention
+            retention.save_trace(self.cfg.data, {
+                "ts": time.time(),
+                "audio": extra.get("audio"),
+                "duration": round(elapsed, 2),
+                "latency": latency,
+                # Snapshot: a timed-out worker join means the thread may
+                # still be appending while we serialize.
+                "passes": list(session.trace),
+            })
         log.info("Streaming done (%.1fs): '%s'", elapsed, final_text)
         # Release the IBus input source now that the final commit is done.
         # Generation-checked inside: if a newer recording started, it already
@@ -565,6 +608,7 @@ class VoiceIO:
                 # Superseded by a newer recording — do not touch the typer.
                 if text and self._generation == gen:
                     self._type_with_fallback(text)
+                    self._copy_result_async(text)
                     self._play_feedback(text)
                     stored = self._strip_voice_prefix(text)
                     self._prompt_builder.add_transcript(stored)
@@ -660,6 +704,35 @@ class VoiceIO:
             from voiceio.feedback import play_record_stop
             play_record_stop()
 
+    def _on_interim_text(self, text: str) -> None:
+        """Streaming update: mirror the best-so-far text to the clipboard.
+
+        Runs on the streaming worker thread (a copy is a few ms). Skipped for
+        the clipboard typer, which pastes FROM the clipboard — overwriting it
+        here could race a pending Ctrl+V and paste the full text twice.
+        """
+        if self.cfg.output.copy_to_clipboard != "live":
+            return
+        if self._typer.name == "clipboard":
+            return
+        from voiceio import clipboard_read
+        clipboard_read.copy_text(text)
+
+    def _copy_result_async(self, text: str) -> None:
+        """Mirror the final text to the clipboard, off the commit hot path."""
+        if self.cfg.output.copy_to_clipboard not in ("final", "live"):
+            return
+
+        def _copy() -> None:
+            # Give a just-sent paste keystroke time to consume the clipboard
+            # before we overwrite it with the full text.
+            if self._typer.name == "clipboard":
+                time.sleep(0.3)
+            from voiceio import clipboard_read
+            clipboard_read.copy_text(text)
+
+        threading.Thread(target=_copy, daemon=True).start()
+
     def _play_feedback(self, text: str) -> None:
         if self.cfg.feedback.sound_enabled:
             from voiceio.feedback import play_commit_sound

voiceio/clipboard_read.py

@@ -1,4 +1,4 @@
-"""Read text from the system clipboard or primary selection."""
+"""Read/write text from/to the system clipboard or primary selection."""
 from __future__ import annotations
 
 import logging
@@ -67,3 +67,49 @@ def read_text() -> str | None:
 
     log.debug("No clipboard tool found")
     return None
+
+
+def _copy_via(cmd: list[str], text: str) -> bool:
+    """Pipe text into a copy command. Returns True on success."""
+    try:
+        result = subprocess.run(
+            cmd, input=text.encode(), capture_output=True, timeout=_TIMEOUT,
+        )
+        return result.returncode == 0
+    except (FileNotFoundError, subprocess.TimeoutExpired, OSError):
+        return False
+
+
+def copy_text(text: str) -> bool:
+    """Copy text to the system CLIPBOARD selection.
+
+    Best-effort: returns False (never raises) when no tool is available
+    or the copy fails.
+    """
+    if not text:
+        return False
+    p = detect()
+
+    if p.is_windows:
+        try:
+            import pyperclip
+            pyperclip.copy(text)
+            return True
+        except Exception:
+            log.debug("pyperclip not available for clipboard write")
+            return False
+
+    if p.is_mac:
+        return _copy_via(["pbcopy"], text)
+
+    if p.is_wayland:
+        if shutil.which("wl-copy"):
+            return _copy_via(["wl-copy", "--"], text)
+    else:
+        if shutil.which("xclip"):
+            return _copy_via(["xclip", "-selection", "clipboard"], text)
+        if shutil.which("xsel"):
+            return _copy_via(["xsel", "-i", "--clipboard"], text)
+
+    log.debug("No clipboard tool found for copy")
+    return False

voiceio/config.py

@@ -33,6 +33,11 @@ PID_PATH = LOG_DIR / "voiceio.pid"
 # and the retired-rule state consulted by the mining side.
 CORRECTIONS_AUDIT_PATH = LOG_DIR / "corrections_audit.jsonl"
 METRICS_PATH = LOG_DIR / "metrics.jsonl"
+# Intermediate pipeline data kept for debugging/profiling and future training:
+# per-pass streaming decode traces and postcorrect before/after pairs. These
+# live in their own JSONL files (not the rotating log) so they survive.
+TRACES_PATH = LOG_DIR / "streaming_trace.jsonl"
+POSTCORRECT_PAIRS_PATH = LOG_DIR / "postcorrect_pairs.jsonl"
 SNAPSHOTS_DIR = CONFIG_DIR / "snapshots"
 AUDIT_STATE_PATH = CONFIG_DIR / "audit_state.json"
 AUTOCORRECT_STATE_PATH = CONFIG_DIR / "autocorrect_state.json"
@@ -79,6 +84,17 @@ class OutputConfig:
     punctuation_cleanup: bool = True
     number_conversion: bool = True
     voice_input_prefix: str = ""           # e.g. "[voice]" — empty disables
+    # Incremental finalization: once the un-finalized audio tail grows past
+    # this many seconds AND ends in silence, beam-decode and freeze it during
+    # recording, so interim passes and the stop-time final decode only cover
+    # the short remaining tail. 0 disables (full re-decode at stop).
+    streaming_freeze_secs: float = 25.0
+    # Mirror transcribed text to the system clipboard so it can be pasted:
+    #   "off"   — never
+    #   "final" — the corrected final text, once ready
+    #   "live"  — also the best-so-far text at each streaming update and the
+    #             instant recording stops (pasteable while the final decode runs)
+    copy_to_clipboard: str = "final"
 
 
 @dataclass
@@ -173,7 +189,14 @@ class DataConfig:
     """
     retain_audio: bool = True
     max_audio_mb: int = 4096   # prune oldest recordings beyond this
+    # Never let retention squeeze the disk: skip saving and prune harder
+    # when the filesystem has less than this much free space.
+    min_free_gb: float = 5.0
     capture_context: bool = True  # best-effort active-window title
+    # Per-pass streaming decode traces + postcorrect before/after pairs
+    # (streaming_trace.jsonl / postcorrect_pairs.jsonl) for debugging,
+    # profiling, and future fine-tuning.
+    capture_intermediates: bool = True
 
 
 @dataclass
@@ -277,6 +300,8 @@ def _content_files() -> list[Path]:
         HISTORY_PATH,
         CORRECTIONS_AUDIT_PATH,
         METRICS_PATH,
+        TRACES_PATH,
+        POSTCORRECT_PAIRS_PATH,
         AUDIT_STATE_PATH,
         AUTOCORRECT_STATE_PATH,
         CONSENT_PATH,

voiceio/postcorrect.py

@@ -15,6 +15,7 @@ from __future__ import annotations
 import dataclasses
 import difflib
 import logging
+import threading
 import time
 
 from voiceio.config import AutocorrectConfig, Config
@@ -90,6 +91,13 @@ class PostCorrector:
         self._vocabulary = ""
         self._recent: list[str] = []
         self._context: str | None = None
+        # Context actually sent with the in-progress correct() call (what
+        # _record must persist — may differ from self._context).
+        self._effective_ctx: str | None = None
+        # A worker abandoned at the deadline may block indefinitely on a hung
+        # endpoint; cap leakage at one thread/socket by skipping new calls
+        # while it is still alive.
+        self._abandoned: threading.Thread | None = None
 
     # ── availability ────────────────────────────────────────────────────
 
@@ -140,6 +148,27 @@ class PostCorrector:
         parts.append(f"Transcript to correct:\n{text}")
         return "\n\n".join(parts)
 
+    def _record(self, before: str, after: str | None, outcome: str) -> None:
+        """Persist one LLM attempt (before/after/outcome) as training data.
+
+        Pairs land in postcorrect_pairs.jsonl — unlike the rotating log they
+        survive, so accepted AND rejected corrections stay available for
+        tuning guards or training a local corrector later.
+        """
+        if not self._cfg.data.capture_intermediates:
+            return
+        from voiceio import retention
+        from voiceio.config import POSTCORRECT_PAIRS_PATH
+        retention.append_jsonl(POSTCORRECT_PAIRS_PATH, {
+            "ts": time.time(),
+            "before": before,
+            "after": after,
+            "outcome": outcome,
+            "secs": round(self.last_secs, 3) if self.last_secs is not None else None,
+            "model": self._pc.model or self._ac.model,
+            "context": self._effective_ctx,
+        })
+
     def correct(
         self, text: str, *, vocabulary: str = "",
         recent: list[str] | None = None, context: str | None = None,
@@ -161,28 +190,65 @@ class PostCorrector:
         vocab = vocabulary or self._vocabulary
         rec = recent if recent is not None else self._recent
         ctx = context if context is not None else self._context
+        self._effective_ctx = ctx
+
+        if self._abandoned is not None:
+            if self._abandoned.is_alive():
+                log.warning(
+                    "PostCorrector: previous request still hung — skipping this one",
+                )
+                self._record(text, None, "skipped_busy")
+                return text
+            self._abandoned = None
 
         from voiceio.llm_api import chat
         user_msg = self._build_user_message(text, vocab, rec, ctx)
+        # timeout_secs must bound the WALL CLOCK the user waits, but urllib's
+        # timeout is per-socket-read — a slowly streaming response can run
+        # far past it (observed ~14s with an 8s config). Run the call in a
+        # thread and abandon it at the deadline.
         t0 = time.monotonic()
-        try:
-            response = chat(self._client_cfg(), _SYSTEM_PROMPT, user_msg, max_tokens=1024)
-        except Exception as e:
-            log.debug("PostCorrector LLM error: %s — keeping original", e)
+        outcome: dict = {}
+
+        def _call() -> None:
+            try:
+                outcome["response"] = chat(
+                    self._client_cfg(), _SYSTEM_PROMPT, user_msg, max_tokens=1024,
+                )
+            except Exception as e:
+                outcome["error"] = e
+
+        worker = threading.Thread(target=_call, daemon=True)
+        worker.start()
+        worker.join(self._pc.timeout_secs)
+        self.last_secs = time.monotonic() - t0
+        if worker.is_alive():
+            log.debug(
+                "PostCorrector deadline (%.1fs) exceeded — keeping original",
+                self._pc.timeout_secs,
+            )
+            self._abandoned = worker
+            self._record(text, None, "timeout")
+            return text
+        if "error" in outcome:
+            log.debug("PostCorrector LLM error: %s — keeping original", outcome["error"])
+            self._record(text, None, "error")
             return text
-        finally:
-            self.last_secs = time.monotonic() - t0
+        response = outcome.get("response")
 
         if not response:
             log.debug("PostCorrector: empty/failed response — keeping original")
+            self._record(text, None, "empty")
             return text
 
         corrected = _strip_wrapping(response)
         if not corrected:
             log.debug("PostCorrector: response empty after stripping — keeping original")
+            self._record(text, None, "empty")
             return text
 
         if corrected == text:
+            self._record(text, corrected, "unchanged")
             return text
 
         # Guard: word-count must not change materially.
@@ -192,6 +258,7 @@ class PostCorrector:
                 "PostCorrector reject: word count %d→%d (>%.0f%%) — keeping original",
                 orig_wc, new_wc, _MAX_WORDCOUNT_DELTA * 100,
             )
+            self._record(text, corrected, "rejected_wordcount")
             return text
 
         # Guard: only a small fraction of words may change.
@@ -201,7 +268,9 @@ class PostCorrector:
                 "PostCorrector reject: edit ratio %.2f > %.2f — keeping original",
                 ratio, _MAX_EDIT_RATIO,
             )
+            self._record(text, corrected, "rejected_editratio")
             return text
 
         log.info("PostCorrector fixed: %s", ", ".join(_changed_words(text, corrected)))
+        self._record(text, corrected, "applied")
         return corrected

voiceio/recorder.py

@@ -162,6 +162,17 @@ class AudioRecorder:
                 return False, f"no audio callback for {stale:.1f}s"
         return True, ""
 
+    def is_zombie(self) -> bool:
+        """Stream firing callbacks but delivering only digital zeros.
+
+        The post-suspend PortAudio failure mode: the heartbeat stays healthy
+        while the capture node is gone. Distinct from a merely-empty ring
+        (fresh stream) or a muted mic (noise floor > 0 on real hardware).
+        """
+        if self._ring._filled < self._ring._max:
+            return False  # ring not yet full — can't judge
+        return not self.has_signal()
+
     def has_signal(self) -> bool:
         """Check if the pre-buffer ring contains non-silence audio.
 

voiceio/retention.py

@@ -7,17 +7,19 @@ mining measurable and personal fine-tuning possible later.
 from __future__ import annotations
 
 import functools
+import json
 import logging
 import shutil
 import subprocess
 import time
 import wave
+from pathlib import Path
 from typing import TYPE_CHECKING
 
 import numpy as np
 
 from voiceio import config
-from voiceio.config import RECORDINGS_DIR
+from voiceio.config import RECORDINGS_DIR, TRACES_PATH
 
 if TYPE_CHECKING:
     from voiceio.config import DataConfig
@@ -27,11 +29,25 @@ log = logging.getLogger(__name__)
 _which = functools.lru_cache(maxsize=8)(shutil.which)
 
 
+def _free_gb(path: Path) -> float:
+    """Free space (GB) on the filesystem holding `path`. Inf on failure."""
+    try:
+        return shutil.disk_usage(path).free / 1024**3
+    except OSError:
+        return float("inf")
+
+
 def save_audio(audio: np.ndarray, ts: float, cfg: DataConfig) -> str | None:
     """Persist one utterance as 16kHz mono int16 WAV. Returns the filename
     (relative to the recordings dir) or None if disabled/failed."""
     if not cfg.retain_audio or audio is None or len(audio) == 0:
         return None
+    if _free_gb(RECORDINGS_DIR.parent) < cfg.min_free_gb:
+        log.warning(
+            "Disk has <%.0fGB free — skipping audio retention for this utterance",
+            cfg.min_free_gb,
+        )
+        return None
     name = time.strftime("%Y%m%d-%H%M%S", time.localtime(ts)) + f"-{int(ts * 1000) % 1000:03d}.wav"
     path = RECORDINGS_DIR / name
     try:
@@ -70,6 +86,15 @@ def prune(cfg: DataConfig) -> None:
         )
         total = sum(p.stat().st_size for p in files)
         budget = cfg.max_audio_mb * 1024 * 1024
+        # Below the free-disk floor, shrink the budget so retention yields
+        # space back instead of holding its full cap on a squeezed disk.
+        free = _free_gb(RECORDINGS_DIR.parent)
+        if free < cfg.min_free_gb:
+            budget = min(budget, total // 2)
+            log.warning(
+                "Disk has %.1fGB free (<%.0fGB floor) — pruning recordings to %.0fMB",
+                free, cfg.min_free_gb, budget / 1024 / 1024,
+            )
         while total > budget and files:
             oldest = files.pop(0)
             total -= oldest.stat().st_size
@@ -79,6 +104,45 @@ def prune(cfg: DataConfig) -> None:
         log.debug("Recording prune failed", exc_info=True)
 
 
+_JSONL_MAX_BYTES = 64 * 1024 * 1024  # per capture file; oldest half dropped
+
+
+def append_jsonl(path: Path, entry: dict) -> None:
+    """Append one JSON line to a 0600 data file. Best-effort, never raises.
+
+    Capture files are bounded: past _JSONL_MAX_BYTES the oldest half of the
+    lines is dropped, so intermediate-data capture can never grow unbounded
+    on a disk the min_free_gb floor is trying to protect.
+    """
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        config._chmod(path.parent, config._SECURE_DIR)
+        newly_created = not path.exists()
+        if not newly_created and path.stat().st_size > _JSONL_MAX_BYTES:
+            lines = path.read_text(encoding="utf-8").splitlines(keepends=True)
+            path.write_text("".join(lines[len(lines) // 2:]), encoding="utf-8")
+            log.info("Trimmed %s to newest %d entries", path.name, len(lines) - len(lines) // 2)
+        with open(path, "a", encoding="utf-8") as f:
+            f.write(json.dumps(entry, ensure_ascii=False) + "\n")
+        if newly_created:
+            config._chmod(path, config._SECURE_FILE)
+    except (OSError, TypeError, ValueError) as e:
+        log.warning("Failed to write %s: %s", path.name, e)
+
+
+def save_trace(cfg: DataConfig, entry: dict) -> None:
+    """Persist one utterance's per-pass streaming decode trace.
+
+    One line per utterance in streaming_trace.jsonl: pass timings, kinds
+    (interim/freeze/final), tail lengths, and raw tail texts — the data
+    needed to debug/profile streaming behaviour and to train on interim
+    hypotheses later. Linked to history via ts + audio filename.
+    """
+    if not cfg.capture_intermediates:
+        return
+    append_jsonl(TRACES_PATH, entry)
+
+
 def active_window_title() -> str | None:
     """Best-effort title of the focused window (dictation target context).
 

voiceio/streaming.py

@@ -8,11 +8,12 @@ import threading
 import time
 from typing import TYPE_CHECKING, Callable
 
+import numpy as np
+
 from voiceio.transcriber import transcribe_timeout
 from voiceio.typers.base import StreamingTyper
 
 if TYPE_CHECKING:
-    import numpy as np
     from voiceio.commands import CommandProcessor
     from voiceio.corrections import CorrectionDict
     from voiceio.llm import LLMProcessor
@@ -24,6 +25,32 @@ if TYPE_CHECKING:
 log = logging.getLogger(__name__)
 DELETE_SETTLE_SECS = 0.05  # delay between delete and type for ydotool reliability
 
+# Incremental finalization: a freeze cut is only safe at a speech pause, so
+# require the tail's trailing window to be quiet before cutting there.
+_FREEZE_SILENCE_WINDOW_SECS = 0.3
+# Quiet is judged RELATIVE to the tail's own level: mic gains vary wildly
+# and the decode path normalizes audio anyway, so an absolute threshold
+# would read a quiet mic's speech as silence (mid-word cuts) and a hot
+# noise floor as speech (freeze never fires).
+_FREEZE_SILENCE_RATIO = 0.15
+_FREEZE_SILENCE_FLOOR = 1e-4  # digital silence is always quiet
+# Whisper conditions on ~224 prompt tokens; more frozen context is wasted.
+_FREEZE_CONTEXT_CHARS = 400
+
+
+def _rms(samples: np.ndarray) -> float:
+    return float(np.sqrt(np.mean(np.square(samples, dtype=np.float64))))
+
+
+def _tail_ends_in_silence(tail: np.ndarray, sample_rate: int) -> bool:
+    """True when the last _FREEZE_SILENCE_WINDOW_SECS of audio are quiet
+    relative to the tail's overall level."""
+    window = tail[-int(_FREEZE_SILENCE_WINDOW_SECS * sample_rate):]
+    if len(window) == 0:
+        return False
+    threshold = max(_FREEZE_SILENCE_RATIO * _rms(tail), _FREEZE_SILENCE_FLOOR)
+    return _rms(window) < threshold
+
 
 def _common_prefix_len(a: str, b: str) -> int:
     """Length of the longest common prefix between two strings."""
@@ -34,6 +61,16 @@ def _common_prefix_len(a: str, b: str) -> int:
     return limit
 
 
+def _join_text(a: str, b: str) -> str:
+    """Join two transcript fragments with a single space."""
+    a, b = a.strip(), (b or "").strip()
+    if not a:
+        return b
+    if not b:
+        return a
+    return a + " " + b
+
+
 def _clean_word(w: str) -> str:
     """Strip punctuation for fuzzy word matching."""
     return re.sub(r'[^\w]', '', w).lower()
@@ -84,6 +121,8 @@ class StreamingSession:
         voice_input_prefix: str = "",
         on_typer_broken: Callable[[], None] | None = None,
         is_current: Callable[[], bool] | None = None,
+        on_interim: Callable[[str], None] | None = None,
+        freeze_secs: float = 25.0,
     ):
         self._transcriber = transcriber
         self._typer = typer
@@ -104,6 +143,7 @@ class StreamingSession:
         self._llm = llm
         self._voice_input_prefix = voice_input_prefix
         self._on_typer_broken = on_typer_broken
+        self._on_interim = on_interim
         self._typer_fail_count = 0
         self._typer_broken_signalled = False
         self._typed_text = ""
@@ -111,10 +151,26 @@ class StreamingSession:
         self._stop_event = threading.Event()
         self._worker_thread: threading.Thread | None = None
         self._final_audio: np.ndarray | None = None  # set on stop
+        # Incremental finalization: audio before _frozen_samples has already
+        # been beam-decoded into _frozen_raw and is never decoded again.
+        # Interim and final passes only decode the tail after this offset.
+        self._freeze_secs = freeze_secs
+        self._frozen_samples = 0
+        self._frozen_raw = ""
+        self._frozen_segments: list[dict] = []
         # Raw (pre-pipeline) text + confidence of the final pass, for history
         self.raw_final_text: str | None = None
         self.final_latency: dict = {}
         self.final_segments: list[dict] = []
+        # Per-pass decode trace (interim/freeze/final) for debugging,
+        # profiling, and future training. Persisted via retention.save_trace.
+        self.trace: list[dict] = []
+        self._t0 = time.monotonic()
+
+    @property
+    def interim_text(self) -> str:
+        """Best-so-far text (post-pipeline). Safe to read while finalizing."""
+        return self._typed_text
 
     def set_is_current(self, is_current: Callable[[], bool]) -> None:
         """Install the output-ownership gate (see __init__).
@@ -206,10 +262,22 @@ class StreamingSession:
             log.exception("Final transcribe/apply error")
         self._final_audio = None  # release memory
 
+    def _frozen_context(self) -> str | None:
+        """Frozen-text suffix used to condition the tail decode."""
+        if not self._frozen_raw:
+            return None
+        return self._frozen_raw[-_FREEZE_CONTEXT_CHARS:]
+
     def _transcribe_and_apply(
         self, min_seconds: float = 1.0, final: bool = False,
     ) -> None:
-        """Get audio, transcribe, apply correction."""
+        """Get audio, transcribe the un-frozen tail, apply correction.
+
+        Incremental finalization: audio before _frozen_samples was already
+        beam-decoded and frozen, so every pass — including the final one —
+        only decodes the tail. Long dictations finalize in O(tail), not
+        O(recording).
+        """
         if final and self._final_audio is not None:
             # Use the snapshot passed to stop() — recorder may be gone
             audio = self._final_audio
@@ -223,22 +291,84 @@ class StreamingSession:
         if len(audio) < self._sample_rate * min_seconds:
             return
 
+        tail = audio[self._frozen_samples:]
+        if not final and len(tail) < self._sample_rate * min_seconds:
+            return  # not enough new audio since the last freeze
+
+        # Freeze when the tail has grown long AND ends at a speech pause
+        # (never cut mid-word). The freeze pass gets beam search because its
+        # text is never decoded again.
+        freeze = (
+            not final
+            and self._freeze_secs > 0
+            and len(tail) >= self._freeze_secs * self._sample_rate
+            and _tail_ends_in_silence(tail, self._sample_rate)
+        )
+
+        tail_text = ""
+        tail_segments: list[dict] = []
         t0 = time.monotonic()
-        try:
-            text = self._transcriber.transcribe(audio, final=final)
-        except Exception:
-            log.exception("Streaming transcription failed")
-            return
+        # The final pass decodes ANY remaining audio (a clipped last word
+        # must not be dropped); interim/freeze passes skip sub-0.3s tails.
+        if len(tail) > (0 if final else self._sample_rate * 0.3):
+            try:
+                tail_text = self._transcriber.transcribe(
+                    tail, final=final or freeze, context=self._frozen_context(),
+                )
+            except Exception:
+                # Decode FAILED (timeout/crash) — this is not silence. Never
+                # advance the freeze boundary or char-diff against a partial
+                # transcript; on final, commit what is already on screen.
+                log.exception("Streaming transcription failed")
+                if final:
+                    self.raw_final_text = ""
+                    self.final_latency = {
+                        "audio_secs": round(len(audio) / self._sample_rate, 2),
+                        "frozen_secs": round(self._frozen_samples / self._sample_rate, 2),
+                        "tail_secs": round(len(tail) / self._sample_rate, 2),
+                        "transcribe": round(time.monotonic() - t0, 3),
+                        "decode_failed": True,
+                    }
+                    self._commit_interim_on_final()
+                return
+            tail_segments = list(getattr(self._transcriber, "last_segments", []))
         t_transcribe = time.monotonic() - t0
 
+        self.trace.append({
+            "t": round(time.monotonic() - self._t0, 2),
+            "kind": "final" if final else ("freeze" if freeze else "interim"),
+            "frozen_secs": round(self._frozen_samples / self._sample_rate, 2),
+            "tail_secs": round(len(tail) / self._sample_rate, 2),
+            "secs": round(t_transcribe, 3),
+            "text": tail_text,
+        })
+
+        if freeze:
+            self._frozen_raw = _join_text(self._frozen_raw, tail_text)
+            self._frozen_samples = len(audio)
+            self._frozen_segments.extend(tail_segments)
+            log.debug(
+                "Froze %.1fs of audio (frozen text now %d chars)",
+                len(tail) / self._sample_rate, len(self._frozen_raw),
+            )
+        raw = self._frozen_raw if freeze else _join_text(self._frozen_raw, tail_text)
+
+        # An interim pass that decoded nothing must not touch the display:
+        # rewriting to frozen-only text would visibly delete the un-frozen
+        # words the previous pass just showed (transient decoder flake).
+        if not final and not tail_text:
+            return
+
         if final:
-            self.raw_final_text = text
-            self.final_segments = getattr(self._transcriber, "last_segments", [])
+            self.raw_final_text = raw
+            self.final_segments = self._frozen_segments + tail_segments
             self.final_latency = {
                 "audio_secs": round(len(audio) / self._sample_rate, 2),
+                "frozen_secs": round(self._frozen_samples / self._sample_rate, 2),
+                "tail_secs": round(len(tail) / self._sample_rate, 2),
                 "transcribe": round(t_transcribe, 3),
             }
-            if not text:
+            if not raw:
                 # The final pass produced nothing. If we already have interim
                 # text (e.g. the final transcription timed out on a long
                 # dictation), commit that instead of silently dropping it —
@@ -246,11 +376,11 @@ class StreamingSession:
                 self._commit_interim_on_final()
                 return
 
-        if text and isinstance(text, str):
+        if raw:
             from voiceio.postprocess import apply_pipeline
             t1 = time.monotonic()
             text, abort = apply_pipeline(
-                text,
+                raw,
                 do_cleanup=self._cleanup,
                 number_conversion=self._number_conversion,
                 language=self._language,
@@ -267,6 +397,11 @@ class StreamingSession:
                 if pc_secs is not None:
                     self.final_latency["postcorrect"] = round(pc_secs, 3)
             if abort:
+                # A voice command wiped the utterance — discard frozen text
+                # too, or the next pass would resurrect it.
+                self._frozen_raw = ""
+                self._frozen_segments = []
+                self._frozen_samples = len(audio)
                 # A superseded session must not touch the typer on the final
                 # path (would corrupt the newer session's output).
                 if final and not self._is_current():
@@ -280,7 +415,13 @@ class StreamingSession:
                 return
 
             if text:
+                prev = self._typed_text
                 self._apply_correction(text, final=final)
+                if not final and self._on_interim and self._typed_text != prev:
+                    try:
+                        self._on_interim(self._typed_text)
+                    except Exception:
+                        log.debug("on_interim callback failed", exc_info=True)
 
     def _commit_interim_on_final(self) -> None:
         """Commit whatever interim text we have when the final pass yields none.

voiceio/transcriber.py

@@ -18,6 +18,12 @@ if TYPE_CHECKING:
 log = logging.getLogger(__name__)
 
 TRANSCRIBE_TIMEOUT = 30  # seconds (floor; scaled up for long audio)
+
+
+class TranscriptionError(RuntimeError):
+    """Decode failed (timeout / worker crash). Distinct from a legitimate
+    empty result ("" = silence) so callers never treat lost audio as decoded
+    silence — the streaming freeze/final paths must not advance state on it."""
 # Realtime-factor headroom for the read timeout. Whisper decodes well faster
 # than realtime, so 1.5x the audio duration is a generous ceiling that still
 # never kills a long dictation mid-decode.
@@ -152,10 +158,17 @@ class Transcriber:
         log.warning("Worker died, restarting (attempt %d/%d)", self._restarts, MAX_RESTARTS)
         self._start_worker()
 
-    def transcribe(self, audio: np.ndarray, final: bool = False) -> str:
+    def transcribe(
+        self, audio: np.ndarray, final: bool = False, context: str | None = None,
+    ) -> str:
         """Transcribe audio. `final=True` marks the pass whose text the user
         keeps (streaming final / batch): it gets beam search; interim streaming
-        passes stay greedy for latency."""
+        passes stay greedy for latency.
+
+        `context` is per-call text appended to the initial_prompt — used by
+        incremental finalization to condition a tail decode on the already-
+        frozen transcript so sentences stay coherent across the cut.
+        """
         with self._lock:
             self._ensure_worker()
 
@@ -165,8 +178,9 @@ class Transcriber:
             audio = normalize_audio(audio)
             audio_b64 = base64.b64encode(audio.tobytes()).decode("ascii")
             req = {"audio_b64": audio_b64, "options": {"beam_size": 5 if final else 1}}
-            if self._initial_prompt:
-                req["initial_prompt"] = self._initial_prompt
+            prompt = "\n".join(p for p in (self._initial_prompt, context) if p)
+            if prompt:
+                req["initial_prompt"] = prompt
             if self._hotwords:
                 req["hotwords"] = self._hotwords
             try:
@@ -184,16 +198,18 @@ class Transcriber:
             timeout = transcribe_timeout(duration)
             result_line = self._read_with_timeout(timeout)
             if result_line is None:
+                self.last_segments = []
                 log.warning("Transcription timed out after %.0fs, restarting worker", timeout)
                 self._kill_worker()
                 self._ensure_worker()
-                return ""
+                raise TranscriptionError(f"decode timed out after {timeout:.0f}s")
 
             try:
                 result = json.loads(result_line)
             except (json.JSONDecodeError, TypeError):
+                self.last_segments = []
                 log.warning("Invalid response from worker: %s", repr(result_line)[:100])
-                return ""
+                raise TranscriptionError("invalid worker response")
             text = result.get("text", "")
             self.last_segments = result.get("segments", [])
 

voiceio/wizard.py

@@ -680,7 +680,7 @@ def _write_config(
             "model": autocorrect_model or "moonshotai/kimi-k2-0905",
         })
 
-    CONFIG_PATH.write_text(_dump_toml(cfg))
+    CONFIG_PATH.write_text(_dump_toml(cfg), encoding="utf-8")
     _secure_config_permissions()
     if not quiet:
         print(f"\n  {GREEN}✓{RESET} Config saved to {DIM}{CONFIG_PATH}{RESET}")