vox-cli 0.1.0__tar.gz

vox_cli-0.1.0/.gitignore

@@ -0,0 +1,23 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.venv/
+venv/
+env/
+.env
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+*.wav
+*.mp3
+*.ogg
+models/
+*.bin
+*.pt

vox_cli-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 beee003
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

vox_cli-0.1.0/PKG-INFO

@@ -0,0 +1,79 @@
+Metadata-Version: 2.4
+Name: vox-cli
+Version: 0.1.0
+Summary: Voice comments for your terminal. Push-to-talk for Claude Code, Cursor, and any CLI.
+Author: beee003
+License: MIT
+License-File: LICENSE
+Keywords: cli,developer-tools,speech-to-text,terminal,voice
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: click>=8.1.0
+Requires-Dist: faster-whisper>=1.0.0
+Requires-Dist: mcp>=1.2.0
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: pynput>=1.7.6
+Requires-Dist: pyperclip>=1.8.2
+Requires-Dist: sounddevice>=0.4.6
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# vox
+
+Voice comments for your terminal. Push-to-talk for Claude Code, Cursor, and any CLI.
+
+## Install
+
+```bash
+pip install vox-cli
+```
+
+## Quick Start
+
+```bash
+# One-shot: speak and get text
+vox say
+
+# Push-to-talk daemon (hold Right Alt to record)
+vox listen
+
+# List audio devices
+vox devices
+```
+
+## Features
+
+- **Local-first** — runs Whisper locally, no cloud API calls
+- **Code-aware cleaning** — fixes capitalization of `API`, `JSON`, `None`, etc.
+- **Voice casing** — say "snake case my variable name" → `my_variable_name`
+- **Multiple outputs** — clipboard (default), stdout, or simulated paste
+- **Push-to-talk** — configurable hotkey, silence detection auto-stops
+
+## Options
+
+```
+vox listen --model small      # tiny|base|small|medium
+vox listen --output stdout    # clipboard|stdout|paste
+vox listen --key f5           # any modifier or function key
+vox say --duration 15         # max recording seconds
+vox --verbose listen          # debug logging
+```
+
+## Requirements
+
+- Python 3.10+
+- A microphone
+- macOS: grant Terminal Accessibility permission for hotkey support
+
+## License
+
+MIT

vox_cli-0.1.0/README.md

@@ -0,0 +1,50 @@
+# vox
+
+Voice comments for your terminal. Push-to-talk for Claude Code, Cursor, and any CLI.
+
+## Install
+
+```bash
+pip install vox-cli
+```
+
+## Quick Start
+
+```bash
+# One-shot: speak and get text
+vox say
+
+# Push-to-talk daemon (hold Right Alt to record)
+vox listen
+
+# List audio devices
+vox devices
+```
+
+## Features
+
+- **Local-first** — runs Whisper locally, no cloud API calls
+- **Code-aware cleaning** — fixes capitalization of `API`, `JSON`, `None`, etc.
+- **Voice casing** — say "snake case my variable name" → `my_variable_name`
+- **Multiple outputs** — clipboard (default), stdout, or simulated paste
+- **Push-to-talk** — configurable hotkey, silence detection auto-stops
+
+## Options
+
+```
+vox listen --model small      # tiny|base|small|medium
+vox listen --output stdout    # clipboard|stdout|paste
+vox listen --key f5           # any modifier or function key
+vox say --duration 15         # max recording seconds
+vox --verbose listen          # debug logging
+```
+
+## Requirements
+
+- Python 3.10+
+- A microphone
+- macOS: grant Terminal Accessibility permission for hotkey support
+
+## License
+
+MIT

vox_cli-0.1.0/pyproject.toml

@@ -0,0 +1,56 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "vox-cli"
+version = "0.1.0"
+description = "Voice comments for your terminal. Push-to-talk for Claude Code, Cursor, and any CLI."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+authors = [{ name = "beee003" }]
+keywords = ["voice", "terminal", "cli", "speech-to-text", "developer-tools"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "faster-whisper>=1.0.0",
+    "sounddevice>=0.4.6",
+    "numpy>=1.24.0",
+    "pyperclip>=1.8.2",
+    "pynput>=1.7.6",
+    "click>=8.1.0",
+    "mcp>=1.2.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-cov>=4.0",
+    "ruff>=0.1.0",
+    "mypy>=1.0",
+]
+
+[project.scripts]
+vox = "vox.cli:main"
+vox-mcp = "vox.mcp_server:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["vox"]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W", "UP", "S", "B", "A", "C4", "PT"]
+ignore = ["S101"]  # allow assert in tests
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

