voxtype: overlay_opacity knob + double-tap right-Option toggle (#195)

* feat(voxtype): overlay_opacity knob and double-tap modifier toggle

Two small UX additions:

- overlay_opacity (0.1-1.0, default 1.0): whole-ghost alpha, applied
  at the NSPanel level so the drawing keeps its per-element alphas.
  For when the ghost hides the text under it.
- double_tap_key / double_tap_ms: a second toggle trigger alongside the
  hotkey chord — tap one modifier (e.g. right_alt, the right Option
  key) twice on its own. Implemented inside the existing macOS event
  tap by observing kCGEventFlagsChanged; the modifier is never
  swallowed. Left/right are told apart by keycode + NX_DEVICE* flag
  bit (verified against the SDK headers and live on the built-in
  keyboard). Clean-tap rules: no other key or modifier during the
  taps, press-to-press within double_tap_ms, fires on the second
  release so Option-chords never trigger it.

Tests: new tests/test_voxtype_doubletap.py (config bounds, detector
state machine, stubbed event-tap integration, app wiring).

* docs: release note for PR #195 (voxtype opacity + double-tap)

* fix(voxtype): keep the double tap armed when a chord falls back

GitHub Codex on PR #195: an unresolvable chord (e.g. ';' needing Shift
on some layouts) sends the chords to pynput's observing fallback, which
silently dropped the layout-independent double-tap binding. Keep a
chord-less event tap for the double tap in that case (built before the
chord listener starts, so a failure leaks no handle-less listener).

Author: pchalasani

docs-site/src/content/docs/tools/voxtype/configuration.mdx

@@ -206,6 +206,12 @@ language = "en"
 
 # Hotkeys (pynput or bracket-less syntax; `voxtype hotkey` records one)
 hotkey = "<ctrl>+;"          # toggle recording
+# A second toggle for the laptop keyboard (macOS): tap a modifier key
+# twice on its own. One of left_alt right_alt left_cmd right_cmd
+# left_ctrl right_ctrl left_shift right_shift ("alt" = Option). The key
+# keeps working as a normal modifier. "" disables.
+double_tap_key = ""
+double_tap_ms = 400          # max gap between the two taps, press to press
 cancel_hotkey = "<esc>"      # cancel recording (only intercepted WHILE recording)
 paste_hotkey = ""            # re-type last transcript, e.g. "<cmd>+<ctrl>+v"
 
@@ -239,6 +245,7 @@ copy_to_clipboard = false
 overlay = true
 overlay_flex = 1.0   # how much the face flexes its shape (higher = more)
 overlay_speed = 1.0  # animation speed (lower = slower/gentler)
+overlay_opacity = 1.0  # 0.1–1.0; lower it if the ghost hides text under it
 
 # Keep the model's memory warm (parakeet-mlx only). After this many
 # minutes without a decode, voxtype quietly decodes a short silent
@@ -296,6 +303,23 @@ Flags mirror the config keys: `--mode`, `--engine`,
 `--stop-phrase`, `--no-sounds`, `--no-overlay`,
 `--config PATH`.
 
+### Double-tap toggle
+
+`double_tap_key` adds a second way to start and stop recording, next
+to the `hotkey` chord: tap one modifier key twice, by itself. It exists
+for the laptop keyboard, where a chord like Ctrl+; is awkward without
+an external keyboard; `right_alt` (the right Option key) is a good
+choice because nothing else uses it alone.
+
+- Both triggers stay active at once; use whichever is under your hand.
+- The taps must be *clean*: press, release, press, release, with no
+  other key in between and within `double_tap_ms` of each other
+  (press to press). Holding the key to type an Option-shortcut or an
+  accented character never triggers it.
+- The modifier is never swallowed — voxtype only observes it — so
+  Option, Command, and friends keep working everywhere.
+- macOS only (it rides on the same event tap as the chord).
+
 ## Hotkey notation
 
 Both spellings work everywhere a chord is accepted:

packages/voxtype/src/voxtype/app.py

@@ -585,6 +585,7 @@ def sample() -> tuple[str, bool, float]:
                 on_ready=self._start_hotkeys_from_loop,
                 flex=self.cfg.overlay_flex,
                 speed=self.cfg.overlay_speed,
+                opacity=self.cfg.overlay_opacity,
             )
             return result["code"]
         while not self._stop.is_set():
@@ -667,16 +668,35 @@ def _start_hotkey_listener(self):  # noqa: ANN202
                 )
                 continue
             bindings.append(binding)
-        if not bindings:
+        double_tap = None
+        if self.cfg.double_tap_key:
+            # Second toggle trigger: two taps of a lone modifier key
+            # (validated by Config, so no per-binding try here).
+            double_tap = (
+                self.cfg.double_tap_key,
+                self.cfg.double_tap_ms,
+                self.toggle,
+            )
+        if not bindings and double_tap is None:
             self._status("no valid hotkeys configured; hotkeys disabled")
             return None
         try:
-            return start_hotkeys(bindings)
+            listener = start_hotkeys(bindings, double_tap=double_tap)
         except ValueError as e:
             self._status(
                 f"invalid hotkey config ({e}); hotkeys disabled"
             )
             return None
+        if double_tap is not None and getattr(
+            listener, "double_tap_active", False
+        ):
+            # Only claim it when the listener actually armed it: the
+            # non-tap fallback reports the omission itself.
+            self._status(
+                f"double-tap {self.cfg.double_tap_key} also toggles "
+                "recording"
+            )
+        return listener
 
     @staticmethod
     def _status(msg: str) -> None:

packages/voxtype/src/voxtype/config.py

