yohoho 0.1.0__tar.gz

yohoho-0.1.0/.gitignore

@@ -0,0 +1,56 @@
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+*.egg-info/
+build/
+dist/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# Node (install wrapper)
+node_modules/
+npm-debug.log*
+yarn-error.log*
+
+# Models & caches (downloaded at runtime, never committed)
+*.onnx
+models/
+.cache/
+.huggingface/
+
+# Env / secrets
+.env
+.env.*
+
+# Bundled fonts are tracked deliberately; ignore stray downloads
+*.ttf.download
+
+# OS cruft
+.DS_Store
+Thumbs.db
+desktop.ini
+
+# Claude local-only settings
+.claude/settings.local.json
+
+# yohoho runtime model cache (downloaded at runtime, never committed)
+hf/
+
+# brainstorming visual-companion artifacts
+.superpowers/
+
+# Private dev/process docs — excluded from the public repo (kept locally)
+/CLAUDE.md
+/.claude/
+/docs/superpowers/
+/docs/plans/
+/docs/specs/
+/docs/m4-followups.md
+/docs/HANDOFF.md
+/docs/README.md
+
+# Skills marketplace lockfile (harness artifact, not project content)
+skills-lock.json

yohoho-0.1.0/LICENSE

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

yohoho-0.1.0/PKG-INFO

