ollama-speak 1.1.0__tar.gz

ollama_speak-1.1.0/.github/workflows/release.yml

@@ -0,0 +1,31 @@
+name: Build, Package & Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  build-pypi:
+    name: Build & Publish to PyPI
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+      - name: Install build tools
+        run: pip install --upgrade build twine
+      - name: Build wheel and sdist
+        run: python -m build
+      - name: Publish to PyPI
+        if: startsWith(github.ref, 'refs/tags/v')
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
+        run: twine upload --skip-existing dist/*

ollama_speak-1.1.0/.gitignore

@@ -0,0 +1,29 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+.git/

ollama_speak-1.1.0/LICENSE

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

ollama_speak-1.1.0/PKG-INFO

@@ -0,0 +1,230 @@
+Metadata-Version: 2.5
+Name: ollama-speak
+Version: 1.1.0
+Summary: 100% Local, Offline Multilingual Neural Text-to-Speech CLI for Ollama (Kokoro-82M & Piper).
+Project-URL: Homepage, https://github.com/AjarnSpencer/ollama-speak
+Project-URL: Repository, https://github.com/AjarnSpencer/ollama-speak
+Project-URL: Issues, https://github.com/AjarnSpencer/ollama-speak/issues
+Author-email: Ajarn Spencer Littlewood <ajarnspencer@gmail.com>
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.9
+Requires-Dist: kokoro>=0.8.4
+Requires-Dist: numpy>=1.21.0
+Requires-Dist: soundfile>=0.12.0
+Provides-Extra: all
+Requires-Dist: kokoro>=0.8.4; extra == 'all'
+Requires-Dist: piper-tts>=1.2.0; extra == 'all'
+Requires-Dist: soundfile>=0.12.0; extra == 'all'
+Provides-Extra: piper
+Requires-Dist: piper-tts>=1.2.0; extra == 'piper'
+Description-Content-Type: text/markdown
+
+# 🗣️ ollama-speak (`ospeak`)
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/)
+[![Ollama](https://img.shields.io/badge/Ollama-Local%20AI-orange.svg)](https://ollama.ai/)
+[![100% Local AI](https://img.shields.io/badge/Privacy-100%25%20Offline%20Local-success.svg)](#100-offline-and-sovereign-guarantee)
+
+> **100% Local, Offline Multilingual Neural Text-to-Speech CLI for Ollama (Kokoro-82M and Piper ONNX).**
+
+`ollama-speak` (`ospeak`) is a standalone, sovereign voice engine built specifically for the local AI and Ollama community. It runs **100% locally on your own machine** using open-weights models:
+
+- **Kokoro-82M (Default):** Apache 2.0 open-weight 82M-parameter neural model providing studio-grade broadcast speech.
+- **Piper TTS (Ultra-lightweight):** Fast ONNX neural voice engine designed to run with sub-100ms latency even on low-spec hardware or a Raspberry Pi.
+
+Zero cloud API calls, zero telemetry, zero corporate tracking, and zero accounts. Once local weights are downloaded, `ollama-speak` works completely with your internet disconnected.
+
+---
+
+## 💻 Minimum System and Hardware Requirements
+
+`ollama-speak` is designed to run smoothly across consumer laptops, older desktop PCs, MacBooks, and high-performance workstations.
+
+### Hardware Requirements Table
+
+| Component | Piper ONNX (Ultra-Lightweight) | Kokoro-82M (Studio Quality Default) |
+| :--- | :--- | :--- |
+| **CPU** | Any 64-bit CPU (Intel, AMD, ARM64 / Apple Silicon, Raspberry Pi 4/5) | Modern multi-core CPU (AVX2 recommended) or Apple Silicon M1–M4 |
+| **GPU (Optional)** | Not needed (pure CPU ONNX) | Accelerated on CUDA / ROCm / Metal, runs easily on CPU |
+| **System RAM** | **1 GB minimum** (uses ~80 MB during inference) | **2 GB to 4 GB RAM** (uses ~350 MB during inference) |
+| **Disk Space** | **~35 MB** for voice model | **~350 MB** for open-weight model checkpoint |
+| **Audio System** | Standard OS sound (ALSA, PulseAudio, PipeWire, CoreAudio, WASAPI) | Standard OS sound |
+| **Internet** | Only required once for initial model download | Only required once for initial model download |
+
+### Supported Operating Systems
+
+- **Linux:** Ubuntu 20.04+, Debian 11+, Fedora 38+, Arch Linux, DGX OS (x86_64 and ARM64).
+- **macOS:** macOS 11 (Big Sur) and newer (Intel and Apple Silicon M1/M2/M3/M4). Uses native `afplay`.
+- **Windows:** Windows 10 & 11 (64-bit). Uses native PowerShell / System.Media audio backend.
+
+---
+
+## ✨ Features
+
+- **100% Sovereign and Offline:** No queries leave your computer. Never sends your text to Microsoft, Google, Bing, or any remote server.
+- **Dual Local Engine Architecture:**
+  - **Kokoro-82M:** Deeply expressive, human-like voice with natural breath pacing and emotional cadence.
+  - **Piper ONNX:** Blazing fast sub-100ms latency for real-time voice assistants.
+- **Self-Contained Model Downloader:** Run `ollama-speak --setup` to pre-download open weights once, or let it fetch them on first run. Once cached, it runs offline indefinitely.
+- **Zero-Swallow Pipe Echo:** When piping text from any command (`ollama run llama3 "..." | ollama-speak`), it mirrors text directly to your terminal so your transcript remains visible and copy-pasteable.
+- **Zero-Flag Pairing with `ollama-web`:** Simply run `ollama-web "your question"`. The text streams live to your terminal while local voice speaks the answer automatically.
+- **Native Cross-Platform Playback:** Automatically utilizes local audio players (`pw-play`, `paplay`, `mpv`, `ffplay`, `afplay` on macOS, PowerShell on Windows).
+
+---
+
+## 🚀 Installation
+
+### Option 1 (Recommended) — One-Line Turnkey Installer
+Works automatically on fresh Linux, macOS, and WSL systems without requiring manual virtual environments or encountering PEP 668 system python locks.
+
+**Linux and macOS:**
+```bash
+curl -fsSL https://raw.githubusercontent.com/AjarnSpencer/ollama-speak/main/install.sh | bash
+```
+
+**Windows (PowerShell):**
+```powershell
+irm https://raw.githubusercontent.com/AjarnSpencer/ollama-speak/main/install.ps1 | iex
+```
+
+What the turnkey installer does:
+- Sets up an isolated virtual environment in `~/.local/share/ollama-speak/venv` (zero system pollution).
+- Symlinks `ollama-speak` and `ospeak` launchers into `~/.local/bin/`.
+- Configures user `PATH` if not already set.
+- Automatically pre-downloads local model weights so it works offline immediately.
+
+---
+
+### Option 2 — Install from GitHub with pipx or pip
+If you prefer managing Python CLI tools via `pipx` (recommended by Python Packaging Authority for standalone tools) or an active virtual environment:
+
+**Using pipx (Recommended for Python users):**
+```bash
+pipx install git+https://github.com/AjarnSpencer/ollama-speak.git
+```
+
+**Using pip in a virtual environment:**
+```bash
+pip install git+https://github.com/AjarnSpencer/ollama-speak.git
+```
+
+---
+
+### Option 3 — Clone and Install Locally
+```bash
+git clone https://github.com/AjarnSpencer/ollama-speak.git
+cd ollama-speak
+./install.sh
+```
+
+---
+
+### Pre-Download Local Models for 100% Offline Use
+```bash
+ollama-speak --setup
+```
+This downloads and caches the Kokoro-82M and Piper open weights into your local user directory. After this step, you can disconnect your computer from the internet completely.
+
+---
+
+### 📦 Publishing to PyPI (For Maintainers)
+To unlock global installation via `pip install ollama-speak` worldwide:
+1. Build distributions: `python3 -m build` (generates wheels and tarballs in `dist/`).
+2. Upload to PyPI: `twine upload dist/*` with your PyPI token.
+Once published, users can install directly via `pip install --upgrade ollama-speak`.
+
+---
+
+## 📖 Command Line Reference and Flags
+
+`ollama-speak` can be invoked as either `ollama-speak` or `ospeak`.
+
+| Flag | Short | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `text` | | STDIN | Text string to speak aloud (reads from STDIN pipe if omitted) |
+| `--engine ENGINE` | `-e` | `kokoro` | Local TTS engine: `kokoro` (studio quality) or `piper` (ultra-fast ONNX) |
+| `--kokoro` | | | Shortcut for `--engine kokoro` |
+| `--piper` | | | Shortcut for `--engine piper` |
+| `--voice VOICE` | `-v` | `bm_george` | Select specific local voice (e.g. `bm_george`, `af_heart`, `bf_alice`) |
+| `--output FILE` | `-o` | `None` | Save spoken audio to a local WAV/MP3 file instead of playing |
+| `--setup` | `--download-models` | | Pre-download all local weights for 100% offline use |
+| `--list-voices` | | | List all available local open-weight voices and aliases |
+| `-h`, `--help` | | | Show full help manual and flags |
+
+---
+
+## 🎙️ Supported Local Open-Weight Voices
+
+Run `ollama-speak --list-voices` to see all local voices:
+
+| Voice Name | Language | Gender / Style | Engine |
+| :--- | :--- | :--- | :--- |
+| **`bm_george` (Default)** | British English | Male (Warm Baritone) | Kokoro-82M |
+| **`bm_lewis`** | British English | Male | Kokoro-82M |
+| **`bf_alice`** | British English | Female | Kokoro-82M |
+| **`af_heart`** | American English | Female (Warm) | Kokoro-82M |
+| **`am_adam`** | American English | Male | Kokoro-82M |
+| **`jf_tebukuro`** | Japanese | Female | Kokoro-82M |
+| **`zf_xiaobei`** | Mandarin Chinese | Female | Kokoro-82M |
+| **`ef_dora`** | Spanish | Female | Kokoro-82M |
+| **`ff_siwis`** | French | Female | Kokoro-82M |
+| **`if_sara`** | Italian | Female | Kokoro-82M |
+| **`pf_dora`** | Portuguese | Female | Kokoro-82M |
+| **`hf_alpha`** | Hindi | Female | Kokoro-82M |
+| **`piper`** | British English | Clear / Fast ONNX | Piper |
+
+---
+
+## 💡 Practical Tutorials and Workflows
+
+### Tutorial 1 — Direct Local Text Narration
+Speak any text locally using your default Kokoro voice:
+```bash
+ollama-speak "All local systems are operational and running completely offline."
+```
+
+### Tutorial 2 — Zero-Swallow Piped Input from Local Ollama
+Pipe output from any local Ollama model directly into `ollama-speak`. The text prints on screen in real-time, and local voice speaks the answer:
+```bash
+ollama run llama3 "Explain quantum computing in two sentences" | ollama-speak
+```
+
+### Tutorial 3 — Fast Piper ONNX for Low-Spec PCs
+If you are running on a Raspberry Pi or low-spec laptop, pass `--piper` for ultra-fast, lightweight inference:
+```bash
+ollama run llama3 "Give me one piece of life advice" | ollama-speak --piper
+```
+
+### Tutorial 4 — Changing Local Voices
+Choose between different genders, accents, and languages:
+```bash
+# American Female (Kokoro-82M):
+ollama-speak -v af_heart "Welcome to the future of sovereign, local artificial intelligence."
+
+# British Female (Kokoro-82M):
+ollama-speak -v bf_alice "It is a pleasure to assist you today."
+```
+
+### Tutorial 5 — Exporting Audio to File
+Save the synthesized speech directly to a standard audio file:
+```bash
+ollama-speak -o ~/Music/summary.wav "Your daily briefing has been saved locally."
+```
+
+---
+
+## 🔒 100% Offline and Sovereign Guarantee
+
+- **No Remote Servers:** Text is synthesized entirely inside your computer's RAM using open-weights models.
+- **No Cloud Fallbacks:** It will never silently phone home to Microsoft, Bing, Google, or any cloud API.
+- **No API Keys or Subscriptions:** You own your hardware, and you own your voice assistant.
+
+---
+
+## 📄 License
+
+This project is licensed under the [MIT License](LICENSE).
+Kokoro-82M model weights are released under the [Apache 2.0 License](https://huggingface.co/hexgrad/Kokoro-82M).
+Piper TTS is released under the [MIT License](https://github.com/rhasspy/piper).

ollama_speak-1.1.0/README.md

@@ -0,0 +1,208 @@
+# 🗣️ ollama-speak (`ospeak`)
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/)
+[![Ollama](https://img.shields.io/badge/Ollama-Local%20AI-orange.svg)](https://ollama.ai/)
+[![100% Local AI](https://img.shields.io/badge/Privacy-100%25%20Offline%20Local-success.svg)](#100-offline-and-sovereign-guarantee)
+
+> **100% Local, Offline Multilingual Neural Text-to-Speech CLI for Ollama (Kokoro-82M and Piper ONNX).**
+
+`ollama-speak` (`ospeak`) is a standalone, sovereign voice engine built specifically for the local AI and Ollama community. It runs **100% locally on your own machine** using open-weights models:
+
+- **Kokoro-82M (Default):** Apache 2.0 open-weight 82M-parameter neural model providing studio-grade broadcast speech.
+- **Piper TTS (Ultra-lightweight):** Fast ONNX neural voice engine designed to run with sub-100ms latency even on low-spec hardware or a Raspberry Pi.
+
+Zero cloud API calls, zero telemetry, zero corporate tracking, and zero accounts. Once local weights are downloaded, `ollama-speak` works completely with your internet disconnected.
+
+---
+
+## 💻 Minimum System and Hardware Requirements
+
+`ollama-speak` is designed to run smoothly across consumer laptops, older desktop PCs, MacBooks, and high-performance workstations.
+
+### Hardware Requirements Table
+
+| Component | Piper ONNX (Ultra-Lightweight) | Kokoro-82M (Studio Quality Default) |
+| :--- | :--- | :--- |
+| **CPU** | Any 64-bit CPU (Intel, AMD, ARM64 / Apple Silicon, Raspberry Pi 4/5) | Modern multi-core CPU (AVX2 recommended) or Apple Silicon M1–M4 |
+| **GPU (Optional)** | Not needed (pure CPU ONNX) | Accelerated on CUDA / ROCm / Metal, runs easily on CPU |
+| **System RAM** | **1 GB minimum** (uses ~80 MB during inference) | **2 GB to 4 GB RAM** (uses ~350 MB during inference) |
+| **Disk Space** | **~35 MB** for voice model | **~350 MB** for open-weight model checkpoint |
+| **Audio System** | Standard OS sound (ALSA, PulseAudio, PipeWire, CoreAudio, WASAPI) | Standard OS sound |
+| **Internet** | Only required once for initial model download | Only required once for initial model download |
+
+### Supported Operating Systems
+
+- **Linux:** Ubuntu 20.04+, Debian 11+, Fedora 38+, Arch Linux, DGX OS (x86_64 and ARM64).
+- **macOS:** macOS 11 (Big Sur) and newer (Intel and Apple Silicon M1/M2/M3/M4). Uses native `afplay`.
+- **Windows:** Windows 10 & 11 (64-bit). Uses native PowerShell / System.Media audio backend.
+
+---
+
+## ✨ Features
+
+- **100% Sovereign and Offline:** No queries leave your computer. Never sends your text to Microsoft, Google, Bing, or any remote server.
+- **Dual Local Engine Architecture:**
+  - **Kokoro-82M:** Deeply expressive, human-like voice with natural breath pacing and emotional cadence.
+  - **Piper ONNX:** Blazing fast sub-100ms latency for real-time voice assistants.
+- **Self-Contained Model Downloader:** Run `ollama-speak --setup` to pre-download open weights once, or let it fetch them on first run. Once cached, it runs offline indefinitely.
+- **Zero-Swallow Pipe Echo:** When piping text from any command (`ollama run llama3 "..." | ollama-speak`), it mirrors text directly to your terminal so your transcript remains visible and copy-pasteable.
+- **Zero-Flag Pairing with `ollama-web`:** Simply run `ollama-web "your question"`. The text streams live to your terminal while local voice speaks the answer automatically.
+- **Native Cross-Platform Playback:** Automatically utilizes local audio players (`pw-play`, `paplay`, `mpv`, `ffplay`, `afplay` on macOS, PowerShell on Windows).
+
+---
+
+## 🚀 Installation
+
+### Option 1 (Recommended) — One-Line Turnkey Installer
+Works automatically on fresh Linux, macOS, and WSL systems without requiring manual virtual environments or encountering PEP 668 system python locks.
+
+**Linux and macOS:**
+```bash
+curl -fsSL https://raw.githubusercontent.com/AjarnSpencer/ollama-speak/main/install.sh | bash
+```
+
+**Windows (PowerShell):**
+```powershell
+irm https://raw.githubusercontent.com/AjarnSpencer/ollama-speak/main/install.ps1 | iex
+```
+
+What the turnkey installer does:
+- Sets up an isolated virtual environment in `~/.local/share/ollama-speak/venv` (zero system pollution).
+- Symlinks `ollama-speak` and `ospeak` launchers into `~/.local/bin/`.
+- Configures user `PATH` if not already set.
+- Automatically pre-downloads local model weights so it works offline immediately.
+
+---
+
+### Option 2 — Install from GitHub with pipx or pip
+If you prefer managing Python CLI tools via `pipx` (recommended by Python Packaging Authority for standalone tools) or an active virtual environment:
+
+**Using pipx (Recommended for Python users):**
+```bash
+pipx install git+https://github.com/AjarnSpencer/ollama-speak.git
+```
+
+**Using pip in a virtual environment:**
+```bash
+pip install git+https://github.com/AjarnSpencer/ollama-speak.git
+```
+
+---
+
+### Option 3 — Clone and Install Locally
+```bash
+git clone https://github.com/AjarnSpencer/ollama-speak.git
+cd ollama-speak
+./install.sh
+```
+
+---
+
+### Pre-Download Local Models for 100% Offline Use
+```bash
+ollama-speak --setup
+```
+This downloads and caches the Kokoro-82M and Piper open weights into your local user directory. After this step, you can disconnect your computer from the internet completely.
+
+---
+
+### 📦 Publishing to PyPI (For Maintainers)
+To unlock global installation via `pip install ollama-speak` worldwide:
+1. Build distributions: `python3 -m build` (generates wheels and tarballs in `dist/`).
+2. Upload to PyPI: `twine upload dist/*` with your PyPI token.
+Once published, users can install directly via `pip install --upgrade ollama-speak`.
+
+---
+
+## 📖 Command Line Reference and Flags
+
+`ollama-speak` can be invoked as either `ollama-speak` or `ospeak`.
+
+| Flag | Short | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `text` | | STDIN | Text string to speak aloud (reads from STDIN pipe if omitted) |
+| `--engine ENGINE` | `-e` | `kokoro` | Local TTS engine: `kokoro` (studio quality) or `piper` (ultra-fast ONNX) |
+| `--kokoro` | | | Shortcut for `--engine kokoro` |
+| `--piper` | | | Shortcut for `--engine piper` |
+| `--voice VOICE` | `-v` | `bm_george` | Select specific local voice (e.g. `bm_george`, `af_heart`, `bf_alice`) |
+| `--output FILE` | `-o` | `None` | Save spoken audio to a local WAV/MP3 file instead of playing |
+| `--setup` | `--download-models` | | Pre-download all local weights for 100% offline use |
+| `--list-voices` | | | List all available local open-weight voices and aliases |
+| `-h`, `--help` | | | Show full help manual and flags |
+
+---
+
+## 🎙️ Supported Local Open-Weight Voices
+
+Run `ollama-speak --list-voices` to see all local voices:
+
+| Voice Name | Language | Gender / Style | Engine |
+| :--- | :--- | :--- | :--- |
+| **`bm_george` (Default)** | British English | Male (Warm Baritone) | Kokoro-82M |
+| **`bm_lewis`** | British English | Male | Kokoro-82M |
+| **`bf_alice`** | British English | Female | Kokoro-82M |
+| **`af_heart`** | American English | Female (Warm) | Kokoro-82M |
+| **`am_adam`** | American English | Male | Kokoro-82M |
+| **`jf_tebukuro`** | Japanese | Female | Kokoro-82M |
+| **`zf_xiaobei`** | Mandarin Chinese | Female | Kokoro-82M |
+| **`ef_dora`** | Spanish | Female | Kokoro-82M |
+| **`ff_siwis`** | French | Female | Kokoro-82M |
+| **`if_sara`** | Italian | Female | Kokoro-82M |
+| **`pf_dora`** | Portuguese | Female | Kokoro-82M |
+| **`hf_alpha`** | Hindi | Female | Kokoro-82M |
+| **`piper`** | British English | Clear / Fast ONNX | Piper |
+
+---
+
+## 💡 Practical Tutorials and Workflows
+
+### Tutorial 1 — Direct Local Text Narration
+Speak any text locally using your default Kokoro voice:
+```bash
+ollama-speak "All local systems are operational and running completely offline."
+```
+
+### Tutorial 2 — Zero-Swallow Piped Input from Local Ollama
+Pipe output from any local Ollama model directly into `ollama-speak`. The text prints on screen in real-time, and local voice speaks the answer:
+```bash
+ollama run llama3 "Explain quantum computing in two sentences" | ollama-speak
+```
+
+### Tutorial 3 — Fast Piper ONNX for Low-Spec PCs
+If you are running on a Raspberry Pi or low-spec laptop, pass `--piper` for ultra-fast, lightweight inference:
+```bash
+ollama run llama3 "Give me one piece of life advice" | ollama-speak --piper
+```
+
+### Tutorial 4 — Changing Local Voices
+Choose between different genders, accents, and languages:
+```bash
+# American Female (Kokoro-82M):
+ollama-speak -v af_heart "Welcome to the future of sovereign, local artificial intelligence."
+
+# British Female (Kokoro-82M):
+ollama-speak -v bf_alice "It is a pleasure to assist you today."
+```
+
+### Tutorial 5 — Exporting Audio to File
+Save the synthesized speech directly to a standard audio file:
+```bash
+ollama-speak -o ~/Music/summary.wav "Your daily briefing has been saved locally."
+```
+
+---
+
+## 🔒 100% Offline and Sovereign Guarantee
+
+- **No Remote Servers:** Text is synthesized entirely inside your computer's RAM using open-weights models.
+- **No Cloud Fallbacks:** It will never silently phone home to Microsoft, Bing, Google, or any cloud API.
+- **No API Keys or Subscriptions:** You own your hardware, and you own your voice assistant.
+
+---
+
+## 📄 License
+
+This project is licensed under the [MIT License](LICENSE).
+Kokoro-82M model weights are released under the [Apache 2.0 License](https://huggingface.co/hexgrad/Kokoro-82M).
+Piper TTS is released under the [MIT License](https://github.com/rhasspy/piper).

ollama_speak-1.1.0/install.ps1

@@ -0,0 +1,65 @@
+# ollama-speak turnkey isolated installer for Windows PowerShell
+# 100% Local Neural Voice CLI (Kokoro-82M and Piper ONNX)
+$ErrorActionPreference = "Stop"
+
+Write-Host "==================================================" -ForegroundColor Cyan
+Write-Host " 🗣️ Installing ollama-speak for Windows (Isolated)" -ForegroundColor Cyan
+Write-Host "==================================================" -ForegroundColor Cyan
+
+# 1. Detect Python
+$pythonCmd = Get-Command python -ErrorAction SilentlyContinue
+if (-not $pythonCmd) {
+    $pythonCmd = Get-Command py -ErrorAction SilentlyContinue
+}
+
+if (-not $pythonCmd) {
+    Write-Host "[!] Error: Python 3.9+ was not found on your system PATH." -ForegroundColor Red
+    Write-Host "Please install Python from https://www.python.org/ (ensure 'Add Python to PATH' is checked)." -ForegroundColor Yellow
+    exit 1
+}
+
+$InstallDir = Join-Path $env:LOCALAPPDATA "ollama-speak"
+$VenvDir = Join-Path $InstallDir "venv"
+$VenvPython = Join-Path $VenvDir "Scripts\python.exe"
+$VenvPip = Join-Path $VenvDir "Scripts\pip.exe"
+$VenvScripts = Join-Path $VenvDir "Scripts"
+
+# 2. Create isolated venv
+Write-Host "→ Creating isolated virtual environment in $VenvDir..." -ForegroundColor Green
+if (-not (Test-Path $VenvDir)) {
+    & $pythonCmd.Source -m venv $VenvDir
+}
+
+# 3. Upgrade pip and install package
+Write-Host "→ Installing dependencies in isolated environment..." -ForegroundColor Green
+& $VenvPip install --quiet --upgrade pip wheel setuptools
+
+$ScriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path
+if (Test-Path (Join-Path $ScriptDir "pyproject.toml")) {
+    Write-Host "→ Installing from local directory ($ScriptDir)..." -ForegroundColor Green
+    & $VenvPip install --upgrade $ScriptDir
+} else {
+    Write-Host "→ Installing from GitHub..." -ForegroundColor Green
+    & $VenvPip install --upgrade "git+https://github.com/AjarnSpencer/ollama-speak.git"
+}
+
+# 4. Add Scripts to User PATH
+$UserPath = [Environment]::GetEnvironmentVariable("Path", [EnvironmentVariableTarget]::User)
+if ($UserPath -notlike "*$VenvScripts*") {
+    Write-Host "→ Adding $VenvScripts to User PATH..." -ForegroundColor Green
+    [Environment]::SetEnvironmentVariable("Path", "$UserPath;$VenvScripts", [EnvironmentVariableTarget]::User)
+    $env:Path = "$env:Path;$VenvScripts"
+}
+
+# 5. Pre-download open weights
+$OllamaSpeakExe = Join-Path $VenvScripts "ollama-speak.exe"
+if (Test-Path $OllamaSpeakExe) {
+    Write-Host "→ Pre-downloading open weights for 100% offline use..." -ForegroundColor Green
+    & $OllamaSpeakExe --setup
+}
+
+Write-Host "==================================================" -ForegroundColor Cyan
+Write-Host " ✓ Installation complete!" -ForegroundColor Green
+Write-Host " Run: 'ollama-speak ""Hello from local voice""'" -ForegroundColor White
+Write-Host " Or shortcut: 'ospeak ""Fast voice""'" -ForegroundColor White
+Write-Host "==================================================" -ForegroundColor Cyan

ollama_speak-1.1.0/install.sh

@@ -0,0 +1,118 @@
+#!/usr/bin/env bash
+# ollama-speak turnkey isolated installer for Linux and macOS
+# 100% Local Neural Voice CLI (Kokoro-82M and Piper ONNX)
+set -e
+
+APP_NAME="ollama-speak"
+INSTALL_DIR="${HOME}/.local/share/${APP_NAME}"
+BIN_DIR="${HOME}/.local/bin"
+REPO_URL="https://github.com/AjarnSpencer/ollama-speak.git"
+
+echo "=================================================="
+echo " 🗣️ Installing ${APP_NAME} (Local Neural Voice CLI)"
+echo "=================================================="
+
+# 1. Detect Python 3.9+
+if command -v python3 >/dev/null 2>&1; then
+    PY_SYSTEM="python3"
+elif command -v python >/dev/null 2>&1; then
+    PY_SYSTEM="python"
+else
+    echo "❌ Error: Python 3.9+ is required but not installed." >&2
+    echo "   Ubuntu/Debian: sudo apt update && sudo apt install -y python3 python3-venv python3-pip" >&2
+    echo "   Fedora/RHEL:   sudo dnf install -y python3" >&2
+    echo "   macOS:         brew install python" >&2
+    exit 1
+fi
+
+# Verify Python version >= 3.9
+PY_VER=$($PY_SYSTEM -c "import sys; print(f'{sys.version_info.major}.{sys.version_info.minor}')")
+PY_MAJOR=$($PY_SYSTEM -c "import sys; print(sys.version_info.major)")
+PY_MINOR=$($PY_SYSTEM -c "import sys; print(sys.version_info.minor)")
+if [ "$PY_MAJOR" -lt 3 ] || ([ "$PY_MAJOR" -eq 3 ] && [ "$PY_MINOR" -lt 9 ]); then
+    echo "❌ Error: Python 3.9+ required. Found Python ${PY_VER}." >&2
+    exit 1
+fi
+echo "✓ Detected Python ${PY_VER} (${PY_SYSTEM})"
+
+# 2. Check for python3-venv support
+if ! $PY_SYSTEM -m venv --help >/dev/null 2>&1; then
+    echo "❌ Error: The 'venv' module is missing from your Python installation." >&2
+    echo "   On Ubuntu/Debian, run: sudo apt install -y python3-venv" >&2
+    exit 1
+fi
+
+# 3. Create dedicated isolated virtual environment (bypasses PEP 668 cleanly)
+echo "→ Setting up isolated virtual environment in ${INSTALL_DIR}/venv..."
+mkdir -p "${INSTALL_DIR}"
+$PY_SYSTEM -m venv "${INSTALL_DIR}/venv"
+VENV_PY="${INSTALL_DIR}/venv/bin/python"
+VENV_PIP="${INSTALL_DIR}/venv/bin/pip"
+
+# Upgrade pip and wheel in isolated venv
+"${VENV_PIP}" install --quiet --upgrade pip wheel setuptools
+
+# 4. Install the package
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" 2>/dev/null && pwd)"
+if [ -f "${SCRIPT_DIR}/pyproject.toml" ]; then
+    echo "→ Installing from local source (${SCRIPT_DIR})..."
+    "${VENV_PIP}" install --upgrade "${SCRIPT_DIR}"
+else
+    echo "→ Installing latest release from GitHub (${REPO_URL})..."
+    "${VENV_PIP}" install --upgrade "git+${REPO_URL}"
+fi
+
+# 5. Create symlinks in ~/.local/bin
+mkdir -p "${BIN_DIR}"
+ln -sf "${INSTALL_DIR}/venv/bin/ollama-speak" "${BIN_DIR}/ollama-speak"
+ln -sf "${INSTALL_DIR}/venv/bin/ospeak" "${BIN_DIR}/ospeak"
+echo "✓ Created launcher symlinks in ${BIN_DIR}"
+
+# 6. Ensure ~/.local/bin is on PATH
+PATH_CONFIGURED=false
+case ":$PATH:" in
+    *":${BIN_DIR}:"*) PATH_CONFIGURED=true ;;
+esac
+
+if [ "$PATH_CONFIGURED" = false ]; then
+    echo "→ Adding ${BIN_DIR} to your shell profile..."
+    SHELL_NAME=$(basename "${SHELL:-bash}")
+    RC_FILE=""
+    if [ "$SHELL_NAME" = "zsh" ]; then
+        RC_FILE="${HOME}/.zshrc"
+    elif [ "$SHELL_NAME" = "bash" ]; then
+        if [ -f "${HOME}/.bashrc" ]; then
+            RC_FILE="${HOME}/.bashrc"
+        elif [ -f "${HOME}/.bash_profile" ]; then
+            RC_FILE="${HOME}/.bash_profile"
+        fi
+    fi
+    if [ -n "$RC_FILE" ] && [ -w "$RC_FILE" ]; then
+        if ! grep -q ".local/bin" "$RC_FILE"; then
+            echo '' >> "$RC_FILE"
+            echo '# Added by ollama-speak installer' >> "$RC_FILE"
+            echo 'export PATH="$HOME/.local/bin:$PATH"' >> "$RC_FILE"
+            echo "✓ Added PATH export to ${RC_FILE}"
+        fi
+    fi
+fi
+
+# 7. Pre-download open weights for 100% offline use
+echo "→ Pre-downloading open weights for 100% offline use..."
+"${BIN_DIR}/ollama-speak" --setup || true
+
+echo "=================================================="
+echo " 🎉 Installation Complete!"
+echo "=================================================="
+echo " You can now run:"
+echo "   ollama-speak \"Hello from local voice\""
+echo "   ospeak \"Fast shortcut\""
+echo " Or pipe directly from Ollama:"
+echo "   ollama run llama3 \"Tell me a one-liner\" | ollama-speak"
+if [ "$PATH_CONFIGURED" = false ]; then
+    echo ""
+    echo " ⚠️  Note: If 'ollama-speak' is not recognized immediately in your current terminal,"
+    echo "     run: export PATH=\"\$HOME/.local/bin:\$PATH\""
+    echo "     or restart your terminal."
+fi
+echo "=================================================="

ollama_speak-1.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "ollama-speak"
+version = "1.1.0"
+description = "100% Local, Offline Multilingual Neural Text-to-Speech CLI for Ollama (Kokoro-82M & Piper)."
+readme = "README.md"
+authors = [
+    { name = "Ajarn Spencer Littlewood", email = "ajarnspencer@gmail.com" }
+]
+license = { text = "MIT" }
+requires-python = ">=3.9"
+dependencies = [
+    "kokoro>=0.8.4",
+    "soundfile>=0.12.0",
+    "numpy>=1.21.0",
+]
+
+[project.optional-dependencies]
+piper = [
+    "piper-tts>=1.2.0",
+]
+all = [
+    "kokoro>=0.8.4",
+    "piper-tts>=1.2.0",
+    "soundfile>=0.12.0",
+]
+
+[project.scripts]
+ollama-speak = "ollama_speak.cli:main"
+ospeak = "ollama_speak.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/AjarnSpencer/ollama-speak"
+Repository = "https://github.com/AjarnSpencer/ollama-speak"
+Issues = "https://github.com/AjarnSpencer/ollama-speak/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ollama_speak"]

ollama_speak-1.1.0/requirements.txt

@@ -0,0 +1,4 @@
+kokoro>=0.8.4
+soundfile>=0.12.0
+numpy>=1.21.0
+piper-tts>=1.2.0

ollama_speak-1.1.0/src/ollama_speak/__init__.py

@@ -0,0 +1,5 @@
+"""
+ollama-speak — Universal multilingual neural text-to-speech CLI and pipe companion for Ollama models.
+"""
+
+__version__ = "1.0.0"

ollama_speak-1.1.0/src/ollama_speak/__main__.py

@@ -0,0 +1,4 @@
+from ollama_speak.cli import main
+
+if __name__ == "__main__":
+    main()

ollama_speak-1.1.0/src/ollama_speak/cli.py

@@ -0,0 +1,100 @@
+"""
+Command-line interface for ollama-speak.
+100% Local, Offline Multilingual Neural Text-to-Speech CLI for Ollama (Kokoro-82M & Piper).
+Accepts text from arguments or STDIN pipes (e.g. `ollama-web "query" | ollama-speak`).
+"""
+
+import os
+import sys
+import argparse
+from .voice import (
+    synthesize_and_speak,
+    download_all_models,
+    KOKORO_VOICES,
+    DEFAULT_KOKORO_VOICE
+)
+
+
+def print_voices():
+    print("==================================================================")
+    print(" 🗣️ ollama-speak 100% Local Neural Voices (Kokoro-82M & Piper)")
+    print("==================================================================")
+    print(f"\nDefault Local Voice: {DEFAULT_KOKORO_VOICE} (Warm British Baritone, Kokoro-82M)")
+    print("\nSupported Local Open-Weight Voices:")
+    print("-" * 66)
+    print(f"  {'ALIAS / NAME':<18} {'LANGUAGE':<18} {'GENDER / STYLE'}")
+    print("-" * 66)
+    print(f"  {'bm_george (default)':<18} {'British English':<18} {'Male (Warm Baritone)'}")
+    print(f"  {'bm_lewis':<18} {'British English':<18} {'Male'}")
+    print(f"  {'bf_alice':<18} {'British English':<18} {'Female'}")
+    print(f"  {'af_heart':<18} {'American English':<18} {'Female (Warm)'}")
+    print(f"  {'am_adam':<18} {'American English':<18} {'Male'}")
+    print(f"  {'jf_tebukuro':<18} {'Japanese':<18} {'Female'}")
+    print(f"  {'zf_xiaobei':<18} {'Mandarin Chinese':<18} {'Female'}")
+    print(f"  {'ef_dora':<18} {'Spanish':<18} {'Female'}")
+    print(f"  {'ff_siwis':<18} {'French':<18} {'Female'}")
+    print(f"  {'if_sara':<18} {'Italian':<18} {'Female'}")
+    print(f"  {'pf_dora':<18} {'Portuguese':<18} {'Female'}")
+    print(f"  {'hf_alpha':<18} {'Hindi':<18} {'Female'}")
+    print(f"  {'piper (engine)':<18} {'British / English':<18} {'Ultra-lightweight ONNX'}")
+    print("\nAll models run 100% locally and offline on your CPU or GPU.")
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        prog="ollama-speak",
+        description="100%% Local, Offline Multilingual Neural Text-to-Speech CLI for Ollama (Kokoro-82M and Piper)."
+    )
+    parser.add_argument("text", nargs="*", help="Text to speak (reads from STDIN if omitted)")
+    parser.add_argument("-v", "--voice", default=None, help="Local voice name (e.g. bm_george, af_heart, bf_alice)")
+    parser.add_argument("-e", "--engine", choices=["kokoro", "piper"], default="kokoro", help="TTS engine: kokoro (default, studio quality) or piper (ultra-fast ONNX)")
+    parser.add_argument("--piper", action="store_true", help="Shortcut for --engine piper (ultra-lightweight local ONNX)")
+    parser.add_argument("--kokoro", action="store_true", help="Shortcut for --engine kokoro (studio quality open-weights)")
+    parser.add_argument("-o", "--output", default=None, help="Save audio to specified WAV/MP3 file instead of playing")
+    parser.add_argument("--setup", "--download-models", action="store_true", help="Pre-download local model weights for 100%% offline use")
+    parser.add_argument("--list-voices", action="store_true", help="List available local open-weight voices")
+
+    args = parser.parse_args()
+
+    if args.setup:
+        download_all_models()
+        return
+
+    if args.list_voices:
+        print_voices()
+        return
+
+    engine = "piper" if args.piper else ("kokoro" if args.kokoro else args.engine)
+
+    # 1. Check positional arguments
+    if args.text:
+        content = " ".join(args.text).strip()
+    # 2. Check STDIN pipe (e.g. ollama-web ... | ollama-speak)
+    elif not sys.stdin.isatty():
+        content = sys.stdin.read().strip()
+        # Always echo piped text to stdout so the human sees, reads, and can copy-paste it!
+        if content:
+            print(content, flush=True)
+    else:
+        parser.print_help()
+        sys.exit(0)
+
+    if not content:
+        sys.exit(0)
+
+    output_path = os.path.expanduser(args.output) if args.output else None
+
+    # Synthesize and speak using 100% local model
+    success = synthesize_and_speak(
+        text=content,
+        voice=args.voice,
+        engine=engine,
+        output_file=output_path
+    )
+
+    if output_path and success:
+        print(f"✓ Saved audio to: {output_path}")
+
+
+if __name__ == "__main__":
+    main()

ollama_speak-1.1.0/src/ollama_speak/voice.py

@@ -0,0 +1,371 @@
+"""
+Core local voice engine for ollama-speak.
+100% Local, Offline, Private Neural Text-to-Speech using Kokoro-82M and Piper ONNX.
+Zero cloud APIs, zero big-tech telemetry, zero external data leaks.
+"""
+
+import os
+import re
+import sys
+import time
+import socket
+import shutil
+import urllib.request
+import tempfile
+import subprocess
+from pathlib import Path
+
+# Common Kokoro-82M open-weight voices
+KOKORO_VOICES = {
+    # British English (b)
+    "en-gb": ("bm_george", "b"),
+    "british": ("bm_george", "b"),
+    "bm_george": ("bm_george", "b"),
+    "bm_lewis": ("bm_lewis", "b"),
+    "bm_daniel": ("bm_daniel", "b"),
+    "bm_fable": ("bm_fable", "b"),
+    "bf_alice": ("bf_alice", "b"),
+    "bf_isabella": ("bf_isabella", "b"),
+    "bf_emma": ("bf_emma", "b"),
+    "bf_lily": ("bf_lily", "b"),
+
+    # American English (a)
+    "en-us": ("af_heart", "a"),
+    "american": ("af_heart", "a"),
+    "af_heart": ("af_heart", "a"),
+    "af_bella": ("af_bella", "a"),
+    "af_sarah": ("af_sarah", "a"),
+    "af_nicole": ("af_nicole", "a"),
+    "af_sky": ("af_sky", "a"),
+    "am_adam": ("am_adam", "a"),
+    "am_michael": ("am_michael", "a"),
+    "am_echo": ("am_echo", "a"),
+    "am_eric": ("am_eric", "a"),
+    "am_onyx": ("am_onyx", "a"),
+
+    # Japanese (j)
+    "ja": ("jf_tebukuro", "j"),
+    "japanese": ("jf_tebukuro", "j"),
+    "jf_tebukuro": ("jf_tebukuro", "j"),
+    "jm_kumo": ("jm_kumo", "j"),
+
+    # Mandarin Chinese (z)
+    "zh": ("zf_xiaobei", "z"),
+    "chinese": ("zf_xiaobei", "z"),
+    "zf_xiaobei": ("zf_xiaobei", "z"),
+    "zm_yunjian": ("zm_yunjian", "z"),
+
+    # Spanish (e)
+    "es": ("ef_dora", "e"),
+    "spanish": ("ef_dora", "e"),
+    "ef_dora": ("ef_dora", "e"),
+    "em_alex": ("em_alex", "e"),
+
+    # French (f)
+    "fr": ("ff_siwis", "f"),
+    "french": ("ff_siwis", "f"),
+    "ff_siwis": ("ff_siwis", "f"),
+
+    # Italian (i)
+    "it": ("if_sara", "i"),
+    "italian": ("if_sara", "i"),
+    "if_sara": ("if_sara", "i"),
+    "im_nicola": ("im_nicola", "i"),
+
+    # Portuguese (p)
+    "pt": ("pf_dora", "p"),
+    "portuguese": ("pf_dora", "p"),
+    "pf_dora": ("pf_dora", "p"),
+    "pm_alex": ("pm_alex", "p"),
+
+    # Hindi (h)
+    "hi": ("hf_alpha", "h"),
+    "hindi": ("hf_alpha", "h"),
+    "hf_alpha": ("hf_alpha", "h"),
+    "hm_psi": ("hm_psi", "h"),
+}
+
+DEFAULT_KOKORO_VOICE = "bm_george"
+DEFAULT_KOKORO_LANG = "b"
+
+
+def get_models_dir() -> Path:
+    """Returns local model cache directory (~/.local/share/ollama-speak/models)."""
+    base = Path(os.environ.get("XDG_DATA_HOME", Path.home() / ".local" / "share"))
+    d = base / "ollama-speak" / "models"
+    d.mkdir(parents=True, exist_ok=True)
+    return d
+
+
+def find_piper_model() -> tuple[str, str]:
+    """Finds or returns expected path for local Piper ONNX model and config."""
+    # 1. Custom env var
+    custom = os.environ.get("PIPER_MODEL")
+    if custom and os.path.exists(custom):
+        json_path = custom + ".json" if not custom.endswith(".json") else custom
+        onnx_path = custom.replace(".json", "")
+        return onnx_path, json_path
+
+    # 2. DGX / Host workspace path
+    workspace_piper = Path.home() / "ai-workspace" / "models" / "tts" / "piper" / "en_GB-alan-medium.onnx"
+    if workspace_piper.exists():
+        return str(workspace_piper), str(workspace_piper) + ".json"
+
+    # 3. Standard user data dir
+    user_piper = get_models_dir() / "piper" / "en_GB-alan-medium.onnx"
+    return str(user_piper), str(user_piper) + ".json"
+
+
+def play_audio_file(file_path: str) -> bool:
+    """Plays an audio file (.wav or .mp3) natively across Linux, macOS, and Windows."""
+    if not os.path.exists(file_path) or os.path.getsize(file_path) < 100:
+        return False
+
+    # macOS: native afplay
+    if sys.platform == "darwin":
+        if shutil.which("afplay"):
+            res = subprocess.run(["afplay", file_path], check=False, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+            return res.returncode == 0
+
+    # Windows: native PowerShell
+    if sys.platform == "win32":
+        abs_p = os.path.abspath(file_path).replace("\\", "\\\\")
+        ps_cmd = (
+            f"$player = New-Object System.Media.SoundPlayer('{abs_p}'); "
+            f"if ($player) {{ $player.PlaySync() }}"
+        )
+        res = subprocess.run(["powershell", "-NoProfile", "-Command", ps_cmd], check=False, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+        return res.returncode == 0
+
+    # Linux: check audio players
+    for cmd in ["pw-play", "paplay", "mpv", "ffplay", "aplay"]:
+        if shutil.which(cmd):
+            if cmd == "mpv":
+                res = subprocess.run(["mpv", "--no-video", "--really-quiet", file_path], check=False, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+            elif cmd == "ffplay":
+                res = subprocess.run(["ffplay", "-nodisp", "-autoexit", "-loglevel", "quiet", file_path], check=False, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+            elif cmd in ("pw-play", "paplay"):
+                res = subprocess.run([cmd, file_path], check=False, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+            elif cmd == "aplay" and file_path.endswith(".wav"):
+                res = subprocess.run(["aplay", "-q", file_path], check=False, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+            else:
+                continue
+
+            if res.returncode == 0:
+                return True
+
+    return False
+
+
+def try_local_daemon(text: str, engine: str = "kokoro") -> bool:
+    """
+    Checks if a local sovereign voice daemon is already active on localhost.
+    Provides sub-50ms warm inference without reloading weights into memory.
+    """
+    uid = os.getuid() if hasattr(os, "getuid") else 1000
+    socket_path = f"/run/user/{uid}/voice_dictate.sock"
+    if not os.path.exists(socket_path):
+        return False
+
+    cmd = f"SPEAK_KOKORO:{text}\n" if engine == "kokoro" else f"SPEAK:{text}\n"
+    try:
+        s = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+        s.settimeout(10.0)
+        s.connect(socket_path)
+        s.sendall(cmd.encode("utf-8"))
+        resp = s.recv(1024).decode("utf-8", errors="replace")
+        s.close()
+        return "OK:" in resp
+    except Exception:
+        return False
+
+
+def synthesize_with_kokoro(
+    text: str,
+    voice_name: str = None,
+    speed: float = 1.0,
+    output_path: str = None
+) -> bool:
+    """
+    Synthesizes speech using local Kokoro-82M open-weight model.
+    Runs 100% locally on CPU or GPU with zero cloud network calls.
+    """
+    try:
+        import numpy as np
+        import soundfile as sf
+        from kokoro import KPipeline
+    except ImportError as e:
+        print(f"[!] Kokoro dependencies not found ({e}). Run: pip install kokoro soundfile", file=sys.stderr)
+        return False
+
+    # Resolve voice and language code
+    selected_voice = DEFAULT_KOKORO_VOICE
+    selected_lang = DEFAULT_KOKORO_LANG
+
+    if voice_name:
+        v_lower = voice_name.lower().strip()
+        if v_lower in KOKORO_VOICES:
+            selected_voice, selected_lang = KOKORO_VOICES[v_lower]
+        else:
+            selected_voice = voice_name
+            # Auto-detect lang from prefix
+            prefix = voice_name[0].lower()
+            if prefix in ("b", "a", "j", "z", "e", "f", "i", "p", "h"):
+                selected_lang = prefix
+
+    # Load local Kokoro pipeline
+    try:
+        pipeline = KPipeline(lang_code=selected_lang, repo_id="hexgrad/Kokoro-82M")
+        generator = pipeline(text, voice=selected_voice, speed=speed)
+        chunks = [a for _, _, a in generator]
+        if not chunks:
+            return False
+
+        audio = np.concatenate(chunks)
+        save_file = output_path
+        is_temp = False
+        if not save_file:
+            is_temp = True
+            tmp = tempfile.NamedTemporaryFile(suffix=".wav", delete=False)
+            save_file = tmp.name
+            tmp.close()
+
+        sf.write(save_file, audio, 24000)
+
+        if is_temp:
+            success = play_audio_file(save_file)
+            try:
+                os.remove(save_file)
+            except OSError:
+                pass
+            return success
+        else:
+            return os.path.exists(save_file) and os.path.getsize(save_file) > 100
+    except Exception as e:
+        print(f"[!] Kokoro synthesis error: {e}", file=sys.stderr)
+        return False
+
+
+def synthesize_with_piper(
+    text: str,
+    output_path: str = None
+) -> bool:
+    """
+    Synthesizes speech using local Piper ONNX model.
+    Ultra-lightweight local engine (~35MB model) for low-spec PCs.
+    """
+    onnx_path, json_path = find_piper_model()
+    if not os.path.exists(onnx_path):
+        print(f"[!] Piper ONNX model not found at: {onnx_path}", file=sys.stderr)
+        print("    Download it with: ollama-speak --setup", file=sys.stderr)
+        return False
+
+    save_file = output_path
+    is_temp = False
+    if not save_file:
+        is_temp = True
+        tmp = tempfile.NamedTemporaryFile(suffix=".wav", delete=False)
+        save_file = tmp.name
+        tmp.close()
+
+    try:
+        # Try python piper module
+        import wave
+        from piper.voice import PiperVoice
+        voice = PiperVoice.load(onnx_path, config_path=json_path if os.path.exists(json_path) else None)
+        with wave.open(save_file, "wb") as wf:
+            voice.synthesize_wav(text, wf)
+    except Exception:
+        # Fall back to piper CLI if available
+        piper_bin = shutil.which("piper")
+        if piper_bin:
+            res = subprocess.run([piper_bin, "-m", onnx_path, "-f", save_file], input=text.encode("utf-8"), check=False)
+            if res.returncode != 0:
+                return False
+        else:
+            return False
+
+    if is_temp:
+        success = play_audio_file(save_file)
+        try:
+            os.remove(save_file)
+        except OSError:
+            pass
+        return success
+    else:
+        return os.path.exists(save_file) and os.path.getsize(save_file) > 100
+
+
+def download_all_models() -> None:
+    """
+    Pre-downloads Kokoro-82M and Piper open-weight models for 100% offline use.
+    """
+    print("==================================================================")
+    print(" 📥 ollama-speak Local Model Downloader (100% Offline Setup)")
+    print("==================================================================")
+
+    # 1. Kokoro-82M
+    print("\n1. Verifying / Downloading Kokoro-82M open-weight model (~350 MB)...")
+    try:
+        from kokoro import KPipeline
+        p = KPipeline(lang_code="b", repo_id="hexgrad/Kokoro-82M")
+        # Synthesize a 1-word smoke test to cache default voices
+        for v in ["bm_george", "af_heart"]:
+            gen = p("Ready", voice=v)
+            _ = [a for _, _, a in gen]
+        print("✓ Kokoro-82M weights verified and cached locally.")
+    except Exception as e:
+        print(f"[!] Kokoro download error: {e}")
+
+    # 2. Piper ONNX
+    print("\n2. Verifying / Downloading Piper British ONNX model (~35 MB)...")
+    onnx_path, json_path = find_piper_model()
+    if os.path.exists(onnx_path):
+        print(f"✓ Piper ONNX already exists at: {onnx_path}")
+    else:
+        try:
+            target_dir = Path(onnx_path).parent
+            target_dir.mkdir(parents=True, exist_ok=True)
+            url_base = "https://huggingface.co/rhasspy/piper-voices/resolve/v1.0.0/en/en_GB/alan/medium"
+            print(f"Downloading {onnx_path}...")
+            urllib.request.urlretrieve(f"{url_base}/en_GB-alan-medium.onnx", onnx_path)
+            urllib.request.urlretrieve(f"{url_base}/en_GB-alan-medium.onnx.json", json_path)
+            print("✓ Piper ONNX model downloaded successfully.")
+        except Exception as e:
+            print(f"[!] Piper download warning: {e}")
+
+    print("\n==================================================================")
+    print(" All local models are ready. ollama-speak is 100% offline and sovereign!")
+    print("==================================================================")
+
+
+def synthesize_and_speak(
+    text: str,
+    voice: str = None,
+    engine: str = "kokoro",
+    output_file: str = None
+) -> bool:
+    """
+    Main dispatch function for ollama-speak.
+    Synthesizes and speaks text using 100% LOCAL models.
+    """
+    clean = re.sub(r"https?://\S+", "", text)
+    clean = re.sub(r"[`*_#>\[\]()~|]+", " ", clean)
+    clean = re.sub(r"\s+", " ", clean).strip()
+    if not clean:
+        return False
+
+    # Detect unsupported scripts for local models
+    if re.search(r"[\u0e00-\u0e7f]", clean):
+        print("[ollama-speak] Note: Thai script detected. Local Kokoro/Piper currently support English, Japanese, Chinese, Spanish, French, Italian, Portuguese, and Hindi.", file=sys.stderr)
+
+    # 1. Fast-path: Check for already warm local voice daemon on host
+    if not output_file and try_local_daemon(clean, engine=engine):
+        return True
+
+    # 2. Piper Engine
+    if engine.lower() in ("piper", "fast"):
+        return synthesize_with_piper(clean, output_path=output_file)
+
+    # 3. Kokoro Engine (Default Local SOTA)
+    return synthesize_with_kokoro(clean, voice_name=voice, output_path=output_file)

ollama_speak-1.1.0/verify.py

@@ -0,0 +1,89 @@
+#!/usr/bin/env python3
+"""
+Diagnostic & Verification Suite for ollama-speak.
+Runs automated smoke tests to verify local Kokoro-82M, Piper ONNX, and OS audio playback.
+"""
+
+import os
+import sys
+import shutil
+import tempfile
+
+# Auto re-exec into isolated venv if run from bare system python without dependencies
+venv_dir = os.path.expanduser("~/.local/share/ollama-speak/venv")
+venv_py = os.path.join(venv_dir, "bin", "python")
+if os.path.exists(venv_py) and sys.prefix != venv_dir:
+    try:
+        import kokoro
+    except ImportError:
+        os.execv(venv_py, [venv_py] + sys.argv)
+
+def test_audio_backends():
+    print("[1/3] Checking OS audio playback engines...", end=" ", flush=True)
+    found = []
+    for cmd in ["pw-play", "paplay", "mpv", "ffplay", "aplay", "afplay"]:
+        if shutil.which(cmd):
+            found.append(cmd)
+    if sys.platform == "win32":
+        found.append("powershell (System.Media)")
+
+    if found:
+        print(f"✓ OK (Found: {', '.join(found)})")
+        return True
+    else:
+        print("❌ Warning: No audio player found. Install mpv or ffmpeg.")
+        return False
+
+def test_kokoro_local():
+    print("[2/3] Checking local Kokoro-82M open-weight model...", end=" ", flush=True)
+    try:
+        from kokoro import KPipeline
+        import soundfile as sf
+        import numpy as np
+
+        p = KPipeline(lang_code="b", repo_id="hexgrad/Kokoro-82M")
+        gen = p("Diagnostic test.", voice="bm_george", speed=1.0)
+        chunks = [a for _, _, a in gen]
+        if chunks:
+            audio = np.concatenate(chunks)
+            tmp = tempfile.NamedTemporaryFile(suffix=".wav", delete=False)
+            sf.write(tmp.name, audio, 24000)
+            sz = os.path.getsize(tmp.name)
+            os.remove(tmp.name)
+            print(f"✓ OK (Synthesized {len(audio)} samples, {sz} bytes)")
+            return True
+        else:
+            print("❌ Failed (Empty audio generated)")
+            return False
+    except Exception as e:
+        print(f"❌ Error: {e}")
+        return False
+
+def test_piper_local():
+    print("[3/3] Checking local Piper ONNX model...", end=" ", flush=True)
+    from ollama_speak.voice import find_piper_model
+    onnx_path, json_path = find_piper_model()
+    if os.path.exists(onnx_path):
+        print(f"✓ OK (Found: {onnx_path})")
+        return True
+    else:
+        print(f"⚠️ Notice: Piper ONNX not cached yet at {onnx_path}. Run 'ollama-speak --setup' to pre-download.")
+        return True
+
+def main():
+    print("==================================================")
+    print(" 🛠️  ollama-speak System Diagnostic & Smoke Test")
+    print("==================================================")
+    t1 = test_audio_backends()
+    t2 = test_kokoro_local()
+    t3 = test_piper_local()
+    print("==================================================")
+    if t1 and t2 and t3:
+        print("🎉 100% Local voice engine verified and operational!")
+        sys.exit(0)
+    else:
+        print("❌ Diagnostic failures detected. Check logs above.")
+        sys.exit(1)
+
+if __name__ == "__main__":
+    main()