python-voiceio 1.9.3__tar.gz → 1.10.0__tar.gz

{python_voiceio-1.9.3/python_voiceio.egg-info → python_voiceio-1.10.0}/PKG-INFO

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

{python_voiceio-1.9.3 → python_voiceio-1.10.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-voiceio"
-version = "1.9.3"
+version = "1.10.0"
 description = "Voice dictation for Linux. Speak → text, locally, instantly."
 readme = "README.md"
 license = "MIT"

{python_voiceio-1.9.3 → python_voiceio-1.10.0/python_voiceio.egg-info}/PKG-INFO

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

{python_voiceio-1.9.3 → python_voiceio-1.10.0}/python_voiceio.egg-info/SOURCES.txt

@@ -52,6 +52,7 @@ tests/test_learn_review.py
 tests/test_learn_targets.py
 tests/test_llm.py
 tests/test_llm_api.py
+tests/test_mic_gain.py
 tests/test_modifier_guard.py
 tests/test_numbers.py
 tests/test_paste_last.py
@@ -101,6 +102,7 @@ voiceio/history.py
 voiceio/idle_audio.py
 voiceio/llm.py
 voiceio/llm_api.py
+voiceio/mic_gain.py
 voiceio/numbers.py
 voiceio/pidlock.py
 voiceio/platform.py
@@ -187,6 +189,7 @@ voiceio/setup/steps.py
 voiceio/setup/system.py
 voiceio/setup/ui.py
 voiceio/sounds/__init__.py
+voiceio/sounds/alert.wav
 voiceio/sounds/commit.wav
 voiceio/sounds/start.wav
 voiceio/sounds/stop.wav

python_voiceio-1.10.0/tests/test_mic_gain.py

@@ -0,0 +1,85 @@
+"""Input gain follows the recordings: down on clipping, up when very quiet,
+never back to a level that clipped."""
+from __future__ import annotations
+
+from voiceio import mic_gain
+from voiceio.mic_gain import MicGain
+
+
+class FakeSource:
+    def __init__(self, volume):
+        self.volume = volume
+        self.sets = []
+
+    def get(self):
+        return self.volume
+
+    def set(self, v):
+        self.sets.append(v)
+        self.volume = v
+        return True
+
+
+def _gain(volume=0.5):
+    g = MicGain(enabled=False)
+    g._source = FakeSource(volume)
+    return g
+
+
+def test_clipping_lowers_by_a_fifth():
+    g = _gain(0.5)
+    change = g.after_recording(peak=1.0, clip_ratio=0.02, secs=10)
+    assert change.reason == "clipping" and g._source.volume == 0.4
+
+
+def test_never_below_the_floor():
+    g = _gain(0.11)
+    g.after_recording(1.0, 0.02, 10)
+    assert g._source.volume == mic_gain.FLOOR
+
+
+def test_three_quiet_recordings_raise_but_not_to_a_level_that_clipped():
+    g = _gain(0.5)
+    g.after_recording(1.0, 0.02, 10)                 # 0.5 clipped -> 0.4
+    for _ in range(2):
+        assert g.after_recording(0.05, 0.0, 10) is None
+    assert g.after_recording(0.05, 0.0, 10) is None  # third quiet one: would reach 0.5
+    assert g._source.volume == 0.4                  # capped at 0.5 * 0.8: no oscillation
+
+
+def test_quiet_without_any_clipping_history_raises():
+    g = _gain(0.3)
+    for _ in range(3):
+        change = g.after_recording(0.05, 0.0, 10)
+    assert change.new == round(0.3 / mic_gain.STEP, 2)
+
+
+def test_short_or_dead_recordings_dont_count():
+    g = _gain(0.3)
+    for _ in range(5):
+        assert g.after_recording(0.05, 0.0, 1.0) is None   # too short
+        assert g.after_recording(0.0, 0.0, 10) is None     # muted mic: not a gain problem
+    assert g._source.sets == []
+
+
+def test_normal_level_resets_the_quiet_streak():
+    g = _gain(0.3)
+    g.after_recording(0.05, 0.0, 10)
+    g.after_recording(0.05, 0.0, 10)
+    g.after_recording(0.5, 0.0, 10)
+    assert g.after_recording(0.05, 0.0, 10) is None
+
+
+def test_a_chosen_device_is_left_alone():
+    assert not MicGain(enabled=True, device="hw:1").active
+
+
+def test_off_without_volume_tools(monkeypatch):
+    # conftest: quiet_audio._which finds nothing in tests
+    assert not MicGain(enabled=True).active
+
+
+def test_failures_never_raise():
+    g = _gain(0.5)
+    g._source.get = lambda: (_ for _ in ()).throw(RuntimeError("boom"))
+    assert g.after_recording(1.0, 0.02, 10) is None

{python_voiceio-1.9.3 → python_voiceio-1.10.0}/tests/test_service.py

@@ -44,7 +44,7 @@ def test_learn_timer_runs_maintain_at_idle_priority(monkeypatch, tmp_path):
                  "MemoryHigh=25%", "OOMScoreAdjust=500"):
         assert f"\n{line}\n" in unit, line
     timer = service.LEARN_TIMER_PATH.read_text()