@@ -0,0 +1,162 @@
+Metadata-Version: 2.4
+Name: yohoho
+Version: 0.1.0
+Summary: Free, fully-local voice dictation
+Project-URL: Homepage, https://github.com/by-k4n/yohoho
+Project-URL: Repository, https://github.com/by-k4n/yohoho
+Project-URL: Issues, https://github.com/by-k4n/yohoho/issues
+Author: by-k4n
+License: MIT
+License-File: LICENSE
+Keywords: dictation,local,macos,parakeet,privacy,speech-to-text,transcription,voice
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: MacOS X
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
+Classifier: Topic :: Utilities
+Requires-Python: <3.12,>=3.11
+Requires-Dist: numpy>=1.26
+Requires-Dist: onnx-asr[cpu,hub]>=0.6
+Requires-Dist: onnxruntime>=1.27
+Requires-Dist: pynput>=1.7
+Requires-Dist: pyobjc-framework-applicationservices>=10; sys_platform == 'darwin'
+Requires-Dist: pyobjc-framework-cocoa>=10; sys_platform == 'darwin'
+Requires-Dist: pyobjc-framework-quartz>=10; sys_platform == 'darwin'
+Requires-Dist: pywin32>=306; sys_platform == 'win32'
+Requires-Dist: pyyaml>=6
+Requires-Dist: sounddevice>=0.4.7
+Requires-Dist: soundfile>=0.12
+Requires-Dist: soxr>=0.5
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# yohoho
+
+> **speak. it types.** — free, fully-local voice dictation for developers.
+
+`yohoho` turns speech into text entirely on your machine. Hit a hotkey, talk, and an on-device model
+(NVIDIA Parakeet) transcribes your speech and pastes the text into whatever app is focused. No cloud,
+no API key, no subscription — your voice never leaves your laptop.
+
+It's a free, open-source alternative to Wispr Flow and VoiceInk, for people who'd rather own their
+tools than rent them. (The name is Brook's laugh from *One Piece* crossed with the "yo ho ho" shanty
+— a laugh is a voice, after all.)
+
+## Status
+
+**Working on macOS today.** Press the hotkey, speak, press again — your words transcribe on-device and
+paste at the cursor, with a live dot-matrix panel and on/off chimes. Windows and a one-line installer
+are next.
+
+| | |
+|---|---|
+| ✅ Working (macOS / Apple Silicon) | global hotkey, on-device transcription (Parakeet int8), live dot-matrix status panel, auto-paste, on/off chimes, run-on-login |
+| 🚧 Next | smoother permission setup, background-daemon supervisor, Windows adapter |
+
+## Install & set up (macOS)
+
+Install with whichever you have — each puts a `yohoho` command on your PATH:
+
+```bash
+npm i -g @by-k4n/yohoho    # Node users — bootstraps Python via uv under the hood
+uv tool install yohoho     # uv users
+pipx install yohoho        # pipx users
+```
+
+The **npm** install adds `yohoho` to your PATH automatically (it lands in npm's global bin) — open a
+new shell and you're set, no Python needed. With **uv** or **pipx**, if `yohoho` isn't found afterward,
+run `uv tool ensurepath` (or `pipx ensurepath`) once to add their bin directory, then restart your shell.
+
+Bleeding edge / no PyPI: `uv tool install 'git+https://github.com/by-k4n/yohoho.git@vX.Y.Z'`.
+
+Then:
+
+```bash
+yohoho setup     # pick a hotkey, grant permissions, download the model (~660 MB, first run)
+yohoho start     # press your hotkey anywhere to dictate
+yohoho config    # interactive settings menu — record a new hotkey, tweak chimes, and more
+```
+
+`setup` walks you through it, opens the right System Settings panes, and installs a launch-on-login
+agent so yohoho is ready whenever you are; the default hotkey is **⌃⌥Space** (Control-Option-Space).
+`start` runs the dictation loop in the foreground now (Ctrl-C to quit).
+
+**To dictate:** press **⌃⌥Space** (you'll hear the "on" chime), speak, then press **⌃⌥Space** again —
+the text transcribes on-device and pastes at your cursor (the "off" chime confirms it). Run
+`yohoho doctor` any time to check permissions and your hotkey.
+
+## Permissions (macOS) — please read
+
+macOS gates the hotkey and the paste behind three privacy permissions. **Grant them to the terminal
+app you launch yohoho from** — Terminal, iTerm, Warp, Ghostty, … — *not* to "python":
+
+| Permission | Why it's needed | System Settings ▸ Privacy & Security ▸ |
+|---|---|---|
+| **Microphone** | record your voice | Microphone |
+| **Input Monitoring** | detect the global hotkey | Input Monitoring |
+| **Accessibility** | paste into the focused app | Accessibility |
+
+> **Why your terminal, not python?** macOS attributes these grants to the *responsible process* — the
+> app that launched yohoho — which is your terminal, not the Python interpreter. `yohoho setup` opens
+> the right panes; add your terminal app under each one and toggle it on. If you later launch from a
+> *different* terminal, grant it there too.
+
+**Known rough edge:** if dictation transcribes but doesn't paste (you have to press ⌘V yourself), your
+terminal is missing **Accessibility** — add it there and restart the terminal. This terminal-by-terminal
+grant is the price of shipping as a dev script today; a future version will ship a small signed app so
+you grant once and forget it. For now, that's a known trade-off we've chosen on purpose.
+
+## Why
+
+- **Private** — audio is transcribed locally and never touches a server. Transcripts are never written
+  to logs, and history stays on your machine.
+- **Fast** — Parakeet runs several times faster than realtime on CPU; on Apple Silicon it offloads to
+  the Neural Engine via CoreML. Text lands in ~1–2 s for a short clip.
+- **Free** — MIT licensed. No subscription, ever.
+
+## Architecture
+
+A portable **core** (identical on every OS) sits behind six small platform-adapter contracts —
+hotkey · clipboard · inject · focus · autostart · permissions — the only OS-specific code, selected at
+runtime by `platform_factory`. Engine: NVIDIA Parakeet TDT 0.6b v2 (int8 ONNX) via `onnx-asr`. UI: a
+Tkinter dot-matrix panel. Output: clipboard paste (lossless, unlike per-key typing).
+
+The full design is in [`docs/DESIGN.md`](docs/DESIGN.md); the 149-case failure-mode matrix is in
+[`docs/edge-cases.md`](docs/edge-cases.md).
+
+## Roadmap
+
+- [x] **M1** — portable core (engine, recorder, controller, config, observability, history) + `yohoho dictate`
+- [x] **M2** — dot-matrix status panel (Tkinter)
+- [x] **M3** — macOS adapter: global hotkey, TCC permissions, auto-paste, on/off chimes, run-on-login
+- [x] **M4 (install)** — PyPI + npm wrapper install (this ship); daemon/signed-app/tray are later M4 pieces
+- [ ] **M4** — background-daemon supervisor, smoother permission flow (signed app), full `status`/`history`/`logs`
+- [ ] **M5** — Windows adapter
+- [ ] **M6** — standalone per-OS binaries
+
+Linux is on the map but deferred from v1; the adapter layer is kept Linux-ready.
+
+## Development
+
+```bash
+uv sync --extra dev
+uv run pytest                       # unit suite
+uv run pytest -m "gui or not gui"   # include the Tk panel tests
+uv run pytest -m integration        # real-model test (needs the model cached + tests/fixtures/hello.wav)
+uv run ruff check .
+```
+
+## Design
+
+Terminal / dot-matrix aesthetic — brand color `#39BFC6` on near-black,
+[Doto](https://fonts.google.com/specimen/Doto) wordmark, everything rendered in dots.
+
+## License
+
+MIT — see [LICENSE](LICENSE). If it saves you a subscription, buy yourself a coffee.

yohoho-0.1.0/README.md

@@ -0,0 +1,124 @@
+# yohoho
+
+> **speak. it types.** — free, fully-local voice dictation for developers.
+
+`yohoho` turns speech into text entirely on your machine. Hit a hotkey, talk, and an on-device model
+(NVIDIA Parakeet) transcribes your speech and pastes the text into whatever app is focused. No cloud,
+no API key, no subscription — your voice never leaves your laptop.
+
+It's a free, open-source alternative to Wispr Flow and VoiceInk, for people who'd rather own their
+tools than rent them. (The name is Brook's laugh from *One Piece* crossed with the "yo ho ho" shanty
+— a laugh is a voice, after all.)
+
+## Status
+
+**Working on macOS today.** Press the hotkey, speak, press again — your words transcribe on-device and
+paste at the cursor, with a live dot-matrix panel and on/off chimes. Windows and a one-line installer
+are next.
+
+| | |
+|---|---|
+| ✅ Working (macOS / Apple Silicon) | global hotkey, on-device transcription (Parakeet int8), live dot-matrix status panel, auto-paste, on/off chimes, run-on-login |
+| 🚧 Next | smoother permission setup, background-daemon supervisor, Windows adapter |
+
+## Install & set up (macOS)
+
+Install with whichever you have — each puts a `yohoho` command on your PATH:
+
+```bash
+npm i -g @by-k4n/yohoho    # Node users — bootstraps Python via uv under the hood
+uv tool install yohoho     # uv users
+pipx install yohoho        # pipx users
+```
+
+The **npm** install adds `yohoho` to your PATH automatically (it lands in npm's global bin) — open a
+new shell and you're set, no Python needed. With **uv** or **pipx**, if `yohoho` isn't found afterward,
+run `uv tool ensurepath` (or `pipx ensurepath`) once to add their bin directory, then restart your shell.
+
+Bleeding edge / no PyPI: `uv tool install 'git+https://github.com/by-k4n/yohoho.git@vX.Y.Z'`.
+
+Then:
+
+```bash
+yohoho setup     # pick a hotkey, grant permissions, download the model (~660 MB, first run)
+yohoho start     # press your hotkey anywhere to dictate
+yohoho config    # interactive settings menu — record a new hotkey, tweak chimes, and more
+```
+
+`setup` walks you through it, opens the right System Settings panes, and installs a launch-on-login
+agent so yohoho is ready whenever you are; the default hotkey is **⌃⌥Space** (Control-Option-Space).
+`start` runs the dictation loop in the foreground now (Ctrl-C to quit).
+
+**To dictate:** press **⌃⌥Space** (you'll hear the "on" chime), speak, then press **⌃⌥Space** again —
+the text transcribes on-device and pastes at your cursor (the "off" chime confirms it). Run
+`yohoho doctor` any time to check permissions and your hotkey.
+
+## Permissions (macOS) — please read
+
+macOS gates the hotkey and the paste behind three privacy permissions. **Grant them to the terminal
+app you launch yohoho from** — Terminal, iTerm, Warp, Ghostty, … — *not* to "python":
+
+| Permission | Why it's needed | System Settings ▸ Privacy & Security ▸ |
+|---|---|---|
+| **Microphone** | record your voice | Microphone |
+| **Input Monitoring** | detect the global hotkey | Input Monitoring |
+| **Accessibility** | paste into the focused app | Accessibility |
+
+> **Why your terminal, not python?** macOS attributes these grants to the *responsible process* — the
+> app that launched yohoho — which is your terminal, not the Python interpreter. `yohoho setup` opens
+> the right panes; add your terminal app under each one and toggle it on. If you later launch from a
+> *different* terminal, grant it there too.
+
+**Known rough edge:** if dictation transcribes but doesn't paste (you have to press ⌘V yourself), your
+terminal is missing **Accessibility** — add it there and restart the terminal. This terminal-by-terminal
+grant is the price of shipping as a dev script today; a future version will ship a small signed app so
+you grant once and forget it. For now, that's a known trade-off we've chosen on purpose.
+
+## Why
+
+- **Private** — audio is transcribed locally and never touches a server. Transcripts are never written
+  to logs, and history stays on your machine.
+- **Fast** — Parakeet runs several times faster than realtime on CPU; on Apple Silicon it offloads to
+  the Neural Engine via CoreML. Text lands in ~1–2 s for a short clip.
+- **Free** — MIT licensed. No subscription, ever.
+
+## Architecture
+
+A portable **core** (identical on every OS) sits behind six small platform-adapter contracts —
+hotkey · clipboard · inject · focus · autostart · permissions — the only OS-specific code, selected at
+runtime by `platform_factory`. Engine: NVIDIA Parakeet TDT 0.6b v2 (int8 ONNX) via `onnx-asr`. UI: a
+Tkinter dot-matrix panel. Output: clipboard paste (lossless, unlike per-key typing).
+
+The full design is in [`docs/DESIGN.md`](docs/DESIGN.md); the 149-case failure-mode matrix is in
+[`docs/edge-cases.md`](docs/edge-cases.md).
+
+## Roadmap
+
+- [x] **M1** — portable core (engine, recorder, controller, config, observability, history) + `yohoho dictate`
+- [x] **M2** — dot-matrix status panel (Tkinter)
+- [x] **M3** — macOS adapter: global hotkey, TCC permissions, auto-paste, on/off chimes, run-on-login
+- [x] **M4 (install)** — PyPI + npm wrapper install (this ship); daemon/signed-app/tray are later M4 pieces
+- [ ] **M4** — background-daemon supervisor, smoother permission flow (signed app), full `status`/`history`/`logs`
+- [ ] **M5** — Windows adapter
+- [ ] **M6** — standalone per-OS binaries
+
+Linux is on the map but deferred from v1; the adapter layer is kept Linux-ready.
+
+## Development
+
+```bash
+uv sync --extra dev
+uv run pytest                       # unit suite
+uv run pytest -m "gui or not gui"   # include the Tk panel tests
+uv run pytest -m integration        # real-model test (needs the model cached + tests/fixtures/hello.wav)
+uv run ruff check .
+```
+
+## Design
+
+Terminal / dot-matrix aesthetic — brand color `#39BFC6` on near-black,
+[Doto](https://fonts.google.com/specimen/Doto) wordmark, everything rendered in dots.
+
+## License
+
+MIT — see [LICENSE](LICENSE). If it saves you a subscription, buy yourself a coffee.

yohoho-0.1.0/pyproject.toml

@@ -0,0 +1,75 @@
+[project]
+name = "yohoho"
+version = "0.1.0"
+description = "Free, fully-local voice dictation"
+requires-python = ">=3.11,<3.12"
+dependencies = [
+  "onnx-asr[cpu,hub]>=0.6",
+  "onnxruntime>=1.27",
+  "sounddevice>=0.4.7",
+  "soundfile>=0.12",
+  "soxr>=0.5",
+  "numpy>=1.26",
+  "pyyaml>=6",
+  "pyobjc-framework-Cocoa>=10 ; sys_platform == 'darwin'",
+  "pyobjc-framework-Quartz>=10 ; sys_platform == 'darwin'",
+  "pyobjc-framework-ApplicationServices>=10 ; sys_platform == 'darwin'",
+  "pynput>=1.7",
+  "pywin32>=306 ; sys_platform == 'win32'",
+]
+readme = "README.md"
+license = { text = "MIT" }
+authors = [{ name = "by-k4n" }]
+keywords = ["dictation", "speech-to-text", "voice", "transcription", "parakeet", "local", "privacy", "macos"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: MacOS X",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: MacOS :: MacOS X",
+  "Operating System :: Microsoft :: Windows",
+  "Programming Language :: Python :: 3.11",
+  "Topic :: Multimedia :: Sound/Audio :: Speech",
+  "Topic :: Utilities",
+]
+
+[project.urls]
+Homepage = "https://github.com/by-k4n/yohoho"
+Repository = "https://github.com/by-k4n/yohoho"
+Issues = "https://github.com/by-k4n/yohoho/issues"
+
+[project.scripts]
+yohoho = "yohoho.core.cli:main"
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "ruff>=0.6"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/yohoho"]
+
+[tool.hatch.build.targets.sdist]
+# Lean source distribution: only the importable code + user-facing README/LICENSE/
+# pyproject. Excludes docs/ (design + planning notes), CLAUDE.md, .claude/, tests/
+# (incl. fixtures), packaging/, RELEASING.md — none belong in the installable package.
+include = [
+  "/src/yohoho",
+  "/README.md",
+  "/LICENSE",
+  "/pyproject.toml",
+]
+
+[tool.pytest.ini_options]
+pythonpath = ["src", "."]
+markers = [
+  "integration: loads the real model / touches real audio devices (slow)",
+  "gui: real-Tk smoke tests; need a windowing server (skipped headless)",
+]
+addopts = "-m 'not integration and not gui'"
+
+[tool.ruff]
+line-length = 100
+src = ["src", "tests"]

yohoho-0.1.0/src/yohoho/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.0.1"

yohoho-0.1.0/src/yohoho/__main__.py

@@ -0,0 +1,4 @@
+"""Enables `python -m yohoho ...` (used by the LaunchAgent's ProgramArguments)."""
+import sys
+from yohoho.core.cli import main
+sys.exit(main())

yohoho-0.1.0/src/yohoho/core/audio.py

@@ -0,0 +1,42 @@
+"""Pure DSP helpers — no device I/O, fully testable in isolation.
+
+Functions:
+  resample_to_16k  — downsample arbitrary-rate mono audio to 16 kHz (soxr)
+  rms              — root-mean-square amplitude of a float32 array
+  is_silent        — resilience P2 silence guard: rms(x) < floor
+"""
+
+import numpy as np
+import soxr
+
+_TARGET_SR = 16000
+_SILENCE_FLOOR = 0.003
+
+
+def resample_to_16k(x: np.ndarray, sr: int) -> np.ndarray:
+    """Return mono float32 audio resampled to 16 kHz.
+
+    If *sr* is already 16000 the array is returned unchanged (zero-copy passthrough).
+    Built-in / Bluetooth mics are typically 44.1 or 48 kHz; skipping this step feeds
+    the model confident garbage that passes the silence guard.
+    """
+    if sr == _TARGET_SR:
+        return x
+    out = soxr.resample(x, sr, _TARGET_SR, quality="HQ")
+    return out.astype(np.float32, copy=False)
+
+
+def rms(x: np.ndarray) -> float:
+    """Root-mean-square of *x*.  Returns 0.0 for empty input."""
+    if x.size == 0:
+        return 0.0
+    return float(np.sqrt(np.mean(x.astype(np.float64) ** 2)))
+
+
+def is_silent(x: np.ndarray, floor: float = _SILENCE_FLOOR) -> bool:
+    """Return True when the clip is below *floor* RMS (i.e. silence / no speech).
+
+    Used by the controller before calling recognize() so an empty or background-noise
+    clip never reaches the model (resilience primitive P2).
+    """
+    return rms(x) < floor