stttui 0.2.0__tar.gz

stttui-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 stttui contributors
+
+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.

stttui-0.2.0/PKG-INFO

@@ -0,0 +1,195 @@
+Metadata-Version: 2.4
+Name: stttui
+Version: 0.2.0
+Summary: Speech-to-Text TUI — offline transcription powered by faster-whisper
+Author: Anthony Holten
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/aholten/sttui
+Project-URL: Repository, https://github.com/aholten/sttui
+Project-URL: Issues, https://github.com/aholten/sttui/issues
+Keywords: speech-to-text,whisper,tui,transcription,offline
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: faster-whisper<2.0.0,>=1.0.0
+Requires-Dist: sounddevice<1.0.0,>=0.4.0
+Requires-Dist: soundfile<1.0.0,>=0.12.0
+Requires-Dist: pynput<2.0.0,>=1.7.0
+Requires-Dist: pyperclip<2.0.0,>=1.8.0
+Requires-Dist: numpy<3.0.0,>=1.24.0
+Requires-Dist: tzdata>=2024.1
+Requires-Dist: textual<1.0.0,>=0.40.0
+Dynamic: license-file
+
+# stttui: Speech To Text Terminal User Interface
+
+> **v0.2.0** | Python 3.10+ | MIT License
+
+A local, fully offline speech-to-text tool powered by [faster-whisper](https://github.com/SYSTRAN/faster-whisper). Record audio with a global hotkey from any window, transcribe it on-device, and get the result copied straight to your clipboard — no cloud, no API keys, no latency.
+
+Comes with a polished terminal UI built on [Textual](https://github.com/Textualize/textual), complete with a live audio level meter, transcription history, and on-the-fly model switching.
+
+<p align="center">
+  <img src="demo.gif" alt="stttui in action" width="700">
+</p>
+
+---
+
+## Features
+
+- **Fully offline** — runs entirely on your machine using faster-whisper with int8 quantization. No data ever leaves your device.
+- **Global hotkeys** — record from anywhere without focusing the terminal
+- **Live audio meter** — real-time visual feedback while recording
+- **Transcription history** — timestamped, scrollable log of every dictation
+- **Model switching** — swap between `tiny`, `base`, `small`, `medium`, and `large` whisper models on the fly
+- **Clipboard integration** — transcriptions are automatically copied and ready to paste
+- **Cross-platform** — works on Windows, macOS, and Linux
+- **Three modes** — rich TUI (default), lightweight CLI (`--cli`), or headless (`--headless`) for scripting/piping
+
+## Installation
+
+### Homebrew (macOS / Linux)
+
+```bash
+brew tap aholten/tap
+brew install stttui
+```
+
+### pip / pipx
+
+```bash
+# With pipx (recommended — isolated environment)
+pipx install stttui
+
+# Or with pip
+pip install stttui
+```
+
+### From source
+
+```bash
+git clone https://github.com/aholten/sttui.git
+cd stttui
+pip install .
+```
+
+> On macOS you may need to grant terminal accessibility permissions for global hotkeys.
+> On Linux, install `portaudio` (`sudo apt install portaudio19-dev`) and `xclip` for clipboard support.
+
+## Usage
+
+### Hotkeys
+
+These work **globally** — even when the terminal is not focused:
+
+| Hotkey | Action |
+|---|---|
+| `Ctrl+Shift+Space` | Start / stop recording |
+| `Ctrl+C` | Quit |
+
+### Workflow
+
+1. Launch the tool — the whisper model loads in the background
+2. Switch to any application (browser, editor, chat, etc.)
+3. Press **Ctrl+Shift+Space** to start recording
+4. Speak
+5. Press **Ctrl+Shift+Space** again to stop
+6. The transcription is copied to your clipboard — paste with **Ctrl+V**
+
+### TUI Mode (default)
+
+```bash
+stttui
+```
+
+The terminal interface includes:
+- **Model selector** — dropdown to switch whisper models without restarting
+- **Status badge** — shows IDLE / RECORDING / TRANSCRIBING state
+- **Level meter** — live audio input visualization
+- **Transcription history** — scrollable log with timestamps
+- **Status log** — model loading progress and system messages
+
+### CLI Mode
+
+```bash
+stttui --cli
+```
+
+Minimal output, no UI — just hotkeys and clipboard.
+
+### Headless Mode
+
+Record, transcribe, print to stdout, and exit. No hotkeys or UI — ideal for scripts and piping.
+
+```bash
+# Record until crtl+shift+space is pressed
+stttui --headless
+
+# Record for exactly 10 seconds
+stttui --headless --duration 10
+
+# Pipe transcription to another command
+stttui --headless --duration 5 | xargs echo "You said:"
+```
+
+Status messages go to stderr, transcription goes to stdout.
+
+### Options
+
+| Flag | Description | Default |
+|---|---|---|
+| `--cli` | Run in CLI-only mode (no TUI) | off |
+| `--headless` | Record, transcribe, print to stdout, and exit | off |
+| `--duration` | Recording duration in seconds (headless mode; omit to wait for Enter) | — |
+| `--model` | Whisper model size | `base` |
+| `--version` | Print version and exit | — |
+
+```bash
+# Example: launch with the small model
+stttui --model small
+```
+
+## Model Sizes
+
+Larger models are more accurate but slower to load and transcribe. All models run on CPU with int8 quantization.
+
+| Model | Parameters | Speed |
+|---|---|---|
+| `tiny` | 39M | Fastest |
+| `base` | 74M | Fast |
+| `small` | 244M | Moderate |
+| `medium` | 769M | Slow |
+| `large` | 1550M | Slowest |
+
+In TUI mode you can switch models from the dropdown at any time.
+
+## Platform Notes
+
+| Platform | Notes |
+|---|---|
+| **Windows** | Works out of the box via Git Bash or MSYS2. |
+| **macOS** | Clipboard works via `pbcopy`. You may need to grant terminal accessibility permissions for global hotkeys. |
+| **Linux** | Install `xclip` or `xsel` for clipboard support (`sudo apt install xclip`). |
+
+## Transcription Log
+
+All transcriptions are automatically saved to `transcription_log.txt` with timestamps for reference.
+
+## License
+
+MIT
+
+## Author
+
+Anthony Holten @aholten on GitHub

stttui-0.2.0/README.md

@@ -0,0 +1,161 @@
+# stttui: Speech To Text Terminal User Interface
+
+> **v0.2.0** | Python 3.10+ | MIT License
+
+A local, fully offline speech-to-text tool powered by [faster-whisper](https://github.com/SYSTRAN/faster-whisper). Record audio with a global hotkey from any window, transcribe it on-device, and get the result copied straight to your clipboard — no cloud, no API keys, no latency.
+
+Comes with a polished terminal UI built on [Textual](https://github.com/Textualize/textual), complete with a live audio level meter, transcription history, and on-the-fly model switching.
+
+<p align="center">
+  <img src="demo.gif" alt="stttui in action" width="700">
+</p>
+
+---
+
+## Features
+
+- **Fully offline** — runs entirely on your machine using faster-whisper with int8 quantization. No data ever leaves your device.
+- **Global hotkeys** — record from anywhere without focusing the terminal
+- **Live audio meter** — real-time visual feedback while recording
+- **Transcription history** — timestamped, scrollable log of every dictation
+- **Model switching** — swap between `tiny`, `base`, `small`, `medium`, and `large` whisper models on the fly
+- **Clipboard integration** — transcriptions are automatically copied and ready to paste
+- **Cross-platform** — works on Windows, macOS, and Linux
+- **Three modes** — rich TUI (default), lightweight CLI (`--cli`), or headless (`--headless`) for scripting/piping
+
+## Installation
+
+### Homebrew (macOS / Linux)
+
+```bash
+brew tap aholten/tap
+brew install stttui
+```
+
+### pip / pipx
+
+```bash
+# With pipx (recommended — isolated environment)
+pipx install stttui
+
+# Or with pip
+pip install stttui
+```
+
+### From source
+
+```bash
+git clone https://github.com/aholten/sttui.git
+cd stttui
+pip install .
+```
+
+> On macOS you may need to grant terminal accessibility permissions for global hotkeys.
+> On Linux, install `portaudio` (`sudo apt install portaudio19-dev`) and `xclip` for clipboard support.
+
+## Usage
+
+### Hotkeys
+
+These work **globally** — even when the terminal is not focused:
+
+| Hotkey | Action |
+|---|---|
+| `Ctrl+Shift+Space` | Start / stop recording |
+| `Ctrl+C` | Quit |
+
+### Workflow
+
+1. Launch the tool — the whisper model loads in the background
+2. Switch to any application (browser, editor, chat, etc.)
+3. Press **Ctrl+Shift+Space** to start recording
+4. Speak
+5. Press **Ctrl+Shift+Space** again to stop
+6. The transcription is copied to your clipboard — paste with **Ctrl+V**
+
+### TUI Mode (default)
+
+```bash
+stttui
+```
+
+The terminal interface includes:
+- **Model selector** — dropdown to switch whisper models without restarting
+- **Status badge** — shows IDLE / RECORDING / TRANSCRIBING state
+- **Level meter** — live audio input visualization
+- **Transcription history** — scrollable log with timestamps
+- **Status log** — model loading progress and system messages
+
+### CLI Mode
+
+```bash
+stttui --cli
+```
+
+Minimal output, no UI — just hotkeys and clipboard.
+
+### Headless Mode
+
+Record, transcribe, print to stdout, and exit. No hotkeys or UI — ideal for scripts and piping.
+
+```bash
+# Record until crtl+shift+space is pressed
+stttui --headless
+
+# Record for exactly 10 seconds
+stttui --headless --duration 10
+
+# Pipe transcription to another command
+stttui --headless --duration 5 | xargs echo "You said:"
+```
+
+Status messages go to stderr, transcription goes to stdout.
+
+### Options
+
+| Flag | Description | Default |
+|---|---|---|
+| `--cli` | Run in CLI-only mode (no TUI) | off |
+| `--headless` | Record, transcribe, print to stdout, and exit | off |
+| `--duration` | Recording duration in seconds (headless mode; omit to wait for Enter) | — |
+| `--model` | Whisper model size | `base` |
+| `--version` | Print version and exit | — |
+
+```bash
+# Example: launch with the small model
+stttui --model small
+```
+
+## Model Sizes
+
+Larger models are more accurate but slower to load and transcribe. All models run on CPU with int8 quantization.
+
+| Model | Parameters | Speed |
+|---|---|---|
+| `tiny` | 39M | Fastest |
+| `base` | 74M | Fast |
+| `small` | 244M | Moderate |
+| `medium` | 769M | Slow |
+| `large` | 1550M | Slowest |
+
+In TUI mode you can switch models from the dropdown at any time.
+
+## Platform Notes
+
+| Platform | Notes |
+|---|---|
+| **Windows** | Works out of the box via Git Bash or MSYS2. |
+| **macOS** | Clipboard works via `pbcopy`. You may need to grant terminal accessibility permissions for global hotkeys. |
+| **Linux** | Install `xclip` or `xsel` for clipboard support (`sudo apt install xclip`). |
+
+## Transcription Log
+
+All transcriptions are automatically saved to `transcription_log.txt` with timestamps for reference.
+
+## License
+
+MIT
+
+## Author
+
+Anthony Holten @aholten on GitHub

stttui-0.2.0/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["setuptools>=68.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "stttui"
+version = "0.2.0"
+description = "Speech-to-Text TUI — offline transcription powered by faster-whisper"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    { name = "Anthony Holten" },
+]
+keywords = ["speech-to-text", "whisper", "tui", "transcription", "offline"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Intended Audience :: End Users/Desktop",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Multimedia :: Sound/Audio :: Speech",
+]
+dependencies = [
+    "faster-whisper>=1.0.0,<2.0.0",
+    "sounddevice>=0.4.0,<1.0.0",
+    "soundfile>=0.12.0,<1.0.0",
+    "pynput>=1.7.0,<2.0.0",
+    "pyperclip>=1.8.0,<2.0.0",
+    "numpy>=1.24.0,<3.0.0",
+    "tzdata>=2024.1",
+    "textual>=0.40.0,<1.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/aholten/sttui"
+Repository = "https://github.com/aholten/sttui"
+Issues = "https://github.com/aholten/sttui/issues"
+
+[project.scripts]
+stttui = "stttui.speech_to_text:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]

stttui-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

stttui-0.2.0/src/stttui/__init__.py

@@ -0,0 +1,3 @@
+"""stttui — Speech-to-Text TUI"""
+
+__version__ = "0.2.0"

stttui-0.2.0/src/stttui/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running as `python -m stttui`."""
+
+from stttui.speech_to_text import main
+
+main()

stttui-0.2.0/src/stttui/speech_to_text.py

@@ -0,0 +1,538 @@
+"""
+stttui — Speech-to-Text TUI
+
+Press Ctrl+Shift+Space to start recording.
+Press Ctrl+Shift+Space again to stop recording, transcribe, and paste.
+Press Ctrl+C to quit.
+
+Run with --cli for CLI-only mode.
+"""
+
+import argparse
+import os
+import signal
+import sys
+import tempfile
+import threading
+import time
+from datetime import datetime
+from pathlib import Path
+from zoneinfo import ZoneInfo
+
+if sys.version_info < (3, 10):
+    sys.exit("stttui requires Python 3.10 or later.")
+
+import numpy as np
+import pyperclip
+import sounddevice as sd
+import soundfile as sf
+from faster_whisper import WhisperModel
+from pynput import keyboard as pynput_keyboard
+
+from stttui import __version__ as VERSION
+
+HOTKEY_RECORD = "ctrl+shift+space"
+HOTKEY_QUIT = "ctrl+c"
+SAMPLE_RATE = 16000
+CHANNELS = 1
+LOG_FILE = Path.home() / ".stttui" / "transcription_log.txt"
+EASTERN = ZoneInfo("America/New_York")
+MODEL_SIZES = ["tiny", "base", "small", "medium", "large"]
+
+# RMS level throttle
+_LEVEL_INTERVAL = 1.0 / 15  # ~15 updates/sec
+
+
+class SpeechToText:
+    """Core engine with callback hooks for UI integration."""
+
+    def __init__(self, model_name="base"):
+        self.recording = False
+        self.audio_chunks = []
+        self.stream = None
+        self.model = None
+        self.model_name = model_name
+        self.lock = threading.Lock()
+        self._last_level_time = 0.0
+
+        # Callback hooks — default to print for CLI mode
+        self.on_status = lambda msg: print(msg)
+        self.on_transcription = lambda text, ts: print(f"Transcription: {text}")
+        self.on_level = lambda rms: None
+        self.on_state_change = lambda state: None
+
+    def load_model(self):
+        self.on_status(f"Loading faster-whisper model '{self.model_name}' (CPU, int8)...")
+        self.model = WhisperModel(
+            self.model_name, device="cpu", compute_type="int8"
+        )
+        self.on_status("Model loaded. Ready!")
+
+    def audio_callback(self, indata, frames, time_info, status):
+        if status:
+            self.on_status(f"Audio status: {status}")
+        self.audio_chunks.append(indata.copy())
+
+        # Throttled RMS level
+        now = time.monotonic()
+        if now - self._last_level_time >= _LEVEL_INTERVAL:
+            self._last_level_time = now
+            rms = float(np.sqrt(np.mean(indata ** 2)))
+            self.on_level(rms)
+
+    def start_recording(self):
+        self.audio_chunks = []
+        self.stream = sd.InputStream(
+            samplerate=SAMPLE_RATE,
+            channels=CHANNELS,
+            dtype="float32",
+            callback=self.audio_callback,
+        )
+        self.stream.start()
+        self.recording = True
+        self.on_state_change("RECORDING")
+        self.on_status(f"Recording... (press {HOTKEY_RECORD} again to stop)")
+
+    def stop_recording(self):
+        if self.stream:
+            self.stream.stop()
+            self.stream.close()
+            self.stream = None
+        self.recording = False
+        self.on_state_change("TRANSCRIBING")
+        self.on_status("Recording stopped. Transcribing...")
+
+    def transcribe(self):
+        if not self.audio_chunks:
+            self.on_status("No audio recorded.")
+            self.on_state_change("IDLE")
+            return
+
+        audio = np.concatenate(self.audio_chunks, axis=0).flatten()
+        duration = len(audio) / SAMPLE_RATE
+        self.on_status(f"Audio duration: {duration:.1f}s")
+
+        if duration < 0.5:
+            self.on_status("Too short, skipping.")
+            self.on_state_change("IDLE")
+            return
+
+        tmp = tempfile.NamedTemporaryFile(suffix=".wav", delete=False)
+        tmp_path = tmp.name
+        tmp.close()
+
+        try:
+            sf.write(tmp_path, audio, SAMPLE_RATE)
+            segments, info = self.model.transcribe(tmp_path)
+            text = " ".join(seg.text.strip() for seg in segments).strip()
+
+            if text:
+                pyperclip.copy(text)
+                timestamp = datetime.now(EASTERN).strftime("%Y-%m-%d %I:%M:%S %p %Z")
+                self.on_transcription(text, timestamp)
+                self._log_transcription(text, timestamp)
+            else:
+                self.on_status("No speech detected.")
+        finally:
+            os.unlink(tmp_path)
+            self.on_state_change("IDLE")
+
+    def _log_transcription(self, text, timestamp=None):
+        if timestamp is None:
+            timestamp = datetime.now(EASTERN).strftime("%Y-%m-%d %I:%M:%S %p %Z")
+        LOG_FILE.parent.mkdir(parents=True, exist_ok=True)
+        with open(LOG_FILE, "a", encoding="utf-8") as f:
+            f.write(f"[{timestamp}] {text}\n")
+
+    def toggle_recording(self):
+        with self.lock:
+            if not self.recording:
+                self.start_recording()
+            else:
+                self.stop_recording()
+                self.transcribe()
+
+
+# ---------------------------------------------------------------------------
+# Cross-platform hotkey handling (pynput)
+# ---------------------------------------------------------------------------
+
+# Canonical key names used in the pressed set
+_KEY_CTRL = "ctrl"
+_KEY_SHIFT = "shift"
+_KEY_SPACE = "space"
+
+_RECORD_COMBO = frozenset({_KEY_CTRL, _KEY_SHIFT, _KEY_SPACE})
+
+
+def _normalise_key(key):
+    """Map any pynput key to a canonical string for reliable matching."""
+    # Modifier keys
+    if key in (pynput_keyboard.Key.shift, pynput_keyboard.Key.shift_l, pynput_keyboard.Key.shift_r):
+        return _KEY_SHIFT
+    if key in (pynput_keyboard.Key.ctrl, pynput_keyboard.Key.ctrl_l, pynput_keyboard.Key.ctrl_r):
+        return _KEY_CTRL
+    # Space — can arrive as Key.space, KeyCode(char=' '), or KeyCode(vk=32, char=None)
+    if key == pynput_keyboard.Key.space:
+        return _KEY_SPACE
+    if isinstance(key, pynput_keyboard.KeyCode):
+        if key.char == ' ':
+            return _KEY_SPACE
+        if getattr(key, 'vk', None) == 32:
+            return _KEY_SPACE
+        if key.char:
+            return key.char.lower()
+    return key
+
+
+def _create_hotkey_listener(on_record):
+    """Create a pynput keyboard listener for the record hotkey.
+
+    The listener never suppresses keys — all other shortcuts continue to work
+    normally while recording. Includes a 300ms debounce to prevent double-fires.
+    """
+    pressed = set()
+    last_fire = [0.0]
+
+    def on_press(key):
+        pressed.add(_normalise_key(key))
+        if _RECORD_COMBO.issubset(pressed):
+            now = time.monotonic()
+            if now - last_fire[0] < 0.3:
+                return
+            last_fire[0] = now
+            threading.Thread(target=on_record, daemon=True).start()
+
+    def on_release(key):
+        pressed.discard(_normalise_key(key))
+
+    return pynput_keyboard.Listener(on_press=on_press, on_release=on_release, suppress=False)
+
+
+# ---------------------------------------------------------------------------
+# CLI mode (original behavior)
+# ---------------------------------------------------------------------------
+
+def run_cli(model_name="base"):
+    stt = SpeechToText(model_name=model_name)
+
+    def cli_transcription(text, ts):
+        print(f"Transcription: {text}")
+        print("Copied to clipboard! Use Ctrl+V to paste.")
+
+    stt.on_transcription = cli_transcription
+
+    stt.load_model()
+    print(f"  Press {HOTKEY_RECORD} to start/stop recording")
+    print(f"  Press {HOTKEY_QUIT} to quit")
+    print("\nListening for hotkey...")
+
+    signal.signal(signal.SIGINT, lambda *_: os._exit(0))
+
+    listener = _create_hotkey_listener(on_record=stt.toggle_recording)
+    listener.start()
+    listener.join()
+
+
+# ---------------------------------------------------------------------------
+# TUI mode (Textual)
+# ---------------------------------------------------------------------------
+
+def run_tui(model_name="base"):
+    from textual.app import App, ComposeResult
+    from textual.binding import Binding
+    from textual.containers import Horizontal, Vertical
+    from textual.reactive import reactive
+    from textual.widgets import Footer, Header, ProgressBar, RichLog, Select, Static
+
+    APP_CSS = """
+    #top-bar {
+        height: 3;
+        padding: 0 1;
+    }
+
+    #model-select {
+        width: 24;
+    }
+
+    #status-badge {
+        width: 20;
+        content-align: center middle;
+        text-style: bold;
+        margin-left: 2;
+        padding: 0 1;
+    }
+
+    #status-badge.idle {
+        background: $primary-darken-2;
+        color: $text;
+    }
+
+    #status-badge.recording {
+        background: $error;
+        color: $text;
+    }
+
+    #status-badge.transcribing {
+        background: $warning;
+        color: $text;
+    }
+
+    #main-content {
+        height: 1fr;
+    }
+
+    #level-meter {
+        height: 1;
+        margin: 0 1;
+    }
+
+    #transcription-history {
+        height: 1fr;
+        margin: 0 1;
+        border: solid $primary;
+    }
+
+    #status-log {
+        height: 7;
+        margin: 0 1;
+        border: solid $accent;
+    }
+    """
+
+    class SpeechToTextApp(App):
+        TITLE = "stttui"
+        CSS = APP_CSS
+
+        BINDINGS = [
+            Binding("ctrl+shift+space", "toggle_record_binding", "Record", show=True),
+            Binding("ctrl+c", "quit_app", "Quit", show=True, priority=True),
+        ]
+
+        state = reactive("IDLE")
+
+        def __init__(self, initial_model: str = "base"):
+            super().__init__()
+            self.engine = SpeechToText(model_name=initial_model)
+            self._initial_model = initial_model
+            self._listener = None
+            # Threading event for cross-thread signalling
+            self._toggle_event = threading.Event()
+            self._last_toggle_time = 0.0
+            # Queues for engine callbacks → UI
+            self._status_queue = []
+            self._transcription_queue = []
+            self._level_value = 0.0
+            self._pending_state = None
+            self._queue_lock = threading.Lock()
+
+        def compose(self) -> ComposeResult:
+            yield Header()
+            with Horizontal(id="top-bar"):
+                yield Select(
+                    [(s, s) for s in MODEL_SIZES],
+                    value=self._initial_model,
+                    id="model-select",
+                    allow_blank=False,
+                )
+                yield Static("IDLE", id="status-badge", classes="idle")
+            with Vertical(id="main-content"):
+                yield ProgressBar(id="level-meter", total=100, show_eta=False, show_percentage=False)
+                yield RichLog(id="transcription-history", highlight=True, markup=True)
+            yield RichLog(id="status-log", highlight=True, markup=True, max_lines=50)
+            yield Footer()
+
+        def on_mount(self) -> None:
+            # Wire engine callbacks to queue updates (thread-safe)
+            self.engine.on_status = self._enqueue_status
+            self.engine.on_transcription = self._enqueue_transcription
+            self.engine.on_level = self._enqueue_level
+            self.engine.on_state_change = self._enqueue_state
+
+            # Register global record hotkey via pynput
+            self._listener = _create_hotkey_listener(
+                on_record=self._toggle_event.set,
+            )
+            self._listener.start()
+
+            # Poll events and queues from Textual's own timer (~20 Hz)
+            self.set_interval(0.05, self._poll)
+
+            # Load model in background
+            self.run_worker(self._load_model_worker, thread=True)
+
+        async def _load_model_worker(self) -> None:
+            self.engine.load_model()
+
+        # -- Thread-safe enqueue helpers (called from engine/audio threads) --
+
+        def _enqueue_status(self, msg: str) -> None:
+            with self._queue_lock:
+                self._status_queue.append(msg)
+
+        def _enqueue_transcription(self, text: str, ts: str) -> None:
+            with self._queue_lock:
+                self._transcription_queue.append((text, ts))
+
+        def _enqueue_level(self, rms: float) -> None:
+            self._level_value = rms
+
+        def _enqueue_state(self, s: str) -> None:
+            self._pending_state = s
+
+        # -- Polling (runs on Textual main thread via set_interval) --
+
+        def _poll(self) -> None:
+            # Check hotkey events
+            if self._toggle_event.is_set():
+                self._toggle_event.clear()
+                self._toggle_record()
+
+            # Drain queued UI updates
+            with self._queue_lock:
+                statuses = self._status_queue[:]
+                self._status_queue.clear()
+                transcriptions = self._transcription_queue[:]
+                self._transcription_queue.clear()
+
+            for msg in statuses:
+                self._log_status(msg)
+            for text, ts in transcriptions:
+                self._add_transcription(text, ts)
+
+            # Update level meter
+            rms = self._level_value
+            level = min(100, int(rms * 700))
+            bar = self.query_one("#level-meter", ProgressBar)
+            bar.update(progress=level)
+
+            # Update state
+            pending = self._pending_state
+            if pending is not None:
+                self._pending_state = None
+                self.state = pending
+
+        # -- State management --
+
+        def watch_state(self, new_state: str) -> None:
+            badge = self.query_one("#status-badge", Static)
+            badge.update(new_state)
+            badge.remove_class("idle", "recording", "transcribing")
+            badge.add_class(new_state.lower())
+
+            if new_state != "RECORDING":
+                level = self.query_one("#level-meter", ProgressBar)
+                level.update(progress=0)
+
+        # -- UI helpers --
+
+        def _log_status(self, msg: str) -> None:
+            log = self.query_one("#status-log", RichLog)
+            log.write(msg)
+
+        def _add_transcription(self, text: str, timestamp: str) -> None:
+            history = self.query_one("#transcription-history", RichLog)
+            history.write(f"[dim]{timestamp}[/dim]  {text}")
+            self._log_status("Copied to clipboard!")
+
+        # -- Actions --
+
+        def _toggle_record(self) -> None:
+            # Debounce: both pynput and Textual may fire for the same keypress
+            now = time.monotonic()
+            if now - self._last_toggle_time < 0.3:
+                return
+            self._last_toggle_time = now
+
+            if self.engine.model is None:
+                self._log_status("Model still loading, please wait...")
+                return
+            if self.state == "TRANSCRIBING":
+                self._log_status("Still transcribing, please wait...")
+                return
+
+            if self.state == "IDLE":
+                self.state = "RECORDING"
+                self.engine.start_recording()
+            else:
+                self.state = "TRANSCRIBING"
+                self.engine.stop_recording()
+                self.run_worker(self._transcribe_worker, thread=True)
+
+        async def _transcribe_worker(self) -> None:
+            self.engine.transcribe()
+
+        def action_toggle_record_binding(self) -> None:
+            self._toggle_record()
+
+        def action_quit_app(self) -> None:
+            if self._listener:
+                self._listener.stop()
+            if self.engine.stream:
+                self.engine.stream.stop()
+                self.engine.stream.close()
+            self.exit()
+
+        def on_select_changed(self, event: Select.Changed) -> None:
+            new_model = str(event.value)
+            if new_model == self.engine.model_name:
+                return
+            if self.state != "IDLE":
+                self._log_status("Cannot change model while recording/transcribing.")
+                event.select.value = self.engine.model_name
+                return
+            self.engine.model_name = new_model
+            self.engine.model = None
+            self._log_status(f"Switching to model '{new_model}'...")
+            self.run_worker(self._load_model_worker, thread=True)
+
+    app = SpeechToTextApp(initial_model=model_name)
+    app.run()
+
+
+# ---------------------------------------------------------------------------
+# Entry point
+# ---------------------------------------------------------------------------
+
+def run_headless(model_name="base", duration=None):
+    """Record for a fixed duration (or until Enter), transcribe, print to stdout, and exit."""
+    stt = SpeechToText(model_name=model_name)
+
+    # Suppress status messages; only output the transcription
+    stt.on_status = lambda msg: sys.stderr.write(f"{msg}\n")
+    stt.on_transcription = lambda text, ts: print(text)
+
+    stt.load_model()
+
+    stt.start_recording()
+
+    if duration:
+        sys.stderr.write(f"Recording for {duration}s...\n")
+        time.sleep(duration)
+    else:
+        sys.stderr.write("Recording... press Enter to stop.\n")
+        input()
+
+    stt.stop_recording()
+    stt.transcribe()
+
+
+def main():
+    parser = argparse.ArgumentParser(description="stttui — Speech-to-Text TUI")
+    parser.add_argument("--version", action="version", version=f"stttui {VERSION}")
+    parser.add_argument("--cli", action="store_true", help="Run in CLI-only mode (no TUI)")
+    parser.add_argument("--headless", action="store_true", help="Record, transcribe, print to stdout, and exit (no hotkeys/UI)")
+    parser.add_argument("--duration", type=float, default=None, help="Recording duration in seconds (headless mode; omit to wait for Enter)")
+    parser.add_argument("--model", default="base", choices=MODEL_SIZES, help="Whisper model size")
+    args = parser.parse_args()
+
+    if args.headless:
+        run_headless(model_name=args.model, duration=args.duration)
+    elif args.cli:
+        run_cli(model_name=args.model)
+    else:
+        run_tui(model_name=args.model)
+
+
+if __name__ == "__main__":
+    main()

stttui-0.2.0/src/stttui.egg-info/PKG-INFO

@@ -0,0 +1,195 @@
+Metadata-Version: 2.4
+Name: stttui
+Version: 0.2.0
+Summary: Speech-to-Text TUI — offline transcription powered by faster-whisper
+Author: Anthony Holten
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/aholten/sttui
+Project-URL: Repository, https://github.com/aholten/sttui
+Project-URL: Issues, https://github.com/aholten/sttui/issues
+Keywords: speech-to-text,whisper,tui,transcription,offline
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: faster-whisper<2.0.0,>=1.0.0
+Requires-Dist: sounddevice<1.0.0,>=0.4.0
+Requires-Dist: soundfile<1.0.0,>=0.12.0
+Requires-Dist: pynput<2.0.0,>=1.7.0
+Requires-Dist: pyperclip<2.0.0,>=1.8.0
+Requires-Dist: numpy<3.0.0,>=1.24.0
+Requires-Dist: tzdata>=2024.1
+Requires-Dist: textual<1.0.0,>=0.40.0
+Dynamic: license-file
+
+# stttui: Speech To Text Terminal User Interface
+
+> **v0.2.0** | Python 3.10+ | MIT License
+
+A local, fully offline speech-to-text tool powered by [faster-whisper](https://github.com/SYSTRAN/faster-whisper). Record audio with a global hotkey from any window, transcribe it on-device, and get the result copied straight to your clipboard — no cloud, no API keys, no latency.
+
+Comes with a polished terminal UI built on [Textual](https://github.com/Textualize/textual), complete with a live audio level meter, transcription history, and on-the-fly model switching.
+
+<p align="center">
+  <img src="demo.gif" alt="stttui in action" width="700">
+</p>
+
+---
+
+## Features
+
+- **Fully offline** — runs entirely on your machine using faster-whisper with int8 quantization. No data ever leaves your device.
+- **Global hotkeys** — record from anywhere without focusing the terminal
+- **Live audio meter** — real-time visual feedback while recording
+- **Transcription history** — timestamped, scrollable log of every dictation
+- **Model switching** — swap between `tiny`, `base`, `small`, `medium`, and `large` whisper models on the fly
+- **Clipboard integration** — transcriptions are automatically copied and ready to paste
+- **Cross-platform** — works on Windows, macOS, and Linux
+- **Three modes** — rich TUI (default), lightweight CLI (`--cli`), or headless (`--headless`) for scripting/piping
+
+## Installation
+
+### Homebrew (macOS / Linux)
+
+```bash
+brew tap aholten/tap
+brew install stttui
+```
+
+### pip / pipx
+
+```bash
+# With pipx (recommended — isolated environment)
+pipx install stttui
+
+# Or with pip
+pip install stttui
+```
+
+### From source
+
+```bash
+git clone https://github.com/aholten/sttui.git
+cd stttui
+pip install .
+```
+
+> On macOS you may need to grant terminal accessibility permissions for global hotkeys.
+> On Linux, install `portaudio` (`sudo apt install portaudio19-dev`) and `xclip` for clipboard support.
+
+## Usage
+
+### Hotkeys
+
+These work **globally** — even when the terminal is not focused:
+
+| Hotkey | Action |
+|---|---|
+| `Ctrl+Shift+Space` | Start / stop recording |
+| `Ctrl+C` | Quit |
+
+### Workflow
+
+1. Launch the tool — the whisper model loads in the background
+2. Switch to any application (browser, editor, chat, etc.)
+3. Press **Ctrl+Shift+Space** to start recording
+4. Speak
+5. Press **Ctrl+Shift+Space** again to stop
+6. The transcription is copied to your clipboard — paste with **Ctrl+V**
+
+### TUI Mode (default)
+
+```bash
+stttui
+```
+
+The terminal interface includes:
+- **Model selector** — dropdown to switch whisper models without restarting
+- **Status badge** — shows IDLE / RECORDING / TRANSCRIBING state
+- **Level meter** — live audio input visualization
+- **Transcription history** — scrollable log with timestamps
+- **Status log** — model loading progress and system messages
+
+### CLI Mode
+
+```bash
+stttui --cli
+```
+
+Minimal output, no UI — just hotkeys and clipboard.
+
+### Headless Mode
+
+Record, transcribe, print to stdout, and exit. No hotkeys or UI — ideal for scripts and piping.
+
+```bash
+# Record until crtl+shift+space is pressed
+stttui --headless
+
+# Record for exactly 10 seconds
+stttui --headless --duration 10
+
+# Pipe transcription to another command
+stttui --headless --duration 5 | xargs echo "You said:"
+```
+
+Status messages go to stderr, transcription goes to stdout.
+
+### Options
+
+| Flag | Description | Default |
+|---|---|---|
+| `--cli` | Run in CLI-only mode (no TUI) | off |
+| `--headless` | Record, transcribe, print to stdout, and exit | off |
+| `--duration` | Recording duration in seconds (headless mode; omit to wait for Enter) | — |
+| `--model` | Whisper model size | `base` |
+| `--version` | Print version and exit | — |
+
+```bash
+# Example: launch with the small model
+stttui --model small
+```
+
+## Model Sizes
+
+Larger models are more accurate but slower to load and transcribe. All models run on CPU with int8 quantization.
+
+| Model | Parameters | Speed |
+|---|---|---|
+| `tiny` | 39M | Fastest |
+| `base` | 74M | Fast |
+| `small` | 244M | Moderate |
+| `medium` | 769M | Slow |
+| `large` | 1550M | Slowest |
+
+In TUI mode you can switch models from the dropdown at any time.
+
+## Platform Notes
+
+| Platform | Notes |
+|---|---|
+| **Windows** | Works out of the box via Git Bash or MSYS2. |
+| **macOS** | Clipboard works via `pbcopy`. You may need to grant terminal accessibility permissions for global hotkeys. |
+| **Linux** | Install `xclip` or `xsel` for clipboard support (`sudo apt install xclip`). |
+
+## Transcription Log
+
+All transcriptions are automatically saved to `transcription_log.txt` with timestamps for reference.
+
+## License
+
+MIT
+
+## Author
+
+Anthony Holten @aholten on GitHub

stttui-0.2.0/src/stttui.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+LICENSE
+README.md
+pyproject.toml
+src/stttui/__init__.py
+src/stttui/__main__.py
+src/stttui/speech_to_text.py
+src/stttui.egg-info/PKG-INFO
+src/stttui.egg-info/SOURCES.txt
+src/stttui.egg-info/dependency_links.txt
+src/stttui.egg-info/entry_points.txt
+src/stttui.egg-info/requires.txt
+src/stttui.egg-info/top_level.txt

stttui-0.2.0/src/stttui.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

stttui-0.2.0/src/stttui.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+stttui = stttui.speech_to_text:main

stttui-0.2.0/src/stttui.egg-info/requires.txt

@@ -0,0 +1,8 @@
+faster-whisper<2.0.0,>=1.0.0
+sounddevice<1.0.0,>=0.4.0
+soundfile<1.0.0,>=0.12.0
+pynput<2.0.0,>=1.7.0
+pyperclip<2.0.0,>=1.8.0
+numpy<3.0.0,>=1.24.0
+tzdata>=2024.1
+textual<1.0.0,>=0.40.0

stttui-0.2.0/src/stttui.egg-info/top_level.txt

@@ -0,0 +1 @@
+stttui