vox_cli-0.1.0/tests/test_cleaner.py

@@ -0,0 +1,108 @@
+"""Tests for vox.cleaner — code-aware text cleaning."""
+
+from vox.cleaner import clean
+
+
+class TestFillerRemoval:
+    def test_removes_um_uh(self):
+        assert clean("um so the function uh returns") == "So the function returns"
+
+    def test_removes_multi_word_fillers(self):
+        assert clean("you know the API is broken") == "The API is broken"
+
+    def test_keeps_like_after_keeper(self):
+        assert "like" in clean("it looks like a bug").lower()
+
+    def test_removes_like_as_filler(self):
+        result = clean("so like the function like returns none")
+        assert result.count("like") == 0
+
+    def test_empty_input(self):
+        assert clean("") == ""
+        assert clean("   ") == ""
+
+
+class TestCodeKeywords:
+    def test_capitalizes_none(self):
+        assert "None" in clean("it returns none")
+
+    def test_capitalizes_true_false(self):
+        result = clean("set it to true or false")
+        assert "True" in result
+        assert "False" in result
+
+    def test_preserves_surrounding_text(self):
+        result = clean("check if the value is none then return")
+        assert "None" in result
+        assert "return" in result
+
+
+class TestTechTerms:
+    def test_capitalizes_api(self):
+        assert "API" in clean("the api is down")
+
+    def test_capitalizes_json(self):
+        assert "JSON" in clean("parse the json response")
+
+    def test_capitalizes_python(self):
+        assert "Python" in clean("write it in python")
+
+    def test_capitalizes_github(self):
+        assert "GitHub" in clean("push to github")
+
+
+class TestCasingCommands:
+    def test_snake_case(self):
+        result = clean("define snake case my variable name.")
+        assert "my_variable_name" in result
+
+    def test_camel_case(self):
+        result = clean("call camel case get user data.")
+        assert "getUserData" in result
+
+    def test_pascal_case(self):
+        result = clean("pascal case user service")
+        assert "UserService" in result
+
+    def test_kebab_case(self):
+        result = clean("use kebab case my component.")
+        assert "my-component" in result
+
+    def test_all_caps(self):
+        result = clean("all caps max retries")
+        assert "MAX_RETRIES" in result
+
+
+class TestFormatCommands:
+    def test_new_line(self):
+        result = clean("first line new line second line")
+        assert "\n" in result
+
+    def test_period(self):
+        result = clean("end of sentence period")
+        assert "." in result
+
+    def test_open_close_paren(self):
+        result = clean("call open paren close paren")
+        assert "(" in result
+        assert ")" in result
+
+    def test_arrow(self):
+        result = clean("returns arrow string")
+        assert "->" in result
+
+
+class TestWhitespace:
+    def test_collapses_spaces(self):
+        assert "  " not in clean("too   many   spaces   here")
+
+    def test_strips_leading_trailing(self):
+        result = clean("  hello world  ")
+        assert not result.startswith(" ")
+        assert not result.endswith(" ")
+
+
+class TestCapitalizeFirst:
+    def test_first_letter_capitalized(self):
+        result = clean("the function works")
+        assert result[0] == "T"

vox_cli-0.1.0/tests/test_cli.py

@@ -0,0 +1,58 @@
+"""Tests for vox.cli — CLI entry point."""
+
+from unittest.mock import patch
+
+from click.testing import CliRunner
+
+from vox.cli import main
+
+
+class TestCLI:
+    def test_version(self):
+        runner = CliRunner()
+        result = runner.invoke(main, ["--version"])
+        assert result.exit_code == 0
+        assert "0.1.0" in result.output
+
+    def test_help(self):
+        runner = CliRunner()
+        result = runner.invoke(main, ["--help"])
+        assert result.exit_code == 0
+        assert "voice comments" in result.output.lower()
+
+    def test_listen_help(self):
+        runner = CliRunner()
+        result = runner.invoke(main, ["listen", "--help"])
+        assert result.exit_code == 0
+        assert "--model" in result.output
+        assert "--output" in result.output
+        assert "--key" in result.output
+
+    def test_say_help(self):
+        runner = CliRunner()
+        result = runner.invoke(main, ["say", "--help"])
+        assert result.exit_code == 0
+        assert "--duration" in result.output
+
+    def test_devices_help(self):
+        runner = CliRunner()
+        result = runner.invoke(main, ["devices", "--help"])
+        assert result.exit_code == 0
+
+    @patch("vox.recorder.get_input_devices")
+    def test_devices_command(self, mock_devices):
+        mock_devices.return_value = [
+            {"index": 0, "name": "Built-in Mic", "channels": 2, "default_samplerate": 44100.0},
+        ]
+        runner = CliRunner()
+        result = runner.invoke(main, ["devices"])
+        assert result.exit_code == 0
+        assert "Built-in Mic" in result.output
+
+    @patch("vox.recorder.get_input_devices")
+    def test_devices_empty(self, mock_devices):
+        mock_devices.return_value = []
+        runner = CliRunner()
+        result = runner.invoke(main, ["devices"])
+        assert result.exit_code == 0
+        assert "No audio input devices found" in result.output

