spych.wake

  1import threading, time
  2from faster_whisper import WhisperModel
  3from spych.utils import Notify, Recorder, get_clean_audio_buffer
  4
  5
  6class SpychWakeListener(Notify):
  7    def __init__(self, spych_wake_object):
  8        """
  9        Usage:
 10
 11        - Initializes a single wake word listener thread worker
 12
 13        Requires:
 14
 15        - `spych_wake_object`:
 16            - Type: SpychWake
 17            - What: The parent SpychWake instance that owns this listener
 18            - Note: Used to access shared state such as `locked`, `wake_word_map`,
 19              and `device_index`
 20        """
 21        self.spych_wake_object = spych_wake_object
 22        self.locked = False
 23        self.kill = False
 24
 25    def stop(self):
 26        """
 27        Usage:
 28
 29        - Signals this listener to stop at the next available checkpoint
 30        - Note: Does not immediately halt execution; the listener will exit cleanly
 31          after its current operation completes
 32        """
 33        self.kill = True
 34
 35    def should_stop(self):
 36        """
 37        Usage:
 38
 39        - Checks whether this listener should stop processing and exit early
 40        - Resets `kill` and `locked` state if stopping is required
 41
 42        Returns:
 43
 44        - `should_stop`:
 45            - Type: bool
 46            - What: True if the listener should stop, False if it should continue
 47            - Note: Returns True if `self.kill` is set or the parent `SpychWake` is locked
 48        """
 49        if self.kill or self.spych_wake_object.locked:
 50            self.kill = False
 51            self.locked = False
 52            return True
 53        return False
 54
 55    def __call__(self):
 56        """
 57        Usage:
 58
 59        - Executes one full listen-and-detect cycle when this listener is invoked as a thread target
 60        - Records audio, transcribes it, and triggers a wake event if any wake word is detected
 61
 62        Notes:
 63
 64        - Skips execution silently if this listener is already locked (i.e. mid-cycle)
 65        - Checks `should_stop` at each major step to allow early exit without blocking
 66        - Uses `beam_size=2` for fast transcription appropriate for short wake word clips
 67        - The `initial_prompt` biases the model toward all registered wake words to reduce
 68          false negatives
 69        - If multiple wake words are present in a single segment, the first match wins
 70        """
 71        if self.locked:
 72            self.notify(
 73                "Listener is locked, skipping...", notification_type="verbose"
 74            )
 75            return
 76        if self.should_stop():
 77            return
 78        self.locked = True
 79        buffer = self.spych_wake_object.recorder.record(
 80            device_index=self.spych_wake_object.device_index,
 81            duration=self.spych_wake_object.wake_listener_time,
 82        )
 83        if self.should_stop():
 84            return
 85        audio_buffer = get_clean_audio_buffer(buffer)
 86        if self.should_stop():
 87            return
 88        wake_words = list(self.spych_wake_object.wake_word_map.keys())
 89        wake_string = "[" + ", ".join(wake_words) + "]"
 90        segments, _ = self.spych_wake_object.wake_model.transcribe(
 91            audio_buffer,
 92            beam_size=2,
 93            initial_prompt=f"""Here are some wake words: {wake_string}. Only return what you understood was said, but place extra weight on those words if there is a tie.""",
 94        )
 95        for segment in segments:
 96            # Skip segments with high no_speech_prob to reduce false positives on silence/background noise;
 97            # the threshold can be adjusted based on testing and environment
 98            if (
 99                segment.no_speech_prob
100                > self.spych_wake_object.no_speech_threshold
101            ):
102                continue
103            if self.should_stop():
104                return
105            text = segment.text.lower()
106            for wake_word in wake_words:
107                if wake_word in text:
108                    self.spych_wake_object.wake(wake_word)
109                    self.locked = False
110                    self.kill = False
111                    return
112        self.locked = False
113        self.kill = False
114
115
116class SpychWake(Notify):
117    def __init__(
118        self,
119        wake_word_map,
120        terminate_words=None,
121        wake_listener_count=3,
122        wake_listener_time=2,
123        wake_listener_max_processing_time=0.5,
124        device_index=-1,
125        whisper_model="tiny.en",
126        whisper_device="cpu",
127        whisper_compute_type="int8",
128        no_speech_threshold=0.3,
129        on_terminate=None,
130    ):
131        """
132        Usage:
133
134        - Initializes a wake word detection system using overlapping listener threads
135          and faster-whisper for offline transcription
136        - Supports multiple wake words, each mapped to a different callback function
137
138        Requires:
139
140        - `wake_word_map`:
141            - Type: dict[str, callable]
142            - What: A dictionary mapping wake words to their corresponding no-argument
143              callback functions
144            - Note: Keys are stored and matched in lowercase
145            - Example:
146                {
147                    "jarvis": on_jarvis_wake,
148                    "computer": on_computer_wake,
149                }
150
151        Optional:
152
153        - `terminate_words`:
154            - Type: list[str]
155            - What: A list of words that, if detected in the wake listener's transcription,
156              will immediately terminate the entire SpychWake system
157            - Note: Use with caution, as any false positive on a terminate word will stop
158              the wake system until it is manually restarted
159            - default: None (disabled)
160
161        - `wake_listener_count`:
162            - Type: int
163            - What: The number of concurrent listener threads to run
164            - Default: 3
165            - Note: More listeners reduce the chance of missing a wake word between
166              recording windows; at least 3 is recommended for continuous coverage
167
168        - `wake_listener_time`:
169            - Type: int | float
170            - What: The duration in seconds each listener records per cycle
171            - Default: 2
172
173        - `wake_listener_max_processing_time`:
174            - Type: int | float
175            - What: The estimated maximum time in seconds for transcription to complete
176            - Default: 0.5
177            - Note: Used alongside `wake_listener_time` and `wake_listener_count` to
178              calculate the stagger delay between thread launches
179
180        - `device_index`:
181            - Type: int
182            - What: The microphone device index to record from
183            - Default: -1
184            - Note: Use `-1` to select the system default input device
185
186        - `whisper_model`:
187            - Type: str
188            - What: The faster-whisper model name to use for wake word transcription
189            - Default: "tiny.en"
190            - Note: Smaller models (tiny, base) are recommended here for low latency
191
192        - `whisper_device`:
193            - Type: str
194            - What: The device to run the whisper model on
195            - Default: "cpu"
196            - Note: Use "cuda" for GPU acceleration if available
197
198        - `whisper_compute_type`:
199            - Type: str
200            - What: The compute type to use for the whisper model
201            - Default: "int8"
202            - Note: "int8" offers a good balance of speed and accuracy on both CPU and GPU
203
204        - `no_speech_threshold`:
205            - Type: float
206            - What: The threshold for the `no_speech_prob` returned by faster-whisper
207            - Default: 0.3
208            - Note: Segments with a `no_speech_prob` above this threshold will be ignored to reduce false positives from silence or background noise
209
210        - `on_terminate`:
211            - Type: callable
212            - What: A no-argument callback function to execute when a terminate word is detected
213            - Default: None (disabled)
214            - Note: If provided, this callback will be executed before the system is stopped when a terminate word is detected
215        """
216        self.recorder = Recorder()
217        self.wake_word_map = {k.lower(): v for k, v in wake_word_map.items()}
218        # Handle Terminating Words
219        self.terminate_words = (
220            [w.lower() for w in terminate_words] if terminate_words else []
221        )
222        for word in self.terminate_words:
223            if word in self.wake_word_map:
224                raise ValueError(
225                    f"Terminate word '{word}' cannot also be a wake word."
226                )
227            self.wake_word_map[word] = self.stop
228        self.no_speech_threshold = no_speech_threshold
229        self.on_terminate = on_terminate
230        self.wake_listener_count = wake_listener_count
231        self.wake_listener_time = wake_listener_time
232        self.wake_listener_max_processing_time = (
233            wake_listener_max_processing_time
234        )
235        self.device_index = device_index
236        self.locked = False
237        self.kill = False
238        self.wake_model = WhisperModel(
239            whisper_model,
240            device=whisper_device,
241            compute_type=whisper_compute_type,
242        )
243        self.wake_listeners = [
244            SpychWakeListener(self) for _ in range(self.wake_listener_count)
245        ]
246
247    def start(self):
248        """
249        Usage:
250
251        - Starts the wake word detection loop using overlapping listener threads
252        - Blocks until a KeyboardInterrupt is received or `stop()` is called
253
254        Notes:
255
256        - Callbacks are defined in `wake_word_map` at init time rather than passed to `start`
257        - Listener threads are staggered by `(wake_listener_time + wake_listener_max_processing_time)
258          / wake_listener_count` seconds to ensure continuous audio coverage
259        - New threads are only launched when the system is not locked (i.e. not currently
260          processing a wake event)
261        """
262        try:
263            while True:
264                for listener in self.wake_listeners:
265                    if self.kill:
266                        self.kill = False
267                        return
268                    if not self.locked:
269                        threading.Thread(target=listener).start()
270                    time.sleep(
271                        (
272                            self.wake_listener_time
273                            + self.wake_listener_max_processing_time
274                        )
275                        / self.wake_listener_count
276                    )
277        except KeyboardInterrupt:
278            self.stop()
279
280    def stop_listeners(self):
281        """
282        Usage:
283
284        - Signals all listener threads to stop at their next available checkpoint
285        - Note: Does not block; listeners will exit cleanly after their current operation
286        """
287        for listener in self.wake_listeners:
288            listener.stop()
289
290    def stop(self):
291        """
292        Usage:
293
294        - Stops all listener threads and exits the `start` loop
295        - Note: Combines `stop_listeners` with setting the kill flag on the main loop
296        """
297        self.stop_listeners()
298        self.kill = True
299        if self.on_terminate:
300            try:
301                self.on_terminate()
302            except Exception as e:
303                self.notify(
304                    f"Error in on_terminate callback: {e}",
305                    notification_type="exception",
306                )
307
308    def wake(self, wake_word):
309        """
310        Usage:
311
312        - Called internally when a wake word is detected
313        - Stops all listeners, locks the system, executes the mapped callback for the
314          detected wake word, then unlocks
315
316        Requires:
317
318        - `wake_word`:
319            - Type: str
320            - What: The detected wake word, used to look up the correct callback in
321              `wake_word_map`
322
323        Notes:
324
325        - If the system is already locked when `wake` is called, the call is a no-op
326          to prevent concurrent wake executions
327        - Any exception raised by the callback is caught and re-raised as a spych exception
328        - The system is always unlocked in the `finally` block, even if the callback raises
329        """
330        self.stop_listeners()
331        if self.locked:
332            return
333        self.locked = True
334        try:
335            self.wake_word_map[wake_word]()
336        except Exception as e:
337            self.notify(
338                f"Error in on_wake_fn for '{wake_word}': {e}",
339                notification_type="exception",
340            )
341        finally:
342            self.locked = False