🗣️ ollama-speak (ospeak)

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

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:

curl -fsSL https://raw.githubusercontent.com/AjarnSpencer/ollama-speak/main/install.sh | bash

Windows (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):

pipx install git+https://github.com/AjarnSpencer/ollama-speak.git

Using pip in a virtual environment:

pip install git+https://github.com/AjarnSpencer/ollama-speak.git

Option 3 — Clone and Install Locally

git clone https://github.com/AjarnSpencer/ollama-speak.git
cd ollama-speak
./install.sh

Pre-Download Local Models for 100% Offline Use

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.

🎙️ Supported Local Open-Weight Voices

Run ollama-speak --list-voices to see all local voices:

💡 Practical Tutorials and Workflows

Tutorial 1 — Direct Local Text Narration

Speak any text locally using your default Kokoro voice:

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:

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:

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:

# 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:

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. Kokoro-82M model weights are released under the Apache 2.0 License. Piper TTS is released under the MIT License.