Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion requirements.txt
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
pytest
SpeechRecognition
anthropic
anthropic
pyperclip
111 changes: 111 additions & 0 deletions src/voice_parser.py
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
import logging
import re
import subprocess
import time

logger = logging.getLogger(__name__)

Expand Down Expand Up @@ -63,6 +65,115 @@ def speech_to_text(self):
return self.sanitize(raw_text)


class HandyVoiceParser:
"""Delegates voice input to a running Handy instance (https://github.com/cjpais/Handy).

Handy is a free, open-source, offline speech-to-text desktop application.
This class triggers Handy's transcription via its CLI flag and monitors the
clipboard for the resulting text, providing the same ``speech_to_text``
interface as :class:`VoiceParser`.

Handy must be installed and running before calling :meth:`speech_to_text`.
See https://github.com/cjpais/Handy for installation instructions.
"""

DEFAULT_HANDY_EXECUTABLE = "handy"
DEFAULT_TIMEOUT = 30
DEFAULT_POLL_INTERVAL = 0.25

def __init__(self, handy_executable=None, timeout=None, poll_interval=None):
self._executable = handy_executable or self.DEFAULT_HANDY_EXECUTABLE
self._timeout = timeout if timeout is not None else self.DEFAULT_TIMEOUT
self._poll_interval = poll_interval if poll_interval is not None else self.DEFAULT_POLL_INTERVAL
try:
import pyperclip
self._pyperclip = pyperclip
except ImportError:
self._pyperclip = None
logger.warning("pyperclip library not available. Install it with: pip install pyperclip")

def trigger(self):
"""Toggle Handy transcription by invoking the CLI flag.

Sends ``--toggle-transcription`` to a running Handy instance.
Raises :class:`VoiceParserError` if the Handy executable is not found
or returns a non-zero exit code.
"""
try:
result = subprocess.run(
[self._executable, "--toggle-transcription"],
capture_output=True,
text=True,
)
if result.returncode != 0:
raise VoiceParserError(
f"Handy returned exit code {result.returncode}: {result.stderr.strip()}"
)
logger.info("Handy transcription toggled.")
except FileNotFoundError as e:
raise VoiceParserError(
f"Handy executable not found: '{self._executable}'. "
"Ensure Handy is installed and available in PATH."
) from e

def wait_for_transcript(self, previous_clipboard=""):
"""Wait for Handy to paste new text to the clipboard.

Polls the clipboard until its content changes from *previous_clipboard*
or until *timeout* seconds have elapsed.

Returns the new clipboard content (stripped of surrounding whitespace).
Raises :class:`VoiceParserError` on timeout or if pyperclip is unavailable.
"""
if self._pyperclip is None:
raise VoiceParserError(
"pyperclip is required to read Handy's transcript from the clipboard. "
"Install it with: pip install pyperclip"
)
deadline = time.monotonic() + self._timeout
while time.monotonic() < deadline:
try:
current = self._pyperclip.paste()
except Exception as e:
raise VoiceParserError(f"Failed to read clipboard: {e}") from e
if current != previous_clipboard:
logger.info("Handy transcript received from clipboard.")
return current.strip()
time.sleep(self._poll_interval)
Comment on lines +133 to +142

Copilot AI Mar 5, 2026

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

wait_for_transcript relies on current != previous_clipboard to detect completion. If the user speaks the same command as what's already on the clipboard (or Handy produces identical text), this will never be observed as a change and will time out even though transcription succeeded. Consider using a sentinel strategy (e.g., optionally write a unique marker / clear clipboard before triggering and optionally restore), or track changes via an additional signal rather than strict inequality with the previous clipboard contents.

Copilot uses AI. Check for mistakes.
raise VoiceParserError(
f"Timed out waiting for Handy transcript after {self._timeout}s. "
"Ensure Handy is running and has finished transcribing."
)

def speech_to_text(self):
"""Delegate voice capture to Handy and return the transcribed text.

Captures the current clipboard content, triggers Handy transcription,
waits for the clipboard to be updated with the transcript, sanitizes
the result, and returns it.

The sanitization step reuses :meth:`VoiceParser.sanitize` logic:
collapses internal whitespace and raises :class:`VoiceParserError` for
empty results.
"""
if self._pyperclip is None:
raise VoiceParserError(
"pyperclip is required for HandyVoiceParser. "
"Install it with: pip install pyperclip"
)
try:
previous = self._pyperclip.paste()
except Exception as e:
raise VoiceParserError(f"Failed to read clipboard: {e}") from e

self.trigger()
raw_text = self.wait_for_transcript(previous_clipboard=previous)

if not raw_text:
raise VoiceParserError("Handy returned an empty transcript.")
return re.sub(r"\s+", " ", raw_text.strip())


# Example usage
if __name__ == "__main__":
parser = VoiceParser()
Expand Down
111 changes: 109 additions & 2 deletions tests/test_voice_parser.py
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
import pytest
from unittest.mock import MagicMock
from unittest.mock import MagicMock, patch, call

from voice_parser import VoiceParser, VoiceParserError
from voice_parser import VoiceParser, VoiceParserError, HandyVoiceParser