vox_cli-0.1.0/tests/test_hotkey.py

@@ -0,0 +1,81 @@
+"""Tests for vox.hotkey — push-to-talk hotkey listener."""
+
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from vox.hotkey import HotkeyError, PushToTalk
+
+
+class TestPushToTalk:
+    def test_init_defaults(self):
+        ptt = PushToTalk()
+        assert ptt._trigger_key_name == "alt_r"
+        assert ptt.is_active is False
+
+    def test_init_custom_key(self):
+        ptt = PushToTalk(trigger_key="f5")
+        assert ptt._trigger_key_name == "f5"
+
+    def test_invalid_key_raises(self):
+        ptt = PushToTalk(trigger_key="nonexistent_key_xyz")
+        with pytest.raises(HotkeyError, match="Unknown key"):
+            ptt._resolve_key()
+
+    @patch("vox.hotkey.Listener", create=True)
+    def test_on_press_activates(self, _mock_listener):
+        callback_called = []
+        ptt = PushToTalk(
+            trigger_key="alt_r",
+            on_start=lambda: callback_called.append("start"),
+        )
+        # Manually resolve key and simulate press
+        with patch("vox.hotkey.Key", create=True) as mock_key:
+            mock_key.alt_r = "ALT_R_KEY"
+            ptt._trigger_key = "ALT_R_KEY"
+            ptt._on_press("ALT_R_KEY")
+
+        assert ptt.is_active is True
+        assert callback_called == ["start"]
+
+    @patch("vox.hotkey.Listener", create=True)
+    def test_on_release_deactivates(self, _mock_listener):
+        callback_called = []
+        ptt = PushToTalk(
+            trigger_key="alt_r",
+            on_stop=lambda: callback_called.append("stop"),
+        )
+        ptt._trigger_key = "ALT_R_KEY"
+        # Activate first
+        ptt._active = True
+        ptt._on_release("ALT_R_KEY")
+
+        assert ptt.is_active is False
+        assert callback_called == ["stop"]
+
+    def test_press_wrong_key_ignored(self):
+        ptt = PushToTalk()
+        ptt._trigger_key = "ALT_R_KEY"
+        ptt._on_press("OTHER_KEY")
+        assert ptt.is_active is False
+
+    def test_double_press_only_fires_once(self):
+        count = []
+        ptt = PushToTalk(on_start=lambda: count.append(1))
+        ptt._trigger_key = "KEY"
+        ptt._on_press("KEY")
+        ptt._on_press("KEY")  # Should not fire again
+        assert len(count) == 1
+
+    def test_double_release_only_fires_once(self):
+        count = []
+        ptt = PushToTalk(on_stop=lambda: count.append(1))
+        ptt._trigger_key = "KEY"
+        ptt._active = True
+        ptt._on_release("KEY")
+        ptt._on_release("KEY")
+        assert len(count) == 1
+
+    def test_stop_without_start(self):
+        ptt = PushToTalk()
+        ptt.stop()  # Should not raise

vox_cli-0.1.0/tests/test_mcp_server.py

