vinospeak 0.1.0__tar.gz

vinospeak-0.1.0/LICENSE

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

vinospeak-0.1.0/PKG-INFO

@@ -0,0 +1,141 @@
+Metadata-Version: 2.4
+Name: vinospeak
+Version: 0.1.0
+Summary: Intel NPU-powered Kokoro text-to-speech with OpenVINO
+Author: Karan Shukla
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/karanshukla/vinoSpeak
+Project-URL: Repository, https://github.com/karanshukla/vinoSpeak
+Project-URL: Issues, https://github.com/karanshukla/vinoSpeak/issues
+Project-URL: Changelog, https://github.com/karanshukla/vinoSpeak/blob/main/CHANGELOG.md
+Keywords: kokoro,openvino,npu,text-to-speech,tts,linux
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: espeakng-loader>=0.2.4
+Requires-Dist: huggingface-hub>=0.24.0
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: openvino==2026.4.1
+Requires-Dist: openvino-genai==2026.4.1.0
+Requires-Dist: soundfile>=0.12.1
+Dynamic: license-file
+
+# vinoSpeak
+
+Intel NPU-powered text-to-speech using the Kokoro-82M INT8 OpenVINO model.
+Text goes in, a WAV comes out, and nothing leaves your machine after the
+one-time model download.
+
+## Requirements
+
+- Python 3.11 or newer
+- An Intel NPU with a compatible driver. GPU and CPU also work
+  (`--device GPU`, `--device CPU`).
+- Internet access on first run to download the model (~160 MB)
+
+OpenVINO is pinned to the release vinoPop and vinoWhisper use, so programs
+sharing one NPU never run mismatched runtimes.
+
+## Install
+
+From PyPI, with [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv tool install vinospeak
+vinospeak "Hello."
+```
+
+OpenVINO is pinned exactly; everything else resolves to the newest release
+that fits. To install exactly what `uv.lock` pins, hashes included, use a
+checkout. `--locked` fails if the lock is out of date:
+
+```bash
+git clone https://github.com/karanshukla/vinoSpeak && cd vinoSpeak
+uv sync --locked
+uv run vinospeak "Hello."
+```
+
+To put that checkout's `vinospeak` on your PATH with the lock's versions as
+constraints (`uv tool install` doesn't read `uv.lock` by itself):
+
+```bash
+uv export --locked --no-dev --no-emit-project --no-hashes -o constraints.txt
+uv tool install --constraints constraints.txt .
+```
+
+## Synthesize speech
+
+The first run downloads `OpenVINO/Kokoro-82M-int8-ov` from Hugging Face, at one
+pinned commit, and checks every file against its sha256 (see
+[SECURITY.md](SECURITY.md)). The model is cached under
+`${XDG_CACHE_HOME:-~/.cache}/vinospeak/` by default.
+
+```bash
+vinospeak "Hello from vinoSpeak."                     # plays it on your speakers
+vinospeak "Hello from vinoSpeak." --output hello.wav  # saves a WAV instead
+```
+
+Playback goes through `pw-play` (PipeWire, what Wayland desktops run), falling
+back to `paplay` or `aplay`.
+
+The default inference device is the Intel NPU. Choose a different OpenVINO
+device, voice, language, speed, or model directory with the corresponding
+options:
+
+```bash
+vinospeak "A sample sentence." \
+  --device NPU \
+  --voice af_heart \
+  --language en-us \
+  --speed 1.0 \
+  --model-dir ./kokoro-model \
+  --output speech.wav
+```
+
+Use `vinospeak --help` to see all options. The audio uses the sample rate
+reported by OpenVINO GenAI.
+
+## Check this machine
+
+```bash
+vinospeak-doctor          # --json for a bug report
+```
+
+Reports the OpenVINO packages and devices, whether the cached model still
+matches its pins, and, if [ovfetch](https://github.com/karanshukla/ovfetch) is
+on your `PATH`, whether your OpenVINO version is inside the range recorded as
+working with your NPU driver. Install it with `cargo install ovfetch --locked`.
+ovfetch is advisory here: it never changes what gets installed or run.
+
+## Use it from Python
+
+```python
+from vino_speak import Synthesizer
+
+synth = Synthesizer("NPU")  # compiles the model once; reuse it
+audio = synth.synthesize("Hello.")  # audio.samples (float32), audio.sample_rate
+
+speech = synth.speak("A long passage.")  # returns at once, plays in the background
+speech.stop()  # cuts it off; speech.wait() blocks until it finishes instead
+```
+
+`speak()` synthesizes the first sentence on its own and plays it while the
+rest is synthesized in chunks that at most double in size, so speech starts
+after about 1.5 s on the NPU however long the text is.
+
+## Development
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). `uv run poe check` runs everything CI
+does; none of it needs OpenVINO or an NPU.

vinospeak-0.1.0/README.md

@@ -0,0 +1,107 @@
+# vinoSpeak
+
+Intel NPU-powered text-to-speech using the Kokoro-82M INT8 OpenVINO model.
+Text goes in, a WAV comes out, and nothing leaves your machine after the
+one-time model download.
+
+## Requirements
+
+- Python 3.11 or newer
+- An Intel NPU with a compatible driver. GPU and CPU also work
+  (`--device GPU`, `--device CPU`).
+- Internet access on first run to download the model (~160 MB)
+
+OpenVINO is pinned to the release vinoPop and vinoWhisper use, so programs
+sharing one NPU never run mismatched runtimes.
+
+## Install
+
+From PyPI, with [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv tool install vinospeak
+vinospeak "Hello."
+```
+
+OpenVINO is pinned exactly; everything else resolves to the newest release
+that fits. To install exactly what `uv.lock` pins, hashes included, use a
+checkout. `--locked` fails if the lock is out of date:
+
+```bash
+git clone https://github.com/karanshukla/vinoSpeak && cd vinoSpeak
+uv sync --locked
+uv run vinospeak "Hello."
+```
+
+To put that checkout's `vinospeak` on your PATH with the lock's versions as
+constraints (`uv tool install` doesn't read `uv.lock` by itself):
+
+```bash
+uv export --locked --no-dev --no-emit-project --no-hashes -o constraints.txt
+uv tool install --constraints constraints.txt .
+```
+
+## Synthesize speech
+
+The first run downloads `OpenVINO/Kokoro-82M-int8-ov` from Hugging Face, at one
+pinned commit, and checks every file against its sha256 (see
+[SECURITY.md](SECURITY.md)). The model is cached under
+`${XDG_CACHE_HOME:-~/.cache}/vinospeak/` by default.
+
+```bash
+vinospeak "Hello from vinoSpeak."                     # plays it on your speakers
+vinospeak "Hello from vinoSpeak." --output hello.wav  # saves a WAV instead
+```
+
+Playback goes through `pw-play` (PipeWire, what Wayland desktops run), falling
+back to `paplay` or `aplay`.
+
+The default inference device is the Intel NPU. Choose a different OpenVINO
+device, voice, language, speed, or model directory with the corresponding
+options:
+
+```bash
+vinospeak "A sample sentence." \
+  --device NPU \
+  --voice af_heart \
+  --language en-us \
+  --speed 1.0 \
+  --model-dir ./kokoro-model \
+  --output speech.wav
+```
+
+Use `vinospeak --help` to see all options. The audio uses the sample rate
+reported by OpenVINO GenAI.
+
+## Check this machine
+
+```bash
+vinospeak-doctor          # --json for a bug report
+```
+
+Reports the OpenVINO packages and devices, whether the cached model still
+matches its pins, and, if [ovfetch](https://github.com/karanshukla/ovfetch) is
+on your `PATH`, whether your OpenVINO version is inside the range recorded as
+working with your NPU driver. Install it with `cargo install ovfetch --locked`.
+ovfetch is advisory here: it never changes what gets installed or run.
+
+## Use it from Python
+
+```python
+from vino_speak import Synthesizer
+
+synth = Synthesizer("NPU")  # compiles the model once; reuse it
+audio = synth.synthesize("Hello.")  # audio.samples (float32), audio.sample_rate
+
+speech = synth.speak("A long passage.")  # returns at once, plays in the background
+speech.stop()  # cuts it off; speech.wait() blocks until it finishes instead
+```
+
+`speak()` synthesizes the first sentence on its own and plays it while the
+rest is synthesized in chunks that at most double in size, so speech starts
+after about 1.5 s on the NPU however long the text is.
+
+## Development
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). `uv run poe check` runs everything CI
+does; none of it needs OpenVINO or an NPU.

vinospeak-0.1.0/pyproject.toml

@@ -0,0 +1,137 @@
+[build-system]
+requires = ["setuptools>=78.1.1"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "vinospeak"
+version = "0.1.0"
+description = "Intel NPU-powered Kokoro text-to-speech with OpenVINO"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Karan Shukla" }]
+keywords = ["kokoro", "openvino", "npu", "text-to-speech", "tts", "linux"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Intended Audience :: End Users/Desktop",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Multimedia :: Sound/Audio :: Speech",
+    "Typing :: Typed",
+]
+requires-python = ">=3.11"
+# OpenVINO is pinned to the exact release the other vino apps use (vinoPop's
+# requirements-ai.txt, vinoWhisper's uv.lock): two programs on one NPU must not
+# run different OpenVINO releases. Bump it in step with them; `ovfetch detect`
+# reports the range your NPU driver is known to work with.
+dependencies = [
+    "espeakng-loader>=0.2.4",
+    "huggingface-hub>=0.24.0",
+    "numpy>=1.24.0",
+    "openvino==2026.4.1",
+    "openvino-genai==2026.4.1.0",
+    "soundfile>=0.12.1",
+]
+
+[project.urls]
+Homepage = "https://github.com/karanshukla/vinoSpeak"
+Repository = "https://github.com/karanshukla/vinoSpeak"
+Issues = "https://github.com/karanshukla/vinoSpeak/issues"
+Changelog = "https://github.com/karanshukla/vinoSpeak/blob/main/CHANGELOG.md"
+
+[project.scripts]
+vinospeak = "vino_speak.cli:main"
+vinospeak-doctor = "vino_speak.doctor:main"
+
+[tool.setuptools.packages.find]
+include = ["vino_speak*"]
+
+# Dropping either from the wheel fails quietly: the pins are read at run time.
+[tool.setuptools.package-data]
+vino_speak = ["model_pins.json", "py.typed"]
+
+# ── uv ────────────────────────────────────────────────────────────────────────
+
+[dependency-groups]
+# Installable alone, so CI never downloads OpenVINO
+dev = [
+    "pytest>=8.0",
+    "pytest-cov>=5.0",
+    "ruff>=0.6",
+    "mypy>=1.10",
+    "poethepoet>=0.27",
+    "bump-my-version>=0.24",
+]
+
+# ── bump-my-version ───────────────────────────────────────────────────────────
+
+[tool.bumpversion]
+current_version = "0.1.0"
+commit = true
+tag = true
+tag_name = "v{new_version}"
+pre_commit_hooks = ["uv lock", "git add uv.lock"]
+
+[[tool.bumpversion.files]]
+filename = "pyproject.toml"
+search = 'version = "{current_version}"'
+replace = 'version = "{new_version}"'
+
+# ── Tasks ─────────────────────────────────────────────────────────────────────
+
+[tool.poe.tasks]
+lint  = "ruff check ."
+fmt   = "ruff format --check ."
+types = "mypy"
+test  = "pytest -v --tb=short"
+fix.sequence = [{ cmd = "ruff check --fix ." }, { cmd = "ruff format ." }]
+security.cmd = "uvx --from bandit[toml]==1.9.4 bandit -c pyproject.toml -r ."
+security.help = "the same Bandit scan the Bandit workflow runs"
+check.sequence = ["lint", "fmt", "types", "test"]
+check.help = "everything CI runs, locally"
+doctor = "vinospeak-doctor"
+
+# ── Ruff ──────────────────────────────────────────────────────────────────────
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+extend-exclude = [".venv"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+ignore = [
+    "E501", # line length is the formatter's job
+]
+
+# ── Mypy ──────────────────────────────────────────────────────────────────────
+
+[tool.mypy]
+files = ["vino_speak", "scripts"]
+ignore_missing_imports = true
+strict = true
+
+# ── Pytest ────────────────────────────────────────────────────────────────────
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+addopts = "-q"
+
+[tool.coverage.report]
+show_missing = true
+
+# ── Bandit ────────────────────────────────────────────────────────────────────
+
+[tool.bandit]
+exclude_dirs = ["tests", ".venv", ".git", "build", "dist"]
+skips = [
+    "B404", # import subprocess: ovfetch is run by design
+    "B603", # subprocess without shell
+]

vinospeak-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

vinospeak-0.1.0/tests/test_cli.py

@@ -0,0 +1,52 @@
+import pytest
+
+from vino_speak import cli
+
+
+def test_parser_defaults_to_npu():
+    arguments = cli.build_parser().parse_args(["Hello"])
+    assert arguments.device == "NPU"
+    assert arguments.voice == "af_heart"
+    assert arguments.model_dir is None
+
+
+def test_main_reports_errors_through_the_parser(monkeypatch, capsys):
+    def refuse(*args, **kwargs):
+        raise ValueError("Speed must be between 0.5 and 2.0.")
+
+    monkeypatch.setattr(cli, "synthesize", refuse)
+    with pytest.raises(SystemExit) as exit_info:
+        cli.main(["Hello", "--speed", "9"])
+    assert exit_info.value.code == 2
+    assert "Speed must be between" in capsys.readouterr().err
+
+
+def test_main_prints_where_the_speech_went(monkeypatch, capsys, tmp_path):
+    monkeypatch.setattr(cli, "synthesize", lambda *args, **kwargs: None)
+    cli.main(["Hello", "--output", str(tmp_path / "out.wav")])
+    assert str(tmp_path / "out.wav") in capsys.readouterr().out
+
+
+def test_main_speaks_when_there_is_no_output(monkeypatch, capsys):
+    spoken = []
+    monkeypatch.setattr(cli, "speak", lambda text, **kwargs: spoken.append(text))
+    monkeypatch.setattr(cli, "synthesize", lambda *args, **kwargs: pytest.fail("wrote a file"))
+    cli.main(["Hello"])
+    assert spoken == ["Hello"]
+    assert capsys.readouterr().out == ""
+
+
+def test_saving_to_a_file_does_not_speak(monkeypatch, tmp_path):
+    monkeypatch.setattr(cli, "synthesize", lambda *args, **kwargs: None)
+    monkeypatch.setattr(cli, "speak", lambda *args, **kwargs: pytest.fail("spoke a saved file"))
+    cli.main(["Hello", "--output", str(tmp_path / "out.wav")])
+
+
+def test_ctrl_c_exits_quietly_with_130(monkeypatch):
+    def interrupted(*args, **kwargs):
+        raise KeyboardInterrupt
+
+    monkeypatch.setattr(cli, "speak", interrupted)
+    with pytest.raises(SystemExit) as exit_info:
+        cli.main(["Hello"])
+    assert exit_info.value.code == 130

vinospeak-0.1.0/tests/test_doctor.py

@@ -0,0 +1,86 @@
+import json
+
+import pytest
+
+from vino_speak import doctor, ovfetch
+from vino_speak.model import MODEL_FILES
+
+
+@pytest.fixture(autouse=True)
+def isolated(monkeypatch, tmp_path):
+    monkeypatch.setenv("XDG_CACHE_HOME", str(tmp_path))
+    monkeypatch.setattr(doctor, "_distribution", lambda name: "1.0")
+    monkeypatch.setattr(
+        doctor, "_devices", lambda: [doctor.Result(doctor.OK, "devices", "CPU, NPU")]
+    )
+
+
+def by_label(results, label):
+    return next(r for r in results if r.label == label)
+
+
+def test_a_missing_package_is_a_failure(monkeypatch):
+    monkeypatch.setattr(doctor, "_distribution", lambda name: None)
+    assert by_label(doctor._packages(), "openvino-genai").status == doctor.FAIL
+
+
+def test_a_model_not_yet_downloaded_is_unknown_not_failed():
+    assert by_label(doctor._model(), "model").status == doctor.UNKNOWN
+
+
+def test_a_stale_model_fails(monkeypatch, tmp_path):
+    for name in MODEL_FILES:
+        path = tmp_path / "vinospeak" / "kokoro-82m-int8-ov" / name
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_bytes(b"stale")
+    assert by_label(doctor._model(), "model").status == doctor.FAIL
+
+
+def test_ovfetch_is_only_consulted_with_an_npu(monkeypatch):
+    monkeypatch.setattr(ovfetch, "detect", lambda: pytest.fail("no NPU, so no ovfetch"))
+    assert doctor._ovfetch(has_npu=False) == []
+
+
+def test_a_missing_ovfetch_is_unknown_with_an_install_hint(monkeypatch):
+    monkeypatch.setattr(ovfetch, "detect", lambda: None)
+    (result,) = doctor._ovfetch(has_npu=True)
+    assert result.status == doctor.UNKNOWN
+    assert ovfetch.INSTALL_HINT in result.detail
+
+
+def test_a_broken_ovfetch_is_a_warning_never_a_failure(monkeypatch):
+    def broken():
+        raise ovfetch.OvfetchError("ovfetch detect exited 2: boom")
+
+    monkeypatch.setattr(ovfetch, "detect", broken)
+    (result,) = doctor._ovfetch(has_npu=True)
+    assert result.status == doctor.WARN
+
+
+def test_ovfetch_notes_become_results_and_never_fail(monkeypatch):
+    status = {
+        "devices": [{"kind": "npu"}],
+        "openvino_ceiling": "2025.4",
+        "platforms": [],
+        "npu_driver": "1.32.0",
+    }
+    monkeypatch.setattr(ovfetch, "detect", lambda: status)
+    monkeypatch.setattr(doctor, "_distribution", lambda name: "2026.4.1")
+    results = doctor._ovfetch(has_npu=True)
+    assert by_label(results, "npu: openvino range").status == doctor.WARN
+    assert all(r.status != doctor.FAIL for r in results)
+
+
+def test_json_output_and_exit_status(capsys, monkeypatch):
+    monkeypatch.setattr(doctor, "_ovfetch", lambda has_npu: [])
+    code = doctor.main(["--json"])
+    report = json.loads(capsys.readouterr().out)
+    assert code == 0
+    assert report["failed"] == []
+    assert by_label([doctor.Result(**c) for c in report["checks"]], "vinospeak").status == doctor.OK
+
+
+def test_exit_status_is_1_when_something_failed(capsys, monkeypatch):
+    monkeypatch.setattr(doctor, "_distribution", lambda name: None)
+    assert doctor.main([]) == 1
+    assert "failed" in capsys.readouterr().out