-    assert "Persistent=true" in timer and "OnCalendar=*-*-* 03:30" in timer
+    assert "Persistent=true" in timer and "OnCalendar=Sun *-*-* 03:30" in timer
     assert ("enable", "--now", service.LEARN_TIMER_NAME) in calls
 
     service.uninstall_learn_timer()
@@ -109,7 +109,7 @@ def test_learn_schedule_comes_from_config(monkeypatch, tmp_path):
     monkeypatch.setattr(service, "LEARN_SERVICE_PATH", tmp_path / "s.service")
     monkeypatch.setattr(service, "LEARN_TIMER_PATH", tmp_path / "s.timer")
     service.install_learn_timer()
-    assert "OnCalendar=*-*-* 03:30" in service.LEARN_TIMER_PATH.read_text()
+    assert "OnCalendar=Sun *-*-* 03:30" in service.LEARN_TIMER_PATH.read_text()   # weekly by default
 
     config.set_value("learn", "at", "2:05")
     config.set_value("learn", "every", "week")

python_voiceio-1.10.0/voiceio/__init__.py

@@ -0,0 +1 @@
+__version__ = "1.10.0"

{python_voiceio-1.9.3 → python_voiceio-1.10.0}/voiceio/app.py

@@ -111,6 +111,8 @@ class VoiceIO:
         self._recording_bias = Bias()
         from voiceio.quiet_audio import QuietAudio
         self._quiet = QuietAudio(cfg.audio.pause_media, cfg.audio.duck_volume)
+        from voiceio.mic_gain import MicGain
+        self._mic_gain = MicGain(cfg.audio.auto_gain, cfg.audio.device)
 
         self._command_processor = CommandProcessor(enabled=cfg.commands.enabled, editing=cfg.commands.editing)
         self._streaming = cfg.output.streaming
@@ -437,10 +439,9 @@ class VoiceIO:
         if dead:
             log.warning("Mic still silent after reopening")
             from voiceio import feedback
