vocalis 0.1.0__tar.gz

vocalis-0.1.0/PKG-INFO

@@ -0,0 +1,230 @@
+Metadata-Version: 2.3
+Name: vocalis
+Version: 0.1.0
+Summary: Wispr Flow-inspired AI voice dictation and code formatting CLI using Groq
+Keywords: voice,dictation,whisper,groq,cli,speech-to-text,developer-tools,wispr-flow
+Author: Ishan Bhat
+Author-email: Ishan Bhat <ishan2003bhat@gmail.com>
+License: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development
+Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
+Requires-Dist: click>=8.5.1
+Requires-Dist: groq>=1.7.0
+Requires-Dist: numpy>=2.5.4
+Requires-Dist: pynput>=1.8.2
+Requires-Dist: rich>=15.0.0
+Requires-Dist: scipy>=1.18.1
+Requires-Dist: soundcard>=0.4.6
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/bhatishan2003/vocalis
+Project-URL: Repository, https://github.com/bhatishan2003/vocalis
+Project-URL: Issues, https://github.com/bhatishan2003/vocalis/issues
+Description-Content-Type: text/markdown
+
+# 🎙️ Vocalis
+
+> **A Wispr Flow–inspired, ultra-fast AI voice dictation and code formatting CLI for developers, powered by Groq & `uv`.**
+
+Vocalis brings the magic of modern voice dictation into your terminal and editor. Speak naturally—mumbling, hesitating, or dictating code—and Vocalis transcribes your voice in **~200ms** via Groq Whisper, removes all filler words (*"um"*, *"ah"*, *"like"*), formats your speech into clean prose or syntax-highlighted code with Llama 3.3, and copies it straight to your clipboard using **OSC 52** and native system clipboards.
+
+---
+
+## ✨ Features
+
+- **⚡ Sub-Second Latency**: Powered by Groq's high-speed Whisper (`whisper-large-v3-turbo`) and `openai/gpt-oss-120b` (or `llama-3.3-70b-versatile`).
+- **🧠 Wispr Flow AI Refinement**: Automatically cleans disfluencies, false starts, and repetitions while preserving your exact intent.
+- **🎯 4 Tailored Modes**:
+  - `prose` (Default): Clean, professional prose for comments, docs, commit messages, and emails.
+  - `code`: Understands programming idioms (`camelCase`, `snake_case`, functions, indentation, syntax).
+  - `prompt`: Transforms spoken brainstorming into structured prompts for AI assistants (Cursor, Claude, Copilot).
+  - `raw`: Verbatim Whisper transcription without LLM post-processing.
+- **🎙️ Zero-Lag Voice Activity Detection (VAD)**: Dynamic noise-floor calibration detects when you start and stop speaking automatically.
+- **📋 Universal Clipboard Injection**: Supports **OSC 52** (works natively inside VS Code, Cursor, Neovim, tmux, Alacritty, Kitty, WezTerm) alongside Wayland (`wl-copy`) and X11 (`xclip`).
+- **📦 Managed with `uv`**: Ultra-fast packaging, deterministic virtualenvs, and simple execution.
+
+---
+
+## 🚀 Quick Start
+
+### 1. Installation
+
+Clone and sync the project with [`uv`](https://github.com/astral-sh/uv):
+
+```bash
+cd vocalis
+uv sync
+```
+
+To run `vocalis` from anywhere, add an alias to your shell profile (`~/.bashrc` or `~/.zshrc`):
+
+```bash
+alias vocalis="uv run --directory /home/ishan/vocalis vocalis"
+```
+
+Or install it globally using `uv tool`:
+
+```bash
+uv tool install .
+```
+
+---
+
+### 2. Configure Your Groq API Key
+
+Set your Groq key via the CLI (saved in `~/.config/vocalis/config.json`):
+
+```bash
+vocalis config set groq_api_key gsk_YOUR_GROQ_API_KEY
+```
+
+Or export the standard environment variable:
+
+```bash
+export GROQ_API_KEY="gsk_YOUR_GROQ_API_KEY"
+```
+
+---
+
+### 3. Test Your Microphone
+
+Run the live visual VU meter to verify your audio input:
+
+```bash
+vocalis test-mic
+```
+
+---
+
+## 💻 Usage
+
+### Basic Dictation
+Start listening in your terminal or editor split:
+
+```bash
+vocalis start
+```
+
+Speak your thoughts naturally. When you finish speaking, Vocalis automatically detects silence, processes the audio through Groq, prints the result card, and copies the refined text to your clipboard.
+
+### One-Shot Mode (Best for Editor Keybindings)
+Record a single thought, copy to clipboard, and exit:
+
+```bash
+vocalis start --once
+```
+
+### Dictate Code
+Converts verbal programming into clean syntax:
+
+```bash
+vocalis start --mode code
+```
+> **You say:** *"Make an async function called fetch user that takes user id as an int and returns a dictionary"*  
+> **Vocalis writes:** `async def fetch_user(user_id: int) -> dict:`
+
+### Dictate Prompts for AI Coding Assistants
+Converts rambling ideas into structured prompts:
+
+```bash
+vocalis start --mode prompt
+```
+
+### Continuous Loop
+Keep listening for multiple thoughts:
+
+```bash
+vocalis start --continuous
+```
+
+### Manual Push-to-Talk
+Ignore silence detection and press **Enter** when you're done speaking:
+
+```bash
+vocalis start --manual
+```
+
+### Quiet / Direct Pipe Mode
+Output only the final text to stdout (ideal for shell piping):
+
+```bash
+vocalis start --once --quiet > draft.txt
+```
+
+---
+
+## 🛠️ Editor Integration
+
+Run `vocalis setup-editor` to view configuration snippets for your editor:
+
+### VS Code / Cursor Integration
+
+1. In `.vscode/tasks.json` (or User Tasks `Ctrl+Shift+P` → `Tasks: Open User Tasks`):
+```json
+{
+  "version": "2.0.0",
+  "tasks": [
+    {
+      "label": "Vocalis: Dictate",
+      "type": "shell",
+      "command": "uv run --directory /home/ishan/vocalis vocalis start --once",
+      "presentation": {
+        "reveal": "always",
+        "panel": "shared",
+        "focus": true
+      },
+      "problemMatcher": []
+    }
+  ]
+}
+```
+
+2. In `keybindings.json` (`Ctrl+Shift+P` → `Preferences: Open Keyboard Shortcuts (JSON)`):
+```json
+[
+  {
+    "key": "ctrl+alt+v",
+    "command": "workbench.action.tasks.runTask",
+    "args": "Vocalis: Dictate"
+  }
+]
+```
+
+Now pressing `Ctrl+Alt+V` in VS Code starts listening, and the moment you pause, the result is in your clipboard ready to paste!
+
+
+## ⚙️ Configuration Reference
+
+Inspect your current configuration:
+
+```bash
+vocalis config show
+```
+
+Update any setting with `vocalis config set <key> <value>`:
+
+| Key | Default | Description |
+| :--- | :--- | :--- |
+| `groq_api_key` | `None` | Your Groq API key |
+| `default_mode` | `prose` | Default mode: `prose`, `code`, `prompt`, `raw` |
+| `stt_model` | `whisper-large-v3-turbo` | Groq Whisper model |
+| `llm_model` | `openai/gpt-oss-120b` | Groq LLM model (`openai/gpt-oss-120b`, `llama-3.3-70b-versatile`, etc.) |
+| `silence_duration` | `0.9` | Seconds of silence before auto-finishing recording |
+| `energy_threshold` | `0.012` | Voice activity detection RMS threshold |
+| `language` | `en` | Speech language code (`en`, `es`, `fr`, or `auto`) |
+| `auto_copy` | `True` | Automatically copy output to clipboard |
+| `input_device` | `None` | Audio input device (run `vocalis list-devices`) |
+
+---
+
+## 🧪 Testing
+
+Run the test suite with `uv`:
+
+```bash
+uv run pytest
+```

vocalis-0.1.0/README.md

@@ -0,0 +1,202 @@
+# 🎙️ Vocalis
+
+> **A Wispr Flow–inspired, ultra-fast AI voice dictation and code formatting CLI for developers, powered by Groq & `uv`.**
+
+Vocalis brings the magic of modern voice dictation into your terminal and editor. Speak naturally—mumbling, hesitating, or dictating code—and Vocalis transcribes your voice in **~200ms** via Groq Whisper, removes all filler words (*"um"*, *"ah"*, *"like"*), formats your speech into clean prose or syntax-highlighted code with Llama 3.3, and copies it straight to your clipboard using **OSC 52** and native system clipboards.
+
+---
+
+## ✨ Features
+
+- **⚡ Sub-Second Latency**: Powered by Groq's high-speed Whisper (`whisper-large-v3-turbo`) and `openai/gpt-oss-120b` (or `llama-3.3-70b-versatile`).
+- **🧠 Wispr Flow AI Refinement**: Automatically cleans disfluencies, false starts, and repetitions while preserving your exact intent.
+- **🎯 4 Tailored Modes**:
+  - `prose` (Default): Clean, professional prose for comments, docs, commit messages, and emails.
+  - `code`: Understands programming idioms (`camelCase`, `snake_case`, functions, indentation, syntax).
+  - `prompt`: Transforms spoken brainstorming into structured prompts for AI assistants (Cursor, Claude, Copilot).
+  - `raw`: Verbatim Whisper transcription without LLM post-processing.
+- **🎙️ Zero-Lag Voice Activity Detection (VAD)**: Dynamic noise-floor calibration detects when you start and stop speaking automatically.
+- **📋 Universal Clipboard Injection**: Supports **OSC 52** (works natively inside VS Code, Cursor, Neovim, tmux, Alacritty, Kitty, WezTerm) alongside Wayland (`wl-copy`) and X11 (`xclip`).
+- **📦 Managed with `uv`**: Ultra-fast packaging, deterministic virtualenvs, and simple execution.
+
+---
+
+## 🚀 Quick Start
+
+### 1. Installation
+
+Clone and sync the project with [`uv`](https://github.com/astral-sh/uv):
+
+```bash
+cd vocalis
+uv sync
+```
+
+To run `vocalis` from anywhere, add an alias to your shell profile (`~/.bashrc` or `~/.zshrc`):
+
+```bash
+alias vocalis="uv run --directory /home/ishan/vocalis vocalis"
+```
+
+Or install it globally using `uv tool`:
+
+```bash
+uv tool install .
+```
+
+---
+
+### 2. Configure Your Groq API Key
+
+Set your Groq key via the CLI (saved in `~/.config/vocalis/config.json`):
+
+```bash
+vocalis config set groq_api_key gsk_YOUR_GROQ_API_KEY
+```
+
+Or export the standard environment variable:
+
+```bash
+export GROQ_API_KEY="gsk_YOUR_GROQ_API_KEY"
+```
+
+---
+
+### 3. Test Your Microphone
+
+Run the live visual VU meter to verify your audio input:
+
+```bash
+vocalis test-mic
+```
+
+---
+
+## 💻 Usage
+
+### Basic Dictation
+Start listening in your terminal or editor split:
+
+```bash
+vocalis start
+```
+
+Speak your thoughts naturally. When you finish speaking, Vocalis automatically detects silence, processes the audio through Groq, prints the result card, and copies the refined text to your clipboard.
+
+### One-Shot Mode (Best for Editor Keybindings)
+Record a single thought, copy to clipboard, and exit:
+
+```bash
+vocalis start --once
+```
+
+### Dictate Code
+Converts verbal programming into clean syntax:
+
+```bash
+vocalis start --mode code
+```
+> **You say:** *"Make an async function called fetch user that takes user id as an int and returns a dictionary"*  
+> **Vocalis writes:** `async def fetch_user(user_id: int) -> dict:`
+
+### Dictate Prompts for AI Coding Assistants
+Converts rambling ideas into structured prompts:
+
+```bash
+vocalis start --mode prompt
+```
+
+### Continuous Loop
+Keep listening for multiple thoughts:
+
+```bash
+vocalis start --continuous
+```
+
+### Manual Push-to-Talk
+Ignore silence detection and press **Enter** when you're done speaking:
+
+```bash
+vocalis start --manual
+```
+
+### Quiet / Direct Pipe Mode
+Output only the final text to stdout (ideal for shell piping):
+
+```bash
+vocalis start --once --quiet > draft.txt
+```
+
+---
+
+## 🛠️ Editor Integration
+
+Run `vocalis setup-editor` to view configuration snippets for your editor:
+
+### VS Code / Cursor Integration
+
+1. In `.vscode/tasks.json` (or User Tasks `Ctrl+Shift+P` → `Tasks: Open User Tasks`):
+```json
+{
+  "version": "2.0.0",
+  "tasks": [
+    {
+      "label": "Vocalis: Dictate",
+      "type": "shell",
+      "command": "uv run --directory /home/ishan/vocalis vocalis start --once",
+      "presentation": {
+        "reveal": "always",
+        "panel": "shared",
+        "focus": true
+      },
+      "problemMatcher": []
+    }
+  ]
+}
+```
+
+2. In `keybindings.json` (`Ctrl+Shift+P` → `Preferences: Open Keyboard Shortcuts (JSON)`):
+```json
+[
+  {
+    "key": "ctrl+alt+v",
+    "command": "workbench.action.tasks.runTask",
+    "args": "Vocalis: Dictate"
+  }
+]
+```
+
+Now pressing `Ctrl+Alt+V` in VS Code starts listening, and the moment you pause, the result is in your clipboard ready to paste!
+
+
+## ⚙️ Configuration Reference
+
+Inspect your current configuration:
+
+```bash
+vocalis config show
+```
+
+Update any setting with `vocalis config set <key> <value>`:
+
+| Key | Default | Description |
+| :--- | :--- | :--- |
+| `groq_api_key` | `None` | Your Groq API key |
+| `default_mode` | `prose` | Default mode: `prose`, `code`, `prompt`, `raw` |
+| `stt_model` | `whisper-large-v3-turbo` | Groq Whisper model |
+| `llm_model` | `openai/gpt-oss-120b` | Groq LLM model (`openai/gpt-oss-120b`, `llama-3.3-70b-versatile`, etc.) |
+| `silence_duration` | `0.9` | Seconds of silence before auto-finishing recording |
+| `energy_threshold` | `0.012` | Voice activity detection RMS threshold |
+| `language` | `en` | Speech language code (`en`, `es`, `fr`, or `auto`) |
+| `auto_copy` | `True` | Automatically copy output to clipboard |
+| `input_device` | `None` | Audio input device (run `vocalis list-devices`) |
+
+---
+
+## 🧪 Testing
+
+Run the test suite with `uv`:
+
+```bash
+uv run pytest
+```

vocalis-0.1.0/pyproject.toml

@@ -0,0 +1,56 @@
+[project]
+name = "vocalis"
+version = "0.1.0"
+description = "Wispr Flow-inspired AI voice dictation and code formatting CLI using Groq"
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+    "click>=8.5.1",
+    "groq>=1.7.0",
+    "numpy>=2.5.4",
+    "pynput>=1.8.2",
+    "rich>=15.0.0",
+    "scipy>=1.18.1",
+    "soundcard>=0.4.6",
+]
+keywords = [
+    "voice",
+    "dictation",
+    "whisper",
+    "groq",
+    "cli",
+    "speech-to-text",
+    "developer-tools",
+    "wispr-flow",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development",
+    "Topic :: Multimedia :: Sound/Audio :: Speech",
+]
+
+[[project.authors]]
+name = "Ishan Bhat"
+email = "ishan2003bhat@gmail.com"
+
+[project.license]
+text = "MIT"
+
+[project.urls]
+Homepage = "https://github.com/bhatishan2003/vocalis"
+Repository = "https://github.com/bhatishan2003/vocalis"
+Issues = "https://github.com/bhatishan2003/vocalis/issues"
+
+[project.scripts]
+vocalis = "vocalis:main"
+
+[build-system]
+requires = ["uv_build>=0.12.20,<0.13.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = ["pytest>=9.2.0"]

vocalis-0.1.0/pyproject.toml.orig

@@ -0,0 +1,47 @@
+[project]
+name = "vocalis"
+version = "0.1.0"
+description = "Wispr Flow-inspired AI voice dictation and code formatting CLI using Groq"
+readme = "README.md"
+authors = [
+    { name = "Ishan Bhat", email = "ishan2003bhat@gmail.com" }
+]
+requires-python = ">=3.12"
+dependencies = [
+    "click>=8.5.1",
+    "groq>=1.7.0",
+    "numpy>=2.5.4",
+    "pynput>=1.8.2",
+    "rich>=15.0.0",
+    "scipy>=1.18.1",
+    "soundcard>=0.4.6",
+]
+
+license = { text = "MIT" }
+keywords = ["voice", "dictation", "whisper", "groq", "cli", "speech-to-text", "developer-tools", "wispr-flow"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development",
+    "Topic :: Multimedia :: Sound/Audio :: Speech",
+]
+
+[project.urls]
+Homepage = "https://github.com/bhatishan2003/vocalis"
+Repository = "https://github.com/bhatishan2003/vocalis"
+Issues = "https://github.com/bhatishan2003/vocalis/issues"
+
+[project.scripts]
+vocalis = "vocalis:main"
+
+[build-system]
+requires = ["uv_build>=0.12.20,<0.13.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.2.0",
+]

vocalis-0.1.0/src/vocalis/__init__.py

@@ -0,0 +1,6 @@
+"""Vocalis: Wispr Flow-inspired AI voice dictation CLI."""
+
+from vocalis.cli import cli, main
+
+__version__ = "0.1.0"
+__all__ = ["cli", "main", "__version__"]

vocalis-0.1.0/src/vocalis/audio/__init__.py

@@ -0,0 +1,7 @@
+"""Audio recording, processing, and sound effects module."""
+
+from vocalis.audio.chime import ChimePlayer
+from vocalis.audio.recorder import AudioRecorder
+from vocalis.audio.vad import SpeechState, VADDetector
+
+__all__ = ["AudioRecorder", "ChimePlayer", "SpeechState", "VADDetector"]

vocalis-0.1.0/src/vocalis/audio/chime.py

@@ -0,0 +1,77 @@
+"""Non-blocking audio cues and earcons for Vocalis."""
+
+from __future__ import annotations
+
+import io
+import shutil
+import subprocess
+import threading
+from typing import Optional
+
+import numpy as np
+from scipy.io import wavfile
+
+
+class ChimePlayer:
+    """Generates and plays lightweight audio chimes for voice state transitions."""
+
+    def __init__(self, enabled: bool = True) -> None:
+        self.enabled = enabled
+        self._start_wav: Optional[bytes] = None
+        self._done_wav: Optional[bytes] = None
+        if self.enabled:
+            self._prepare_chimes()
+
+    def _generate_tone(self, freq: float, duration: float, volume: float = 0.12) -> bytes:
+        """Synthesize a soft sine wave chime with smooth cosine envelope."""
+        sample_rate = 16000
+        num_samples = int(sample_rate * duration)
+        t = np.linspace(0, duration, num_samples, endpoint=False)
+
+        # Smooth bell envelope (raised cosine) to eliminate clicks
+        envelope = np.sin(np.pi * t / duration)
+        signal = (envelope * volume * np.sin(2 * np.pi * freq * t) * 32767.0).astype(np.int16)
+
+        buf = io.BytesIO()
+        wavfile.write(buf, sample_rate, signal)
+        return buf.getvalue()
+
+    def _prepare_chimes(self) -> None:
+        """Pre-generate in-memory WAV bytes so playback has zero computational latency."""
+        try:
+            # Start chime: Pleasant high A5 (880 Hz, 35ms)
+            self._start_wav = self._generate_tone(880.0, 0.035, volume=0.10)
+            # Done chime: Bright C6 (1046.5 Hz, 45ms)
+            self._done_wav = self._generate_tone(1046.5, 0.045, volume=0.10)
+        except Exception:
+            self.enabled = False
+
+    def _play_raw(self, wav_bytes: Optional[bytes]) -> None:
+        """Play WAV audio in a subprocess without blocking the main thread."""
+        if not self.enabled or not wav_bytes:
+            return
+
+        def worker():
+            for cmd in (["aplay", "-q"], ["pw-play", "-"]):
+                if shutil.which(cmd[0]):
+                    try:
+                        proc = subprocess.Popen(
+                            cmd,
+                            stdin=subprocess.PIPE,
+                            stdout=subprocess.DEVNULL,
+                            stderr=subprocess.DEVNULL,
+                        )
+                        proc.communicate(input=wav_bytes, timeout=0.6)
+                        return
+                    except Exception:
+                        continue
+
+        threading.Thread(target=worker, daemon=True).start()
+
+    def play_start(self) -> None:
+        """Play cue when speech starts."""
+        self._play_raw(self._start_wav)
+
+    def play_done(self) -> None:
+        """Play cue when processing completes and text is typed."""
+        self._play_raw(self._done_wav)