Correct the voice_gate_ratio tuning direction

A higher ratio raises the loudness gate, so it rejects more audio rather than less. The config guidance claimed the opposite; pin the direction with a test.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

config.example.yaml

@@ -58,8 +58,9 @@ wake_word:
   silence_ms: 800            # end-of-utterance silence
   voice_gate_ratio: 3.0      # how much louder than the background a frame must be to count as
                              # the user talking — lets recording end while your own speakers play
-                             # music (Silero rates music as speech). 0 = off, raise if commands
+                             # music (Silero rates music as speech). 0 = off. Higher is stricter:
-                             # get cut off, lower if music keeps the recorder running.
+                             # raise it if music keeps the recorder running, lower it if quiet
+                             # commands get cut off.
 
 mcp:
   servers_config: "mcp_servers.json"

src/javis/core/config.py

@@ -131,7 +131,9 @@ class WakeWordConfig:
     # How much louder than the background a frame must be to count as the user
     # talking.  This is what lets a recording end when the *user* stops even
     # while the device's own speakers keep playing music (which Silero happily
-    # classifies as speech).  0 = off (plain VAD endpointing).
+    # classifies as speech).  Higher is stricter: raise it when playback keeps
+    # the recorder running, lower it when quiet commands get cut off.
+    # 0 = off (plain VAD endpointing).
     voice_gate_ratio: float = 3.0
 
 

tests/test_endpointing.py

@@ -129,6 +129,22 @@ class SpeechEndpointerTests(unittest.TestCase):
         self.assertAlmostEqual(ep.background, before)
         self.assertFalse(ep.process(frame(MUSIC_RMS * 2.0)).is_speech)
 
+    def test_a_higher_ratio_is_stricter(self) -> None:
+        """Pins the documented tuning direction.
+
+        Raising the ratio rejects more audio (so it can clip quiet commands);
+        lowering it admits more (so playback can keep the recorder running).
+        """
+        def accepts(ratio: float) -> bool:
+            ep = endpointer(ratio=ratio)
+            for _ in range(50):
+                ep.observe(frame(MUSIC_RMS))
+            ep.reset()
+            return ep.process(frame(MUSIC_RMS * 2.5)).is_speech
+
+        self.assertTrue(accepts(2.0))    # permissive — the frame counts as the user
+        self.assertFalse(accepts(4.0))   # strict — the same frame is rejected
+
     def test_ratio_zero_disables_the_gate(self) -> None:
         ep = endpointer(ratio=0.0)
         self.assertFalse(ep.enabled)