fix: keepalive as configurable, to prevent hung indicators

Author: goodroot

docs/CONFIGURATION.md

@@ -655,6 +655,24 @@ Custom sounds:
 - **Supported formats**: `.ogg`, `.wav`, `.mp3`
 - **Fallback**: Uses defaults if custom files don't exist
 
+### Audio stream keepalive
+
+By default hyprwhspr opens the microphone only while recording. 
+
+On some hardware (certain USB mics on raw ALSA), the first recording after an idle period fails with a `paTimedOut` error because the audio device suspends between uses.
+
+If you see this, enable the keepalive stream:
+
+```json
+{
+  "keepalive_stream": true
+}
+```
+
+This holds a silent input stream open in the background so the device stays warm. 
+
+**Leave this off unless you need it** — an open input stream triggers the microphone-in-use indicator on most desktops (GNOME, KDE, Ubuntu, etc.), making it appear as though hyprwhspr is always listening. It's not!
+
 ### Audio ducking
 
 Quiet system volume on record:
@@ -1080,6 +1098,18 @@ pactl list short sources
 systemctl --user restart pipewire
 ```
 
+#### Microphone indicator shows on while idle
+
+If your desktop (GNOME, Ubuntu, etc.) shows the microphone as active whenever the hyprwhspr service is running, you likely have `keepalive_stream` enabled. Disable it:
+
+```json
+{
+  "keepalive_stream": false
+}
+```
+
+This is the default. If you previously enabled it to fix `paTimedOut` errors, see [Audio stream keepalive](#audio-stream-keepalive) for the trade-off.
+
 #### Audio feedback not working
 
 ```bash

lib/src/audio_capture.py

@@ -237,6 +237,8 @@ def _start_keepalive(self, _attempt: int = 0):
         with self._keepalive_lock:
             if self._keepalive_stream is not None or self.device_id is None:
                 return
+        if self.config is None or not self.config.get_setting('keepalive_stream', False):
+            return
         if not self._is_multiplexed_audio_server():
             return
         stream = None

lib/src/config_manager.py

@@ -116,7 +116,12 @@ def __init__(self):
             # Audio stream cold-start recovery
             # How long (seconds) to wait between stream.start() retries when PortAudio times out.
             # Increase this if your USB mic frequently fails on the first recording after idle.
-            'stream_start_retry_delay': 1.5
+            'stream_start_retry_delay': 1.5,
+            # Keep a silent audio stream open between recordings to prevent ALSA cold-start
+            # timeouts on some hardware. Disabled by default because active input streams
+            # trigger the microphone-in-use indicator on many desktops (GNOME, Ubuntu, etc.).
+            # Enable only if you see paTimedOut errors on your first recording after idle.
+            'keepalive_stream': False
         }
 
         # Set up config directory and file path