-            feedback.notify(
+            feedback.mic_alert(
                 "VoiceIO: microphone stopped sending audio",
-                "Your words so far are kept. Stop, check the input device, and try again.",
-                urgent=True,
+                "Your words so far are kept.",
             )
         else:
             log.info("Mic stream recovered mid-recording")
@@ -457,10 +458,9 @@ class VoiceIO:
         if reason == "no_speech":
             from voiceio import feedback
             if not self.recorder.has_signal():
-                feedback.notify(
+                feedback.mic_alert(
                     "VoiceIO: microphone is muted",
-                    "Stopped — no audio is reaching voiceio. Check your mic's "
-                    "mute button and that the right input device is selected.",
+                    "Stopped — no audio is reaching voiceio.",
                 )
             else:
                 feedback.notify(
@@ -485,11 +485,9 @@ class VoiceIO:
             return
         log.warning("Recording captured no audio at all — mic muted?")
         from voiceio import feedback
-        feedback.notify(
+        feedback.mic_alert(
             "VoiceIO: microphone is muted — nothing recorded",
-            "No audio reached voiceio for that entire recording. Check your "
-            "mic's mute button and which input device is selected.",
-            urgent=True,
+            "No audio reached voiceio for that entire recording.",
         )
 
     def _request_stop(self) -> None:
@@ -576,10 +574,9 @@ class VoiceIO:
             if not self.recorder.has_signal():
                 log.warning("Mic still silent after reopen — muted or wrong device?")
                 from voiceio import feedback
-                feedback.notify(
+                feedback.mic_alert(
                     "VoiceIO: microphone appears silent",
-                    "Check that your mic is unmuted and the right input device is selected.",
-                    urgent=True,
+                    "No sound is coming from the input device.",
                 )
         elif not self.recorder.has_signal():
             log.warning("Mic appears silent or muted (pre-buffer is all zeros)")
@@ -634,7 +631,7 @@ class VoiceIO:
         audio = self.recorder.stop()
         tray.set_recording(False)
         self._idle_audio.touch()
-        self._warn_if_clipping()
+        self._check_input_level(time.monotonic() - self._record_start)
 
         self.engine.prepare_final(title=self._context_title)
 
@@ -706,13 +703,15 @@ class VoiceIO:
     _CLIP_RATIO_WARN = 0.005   # >0.5% of samples in flat-top runs
     _CLIP_WARN_INTERVAL = 300  # seconds between warnings
 
-    def _warn_if_clipping(self) -> None:
-        """Warn (rate-limited) when the mic input is saturating the ADC.
-
-        Clipping cannot be repaired in software — the gain must come down
-        before the ADC — so tell the user how to lower it.
-        """
+    def _check_input_level(self, secs: float) -> None:
+        """After a recording: fix the input gain when auto_gain can, else
+        warn (rate-limited) about clipping. Off this thread: the volume tools
+        are subprocesses."""
         meter = self.recorder.get_meter()
+        if self._mic_gain.active:
+            threading.Thread(target=self._adjust_gain, args=(meter, secs),
+                             daemon=True, name="mic-gain").start()
+            return
         if meter["clip_ratio"] < self._CLIP_RATIO_WARN:
             return
         now = time.monotonic()
@@ -731,6 +730,21 @@ class VoiceIO:
             "Input is clipping — lower your mic gain in system sound settings.",
         )
 
+    def _adjust_gain(self, meter: dict[str, float], secs: float) -> None:
+        change = self._mic_gain.after_recording(meter["peak"], meter["clip_ratio"], secs)
+        if change is None or change.reason != "clipping":
+            return
+        now = time.monotonic()
+        if now - self._last_clip_warn < self._CLIP_WARN_INTERVAL:
+            return
+        self._last_clip_warn = now
+        from voiceio import feedback
+        feedback.notify(
+            "VoiceIO lowered your mic volume",
+            f"It was clipping: {change.old:.0%} → {change.new:.0%}. "
+            "Turn it off with: voiceio config set audio.auto_gain false",
+        )
+
     # ── Background work ─────────────────────────────────────────────────
 
     def _finalize_streaming(

{python_voiceio-1.9.3 → python_voiceio-1.10.0}/voiceio/config.py

@@ -128,6 +128,10 @@ class AudioConfig:
     # last dictation; "never": closed between dictations, opened on the hotkey.
     keep_warm: str = "auto"
     warm_minutes: float = 5.0
+    # Follow your recordings with the default mic's input volume
+    # (voiceio/mic_gain.py): down a fifth after one that clipped, up a fifth
+    # after three that were very quiet, never back to a level that clipped.
+    auto_gain: bool = True
 
 
 @dataclass
@@ -290,7 +294,7 @@ class LearnConfig:
     # When nightly learning runs (`voiceio learn schedule on`): a time of day,
     # and "day" or "week" (weekly runs on Sunday).
     at: str = "03:30"
-    every: str = "day"
+    every: str = "week"
     # It works only while nobody is using the computer: no keyboard or mouse
     # input for away_minutes (or the screen locked), on mains power, and
     # starts only when the 1-minute load per CPU is at most max_load. When

{python_voiceio-1.9.3 → python_voiceio-1.10.0}/voiceio/feedback.py

@@ -76,7 +76,7 @@ def warm_up() -> None:
 
 
 def _load_sounds() -> None:
-    for name in ("start", "stop", "commit"):
+    for name in ("start", "stop", "commit", "alert"):
         path = _SOUNDS_DIR / f"{name}.wav"
         if name in _sounds or not path.exists():
             continue
@@ -141,6 +141,18 @@ def play_commit_sound() -> None:
     _play("commit")
 
 
+# The usual cause, by far: a hardware mic switch, a mute key or a muted
+# source. Each look the same to voiceio — a stream that sends only zeros.
+MIC_HINT = "Is the mic switched off or muted (privacy switch, mute key)?"
+
+
+def mic_alert(title: str, body: str) -> None:
+    """A dead or muted mic: an alert sound as well as the notification, since
+    you are talking, not looking at the screen."""
+    _play("alert")
+    notify(title, f"{body} {MIC_HINT}", urgent=True)
+
+
 def cue_secs(name: str) -> float:
     """How long a cue takes to play out; 0 when sound output is off."""
     if _stream is None or name not in _sounds:

python_voiceio-1.10.0/voiceio/mic_gain.py

@@ -0,0 +1,123 @@
+"""Mic input gain that follows your recordings ([audio] auto_gain).
+
+Clipping can't be repaired after the ADC, so the fix is the input volume.
+After each recording:
+
+  clipped (flat-top runs in >= 0.5% of samples)
+      → lower the default source's volume by a fifth, and remember that the
+        old level clipped: it is never raised back to it
+  three spoken recordings in a row that peaked below 0.1
+      → raise it by a fifth, staying under the level that clipped
+
+Only the default PipeWire/Pulse source is touched (wpctl, else pactl), and
+never below 10% or above 100%. A device chosen in [audio] device is the
+user's to set.
+"""
+from __future__ import annotations
+
+import logging
+import re
+from dataclasses import dataclass
+
+from voiceio import quiet_audio
+from voiceio.quiet_audio import _Caller
+
+log = logging.getLogger(__name__)
+
+CLIP_RATIO = 0.005
+QUIET_PEAK = 0.1
+QUIET_STREAK = 3
+MIN_SPEECH_SECS = 3.0
+STEP = 0.8
+FLOOR, CEILING = 0.10, 1.0
+
+
+class _WpctlSource:
+    def __init__(self, call: _Caller):
+        self._call = call
+
+    def get(self) -> float | None:
+        m = re.match(r"Volume: ([\d.]+)", self._call("wpctl", "get-volume", "@DEFAULT_AUDIO_SOURCE@") or "")
+        return float(m[1]) if m else None
+
+    def set(self, volume: float) -> bool:
+        return self._call("wpctl", "set-volume", "@DEFAULT_AUDIO_SOURCE@", f"{volume:.2f}") is not None
+
+
+class _PactlSource:
+    def __init__(self, call: _Caller):
+        self._call = call
+
+    def get(self) -> float | None:
+        m = re.search(r"(\d+)%", self._call("pactl", "get-source-volume", "@DEFAULT_SOURCE@") or "")
+        return int(m[1]) / 100 if m else None
+
+    def set(self, volume: float) -> bool:
+        return self._call("pactl", "set-source-volume", "@DEFAULT_SOURCE@",
+                          f"{round(volume * 100)}%") is not None
+
+
+@dataclass
+class Change:
+    old: float
+    new: float
+    reason: str   # "clipping" | "quiet"
+
+
+class MicGain:
+    def __init__(self, enabled: bool = True, device: str = "default", run=None):
+        call = _Caller(run)
+        self._source = None
+        if enabled and device in ("", "default"):
+            # Through the module: tests swap quiet_audio._which/_run for guards.
+            if quiet_audio._which("wpctl"):
+                self._source = _WpctlSource(call)
+            elif quiet_audio._which("pactl"):
+                self._source = _PactlSource(call)
+        self._clipped_at: float | None = None   # lowest level known to clip
+        self._quiet = 0
+
+    @property
+    def active(self) -> bool:
+        return self._source is not None
+
+    def after_recording(self, peak: float, clip_ratio: float, secs: float) -> Change | None:
+        """Adjust after one recording; the change made, if any. Never raises."""
+        if self._source is None:
+            return None
+        try:
+            return self._adjust(peak, clip_ratio, secs)
+        except Exception:  # noqa: BLE001 — a gain tweak must never break dictation
+            log.debug("mic gain adjustment failed", exc_info=True)
+            return None
+
+    def _adjust(self, peak: float, clip_ratio: float, secs: float) -> Change | None:
+        if clip_ratio >= CLIP_RATIO:
+            self._quiet = 0
+            old = self._source.get()
+            if old is None:
+                return None
+            self._clipped_at = old if self._clipped_at is None else min(self._clipped_at, old)
+            new = max(FLOOR, round(old * STEP, 2))
+            return self._set(old, new, "clipping")
+        if secs < MIN_SPEECH_SECS or peak <= 0:
+            return None   # too short to judge, or a dead/muted mic: not a gain problem
+        if peak >= QUIET_PEAK:
+            self._quiet = 0
+            return None
+        self._quiet += 1
+        if self._quiet < QUIET_STREAK:
+            return None
+        self._quiet = 0
+        old = self._source.get()
+        if old is None:
+            return None
+        top = CEILING if self._clipped_at is None else min(CEILING, round(self._clipped_at * STEP, 2))
+        new = min(top, round(old / STEP, 2))
+        return self._set(old, new, "quiet")
+
+    def _set(self, old: float, new: float, reason: str) -> Change | None:
+        if abs(new - old) < 0.005 or not self._source.set(new):
+            return None
+        log.info("Mic gain %s: input volume %.0f%% → %.0f%%", reason, old * 100, new * 100)
+        return Change(old, new, reason)

python_voiceio-1.9.3/voiceio/__init__.py

@@ -1 +0,0 @@
-__version__ = "1.9.3"