speaksy 0.1.0__tar.gz

speaksy-0.1.0/.claude/settings.local.json

@@ -0,0 +1,19 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(source:*)",
+      "Bash(systemctl:*)",
+      "Bash(systemctl --user enable:*)",
+      "Bash(for name in scribe mumble hark dictly speaksy flowkey)",
+      "Bash(do echo -n \"$name: \")",
+      "Bash(pip index:*)",
+      "Bash(done)",
+      "Bash(pip install:*)",
+      "Bash(python -c:*)",
+      "Bash(git init:*)",
+      "Bash(git branch:*)",
+      "Bash(git rm:*)",
+      "Bash(python -m build:*)"
+    ]
+  }
+}

speaksy-0.1.0/.gitignore

@@ -0,0 +1,30 @@
+# Environment
+.env
+.venv/
+venv/
+
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+*.egg
+
+# Audio
+*.wav
+
+# IDE
+.idea/
+.vscode/
+*.swp
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Old files (replaced by src/speaksy/)
+voicetype.py
+config.yaml
+requirements.txt

speaksy-0.1.0/LICENSE

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

speaksy-0.1.0/PKG-INFO

@@ -0,0 +1,246 @@
+Metadata-Version: 2.4
+Name: speaksy
+Version: 0.1.0
+Summary: Voice typing for Linux. Talk it. Type it. Ship it.
+Project-URL: Homepage, https://github.com/oneKn8/speaksy
+Project-URL: Repository, https://github.com/oneKn8/speaksy
+Project-URL: Issues, https://github.com/oneKn8/speaksy/issues
+Author: oneknight
+License-Expression: MIT
+License-File: LICENSE
+Keywords: dictation,linux,speech-to-text,typing,voice,whisper
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
+Classifier: Topic :: Text Processing
+Requires-Python: >=3.10
+Requires-Dist: faster-whisper>=1.1.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: pillow>=10.0.0
+Requires-Dist: pynput>=1.7.0
+Requires-Dist: pystray>=0.19.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: sounddevice>=0.5.0
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="https://img.shields.io/badge/speaksy-voice%20typing-blueviolet?style=for-the-badge&logo=microphone" alt="speaksy">
+</p>
+
+<h1 align="center">speaksy</h1>
+
+<p align="center">
+  <strong>talk it. type it. ship it.</strong>
+</p>
+
+<p align="center">
+  <a href="https://github.com/oneKn8/speaksy/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-green.svg" alt="License"></a>
+  <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.10+-blue.svg" alt="Python"></a>
+  <a href="https://github.com/oneKn8/speaksy"><img src="https://img.shields.io/badge/platform-Linux-orange.svg" alt="Platform"></a>
+  <a href="https://console.groq.com"><img src="https://img.shields.io/badge/powered%20by-Groq-ff6600.svg" alt="Groq"></a>
+</p>
+
+<p align="center">
+  <em>Voice typing for Linux that actually works.<br>Hold a key, speak, release — your words appear wherever you're typing.</em>
+</p>
+
+---
+
+## Demo
+
+```
+$ speaksy
+
+  ╭────────────────────────────────────────╮
+  │  SPEAKSY                               │
+  │  talk it. type it. ship it.            │
+  ╰────────────────────────────────────────╯
+
+  Status: vibing
+  Hotkeys: Right Ctrl (hold) | F8 (toggle)
+
+speaksy> _
+```
+
+<!-- TODO: Add demo GIF here -->
+<!-- ![Demo](assets/demo.gif) -->
+
+---
+
+## Quick Start
+
+```bash
+# Install
+pipx install speaksy
+
+# Run (interactive setup on first launch)
+speaksy
+```
+
+That's it. 30 seconds to voice typing.
+
+---
+
+## Features
+
+| | Feature | Description |
+|---|---------|-------------|
+| **Speed** | < 1 second latency | Groq's Whisper API is blazing fast |
+| **Smart** | AI text cleanup | Fixes grammar, removes "um", "uh", "like" |
+| **Free** | No credit card | Groq's free tier is generous |
+| **Offline** | Local fallback | Works without internet via faster-whisper |
+| **Private** | Privacy mode | Keep voice 100% on your machine |
+| **Auto** | Runs on login | Always ready when you are |
+
+---
+
+## How It Works
+
+```
+┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐
+│  Hold Key   │ -> │   Speak     │ -> │  Release    │ -> │ Text Appears│
+│  (Right Ctrl)    │  naturally  │    │   key       │    │  at cursor  │
+└─────────────┘    └─────────────┘    └─────────────┘    └─────────────┘
+                            |
+                            v
+                   ┌─────────────────┐
+                   │  Groq Whisper   │
+                   │  + LLM cleanup  │
+                   └─────────────────┘
+```
+
+1. Press hotkey (Right Ctrl = hold, F8 = toggle)
+2. Speak naturally
+3. Release — text appears in < 1 second
+
+Works everywhere: browser, terminal, IDE, Slack, Discord, anywhere you type.
+
+---
+
+## Commands
+
+Run `speaksy` to open the interactive CLI:
+
+| Command | Description |
+|---------|-------------|
+| `/setup` | Configure API key & hotkeys |
+| `/start` | Start voice typing |
+| `/stop` | Take a break |
+| `/status` | Check the vibe |
+| `/logs` | View receipts |
+| `/config` | Tweak settings |
+| `/help` | Get backup |
+| `/quit` | Peace out |
+
+---
+
+## Requirements
+
+- **OS:** Linux (X11 or XWayland)
+- **Python:** 3.10+
+- **API Key:** Free from [console.groq.com](https://console.groq.com)
+
+System dependencies (auto-installed during setup):
+```bash
+sudo apt install xclip xdotool
+```
+
+---
+
+## Privacy Mode
+
+By default, audio goes to Groq for fast transcription. Want to keep it local?
+
+```
+speaksy> /config
+# Select "Privacy mode" -> "local"
+```
+
+Local mode uses [faster-whisper](https://github.com/SYSTRAN/faster-whisper) on your CPU. Slower (~3-5s) but your voice never leaves your machine.
+
+---
+
+## Troubleshooting
+
+<details>
+<summary><strong>No audio input detected</strong></summary>
+
+- Check your mic is connected
+- Run `arecord -l` to list audio devices
+</details>
+
+<details>
+<summary><strong>Text not appearing</strong></summary>
+
+- Install dependencies: `sudo apt install xclip xdotool`
+- Some pure Wayland apps may not work with xdotool
+</details>
+
+<details>
+<summary><strong>Service won't start</strong></summary>
+
+- Check logs: run `speaksy` then `/logs`
+- Verify API key at console.groq.com
+</details>
+
+---
+
+## Uninstall
+
+```bash
+# Stop service
+speaksy
+# > /stop
+# > /quit
+
+# Remove package
+pipx uninstall speaksy
+
+# Remove config (optional)
+rm -rf ~/.config/speaksy
+rm ~/.config/systemd/user/speaksy.service
+systemctl --user daemon-reload
+```
+
+---
+
+## Tech Stack
+
+- **STT:** [Groq Whisper API](https://groq.com) / [faster-whisper](https://github.com/SYSTRAN/faster-whisper)
+- **LLM:** Llama 3.1 8B (via Groq) for text cleanup
+- **Audio:** [sounddevice](https://python-sounddevice.readthedocs.io/)
+- **Hotkeys:** [pynput](https://pynput.readthedocs.io/)
+- **CLI:** [Rich](https://rich.readthedocs.io/)
+
+---
+
+## Contributing
+
+PRs and issues welcome!
+
+<a href="https://github.com/oneKn8/speaksy/issues">Report Bug</a>
+·
+<a href="https://github.com/oneKn8/speaksy/issues">Request Feature</a>
+
+---
+
+## License
+
+MIT - do whatever you want with it.
+
+---
+
+<p align="center">
+  <sub>Built with caffeine and voice commands</sub>
+</p>

speaksy-0.1.0/README.md

@@ -0,0 +1,210 @@
+<p align="center">
+  <img src="https://img.shields.io/badge/speaksy-voice%20typing-blueviolet?style=for-the-badge&logo=microphone" alt="speaksy">
+</p>
+
+<h1 align="center">speaksy</h1>
+
+<p align="center">
+  <strong>talk it. type it. ship it.</strong>
+</p>
+
+<p align="center">
+  <a href="https://github.com/oneKn8/speaksy/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-green.svg" alt="License"></a>
+  <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.10+-blue.svg" alt="Python"></a>
+  <a href="https://github.com/oneKn8/speaksy"><img src="https://img.shields.io/badge/platform-Linux-orange.svg" alt="Platform"></a>
+  <a href="https://console.groq.com"><img src="https://img.shields.io/badge/powered%20by-Groq-ff6600.svg" alt="Groq"></a>
+</p>
+
+<p align="center">
+  <em>Voice typing for Linux that actually works.<br>Hold a key, speak, release — your words appear wherever you're typing.</em>
+</p>
+
+---
+
+## Demo
+
+```
+$ speaksy
+
+  ╭────────────────────────────────────────╮
+  │  SPEAKSY                               │
+  │  talk it. type it. ship it.            │
+  ╰────────────────────────────────────────╯
+
+  Status: vibing
+  Hotkeys: Right Ctrl (hold) | F8 (toggle)
+
+speaksy> _
+```
+
+<!-- TODO: Add demo GIF here -->
+<!-- ![Demo](assets/demo.gif) -->
+
+---
+
+## Quick Start
+
+```bash
+# Install
+pipx install speaksy
+
+# Run (interactive setup on first launch)
+speaksy
+```
+
+That's it. 30 seconds to voice typing.
+
+---
+
+## Features
+
+| | Feature | Description |
+|---|---------|-------------|
+| **Speed** | < 1 second latency | Groq's Whisper API is blazing fast |
+| **Smart** | AI text cleanup | Fixes grammar, removes "um", "uh", "like" |
+| **Free** | No credit card | Groq's free tier is generous |
+| **Offline** | Local fallback | Works without internet via faster-whisper |
+| **Private** | Privacy mode | Keep voice 100% on your machine |
+| **Auto** | Runs on login | Always ready when you are |
+
+---
+
+## How It Works
+
+```
+┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐
+│  Hold Key   │ -> │   Speak     │ -> │  Release    │ -> │ Text Appears│
+│  (Right Ctrl)    │  naturally  │    │   key       │    │  at cursor  │
+└─────────────┘    └─────────────┘    └─────────────┘    └─────────────┘
+                            |
+                            v
+                   ┌─────────────────┐
+                   │  Groq Whisper   │
+                   │  + LLM cleanup  │
+                   └─────────────────┘
+```
+
+1. Press hotkey (Right Ctrl = hold, F8 = toggle)
+2. Speak naturally
+3. Release — text appears in < 1 second
+
+Works everywhere: browser, terminal, IDE, Slack, Discord, anywhere you type.
+
+---
+
+## Commands
+
+Run `speaksy` to open the interactive CLI:
+
+| Command | Description |
+|---------|-------------|
+| `/setup` | Configure API key & hotkeys |
+| `/start` | Start voice typing |
+| `/stop` | Take a break |
+| `/status` | Check the vibe |
+| `/logs` | View receipts |
+| `/config` | Tweak settings |
+| `/help` | Get backup |
+| `/quit` | Peace out |
+
+---
+
+## Requirements
+
+- **OS:** Linux (X11 or XWayland)
+- **Python:** 3.10+
+- **API Key:** Free from [console.groq.com](https://console.groq.com)
+
+System dependencies (auto-installed during setup):
+```bash
+sudo apt install xclip xdotool
+```
+
+---
+
+## Privacy Mode
+
+By default, audio goes to Groq for fast transcription. Want to keep it local?
+
+```
+speaksy> /config
+# Select "Privacy mode" -> "local"
+```
+
+Local mode uses [faster-whisper](https://github.com/SYSTRAN/faster-whisper) on your CPU. Slower (~3-5s) but your voice never leaves your machine.
+
+---
+
+## Troubleshooting
+
+<details>
+<summary><strong>No audio input detected</strong></summary>
+
+- Check your mic is connected
+- Run `arecord -l` to list audio devices
+</details>
+
+<details>
+<summary><strong>Text not appearing</strong></summary>
+
+- Install dependencies: `sudo apt install xclip xdotool`
+- Some pure Wayland apps may not work with xdotool
+</details>
+
+<details>
+<summary><strong>Service won't start</strong></summary>
+
+- Check logs: run `speaksy` then `/logs`
+- Verify API key at console.groq.com
+</details>
+
+---
+
+## Uninstall
+
+```bash
+# Stop service
+speaksy
+# > /stop
+# > /quit
+
+# Remove package
+pipx uninstall speaksy
+
+# Remove config (optional)
+rm -rf ~/.config/speaksy
+rm ~/.config/systemd/user/speaksy.service
+systemctl --user daemon-reload
+```
+
+---
+
+## Tech Stack
+
+- **STT:** [Groq Whisper API](https://groq.com) / [faster-whisper](https://github.com/SYSTRAN/faster-whisper)
+- **LLM:** Llama 3.1 8B (via Groq) for text cleanup
+- **Audio:** [sounddevice](https://python-sounddevice.readthedocs.io/)
+- **Hotkeys:** [pynput](https://pynput.readthedocs.io/)
+- **CLI:** [Rich](https://rich.readthedocs.io/)
+
+---
+
+## Contributing
+
+PRs and issues welcome!
+
+<a href="https://github.com/oneKn8/speaksy/issues">Report Bug</a>
+·
+<a href="https://github.com/oneKn8/speaksy/issues">Request Feature</a>
+
+---
+
+## License
+
+MIT - do whatever you want with it.
+
+---
+
+<p align="center">
+  <sub>Built with caffeine and voice commands</sub>
+</p>

speaksy-0.1.0/docs/plans/2026-02-05-speaksy-design.md

@@ -0,0 +1,173 @@
+# Speaksy Design Document
+
+**Date:** 2026-02-05
+**Status:** Approved
+
+## Overview
+
+Speaksy is a voice typing tool for Linux. Users speak, and their words appear wherever they're typing.
+
+**Tagline:** talk it. type it. ship it.
+
+## Installation
+
+```bash
+pipx install speaksy    # recommended
+pip3 install speaksy    # alternative
+```
+
+## User Experience
+
+Single command `speaksy` opens an interactive CLI with slash commands:
+
+- `/setup` - Configure API key, hotkeys, install service
+- `/start` - Start voice typing service
+- `/stop` - Stop voice typing service
+- `/status` - Show current status
+- `/logs` - View recent activity
+- `/config` - Edit settings
+- `/help` - Show all commands
+- `/quit` - Exit CLI (service keeps running)
+
+### First Run
+
+On first run (no config), auto-triggers `/setup` wizard:
+
+1. Check system deps (xclip, xdotool)
+2. Prompt for Groq API key
+3. Validate key works
+4. Optional: customize hotkeys
+5. Install systemd user service
+6. Start service
+
+### UI Style
+
+Gen-Z friendly with colors and personality:
+- Status messages: "vibing", "sleeping", "dead"
+- Helpful with links and next steps
+- Error messages are friendly, not scary
+
+## Architecture
+
+### Project Structure
+
+```
+speaksy/
+├── pyproject.toml
+├── README.md
+├── LICENSE
+└── src/
+    └── speaksy/
+        ├── __init__.py
+        ├── __main__.py
+        ├── cli.py
+        ├── core.py
+        ├── config.py
+        ├── service.py
+        └── setup_wizard.py
+```
+
+### Config Location
+
+- Config: `~/.config/speaksy/config.yaml`
+- API key: `~/.config/speaksy/.env`
+- Service: `~/.config/systemd/user/speaksy.service`
+
+### Runtime
+
+Always runs as systemd user service. CLI is for management only.
+
+## Features
+
+### Transcription
+
+- **Primary:** Groq Whisper API (fast, <1s)
+- **Fallback:** Local faster-whisper (offline, ~3-5s)
+- **Cleanup:** LLM post-processing for grammar/filler words
+
+### Hotkeys
+
+- Push-to-talk: Hold Right Ctrl (default)
+- Toggle mode: Press F8 (default)
+- Customizable via `/config`
+
+### Privacy Mode
+
+Local-only option for users who don't want cloud:
+- Uses faster-whisper on CPU
+- Voice never leaves the machine
+- Slower but private
+
+### Error Handling
+
+- Invalid API key: Warn user, fall back to local
+- Expired key: Same behavior
+- Network down: Silent fallback to local
+- Rate limited: Wait, retry, fallback
+
+### Tray Icon
+
+- Green: Groq API working
+- Yellow: Using local fallback
+- Red: Both failed
+
+## CLI Commands Detail
+
+### /setup
+Interactive wizard for first-time configuration.
+
+### /start
+```
+speaksy> /start
+🚀 lesss gooo! speaksy is now listening...
+```
+
+### /stop
+```
+speaksy> /stop
+😴 aight speaksy is taking a nap
+```
+
+### /status
+```
+speaksy> /status
+📊 the vibe check:
+   ├─ service: running for 2h 34m
+   ├─ api key: configured ✓
+   └─ mode: cloud (groq)
+```
+
+### /config
+Interactive menu for:
+1. API key
+2. Hotkeys
+3. Privacy mode (cloud/local)
+4. Text cleanup on/off
+
+### /logs
+Shows recent transcription activity and errors.
+
+## Dependencies
+
+### Python
+- faster-whisper
+- sounddevice
+- numpy
+- pynput
+- pystray
+- Pillow
+- PyYAML
+- httpx
+- python-dotenv
+- rich (for CLI styling)
+
+### System
+- xclip
+- xdotool
+- Python 3.10+
+
+## Success Metrics
+
+- Simple install: 2 commands max
+- Setup time: <60 seconds
+- First transcription: <30 seconds after setup