speak-cli 0.1.2

package/LICENSE

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

package/README.md

@@ -0,0 +1,171 @@
+# speak-cli
+
+[![Release](https://img.shields.io/github/v/release/hoveychen/speak-cli)](https://github.com/hoveychen/speak-cli/releases/latest)
+[![Go](https://img.shields.io/badge/go-1.22+-00ADD8?logo=go)](https://go.dev/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Windows-lightgrey)](https://github.com/hoveychen/speak-cli/releases/latest)
+
+**speak-cli** is a fast, offline-capable multilingual text-to-speech CLI powered by [Kokoro](https://github.com/thewh1teagle/kokoro-onnx). It auto-detects language, supports 150+ voices, and uses the faster MLX backend automatically on Apple Silicon.
+
+```bash
+speak "Hello, world!"
+speak "你好，欢迎使用 speak-cli"
+speak -v af_sky -s 1.2 "Speed it up a bit"
+speak --output hello.wav "Save to file"
+```
+
+---
+
+## Features
+
+- **Auto language detection** — switches between English and Chinese based on text content
+- **150+ voices** — 54 English voices (American, British, Spanish, French, Hindi, Japanese, Portuguese, Italian) and 103 Chinese voices
+- **Apple Silicon optimised** — uses MLX backend for English on M-series Macs, falls back to ONNX automatically
+- **Offline after first use** — engine and models are cached in `~/.cache/speak-cli/`
+- **Save to file** — export speech as WAV with `--output`
+- **Tiny binary** — ~8 MB Go binary; engine and models are downloaded on demand
+
+## Supported Platforms
+
+| Platform | Architecture | Backend |
+|----------|-------------|---------|
+| macOS | Apple Silicon (arm64) | MLX (fast) + ONNX fallback |
+| macOS | Intel (amd64) | ONNX |
+| Windows | amd64 | ONNX |
+| Linux | — | Export to file only (no audio playback) |
+
+---
+
+## Installation
+
+### npm (Node.js 18+)
+
+```bash
+npm install -g speak-cli
+```
+
+### One-line install
+
+**macOS:**
+```bash
+curl -fsSL https://raw.githubusercontent.com/hoveychen/speak-cli/main/install.sh | bash
+```
+
+**Windows (PowerShell):**
+```powershell
+powershell -c "irm https://raw.githubusercontent.com/hoveychen/speak-cli/main/install.ps1 | iex"
+```
+
+Auto-detects your platform and architecture, installs to `~/.local/bin` (macOS) or `%LOCALAPPDATA%\speak-cli\bin` (Windows), and adds it to your PATH automatically.
+
+To install a specific version or change the install directory:
+```bash
+# macOS
+SPEAK_VERSION=v0.2.0 SPEAK_INSTALL_DIR=/usr/local/bin curl -fsSL https://raw.githubusercontent.com/hoveychen/speak-cli/main/install.sh | bash
+
+# Windows
+$env:SPEAK_VERSION="v0.2.0"; $env:SPEAK_INSTALL_DIR="C:\Tools"; powershell -c "irm https://raw.githubusercontent.com/hoveychen/speak-cli/main/install.ps1 | iex"
+```
+
+### Build from source
+
+Requires Go 1.22+.
+
+```bash
+git clone https://github.com/hoveychen/speak-cli.git
+cd speak-cli
+make build       # outputs to bin/
+```
+
+---
+
+## Usage
+
+### Speak text
+
+```bash
+speak "Hello, world!"                        # English (auto-detected)
+speak "你好，欢迎使用 speak-cli"               # Chinese (auto-detected)
+speak --lang zh "Kokoro is great"            # Force language
+speak -v af_sky "Choose a specific voice"    # Choose voice
+speak -s 1.5 "Speak 50% faster"             # Adjust speed (0.5–2.0)
+speak -o out.wav "Save as WAV"              # Export to file
+```
+
+### List voices
+
+```bash
+speak voices              # All voices
+speak voices --lang en    # English only
+speak voices --lang zh    # Chinese only
+```
+
+### Pre-download assets (for offline use)
+
+```bash
+speak init                # Download both English and Chinese
+speak init --lang en      # English only
+speak init --lang zh      # Chinese only
+```
+
+### All flags
+
+```
+Flags:
+      --lang string     Language: auto, en, zh (default "auto")
+  -v, --voice string    Voice name (default depends on language)
+  -s, --speed float     Speed multiplier 0.5–2.0 (default 1.0)
+  -o, --output string   Save WAV to file instead of playing
+      --no-progress     Suppress download progress bar
+  -h, --help            Help
+```
+
+---
+
+## How it works
+
+On first use, `speak` downloads the appropriate engine bundle and model:
+
+```
+~/.cache/speak-cli/
+├── en/
+│   ├── engine/     # PyInstaller-packaged Kokoro ONNX or MLX engine
+│   └── model/      # model.onnx + voices.bin (~88 MB INT8)
+└── zh/
+    ├── engine/     # PyInstaller-packaged Kokoro ONNX engine
+    └── model/      # model.onnx + voices.bin + config.json (~82 MB INT8)
+```
+
+The Go binary manages downloads, invokes the engine subprocess with JSON arguments, and plays back the WAV output. Language auto-detection uses Unicode CJK block (U+4E00–U+9FFF).
+
+---
+
+## Models
+
+| Language | Model | Size | Source |
+|----------|-------|------|--------|
+| English | Kokoro v1.0 (INT8 ONNX) | ~88 MB | [thewh1teagle/kokoro-onnx](https://huggingface.co/thewh1teagle/kokoro-onnx) |
+| Chinese | Kokoro v1.1-zh (INT8 ONNX) | ~82 MB | [hoveyc/speak-cli-models](https://huggingface.co/hoveyc/speak-cli-models) |
+| English (MLX) | Kokoro-82M-bf16 | streamed | [mlx-community/Kokoro-82M-bf16](https://huggingface.co/mlx-community/Kokoro-82M-bf16) |
+
+---
+
+## AI Agent Integration
+
+speak-cli ships with AI skills compatible with [Claude Code](https://claude.ai/claude-code), [Cursor](https://cursor.com), and other AI coding agents. Install the skill to let your AI assistant use speak-cli:
+
+```bash
+npx skills add hoveychen/speak-cli
+```
+
+---
+
+## Contributing
+
+Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+---
+
+## License
+
+[MIT](LICENSE)

package/npm/install.js

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+"use strict";
+
+const https = require("https");
+const fs = require("fs");
+const path = require("path");
+
+// Platform → GitHub Release asset mapping
+const PLATFORMS = {
+  "darwin-arm64": "speak-darwin-arm64",
+  "darwin-x64": "speak-darwin-amd64",
+  "win32-x64": "speak-windows-amd64.exe",
+};
+
+const pkg = require("../package.json");
+const version = pkg.version;
+const key = `${process.platform}-${process.arch}`;
+const asset = PLATFORMS[key];
+
+if (!asset) {
+  console.error(
+    `speak-cli: unsupported platform ${process.platform}/${process.arch}\n` +
+      `Supported: macOS (arm64, x64), Windows (x64)\n` +
+      `Build from source: https://github.com/hoveychen/speak-cli`
+  );
+  process.exit(1);
+}
+
+const binDir = path.join(__dirname, "bin");
+const binName = process.platform === "win32" ? "speak.exe" : "speak";
+const binPath = path.join(binDir, binName);
+const url = `https://github.com/hoveychen/speak-cli/releases/download/v${version}/${asset}`;
+
+function download(url, dest, redirects) {
+  if (redirects <= 0) {
+    console.error("speak-cli: too many redirects");
+    process.exit(1);
+  }
+
+  return new Promise((resolve, reject) => {
+    const mod = url.startsWith("https") ? https : require("http");
+    mod
+      .get(url, (res) => {
+        // Follow redirects (GitHub uses 302)
+        if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+          res.resume();
+          return resolve(download(res.headers.location, dest, redirects - 1));
+        }
+
+        if (res.statusCode !== 200) {
+          res.resume();
+          return reject(new Error(`HTTP ${res.statusCode} downloading ${url}`));
+        }
+
+        const totalBytes = parseInt(res.headers["content-length"], 10) || 0;
+        let downloaded = 0;
+
+        const file = fs.createWriteStream(dest);
+        res.on("data", (chunk) => {
+          downloaded += chunk.length;
+          if (totalBytes > 0 && process.stderr.isTTY) {
+            const pct = ((downloaded / totalBytes) * 100).toFixed(0);
+            process.stderr.write(`\rspeak-cli: downloading ${pct}%`);
+          }
+        });
+        res.pipe(file);
+        file.on("finish", () => {
+          if (process.stderr.isTTY) process.stderr.write("\n");
+          file.close(resolve);
+        });
+        file.on("error", reject);
+      })
+      .on("error", reject);
+  });
+}
+
+async function main() {
+  fs.mkdirSync(binDir, { recursive: true });
+
+  console.log(`speak-cli: downloading speak v${version} for ${key}...`);
+  await download(url, binPath, 5);
+
+  if (process.platform !== "win32") {
+    fs.chmodSync(binPath, 0o755);
+  }
+
+  console.log(`speak-cli: installed to ${binPath}`);
+}
+
+main().catch((err) => {
+  console.error(`speak-cli: ${err.message}`);
+  process.exit(1);
+});

package/npm/run.js

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+"use strict";
+
+const { execFileSync } = require("child_process");
+const path = require("path");
+const fs = require("fs");
+
+const binName = process.platform === "win32" ? "speak.exe" : "speak";
+const binPath = path.join(__dirname, "bin", binName);
+
+if (!fs.existsSync(binPath)) {
+  console.error(
+    "speak-cli: binary not found. Run `node npm/install.js` or reinstall:\n" +
+      "  npm install -g speak-cli"
+  );
+  process.exit(1);
+}
+
+try {
+  execFileSync(binPath, process.argv.slice(2), { stdio: "inherit" });
+} catch (err) {
+  process.exit(err.status ?? 1);
+}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "speak-cli",
+  "version": "0.1.2",
+  "description": "Multilingual text-to-speech CLI powered by Kokoro",
+  "bin": {
+    "speak": "npm/run.js"
+  },
+  "scripts": {
+    "postinstall": "node npm/install.js"
+  },
+  "files": [
+    "npm/",
+    "skills/",
+    "README.md",
+    "LICENSE"
+  ],
+  "os": [
+    "darwin",
+    "win32"
+  ],
+  "keywords": [
+    "tts",
+    "text-to-speech",
+    "kokoro",
+    "cli",
+    "offline",
+    "multilingual"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/hoveychen/speak-cli.git"
+  }
+}

package/skills/speak-cli/SKILL.md

@@ -0,0 +1,183 @@
+---
+name: speak-cli
+description: Multilingual text-to-speech CLI — synthesize speech, select voices, export audio
+---
+
+# speak-cli
+
+`speak` is a fast, offline-capable multilingual text-to-speech CLI powered by Kokoro. It auto-detects language, supports 150+ voices across 8 languages, and uses the faster MLX backend automatically on Apple Silicon.
+
+After first use, the engine and models are cached locally — subsequent runs start instantly with no network required.
+
+## Installation
+
+Before using speak commands, verify it is installed:
+
+```bash
+speak --help
+```
+
+If not installed, use one of:
+
+```bash
+# npm (Node.js 18+)
+npm install -g speak-cli
+
+# macOS
+curl -fsSL https://raw.githubusercontent.com/hoveychen/speak-cli/main/install.sh | bash
+
+# Windows PowerShell
+powershell -c "irm https://raw.githubusercontent.com/hoveychen/speak-cli/main/install.ps1 | iex"
+```
+
+## Commands Reference
+
+### `speak [flags] <text>` — Synthesize speech
+
+Speak text aloud or save to WAV. Language is auto-detected from the text unless `--lang` is specified.
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--lang` | `auto` | Language: `auto`, `en`, `zh`, `es`, `fr`, `hi`, `it`, `ja`, `pt` |
+| `-v, --voice` | per-language default | Voice name (see voice naming below) |
+| `-s, --speed` | `1.0` | Speed multiplier, range `0.5`–`2.0` |
+| `-o, --output` | _(play audio)_ | Save WAV to file instead of playing |
+| `--no-progress` | `false` | Suppress download progress bar |
+
+**Important:** The text argument must be a single quoted string. Wrap it in quotes.
+
+### `speak voices [--lang <lang>]` — List available voices
+
+Lists all available voices offline (no engine or model download needed).
+
+- `--lang all` (default): show all voices
+- `--lang en`: English voices only
+- `--lang zh`: Chinese voices only
+- Also supports: `es`, `fr`, `hi`, `it`, `ja`, `pt`
+
+### `speak init [--lang <lang>]` — Pre-download assets
+
+Downloads engine and model files for offline use.
+
+- `--lang all` (default): download all languages
+- `--lang en`: English only (~88 MB model + engine)
+- `--lang zh`: Chinese only (~82 MB model + engine)
+
+## Language Detection
+
+When `--lang` is `auto` (default), speak inspects the text for CJK characters (Unicode U+4E00–U+9FFF):
+- If any CJK character is found → Chinese (`zh`)
+- Otherwise → English (`en`)
+
+For other languages (Spanish, French, Hindi, Italian, Japanese, Portuguese), you **must** specify `--lang` explicitly.
+
+**Supported languages:** `en`, `zh`, `es`, `fr`, `hi`, `it`, `ja`, `pt`
+
+## Voice Naming Convention
+
+Voices follow the pattern `{language}{gender}_{name}`:
+
+| Prefix | Language | Gender |
+|--------|----------|--------|
+| `af_` | American English | Female |
+| `am_` | American English | Male |
+| `bf_` | British English | Female |
+| `bm_` | British English | Male |
+| `ef_` | Spanish | Female |
+| `em_` | Spanish | Male |
+| `ff_` | French | Female |
+| `hf_` | Hindi | Female |
+| `hm_` | Hindi | Male |
+| `if_` | Italian | Female |
+| `im_` | Italian | Male |
+| `jf_` | Japanese | Female |
+| `jm_` | Japanese | Male |
+| `pf_` | Portuguese (BR) | Female |
+| `pm_` | Portuguese (BR) | Male |
+| `zf_` | Mandarin Chinese | Female |
+| `zm_` | Mandarin Chinese | Male |
+
+**Default voices per language:**
+
+| Language | Default Voice |
+|----------|--------------|
+| English | `af_heart` |
+| Chinese | `zf_001` |
+| Spanish | `ef_dora` |
+| French | `ff_siwis` |
+| Hindi | `hf_alpha` |
+| Italian | `if_sara` |
+| Japanese | `jf_alpha` |
+| Portuguese | `pf_dora` |
+
+Use `speak voices --lang <code>` to see all available voices for a language.
+
+## Common Patterns
+
+```bash
+# Basic speech (language auto-detected)
+speak "Hello, world!"
+speak "你好，欢迎使用 speak-cli"
+
+# Choose a specific voice
+speak -v af_sky "A different voice"
+speak -v zm_010 "换一个男声"
+
+# Adjust speed
+speak -s 1.5 "Speak faster"
+speak -s 0.7 "Speak slower"
+
+# Save to WAV file
+speak -o greeting.wav "Hello, world!"
+
+# Force language (required for es/fr/hi/it/ja/pt)
+speak --lang ja "こんにちは"
+speak --lang es "Hola, mundo"
+
+# Scripting: suppress progress bar
+speak --no-progress -o out.wav "Silent download"
+
+# Batch export
+for i in 1 2 3; do
+  speak -o "part${i}.wav" "This is part ${i}"
+done
+```
+
+## Offline Setup
+
+For offline environments, pre-download assets:
+
+```bash
+speak init              # All languages
+speak init --lang en    # English only
+speak init --lang zh    # Chinese only
+```
+
+Assets are cached in `~/.cache/speak-cli/`:
+- Engine: PyInstaller-packaged Kokoro engine (~200 MB)
+- Models: ONNX model + voice data (~80–90 MB per language)
+- On Apple Silicon: MLX engine is also downloaded for English (faster)
+
+## Platform Support
+
+| Platform | Architecture | Backend | Notes |
+|----------|-------------|---------|-------|
+| macOS | Apple Silicon (arm64) | MLX + ONNX fallback | Fastest on M-series |
+| macOS | Intel (amd64) | ONNX | |
+| Windows | amd64 | ONNX | |
+| Linux | — | Export only | Use `--output` to save WAV; no audio playback |
+
+## Troubleshooting
+
+- **First run is slow**: The engine and model are downloaded on first use. Use `speak init` to pre-download.
+- **MLX fallback message on Apple Silicon**: If the MLX engine cannot load (e.g., missing Metal libraries), speak automatically falls back to the ONNX engine. This is normal and does not affect output quality.
+- **"unsupported platform" error**: speak currently supports macOS and Windows. On Linux, build from source.
+- **Output format**: Only WAV output is supported. Use external tools (ffmpeg) to convert to other formats.
+
+## Constraints
+
+- Text must be passed as a **single argument** — always wrap in quotes
+- Speed range: `0.5` to `2.0`
+- Output format: WAV only (use `--output` flag)
+- No streaming or pipe support — the full audio is synthesized before playback
+- Auto-detection only distinguishes English and Chinese; other languages require `--lang`