kokorosay 0.1.0__tar.gz

kokorosay-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,35 @@
+name: Upload Python Package
+
+on:
+  push:
+    tags:
+      - 'v*.*.*'
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      # Required for PyPI Trusted Publishing via OIDC token
+      id-token: write
+
+    steps:
+      # 1. Check out code
+      - uses: actions/checkout@v4
+
+      # 2. Install and configure uv
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v8.2.0
+        with:
+          enable-cache: true
+
+      # 3. Build release distributions (dist/)
+      - name: Build release distributions
+        run: uv build
+
+      # 4. Publish directly to PyPI
+      # uv detects GitHub's id-token and handles OIDC exchange with PyPI without API tokens
+      - name: Publish to PyPI
+        run: uv publish

kokorosay-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv

kokorosay-0.1.0/.python-version

@@ -0,0 +1 @@
+3.14

kokorosay-0.1.0/AGENTS.md

@@ -0,0 +1,235 @@
+# AGENTS.md
+
+Guidelines for AI agents and contributors working on **kokorosay**, a command-line
+text-to-speech tool built on top of [Kokoro](https://github.com/hexgrad/kokoro).
+
+## Language Policy
+
+- **Conversation**: Reply to the user in the same language the user writes in.
+- **Artifacts**: Everything committed to the repository MUST be in English:
+  code comments, docstrings, identifiers, log/error messages, CLI help text,
+  commit messages, `README.md`, and any other documentation.
+
+## Keeping This Document in Sync
+
+- This file is the source of truth for the project's specification.
+- Any code change that adds, removes, or alters behavior covered here (CLI
+  arguments, options, subcommands, defaults, exit codes, supported formats,
+  module layout, dependencies, tooling, testing requirements, etc.) MUST update
+  `AGENTS.md` **in the same change**.
+- A task is not considered done while the code and `AGENTS.md` disagree.
+
+## Tooling
+
+| Purpose            | Tool                          |
+| ------------------ | ----------------------------- |
+| Package / env mgmt | [uv](https://docs.astral.sh/uv/) (`uv.lock` is committed) |
+| Lint + format      | [ruff](https://docs.astral.sh/ruff/) |
+| Tests              | [pytest](https://docs.pytest.org/) |
+| Build backend      | hatchling + hatch-vcs (version derived from git tags) |
+| Python             | `>=3.14` (see `.python-version`) |
+
+Common commands:
+
+```sh
+uv sync                     # install runtime + dev dependencies
+uv add <pkg>                # add a runtime dependency
+uv add --dev <pkg>          # add a dev dependency
+uv run ruff check .         # lint
+uv run ruff check --fix .   # lint with autofix
+uv run ruff format .        # format
+uv run pytest               # run tests
+uv run kokorosay --help     # run the CLI from source
+```
+
+Rules:
+
+- Never edit `uv.lock` by hand; always go through `uv add` / `uv remove` / `uv lock`.
+- Do not use `pip install` directly in this project.
+- Code must pass `ruff check` and `ruff format --check` before a task is considered done.
+- All tests must pass before a task is considered done.
+
+## Project Layout (src layout)
+
+```
+kokorosay/
+├── AGENTS.md
+├── README.md
+├── pyproject.toml
+├── uv.lock
+├── src/
+│   └── kokorosay/
+│       ├── __init__.py
+│       ├── __main__.py      # enables `python -m kokorosay`
+│       ├── cli.py           # argument parsing and entry point `main()`
+│       ├── setup_cmd.py     # `--setup`: UniDic dictionary download
+│       ├── voices.py        # voice catalog, language-code mapping
+│       ├── synth.py         # Kokoro pipeline wrapper, segment merging
+│       ├── audio_io.py      # writing WAV/MP3, playback
+│       └── py.typed
+└── tests/
+    ├── conftest.py          # fake kokoro / sounddevice / stdin fixtures
+    └── test_*.py
+```
+
+- The console script is registered in `pyproject.toml` as
+  `kokorosay = "kokorosay.cli:main"`.
+- Keep modules small and focused; the module list above is a guideline, not a contract.
+- Inside the package, reference sibling modules with **relative imports**
+  (e.g. `from .voices import resolve_lang_code`, `from . import audio_io`),
+  never `from kokorosay.xxx import ...`. Tests (outside the package) import via
+  the absolute package name `kokorosay`.
+
+## CLI Specification
+
+```
+kokorosay INPUT [OUTPUT] [OPTIONS]
+kokorosay --list-voices
+kokorosay --setup
+```
+
+### `--setup` option
+
+`kokorosay --setup` downloads the full UniDic dictionary required by the
+Japanese G2P backend (the `unidic` package is a runtime dependency, but its
+dictionary data must be fetched separately). Implementation sketch:
+
+```python
+import subprocess
+import sys
+
+subprocess.check_call([sys.executable, "-m", "unidic", "download"])
+```
+
+- `--setup` is a standalone mode like `--list-voices`: `INPUT` is not required,
+  and the program exits after the download.
+- `--setup` cannot be combined with `INPUT`/`OUTPUT` or `--list-voices`; doing
+  so is a usage error (exit code `2`).
+- Use `sys.executable` so the download runs in the same environment kokorosay
+  is installed in. Do not invoke `python`/`pip` from `PATH`.
+- Progress output from the child process goes straight to the terminal. If the
+  child exits non-zero (`CalledProcessError`) or cannot be started, print a
+  concise error to stderr and exit with code `1`.
+- Must not import `kokoro` or `torch`.
+
+### Positional arguments
+
+| Argument | Description |
+| -------- | ----------- |
+| `INPUT`  | Text to synthesize. If it is exactly `-`, read the text from stdin. |
+| `OUTPUT` | Optional output file path. If omitted, the audio is played directly. |
+
+### Options
+
+| Option | Default | Description |
+| ------ | ------- | ----------- |
+| `--voice NAME` | `af_heart` | Voice name, e.g. `jf_nezumi`. The language is derived from the **first letter** of the voice name; there is no separate language option. |
+| `--speed FLOAT` | `1.0` | Speech rate multiplier passed to Kokoro. |
+| `--split-pattern REGEX` | `None` | Regex used to split text into segments. When not given, do **not** pass `split_pattern` so Kokoro's own default applies. |
+| `--list-voices` | – | Print all supported voices grouped by language, then exit. `INPUT` is not required in this mode; combining it with `INPUT`/`OUTPUT` is a usage error (exit code `2`). |
+| `--setup` | – | Download the full UniDic dictionary, then exit. `INPUT` is not required in this mode. See [`--setup` option](#--setup-option). |
+| `--version` | – | Print the package version (from git tags via hatch-vcs), then exit. |
+
+### Behavior requirements
+
+1. **Stdin input (`-`)**
+   - Read raw bytes from `sys.stdin.buffer` and decode as UTF-8 explicitly
+     (use `utf-8-sig` so a leading BOM, common from PowerShell, is stripped).
+   - Never rely on the platform default encoding; Windows consoles often use a
+     non-UTF-8 code page.
+   - Bytes that are not valid UTF-8 are a runtime failure (exit code `1`).
+   - Text that is empty or whitespace-only (from `INPUT` or stdin) is a usage
+     error (exit code `2`).
+   - Text starting with `-` can be passed after `--` (argparse convention).
+2. **Output file**
+   - Only `.mp3` and `.wav` are supported (extension check is case-insensitive).
+     Any other extension is a usage error and must be rejected **before** loading
+     the model.
+   - Files are written with `soundfile` (libsndfile, which supports MP3).
+   - Existing files are overwritten without prompting.
+   - Missing parent directories are created automatically
+     (`Path.parent.mkdir(parents=True, exist_ok=True)`).
+3. **Segment merging**
+   - Kokoro yields one audio chunk per segment. When writing to a file, all chunks
+     MUST be concatenated in order and written as a **single** file, regardless of
+     whether `--split-pattern` was supplied.
+4. **Playback (no `OUTPUT`)**
+   - Play the synthesized audio on the default output device using
+     `sounddevice` (PortAudio).
+   - Chunks are played sequentially as they are generated to reduce latency; the
+     output stream is opened when the first chunk arrives.
+5. **Voice → language**
+   - `lang_code = voice[0]`, passed to `KPipeline(lang_code=..., repo_id="hexgrad/Kokoro-82M")`
+     (passing `repo_id` explicitly suppresses Kokoro's stdout warning).
+   - An unknown voice or unsupported language prefix is a usage error with a
+     helpful message (suggest `--list-voices`).
+   - Other argument validation (`--speed` must be positive, `--split-pattern`
+     must be a valid regex) also happens before loading the model and is a usage
+     error.
+6. **Exit codes**
+   - `0` success, `1` runtime failure, `2` usage error (argparse convention),
+     `130` interrupted with Ctrl+C.
+   - Synthesis that produces no audio at all is a runtime failure.
+   - Errors go to stderr; stdout is reserved for user-requested output
+     (e.g. `--list-voices`). Anything third-party libraries print to stdout
+     during synthesis is redirected to stderr, and warnings emitted by `torch`
+     are suppressed.
+
+### Kokoro reference
+
+- Audio sample rate is **24000 Hz**.
+- Language prefixes:
+
+  | Prefix | Language |
+  | ------ | -------- |
+  | `a` | American English |
+  | `b` | British English |
+  | `e` | Spanish |
+  | `f` | French |
+  | `h` | Hindi |
+  | `i` | Italian |
+  | `j` | Japanese |
+  | `p` | Brazilian Portuguese |
+  | `z` | Mandarin Chinese |
+
+- Basic pipeline usage:
+
+  ```python
+  from kokoro import KPipeline
+
+  pipeline = KPipeline(lang_code="j")
+  for graphemes, phonemes, audio in pipeline(text, voice="jf_nezumi", speed=1.0):
+      ...
+  ```
+
+## Coding Conventions
+
+- Target Python 3.14; use modern syntax (type hints everywhere, `pathlib.Path`,
+  `from __future__ import annotations` is unnecessary).
+- Public functions have English docstrings.
+- Keep heavy imports (`kokoro`, `torch`) lazy, inside the functions that need them,
+  so `--help`, `--list-voices`, `--setup`, and argument validation stay fast.
+- Prefer the standard library (`argparse`) for CLI parsing unless a dependency is
+  explicitly approved by the user.
+- Do not add new runtime dependencies without the user's approval.
+- Approved runtime dependencies: `kokoro`, `misaki[en,ja,ko,vi,zh]`, `unidic`
+  (Japanese dictionary), `soundfile` (WAV/MP3 writing), `sounddevice`
+  (playback). `numpy` comes in transitively and may be used directly.
+
+## Testing
+
+- Tests live in `tests/` and use pytest.
+- Unit tests MUST NOT download models or require audio hardware: mock
+  `KPipeline` and the playback backend. `tests/conftest.py` provides the
+  `fake_kokoro`, `fake_sounddevice`, and `set_stdin` fixtures, which install fake
+  `kokoro` / `sounddevice` modules into `sys.modules`.
+- Tests that need the real model or a sound device are marked
+  `@pytest.mark.integration` and deselected by default (`addopts` in
+  `pyproject.toml`); run them with `uv run pytest -m integration`.
+- Cover at least: argument parsing, stdin UTF-8 decoding (including BOM and
+  non-ASCII text), output extension validation, parent directory creation,
+  segment concatenation, voice-to-language mapping, `--list-voices` grouping,
+  and `--setup` handling (mock `subprocess.check_call`; never actually download
+  UniDic in unit tests; verify the command uses `sys.executable`, that a
+  failing child results in exit code `1`, and that combining `--setup` with
+  `INPUT` or `--list-voices` results in exit code `2`).

kokorosay-0.1.0/PKG-INFO

@@ -0,0 +1,234 @@
+Metadata-Version: 2.5
+Name: kokorosay
+Version: 0.1.0
+Summary: A CLI tool for Kokoro
+Project-URL: Homepage, https://github.com/ecator/kokorosay
+Project-URL: Repository, https://github.com/ecator/kokorosay
+Author-email: Martin <qule520@126.com>
+Requires-Python: >=3.14
+Requires-Dist: kokoro>=0.9.4
+Requires-Dist: misaki[en,ja,ko,vi,zh]>=0.9.4
+Requires-Dist: sounddevice>=0.5.6
+Requires-Dist: soundfile>=0.14.0
+Requires-Dist: unidic>=1.1.0
+Description-Content-Type: text/markdown
+
+# kokorosay
+
+[![PyPI version](https://img.shields.io/pypi/v/kokorosay.svg)](https://pypi.org/project/kokorosay/)
+[![Python versions](https://img.shields.io/pypi/pyversions/kokorosay.svg)](https://pypi.org/project/kokorosay/)
+
+`kokorosay` is a fast, lightweight command-line text-to-speech (TTS) tool built on top of [Kokoro](https://github.com/hexgrad/kokoro).
+
+Pass text as an argument or pipe it via standard input; `kokorosay` will immediately stream speech through your speakers or export it to high-quality WAV or MP3 audio files.
+
+---
+
+## Features
+
+- ⚡ **Fast & Lightweight**: Built on the open-weights 82M parameter Kokoro model (`hexgrad/Kokoro-82M`).
+- 🔊 **Direct Low-Latency Playback**: Streams audio chunks to your default audio device in real time as they are generated.
+- 💾 **WAV & MP3 Export**: Concatenates synthesized chunks into a seamless 24 kHz audio file; parent directories are created automatically.
+- 🌐 **9 Languages & 50+ Voices**: Supports English, Japanese, Mandarin Chinese, Spanish, French, Hindi, Italian, and Brazilian Portuguese.
+- 🔀 **Automatic Language Detection**: The target language is derived directly from the voice name prefix (e.g. `jf_nezumi` &rarr; Japanese, `zf_xiaobei` &rarr; Mandarin, `af_heart` &rarr; American English).
+- 📥 **Pipeline & Stdin Friendly**: Supports `-` as input with explicit UTF-8 and BOM decoding, ideal for shell pipes and automation scripts.
+- 🎛️ **Synthesis Controls**: Easily adjust speech rate multiplier (`--speed`) or provide custom segment-splitting regexes (`--split-pattern`).
+- 🛡️ **Clean CLI & Standard Exit Codes**: Suppresses third-party noise, outputs errors to `stderr`, and adheres to standard exit codes (`0`, `1`, `2`, `130`).
+
+---
+
+## Installation
+
+`kokorosay` requires **Python 3.14+**.
+
+### Recommended: Using [uv](https://docs.astral.sh/uv/)
+
+Install `kokorosay` as a globally isolated command-line tool:
+
+```sh
+uv tool install kokorosay
+```
+
+### Alternative: Using [pipx](https://github.com/pypa/pipx) or pip
+
+```sh
+# Using pipx
+pipx install kokorosay
+
+# Using standard pip (inside an active virtual environment)
+pip install kokorosay
+```
+
+### System Prerequisites (Linux only)
+
+On Windows and macOS, audio dependencies are bundled automatically. On Linux systems, `portaudio` might be needed for direct speaker playback:
+
+```sh
+# Debian / Ubuntu
+sudo apt-get install libportaudio2
+```
+
+---
+
+## Setup
+
+Before first use, run the one-time dictionary setup:
+
+```sh
+kokorosay --setup
+```
+
+- **Japanese UniDic**: `kokorosay --setup` downloads the full UniDic dictionary required for Japanese G2P (grapheme-to-phoneme) processing.
+- **Model weights**: The Kokoro-82M model and voice weights (~330 MB) are automatically fetched from Hugging Face on your first speech synthesis and cached locally for future offline use.
+
+---
+
+## Quick Start & Examples
+
+### 1. Direct Playback
+
+Provide text in quotes to play speech instantly through the default audio device:
+
+```sh
+# Play using default voice (af_heart - American English female)
+kokorosay "Hello! Kokorosay brings text to life right from your terminal."
+
+# British English voice, slightly faster
+kokorosay "Mind the gap between the train and the platform." --voice bm_george --speed 1.15
+```
+
+### 2. Exporting to Audio Files (`.wav` / `.mp3`)
+
+Specify an output file path as the second positional argument. Only `.mp3` and `.wav` formats are supported (case-insensitive). Missing directories will be created automatically:
+
+```sh
+# Save as MP3
+kokorosay "Speech saved to an MP3 file." output.mp3
+
+# Japanese voice saved to a nested directory
+kokorosay "こんにちは、世界。" audio/japanese/hello.wav --voice jf_nezumi
+
+# Mandarin Chinese voice
+kokorosay "你好，欢迎使用文本转语音工具。" out/welcome.mp3 --voice zf_xiaobei
+```
+
+### 3. Piping from Stdin (`-`)
+
+Pass `-` as `INPUT` to read text from standard input. `kokorosay` decodes standard input as UTF-8 (and strips PowerShell's UTF-8 BOM if present):
+
+```sh
+# Pipe the output of any command
+fortune | kokorosay -
+
+# Read from a file via stdin
+cat story.txt | kokorosay - story.mp3 --voice bf_emma
+
+# In PowerShell:
+Get-Content notes.txt -Raw | kokorosay - notes.wav
+```
+
+### 4. Text Starting with Hyphens (`--`)
+
+If your input text begins with a dash or minus sign, use `--` so the argument parser does not interpret it as a flag:
+
+```sh
+kokorosay -- "-5 degrees Celsius outside today."
+```
+
+---
+
+## CLI Reference
+
+### Synopsis
+
+```sh
+kokorosay INPUT [OUTPUT] [OPTIONS]
+kokorosay --list-voices
+kokorosay --setup
+```
+
+### Arguments and Options
+
+| Argument / Option | Default | Description |
+| ----------------- | ------- | ----------- |
+| `INPUT` | – | Text to synthesize. Use `-` to read UTF-8 text from stdin. |
+| `OUTPUT` | – | Output audio path (`.wav` or `.mp3`). If omitted, audio plays directly. |
+| `--voice NAME` | `af_heart` | Voice identifier (e.g. `jf_nezumi`, `bf_emma`). First letter sets language. |
+| `--speed FLOAT` | `1.0` | Speech rate multiplier (must be a positive number). |
+| `--split-pattern REGEX` | Kokoro default | Regular expression to split input text into segments. |
+| `--list-voices` | – | Print all supported voices grouped by language and exit. |
+| `--setup` | – | Download the UniDic dictionary for Japanese support and exit. |
+| `--version` | – | Show version number and exit. |
+| `-h`, `--help` | – | Show command help and exit. |
+
+> **Note:** `--setup` and `--list-voices` are standalone modes. They cannot be combined with positional arguments (`INPUT` / `OUTPUT`) or with each other.
+
+---
+
+## Supported Languages & Voices
+
+Kokoro determines the language from the **first letter** of the voice name. The **second letter** indicates voice gender (`f` for female, `m` for male).
+
+| Prefix | Language | Example Voices |
+| :---: | --- | --- |
+| `a` | American English | `af_heart` (default), `af_alloy`, `af_bella`, `am_adam`, `am_michael` |
+| `b` | British English | `bf_alice`, `bf_emma`, `bm_daniel`, `bm_george` |
+| `e` | Spanish | `ef_dora`, `em_alex`, `em_santa` |
+| `f` | French | `ff_siwis` |
+| `h` | Hindi | `hf_alpha`, `hf_beta`, `hm_omega`, `hm_psi` |
+| `i` | Italian | `if_sara`, `im_nicola` |
+| `j` | Japanese | `jf_alpha`, `jf_gongitsune`, `jf_nezumi`, `jf_tebukuro`, `jm_kumo` |
+| `p` | Brazilian Portuguese | `pf_dora`, `pm_alex`, `pm_santa` |
+| `z` | Mandarin Chinese | `zf_xiaobei`, `zf_xiaoni`, `zf_xiaoxiao`, `zm_yunjian`, `zm_yunyang` |
+
+To view the complete list of available voices grouped by language, run:
+
+```sh
+kokorosay --list-voices
+```
+
+---
+
+## Exit Codes
+
+| Code | Meaning |
+| :---: | --- |
+| `0` | **Success**: Audio played or written successfully, or `--help` / `--list-voices` completed. |
+| `1` | **Runtime Failure**: Network error downloading weights, synthesis failure, missing audio device, or invalid UTF-8 bytes on stdin. |
+| `2` | **Usage Error**: Missing `INPUT`, invalid argument, unknown voice name, unsupported output extension, or empty text. |
+| `130` | **Interrupted**: Execution aborted by `SIGINT` (Ctrl+C). |
+
+---
+
+## Development
+
+If you wish to contribute or modify `kokorosay`:
+
+```sh
+# Clone repository
+git clone https://github.com/ecator/kokorosay.git
+cd kokorosay
+
+# Install runtime and dev dependencies
+uv sync
+
+# Lint and check formatting
+uv run ruff check .
+uv run ruff format --check .
+
+# Run unit tests (offline, mocked Kokoro/sounddevice)
+uv run pytest
+
+# Run integration tests (requires real model weights & audio device)
+uv run pytest -m integration
+```
+
+See [AGENTS.md](AGENTS.md) for full architecture specifications and coding conventions.
+
+---
+
+## Acknowledgments
+
+- [Kokoro](https://github.com/hexgrad/kokoro) for the TTS model.
+- [Misaki](https://github.com/hexgrad/misaki) for G2P text pre-processing.
+- [UniDic](https://github.com/polm/unidic-py) for Japanese morphological analysis.