class TestVoiceParserSanitize:
Expand Down Expand Up @@ -49,3 +49,110 @@ def test_transcribe_request_error_raises(self):
mock_recognizer.recognize_google.side_effect = sr.RequestError("service down")
with pytest.raises(VoiceParserError, match="service error"):
parser.transcribe(MagicMock())


class TestHandyVoiceParser:
def _make_parser(self, **kwargs):
"""Create a HandyVoiceParser with a mocked pyperclip."""
mock_pyperclip = MagicMock()
parser = HandyVoiceParser(**kwargs)
parser._pyperclip = mock_pyperclip
return parser, mock_pyperclip

# --- trigger() ---

def test_trigger_calls_handy_toggle_transcription(self):
parser, _ = self._make_parser(handy_executable="handy")
with patch("voice_parser.subprocess.run") as mock_run:
mock_run.return_value = MagicMock(returncode=0, stderr="")
parser.trigger()
mock_run.assert_called_once_with(
["handy", "--toggle-transcription"],
capture_output=True,
text=True,
)

def test_trigger_raises_when_executable_not_found(self):
parser, _ = self._make_parser(handy_executable="handy")
with patch("voice_parser.subprocess.run", side_effect=FileNotFoundError):
with pytest.raises(VoiceParserError, match="not found"):
parser.trigger()

def test_trigger_raises_on_nonzero_exit_code(self):
parser, _ = self._make_parser(handy_executable="handy")
with patch("voice_parser.subprocess.run") as mock_run:
mock_run.return_value = MagicMock(returncode=1, stderr="some error")
with pytest.raises(VoiceParserError, match="exit code 1"):
parser.trigger()

# --- wait_for_transcript() ---

def test_wait_for_transcript_returns_new_clipboard_content(self):
parser, mock_pyperclip = self._make_parser(timeout=5, poll_interval=0.01)
mock_pyperclip.paste.side_effect = ["old text", "old text", "new transcript"]
result = parser.wait_for_transcript(previous_clipboard="old text")
assert result == "new transcript"

def test_wait_for_transcript_strips_whitespace(self):
parser, mock_pyperclip = self._make_parser(timeout=5, poll_interval=0.01)
mock_pyperclip.paste.return_value = " transcribed text "
result = parser.wait_for_transcript(previous_clipboard="")
assert result == "transcribed text"

def test_wait_for_transcript_times_out(self):
parser, mock_pyperclip = self._make_parser(timeout=0.05, poll_interval=0.01)
mock_pyperclip.paste.return_value = "unchanged"
with pytest.raises(VoiceParserError, match="Timed out"):
parser.wait_for_transcript(previous_clipboard="unchanged")

def test_wait_for_transcript_raises_without_pyperclip(self):
parser, _ = self._make_parser()
parser._pyperclip = None
with pytest.raises(VoiceParserError, match="pyperclip is required"):
parser.wait_for_transcript()

def test_wait_for_transcript_raises_on_clipboard_error(self):
parser, mock_pyperclip = self._make_parser(timeout=5, poll_interval=0.01)
mock_pyperclip.paste.side_effect = Exception("clipboard unavailable")
with pytest.raises(VoiceParserError, match="Failed to read clipboard"):
parser.wait_for_transcript(previous_clipboard="")

# --- speech_to_text() ---

def test_speech_to_text_returns_sanitized_transcript(self):
parser, mock_pyperclip = self._make_parser(timeout=5, poll_interval=0.01)
mock_pyperclip.paste.side_effect = ["", " write a sort function "]
with patch("voice_parser.subprocess.run") as mock_run:
mock_run.return_value = MagicMock(returncode=0, stderr="")
result = parser.speech_to_text()
assert result == "write a sort function"

def test_speech_to_text_raises_on_empty_transcript(self):
parser, mock_pyperclip = self._make_parser(timeout=5, poll_interval=0.01)
mock_pyperclip.paste.side_effect = ["old", " "]
with patch("voice_parser.subprocess.run") as mock_run:
mock_run.return_value = MagicMock(returncode=0, stderr="")
with pytest.raises(VoiceParserError, match="empty transcript"):
parser.speech_to_text()

def test_speech_to_text_raises_without_pyperclip(self):
parser, _ = self._make_parser()
parser._pyperclip = None
with pytest.raises(VoiceParserError, match="pyperclip is required"):
parser.speech_to_text()

def test_speech_to_text_triggers_handy_once(self):
parser, mock_pyperclip = self._make_parser(timeout=5, poll_interval=0.01)
mock_pyperclip.paste.side_effect = ["before", "after transcription"]
with patch("voice_parser.subprocess.run") as mock_run:
mock_run.return_value = MagicMock(returncode=0, stderr="")
parser.speech_to_text()
mock_run.assert_called_once()

def test_default_executable_is_handy(self):
parser = HandyVoiceParser()
assert parser._executable == "handy"

def test_custom_executable_is_used(self):
parser = HandyVoiceParser(handy_executable="/usr/local/bin/handy")
assert parser._executable == "/usr/local/bin/handy"