@@ -80,6 +80,20 @@ def default_segmentation(engine: str, mode: str) -> str:
     "medium-streaming",
 )
 
+# Modifier keys that may serve as a double-tap toggle trigger. Must stay
+# in sync with hotkey.DOUBLE_TAP_KEYS (a test enforces it); kept here so
+# config validation never imports the (pynput-backed) hotkey module.
+VALID_DOUBLE_TAP_KEYS = (
+    "left_alt",
+    "right_alt",
+    "left_cmd",
+    "right_cmd",
+    "left_ctrl",
+    "right_ctrl",
+    "left_shift",
+    "right_shift",
+)
+
 
 @dataclass
 class Config:
@@ -111,6 +125,8 @@ class Config:
             shape (1.0 = default; higher = more flexible, calmer < 1.0).
         overlay_speed: Overall animation speed multiplier (1.0 =
             default; lower = slower/gentler motion).
+        overlay_opacity: Whole-ghost opacity, 0.1 (barely there) to
+            1.0 (as drawn). Lower it if the ghost hides text under it.
         keepalive_minutes: Re-decode a short silent clip after this
             many minutes without a decode (parakeet-mlx only). Under
             system-wide memory pressure macOS evicts an idle model to
@@ -124,6 +140,14 @@ class Config:
             only).
         language: Language tag understood by Moonshine (e.g. "en").
         hotkey: Global toggle hotkey in pynput syntax, e.g. "<ctrl>+;".
+        double_tap_key: A second way to toggle recording, alongside
+            ``hotkey``: tap this modifier key twice, alone (e.g.
+            "right_alt" — the right Option key — for laptop use where
+            a chord is awkward). One of VALID_DOUBLE_TAP_KEYS; empty
+            disables. The key is never swallowed, so it keeps working
+            as a modifier; macOS only.
+        double_tap_ms: Maximum gap between the two taps, press to
+            press, in milliseconds (50–2000).
         wake_word: Phrase that activates dictation in "wake" mode.
         wake_word_aliases: Alternate spellings the transcriber may
             produce for the wake word (e.g. "claud", "clawed"); any
@@ -165,10 +189,13 @@ class Config:
     overlay: bool = True
     overlay_flex: float = 1.0
     overlay_speed: float = 1.0
+    overlay_opacity: float = 1.0
     keepalive_minutes: float = 0.0
     model_arch: str = "medium-streaming"
     language: str = "en"
     hotkey: str = "<ctrl>+;"
+    double_tap_key: str = ""
+    double_tap_ms: float = 400
     wake_word: str = "claude"
     wake_word_aliases: list[str] = field(default_factory=list)
     stop_phrase: str = "stop listening"
@@ -266,6 +293,40 @@ def validate(self) -> None:
                 raise ValueError(
                     f"{name} must be between 0 and 5, got {value!r}"
                 )
+        if (
+            isinstance(self.overlay_opacity, bool)
+            or not isinstance(self.overlay_opacity, (int, float))
+            or (
+                isinstance(self.overlay_opacity, float)
+                and not math.isfinite(self.overlay_opacity)
+            )
+            or not 0.1 <= self.overlay_opacity <= 1.0
+        ):
+            raise ValueError(
+                "overlay_opacity must be a number between 0.1 and 1.0, "
+                f"got {self.overlay_opacity!r}"
+            )
+        if not isinstance(self.double_tap_key, str) or (
+            self.double_tap_key and
+            self.double_tap_key not in VALID_DOUBLE_TAP_KEYS
+        ):
+            raise ValueError(
+                f"double_tap_key must be empty or one of "
+                f"{VALID_DOUBLE_TAP_KEYS}, got {self.double_tap_key!r}"
+            )
+        if (
+            isinstance(self.double_tap_ms, bool)
+            or not isinstance(self.double_tap_ms, (int, float))
+            or (
+                isinstance(self.double_tap_ms, float)
+                and not math.isfinite(self.double_tap_ms)
+            )
+            or not 50 <= self.double_tap_ms <= 2000
+        ):
+            raise ValueError(
+                "double_tap_ms must be a number of milliseconds between "
+                f"50 and 2000, got {self.double_tap_ms!r}"
+            )
         if isinstance(self.keepalive_minutes, bool) or not isinstance(
             self.keepalive_minutes, (int, float)
         ):
@@ -427,6 +488,9 @@ def sample_config() -> str:
 overlay_flex = 1.0
 # Overall animation speed (lower = slower, gentler motion).
 overlay_speed = 1.0
+# Whole-ghost opacity, 0.1–1.0. Lower it (e.g. 0.6) if the ghost hides
+# the text underneath it.
+overlay_opacity = 1.0
 
 # Remove standalone filler words (uh, um, ...) from typed text.
 strip_fillers = true
@@ -454,6 +518,15 @@ def sample_config() -> str:
 # "<ctrl>+<alt>+d", "<cmd>+<shift>+v"
 hotkey = "<ctrl>+;"
 
+# A second way to toggle recording (macOS): tap a modifier key twice,
+# on its own — handy on the laptop keyboard where a chord is awkward.
+# One of: left_alt right_alt left_cmd right_cmd left_ctrl right_ctrl
+# left_shift right_shift ("alt" is the Option key). The key still works
+# normally as a modifier. Empty disables.
+double_tap_key = ""
+# Max gap between the two taps, press to press, in milliseconds.
+double_tap_ms = 400
+
 # Wake word / stop phrase. The wake word is used in "wake" mode; the
 # stop phrase deactivates dictation wherever utterances are
 # transcribed as you pause (segmentation "vad"). A "hold" take is raw