@@ -0,0 +1,81 @@
+"""Tests for the vox MCP server tool functions."""
+
+from __future__ import annotations
+
+import asyncio
+from unittest.mock import patch, MagicMock
+
+import numpy as np
+import pytest
+
+from vox.mcp_server import record_voice, list_microphones
+
+
+@pytest.fixture()
+def fake_audio():
+    return np.zeros(16000, dtype=np.float32)
+
+
+class TestRecordVoice:
+    """Tests for the record_voice tool."""
+
+    def test_basic_transcription(self, fake_audio):
+        with (
+            patch("vox.recorder.record_until_silence", return_value=fake_audio) as mock_rec,
+            patch("vox.transcriber.transcribe", return_value="hello world") as mock_trans,
+            patch("vox.cleaner.clean", return_value="Hello world") as mock_clean,
+        ):
+            result = asyncio.run(record_voice(max_duration=5, model="tiny"))
+
+            mock_rec.assert_called_once_with(max_duration=5, device=None)
+            mock_trans.assert_called_once_with(fake_audio, "tiny")
+            mock_clean.assert_called_once_with("hello world")
+            assert result == "Hello world"
+
+    def test_skip_cleaning(self, fake_audio):
+        with (
+            patch("vox.recorder.record_until_silence", return_value=fake_audio),
+            patch("vox.transcriber.transcribe", return_value="um hello world"),
+            patch("vox.cleaner.clean") as mock_clean,
+        ):
+            result = asyncio.run(record_voice(clean_text=False))
+
+            mock_clean.assert_not_called()
+            assert result == "um hello world"
+
+    def test_passes_device(self, fake_audio):
+        with (
+            patch("vox.recorder.record_until_silence", return_value=fake_audio) as mock_rec,
+            patch("vox.transcriber.transcribe", return_value="test"),
+            patch("vox.cleaner.clean", return_value="Test"),
+        ):
+            asyncio.run(record_voice(device=3))
+            mock_rec.assert_called_once_with(max_duration=15, device=3)
+
+    def test_recorder_error_propagates(self):
+        with patch(
+            "vox.recorder.record_until_silence",
+            side_effect=RuntimeError("no mic"),
+        ):
+            with pytest.raises(RuntimeError, match="no mic"):
+                asyncio.run(record_voice())
+
+
+class TestListMicrophones:
+    """Tests for the list_microphones tool."""
+
+    def test_devices_listed(self):
+        devices = [
+            {"index": 0, "name": "Built-in Microphone", "channels": 1, "sample_rate": 16000},
+            {"index": 2, "name": "USB Mic", "channels": 2, "sample_rate": 44100},
+        ]
+        with patch("vox.recorder.get_input_devices", return_value=devices):
+            result = asyncio.run(list_microphones())
+
+            assert "[0] Built-in Microphone" in result
+            assert "[2] USB Mic" in result
+
+    def test_no_devices(self):
+        with patch("vox.recorder.get_input_devices", return_value=[]):
+            result = asyncio.run(list_microphones())
+            assert result == "No input devices found."

vox_cli-0.1.0/tests/test_output.py

@@ -0,0 +1,55 @@
+"""Tests for vox.output — text delivery module."""
+
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from vox.output import OutputError, deliver, to_clipboard, to_stdout
+
+
+class TestToStdout:
+    def test_writes_to_stdout(self, capsys):
+        to_stdout("hello world")
+        captured = capsys.readouterr()
+        assert captured.out == "hello world"
+
+
+class TestToClipboard:
+    @patch("vox.output.pyperclip.copy")
+    def test_copies_text(self, mock_copy):
+        to_clipboard("test text")
+        mock_copy.assert_called_once_with("test text")
+
+    @patch("vox.output.pyperclip.copy")
+    def test_raises_on_clipboard_error(self, mock_copy):
+        import pyperclip
+        mock_copy.side_effect = pyperclip.PyperclipException("no clipboard")
+        with pytest.raises(OutputError, match="Clipboard not available"):
+            to_clipboard("text")
+
+
+class TestDeliver:
+    def test_stdout_mode(self, capsys):
+        deliver("hello", mode="stdout")
+        assert capsys.readouterr().out == "hello"
+
+    @patch("vox.output.pyperclip.copy")
+    def test_clipboard_mode(self, mock_copy):
+        deliver("test", mode="clipboard")
+        mock_copy.assert_called_once_with("test")
+
+    def test_invalid_mode_raises(self):
+        with pytest.raises(ValueError, match="Invalid output mode"):
+            deliver("text", mode="email")
+
+
+class TestToPaste:
+    @patch("vox.output.pyperclip.copy")
+    def test_copies_before_paste(self, mock_copy):
+        from vox.output import to_paste
+        # Will fail on paste simulation in test env, but clipboard copy should work
+        try:
+            to_paste("text")
+        except (OutputError, Exception):
+            pass
+        mock_copy.assert_called_with("text")