kokoro-pi 1.2.0__tar.gz

kokoro_pi-1.2.0/CHANGELOG.md

@@ -0,0 +1,121 @@
+# Changelog
+
+Dates are when the work landed on `main`. Versions follow
+[semantic versioning](https://semver.org): the HTTP API and the config file keys
+are the public surface.
+
+## 1.2.0 — 2026-09-18
+
+Installable from PyPI, and usable as a library in place of kokoro-onnx.
+
+### Added
+
+- **`pip install kokoro-pi`.** Binary wheels for `manylinux_2_28` on aarch64 and
+  x86_64 carry a **pre-compiled kernel**, so nothing needs a compiler; anywhere
+  else pip falls back to the source distribution and `kokoro-pi build` compiles
+  the operators there. The wheel is tagged `py3-none`, not per-Python, because
+  the library is loaded by ONNX Runtime rather than imported by CPython.
+  Published by GitHub Actions through PyPI trusted publishing — no API token
+  exists to leak.
+- **`from kokoro_pi import Kokoro`** — kokoro-onnx's API over these kernels.
+  `create`, `create_stream` and `get_voices` take the same arguments and return
+  the same things, delegated to kokoro-onnx itself so nothing about
+  phonemisation or voices is reimplemented. The constructor takes a models
+  *directory* rather than model files, because these models are derived rather
+  than downloaded.
+- `kokoro_pi.paths`, which finds `native/` and `corpus/` whether the package was
+  cloned or installed, and reports a pre-compiled kernel when a wheel shipped one.
+
+### Changed
+
+- **Calibration reduces inside the graph.** Instrumentation used to mark each
+  target's input tensor as a graph output, so every pass copied out 36
+  activation tensors — 313 MB per utterance, measured. It now adds `Abs` and
+  `ReduceMax` and returns one vector per target: **0.5 MB**, with identical
+  ranges (worst difference 0.0).
+- `--corpus` and `--heldout` default to the packaged corpora rather than to
+  paths relative to a repository that may not exist.
+- `Engine(..., warm=False)` skips the warm-up synthesis, for library callers who
+  only want the object.
+
+### Fixed
+
+- **Builds were being killed by the kernel.** A full build peaked at 3.1 GB
+  because nothing was released between stages, and an out-of-memory kill is a
+  `SIGKILL` — no traceback, the log simply stops mid-stage. Every stage now
+  frees what it is finished with before the next allocates, the parity check
+  keeps its six reference waveforms instead of the session that made them, and
+  the build warns up front when `MemAvailable` is below what it needs. The
+  documented 2.5 GB was disk; the memory figure was written down nowhere.
+- Both ARM kernels now round identically (`std::fma` in the portable path,
+  matching `vfmaq_f32`), so a Pi 4 and a Pi 5 produce the same audio rather than
+  differing by the half-ULP this vocoder amplifies to its phase-chaos floor.
+
+## 1.1.0 — 2026-09-18
+
+Speaks other people's protocols, and can be configured without editing a
+systemd unit.
+
+### Added
+
+- **`POST /v1/audio/speech`**, the OpenAI speech API, so Open WebUI, LibreChat,
+  SillyTavern and the OpenAI SDKs work against this service with a base URL
+  change and nothing else. OpenAI's voice names map onto Kokoro's, `mp3`/`opus`/
+  `aac`/`flac` are produced with ffmpeg when it is installed, and `GET
+  /v1/models` answers for clients that ask first.
+- **The Wyoming protocol**, which is how Home Assistant talks to a voice
+  service — `wyoming = true`, and every voice appears in Home Assistant tagged
+  with its language. It advertises `supports_synthesize_streaming` and
+  implements the streaming events, so a sentence from a conversation agent
+  starts playing at its first clause.
+- **Configuration from a file, the environment or a flag**, resolved in that
+  reverse order, with `kokoro-pi config` to print what is in force and where
+  each value came from. `install.sh` writes
+  `~/.config/kokoro-pi/config.toml` and points the unit at it.
+- **`voices`**, an allowlist, so `/v1/voices` is an honest menu of what a
+  service will speak and a typo is a 400 rather than a surprise accent.
+- **`api_key`** (constant-time, on `/v1` and `/readyz`; `/healthz` stays open
+  and says only `{"ready": true}`) and **`allow_origin`** with `OPTIONS`
+  preflight, so a browser page can call a Pi.
+- **`speed`, `stream`, `stream_limit`, `log_requests`** as service-wide
+  defaults. Request logging is off by default and never includes the text.
+- **[A page you can hear it on](https://zreecespieces.github.io/kokoro-pi/)**,
+  and `tools/compare.py` for measuring this against Piper, Kokoro-FastAPI or
+  anything else that speaks the OpenAI API, on your own hardware.
+- `tools/check_protocols.py`, which exercises every protocol a running service
+  speaks and says what broke.
+
+### Changed
+
+- **`lang` defaults to `auto`, which reads the language from the voice's name.**
+  Kokoro names voices `<language><gender>_<name>`, and `bf_emma` was being given
+  American phonemes — a British voice pronouncing an American's vowels. If you
+  were relying on everything being read as `en-us`, set `lang = "en-us"`.
+  Only `en-us` and `en-gb` are tested; espeak's Japanese and Chinese phonemes
+  are not the ones Kokoro was trained on.
+- `/readyz` reports more: voice count, language mode, format, streaming and
+  `wait_seconds`.
+
+### Fixed
+
+- **Re-running `install.sh` to upgrade left the old code running.**
+  `systemctl --user enable --now` does nothing to a unit that is already active,
+  so the installer rewrote the unit, printed "ready", and the previous process
+  kept serving.
+
+## 1.0.0 — 2026-09-17
+
+First public release: the speech engine from a personal assistant, packaged.
+
+- Four algebra-preserving graph rewrites and a fused native Snake activation:
+  1.35× with the waveform preserved to 115 dB.
+- A hand-written fused int8 convolution kernel using ARM's `SDOT`: **451 GOP/s**,
+  faster than ONNX Runtime's own int8 path (336 GOP/s) and 4.4× its float
+  kernel, with per-input-channel activation scales folded into the weights.
+- Clause-level streaming, so first audio arrives after the first clause instead
+  of after the whole passage.
+- **2.0–2.2× over the upstream ONNX export end to end**, about 3× over a
+  PyTorch install, and first audio 6.6× sooner.
+- One-command install, a resident systemd service, 54 voices, three variants
+  side by side, checksum-verified assets, disjoint calibration and held-out
+  corpora, and quality gated on log-spectral distance rather than waveform SNR.

kokoro_pi-1.2.0/LICENSE

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

kokoro_pi-1.2.0/MANIFEST.in

@@ -0,0 +1,10 @@
+# The sdist must be able to build the kernel, so it carries the sources the
+# wheel compiles and the corpora the build calibrates and checks against.
+graft native
+graft corpus
+include LICENSE NOTICE CHANGELOG.md Makefile install.sh
+recursive-include systemd *.service
+recursive-include tools *.py
+prune docs/audio
+prune samples
+prune .github

kokoro_pi-1.2.0/Makefile

@@ -0,0 +1,66 @@
+# Convenience targets. The installer does all of this for you; these are for hacking.
+PREFIX ?= $(HOME)/.kokoro-pi
+MODELS ?= $(PREFIX)/models
+VENV   ?= $(PREFIX)/venv
+PYTHON ?= $(VENV)/bin/python
+PORT   ?= 8080
+THREADS ?= 4
+export PYTHONPATH = $(CURDIR)/src
+
+.PHONY: help venv native build serve validate samples check compare audio clean distclean
+
+help:
+	@echo "make venv      create the virtual environment and install dependencies"
+	@echo "make native    compile the operator library into $(MODELS)"
+	@echo "make build     download the upstream model and derive the optimised ones"
+	@echo "make serve     run the service in the foreground on port $(PORT)"
+	@echo "make validate  measure quality and speed across variants"
+	@echo "make samples   write a WAV per held-out utterance per variant into samples/"
+	@echo "make audio     convert samples/ to the MP3s the web page plays (needs ffmpeg)"
+	@echo "make check     exercise every protocol against a running service on $(PORT)"
+	@echo "make compare   measure against another engine; see tools/compare.py --help"
+	@echo "make clean     remove derived models, keeping the upstream download"
+
+venv:
+	$(PYTHON) -c '' 2>/dev/null || python3 -m venv $(VENV)
+	$(VENV)/bin/pip install --quiet --upgrade pip wheel
+	$(VENV)/bin/pip install --quiet -r requirements.txt
+
+native:
+	mkdir -p $(MODELS)
+	bash native/build.sh $(MODELS)/libkokoro_pi_ops.so
+
+build: venv
+	$(PYTHON) -m kokoro_pi build --models $(MODELS) --threads $(THREADS)
+
+serve:
+	$(PYTHON) -m kokoro_pi serve --models $(MODELS) --port $(PORT) --threads $(THREADS)
+
+validate:
+	$(PYTHON) -m kokoro_pi validate --models $(MODELS) --variants upstream float int8 \
+	  --reference upstream --threads $(THREADS)
+
+samples:
+	$(PYTHON) -m kokoro_pi validate --models $(MODELS) --variants upstream float int8 \
+	  --reference upstream --audio-dir samples --repeats 1 --threads $(THREADS)
+
+check:
+	python3 tools/check_protocols.py --url http://127.0.0.1:$(PORT)
+
+compare:
+	python3 tools/compare.py --kokoro-pi http://127.0.0.1:$(PORT)
+
+# The page plays 64 kbit MP3s so it loads on a phone; the WAVs stay authoritative.
+audio: samples
+	mkdir -p docs/audio
+	for f in samples/*.wav; do \
+	  ffmpeg -hide_banner -loglevel error -y -i "$$f" -c:a libmp3lame -b:a 64k \
+	    "docs/audio/$$(basename $$f .wav).mp3"; \
+	done
+
+clean:
+	rm -f $(MODELS)/kokoro-fused.onnx $(MODELS)/kokoro-int8.onnx \
+	      $(MODELS)/kokoro-calibration.onnx $(MODELS)/calibration.npz $(MODELS)/models.json
+
+distclean:
+	rm -rf $(PREFIX)

kokoro_pi-1.2.0/NOTICE

@@ -0,0 +1,30 @@
+kokoro-pi
+Copyright (c) 2026 Zachary Reece
+Licensed under the MIT License (see LICENSE).
+
+This project optimises and serves models it does not ship. It builds on:
+
+Kokoro-82M
+  https://huggingface.co/hexgrad/Kokoro-82M
+  Copyright (c) hexgrad. Licensed under the Apache License, Version 2.0.
+  The speech model itself. kokoro-pi downloads the ONNX export at install time and
+  rewrites it; the weights are unchanged apart from the documented int8 quantisation
+  of the vocoder's convolutions.
+
+kokoro-onnx
+  https://github.com/thewh1teagle/kokoro-onnx
+  Copyright (c) thewh1teagle. Licensed under the MIT License.
+  Provides the ONNX export, the voice pack, and the tokenisation and phonemisation
+  front end this service calls. Model files are downloaded from its releases.
+
+ONNX Runtime
+  https://github.com/microsoft/onnxruntime
+  Copyright (c) Microsoft Corporation. Licensed under the MIT License.
+  The inference engine. The five public C and C++ API headers under native/include are
+  vendored unmodified from release 1.23 (API version 23) so the custom operators can be
+  compiled without a source checkout or a matching pip package layout.
+
+espeak-ng, via espeakng-loader and phonemizer-fork
+  https://github.com/espeak-ng/espeak-ng (GPLv3)
+  Used at runtime for phonemisation, through the dependencies above. It is invoked as
+  a separate library and is not linked into or redistributed by this project.