voxport 0.4.0__tar.gz

voxport-0.4.0/LICENSE

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

voxport-0.4.0/PKG-INFO

@@ -0,0 +1,218 @@
+Metadata-Version: 2.4
+Name: voxport
+Version: 0.4.0
+Summary: Text-to-speech and speech-to-text interfaces with swappable engine adapters (Kokoro, Wyoming Whisper).
+Author: Brien Alkire
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/brienalkire/voxport
+Project-URL: Repository, https://github.com/brienalkire/voxport
+Project-URL: Changelog, https://github.com/brienalkire/voxport/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/brienalkire/voxport/issues
+Keywords: tts,stt,text-to-speech,speech-to-text,speech,voice,kokoro,whisper,wyoming
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=2.0
+Provides-Extra: kokoro
+Requires-Dist: kokoro>=0.9.4; extra == "kokoro"
+Requires-Dist: torch>=2.12.0; extra == "kokoro"
+Provides-Extra: wyoming
+Requires-Dist: wyoming>=1.5.0; extra == "wyoming"
+Provides-Extra: all
+Requires-Dist: voxport[kokoro,wyoming]; extra == "all"
+Dynamic: license-file
+
+# voxport
+
+Small Python interfaces for text-to-speech and speech-to-text, with
+swappable engine adapters. Your code calls one method,
+`synthesize()` or `transcribe()`, and never touches an engine's API
+directly, so switching engines means changing one line where the adapter
+is created.
+
+```
+TTSEngine.synthesize(text, voice) -> audio
+STTEngine.transcribe(audio) -> text
+```
+
+Included adapters:
+
+- **`KokoroDirectTTS`**: runs the [Kokoro](https://huggingface.co/hexgrad/Kokoro-82M)
+  TTS model in your own process. The model loads once and stays in
+  memory, with no server and no network hop.
+- **`WyomingWhisperSTT`**: a client for a [Wyoming](https://github.com/OHF-Voice/wyoming)
+  protocol Whisper server, the same kind of server Home Assistant's voice
+  pipeline uses. It loads no model itself; transcription happens on the
+  server.
+
+voxport is a library only: it has no command-line tool or app of its
+own. It is pre-1.0, so the API may still change between minor versions
+(see the [changelog](https://github.com/brienalkire/voxport/blob/main/CHANGELOG.md)).
+
+## Installation
+
+Requires Python 3.10+. Each adapter's dependencies are an optional
+extra, so you install only what you use:
+
+```
+pip install "voxport[kokoro]"    # KokoroDirectTTS
+pip install "voxport[wyoming]"   # WyomingWhisperSTT
+pip install "voxport[all]"       # both
+```
+
+| Extra | Adds | For |
+|---|---|---|
+| `kokoro` | Kokoro, torch (about 2 GB) | `KokoroDirectTTS` |
+| `wyoming` | wyoming | `WyomingWhisperSTT` |
+| `all` | both of the above | everything |
+
+A plain `pip install voxport` includes only the interfaces and numpy.
+Importing an adapter without its extra raises an `ImportError` that
+names the extra to install.
+
+Things voxport doesn't install for you:
+
+- `WyomingWhisperSTT` needs a running Wyoming Whisper server. See
+  [Running a Wyoming Whisper server](#running-a-wyoming-whisper-server).
+- On first use, Kokoro downloads its model weights and voice packs from
+  Hugging Face, and spaCy's `en_core_web_sm` English model. See
+  [Offline use](#offline-use) for machines that can't reach those.
+- `soundfile`, used in the examples below to write WAV files.
+
+## Usage
+
+### Text to speech
+
+```python
+import soundfile as sf
+from voxport.tts.kokoro_direct import KokoroDirectTTS
+
+tts = KokoroDirectTTS()  # reuse one instance; models load once per accent
+audio = tts.synthesize("Hello from voxport.", voice="af_heart", speed=1.0)
+sf.write("hello.wav", audio, tts.sample_rate)  # 24 kHz mono
+```
+
+`synthesize()` returns a 1-D numpy array. The first letter of the voice
+name picks the accent (`a` American, `b` British, ...), following
+Kokoro's voice naming; pass `lang_code=` to override it. Kokoro splits
+long text into segments itself, so there is no length limit.
+
+### Speech to text
+
+```python
+from voxport.stt.wyoming_whisper import WyomingWhisperSTT
+
+stt = WyomingWhisperSTT(host="localhost", port=10300)  # the defaults
+text = stt.transcribe(audio_16k, language="en")
+```
+
+`audio_16k` is a 1-D numpy array of mono audio at `stt.sample_rate`
+(16 kHz), either int16 samples or floats in [-1, 1]. Resample first if
+your audio has a different rate; Kokoro's output, for example, is
+24 kHz. Each call opens a new connection to the server.
+
+### From async code
+
+Both calls block, and `transcribe()` runs its own asyncio event loop, so
+from code that already has a running loop, call them in a worker thread:
+
+```python
+audio = await asyncio.to_thread(tts.synthesize, text, "bm_george")
+text = await asyncio.to_thread(stt.transcribe, audio_16k, "en")
+```
+
+## Writing your own adapter
+
+An adapter subclasses `TTSEngine` or `STTEngine`, sets `sample_rate`,
+and implements the one abstract method:
+
+```python
+import numpy as np
+from voxport.tts.base import TTSEngine
+
+class SilenceTTS(TTSEngine):
+    """A toy engine: one second of silence, whatever the text."""
+
+    sample_rate = 16000
+
+    def synthesize(self, text: str, voice: str, speed: float = 1.0):
+        return np.zeros(self.sample_rate, dtype=np.float32)
+```
+
+Code written against `TTSEngine` works with `SilenceTTS` and
+`KokoroDirectTTS` unchanged. Adapters may accept extra, engine-specific
+keyword arguments (like `KokoroDirectTTS`'s `lang_code`), as long as the
+base signature still works.
+
+## Offline use
+
+By default, Kokoro's weights and voice packs download to Hugging Face's
+standard cache (`~/.cache/huggingface`, or wherever `HF_HOME` points).
+To run on a machine that can't reach huggingface.co:
+
+1. On a machine with internet access, synthesize once with each voice
+   you plan to use, so the model and those voice packs are cached.
+2. Copy that cache to the offline machine, keeping Hugging Face's
+   `hub/models--<org>--<name>/...` layout, and point `HF_HOME` at it.
+3. Set `HF_HUB_OFFLINE=1` on the offline machine. voxport never sets
+   this for you. With it set, only voices already in the cache work; an
+   uncached voice fails with a Hub connection error instead of
+   downloading.
+
+Kokoro's English phonemizer also needs spaCy's `en_core_web_sm` model,
+which downloads from GitHub, not Hugging Face, so `HF_HUB_OFFLINE`
+doesn't cover it. It downloads once per Python environment, so install
+it while online:
+
+```
+python -m spacy download en_core_web_sm
+```
+
+**Repo-local cache (source checkouts only).** If you run voxport from a
+clone, you can keep the cache inside it instead: create an `hf_cache/`
+folder at the repo root (it's gitignored) and `KokoroDirectTTS` uses it
+as `HF_HOME`, unless you've set `HF_HOME` yourself. That makes the
+cache easy to copy along with the checkout.
+
+## Running a Wyoming Whisper server
+
+`WyomingWhisperSTT` needs a server to talk to. For local testing, the
+easiest option is the [`rhasspy/wyoming-whisper`](https://github.com/rhasspy/wyoming-faster-whisper)
+Docker image:
+
+```
+docker run -d --name whisper --restart unless-stopped -p 10300:10300 -v wyoming-data:/data rhasspy/wyoming-whisper --model tiny-int8 --language en
+```
+
+The image is named `rhasspy/wyoming-whisper`, even though its GitHub
+repo is `wyoming-faster-whisper`. `docker logs whisper` shows `Ready`
+once the model has loaded. `tiny-int8` is small and fast but not very
+accurate; use a larger model when transcription quality matters.
+
+If you already run Home Assistant with its Whisper add-on, you can point
+`WyomingWhisperSTT` at that server's host and port instead.
+
+## Development
+
+```
+git clone https://github.com/brienalkire/voxport.git
+cd voxport
+pip install -e ".[all]" pytest
+python -m pytest
+```
+
+The tests need no network, no Whisper server and no Kokoro model:
+`WyomingWhisperSTT` is tested against a fake in-process Wyoming server.
+Installing `.[wyoming]` instead of `.[all]` is enough to run them and
+skips the 2 GB torch download.
+
+## License
+
+[MIT](https://github.com/brienalkire/voxport/blob/main/LICENSE)

voxport-0.4.0/README.md

@@ -0,0 +1,187 @@
+# voxport
+
+Small Python interfaces for text-to-speech and speech-to-text, with
+swappable engine adapters. Your code calls one method,
+`synthesize()` or `transcribe()`, and never touches an engine's API
+directly, so switching engines means changing one line where the adapter
+is created.
+
+```
+TTSEngine.synthesize(text, voice) -> audio
+STTEngine.transcribe(audio) -> text
+```
+
+Included adapters:
+
+- **`KokoroDirectTTS`**: runs the [Kokoro](https://huggingface.co/hexgrad/Kokoro-82M)
+  TTS model in your own process. The model loads once and stays in
+  memory, with no server and no network hop.
+- **`WyomingWhisperSTT`**: a client for a [Wyoming](https://github.com/OHF-Voice/wyoming)
+  protocol Whisper server, the same kind of server Home Assistant's voice
+  pipeline uses. It loads no model itself; transcription happens on the
+  server.
+
+voxport is a library only: it has no command-line tool or app of its
+own. It is pre-1.0, so the API may still change between minor versions
+(see the [changelog](https://github.com/brienalkire/voxport/blob/main/CHANGELOG.md)).
+
+## Installation
+
+Requires Python 3.10+. Each adapter's dependencies are an optional
+extra, so you install only what you use:
+
+```
+pip install "voxport[kokoro]"    # KokoroDirectTTS
+pip install "voxport[wyoming]"   # WyomingWhisperSTT
+pip install "voxport[all]"       # both
+```
+
+| Extra | Adds | For |
+|---|---|---|
+| `kokoro` | Kokoro, torch (about 2 GB) | `KokoroDirectTTS` |
+| `wyoming` | wyoming | `WyomingWhisperSTT` |
+| `all` | both of the above | everything |
+
+A plain `pip install voxport` includes only the interfaces and numpy.
+Importing an adapter without its extra raises an `ImportError` that
+names the extra to install.
+
+Things voxport doesn't install for you:
+
+- `WyomingWhisperSTT` needs a running Wyoming Whisper server. See
+  [Running a Wyoming Whisper server](#running-a-wyoming-whisper-server).
+- On first use, Kokoro downloads its model weights and voice packs from
+  Hugging Face, and spaCy's `en_core_web_sm` English model. See
+  [Offline use](#offline-use) for machines that can't reach those.
+- `soundfile`, used in the examples below to write WAV files.
+
+## Usage
+
+### Text to speech
+
+```python
+import soundfile as sf
+from voxport.tts.kokoro_direct import KokoroDirectTTS
+
+tts = KokoroDirectTTS()  # reuse one instance; models load once per accent
+audio = tts.synthesize("Hello from voxport.", voice="af_heart", speed=1.0)
+sf.write("hello.wav", audio, tts.sample_rate)  # 24 kHz mono
+```
+
+`synthesize()` returns a 1-D numpy array. The first letter of the voice
+name picks the accent (`a` American, `b` British, ...), following
+Kokoro's voice naming; pass `lang_code=` to override it. Kokoro splits
+long text into segments itself, so there is no length limit.
+
+### Speech to text
+
+```python
+from voxport.stt.wyoming_whisper import WyomingWhisperSTT
+
+stt = WyomingWhisperSTT(host="localhost", port=10300)  # the defaults
+text = stt.transcribe(audio_16k, language="en")
+```
+
+`audio_16k` is a 1-D numpy array of mono audio at `stt.sample_rate`
+(16 kHz), either int16 samples or floats in [-1, 1]. Resample first if
+your audio has a different rate; Kokoro's output, for example, is
+24 kHz. Each call opens a new connection to the server.
+
+### From async code
+
+Both calls block, and `transcribe()` runs its own asyncio event loop, so
+from code that already has a running loop, call them in a worker thread:
+
+```python
+audio = await asyncio.to_thread(tts.synthesize, text, "bm_george")
+text = await asyncio.to_thread(stt.transcribe, audio_16k, "en")
+```
+
+## Writing your own adapter
+
+An adapter subclasses `TTSEngine` or `STTEngine`, sets `sample_rate`,
+and implements the one abstract method:
+
+```python
+import numpy as np
+from voxport.tts.base import TTSEngine
+
+class SilenceTTS(TTSEngine):
+    """A toy engine: one second of silence, whatever the text."""
+
+    sample_rate = 16000
+
+    def synthesize(self, text: str, voice: str, speed: float = 1.0):
+        return np.zeros(self.sample_rate, dtype=np.float32)
+```
+
+Code written against `TTSEngine` works with `SilenceTTS` and
+`KokoroDirectTTS` unchanged. Adapters may accept extra, engine-specific
+keyword arguments (like `KokoroDirectTTS`'s `lang_code`), as long as the
+base signature still works.
+
+## Offline use
+
+By default, Kokoro's weights and voice packs download to Hugging Face's
+standard cache (`~/.cache/huggingface`, or wherever `HF_HOME` points).
+To run on a machine that can't reach huggingface.co:
+
+1. On a machine with internet access, synthesize once with each voice
+   you plan to use, so the model and those voice packs are cached.
+2. Copy that cache to the offline machine, keeping Hugging Face's
+   `hub/models--<org>--<name>/...` layout, and point `HF_HOME` at it.
+3. Set `HF_HUB_OFFLINE=1` on the offline machine. voxport never sets
+   this for you. With it set, only voices already in the cache work; an
+   uncached voice fails with a Hub connection error instead of
+   downloading.
+
+Kokoro's English phonemizer also needs spaCy's `en_core_web_sm` model,
+which downloads from GitHub, not Hugging Face, so `HF_HUB_OFFLINE`
+doesn't cover it. It downloads once per Python environment, so install
+it while online:
+
+```
+python -m spacy download en_core_web_sm
+```
+
+**Repo-local cache (source checkouts only).** If you run voxport from a
+clone, you can keep the cache inside it instead: create an `hf_cache/`
+folder at the repo root (it's gitignored) and `KokoroDirectTTS` uses it
+as `HF_HOME`, unless you've set `HF_HOME` yourself. That makes the
+cache easy to copy along with the checkout.
+
+## Running a Wyoming Whisper server
+
+`WyomingWhisperSTT` needs a server to talk to. For local testing, the
+easiest option is the [`rhasspy/wyoming-whisper`](https://github.com/rhasspy/wyoming-faster-whisper)
+Docker image:
+
+```
+docker run -d --name whisper --restart unless-stopped -p 10300:10300 -v wyoming-data:/data rhasspy/wyoming-whisper --model tiny-int8 --language en
+```
+
+The image is named `rhasspy/wyoming-whisper`, even though its GitHub
+repo is `wyoming-faster-whisper`. `docker logs whisper` shows `Ready`
+once the model has loaded. `tiny-int8` is small and fast but not very
+accurate; use a larger model when transcription quality matters.
+
+If you already run Home Assistant with its Whisper add-on, you can point
+`WyomingWhisperSTT` at that server's host and port instead.
+
+## Development
+
+```
+git clone https://github.com/brienalkire/voxport.git
+cd voxport
+pip install -e ".[all]" pytest
+python -m pytest
+```
+
+The tests need no network, no Whisper server and no Kokoro model:
+`WyomingWhisperSTT` is tested against a fake in-process Wyoming server.
+Installing `.[wyoming]` instead of `.[all]` is enough to run them and
+skips the 2 GB torch download.
+
+## License
+
+[MIT](https://github.com/brienalkire/voxport/blob/main/LICENSE)

voxport-0.4.0/pyproject.toml

@@ -0,0 +1,63 @@
+[build-system]
+# 77+ for the PEP 639 `license = "MIT"` expression below.
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "voxport"
+version = "0.4.0"
+description = "Text-to-speech and speech-to-text interfaces with swappable engine adapters (Kokoro, Wyoming Whisper)."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Brien Alkire" }]
+requires-python = ">=3.10"
+keywords = [
+    "tts",
+    "stt",
+    "text-to-speech",
+    "speech-to-text",
+    "speech",
+    "voice",
+    "kokoro",
+    "whisper",
+    "wyoming",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Topic :: Multimedia :: Sound/Audio :: Speech",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "numpy>=2.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/brienalkire/voxport"
+Repository = "https://github.com/brienalkire/voxport"
+Changelog = "https://github.com/brienalkire/voxport/blob/main/CHANGELOG.md"
+Issues = "https://github.com/brienalkire/voxport/issues"
+
+[project.optional-dependencies]
+# KokoroDirectTTS: in-process Kokoro model (pulls in torch, ~2 GB).
+kokoro = [
+    "kokoro>=0.9.4",
+    "torch>=2.12.0",
+]
+# WyomingWhisperSTT: lightweight network client, no local model.
+wyoming = [
+    "wyoming>=1.5.0",
+]
+all = [
+    "voxport[kokoro,wyoming]",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.setuptools]
+packages = ["voxport", "voxport.tts", "voxport.stt"]

voxport-0.4.0/setup.cfg

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

voxport-0.4.0/tests/test_interfaces.py

@@ -0,0 +1,46 @@
+"""The TTSEngine and STTEngine ports: abstract, and usable via subclassing."""
+
+import numpy as np
+import pytest
+
+from voxport.stt.base import STTEngine
+from voxport.tts.base import TTSEngine
+
+
+def test_tts_engine_is_abstract():
+    with pytest.raises(TypeError):
+        TTSEngine()
+
+
+def test_stt_engine_is_abstract():
+    with pytest.raises(TypeError):
+        STTEngine()
+
+
+def test_tts_subclass_works():
+    class SilenceTTS(TTSEngine):
+        sample_rate = 16000
+
+        def synthesize(self, text, voice, speed=1.0):
+            return np.zeros(self.sample_rate, dtype=np.float32)
+
+    audio = SilenceTTS().synthesize("hello", "any-voice")
+    assert audio.shape == (16000,)
+
+
+def test_stt_subclass_works():
+    class EchoSTT(STTEngine):
+        sample_rate = 16000
+
+        def transcribe(self, audio):
+            return f"{len(audio)} samples"
+
+    assert EchoSTT().transcribe(np.zeros(5)) == "5 samples"
+
+
+def test_subclass_missing_method_is_rejected():
+    class Incomplete(TTSEngine):
+        sample_rate = 16000
+
+    with pytest.raises(TypeError):
+        Incomplete()

voxport-0.4.0/tests/test_optional_extras.py

@@ -0,0 +1,23 @@
+"""Importing an adapter without its optional extra names the extra to install."""
+
+import importlib.util
+
+import pytest
+
+
+@pytest.mark.skipif(
+    importlib.util.find_spec("torch") is not None,
+    reason="torch is installed, so the kokoro extra is present",
+)
+def test_kokoro_adapter_without_extra_names_the_extra():
+    with pytest.raises(ImportError, match=r"voxport\[kokoro\]"):
+        import voxport.tts.kokoro_direct  # noqa: F401
+
+
+@pytest.mark.skipif(
+    importlib.util.find_spec("wyoming") is not None,
+    reason="wyoming is installed, so the wyoming extra is present",
+)
+def test_wyoming_adapter_without_extra_names_the_extra():
+    with pytest.raises(ImportError, match=r"voxport\[wyoming\]"):
+        import voxport.stt.wyoming_whisper  # noqa: F401

voxport-0.4.0/tests/test_wyoming_whisper.py

@@ -0,0 +1,134 @@
+"""WyomingWhisperSTT against a fake in-process Wyoming server.
+
+transcribe() runs its own event loop via asyncio.run(), so the fake server
+runs on a separate event loop in a background thread.
+"""
+
+import asyncio
+import threading
+
+import numpy as np
+import pytest
+
+pytest.importorskip("wyoming")
+
+from wyoming.asr import Transcribe, Transcript  # noqa: E402
+from wyoming.audio import AudioChunk, AudioStart, AudioStop  # noqa: E402
+from wyoming.event import async_read_event, async_write_event  # noqa: E402
+
+from voxport.stt.wyoming_whisper import (  # noqa: E402
+    CHUNK_SAMPLES,
+    SAMPLE_RATE,
+    WyomingWhisperSTT,
+)
+
+
+class FakeWyomingServer:
+    """Records the events a client sends; replies with a transcript, or
+    closes the connection without one if `reply` is None."""
+
+    def __init__(self, reply="hello world"):
+        self.reply = reply
+        self.events = []
+        self.port = None
+        self._loop = asyncio.new_event_loop()
+        self._ready = threading.Event()
+        self._thread = threading.Thread(target=self._run, daemon=True)
+
+    def _run(self):
+        asyncio.set_event_loop(self._loop)
+        server = self._loop.run_until_complete(
+            asyncio.start_server(self._handle, "127.0.0.1", 0)
+        )
+        self.port = server.sockets[0].getsockname()[1]
+        self._ready.set()
+        self._loop.run_forever()
+        server.close()
+        self._loop.run_until_complete(server.wait_closed())
+        self._loop.close()
+
+    async def _handle(self, reader, writer):
+        while True:
+            event = await async_read_event(reader)
+            if event is None:
+                break
+            self.events.append(event)
+            if AudioStop.is_type(event.type):
+                if self.reply is not None:
+                    await async_write_event(Transcript(text=self.reply).event(), writer)
+                break
+        writer.close()
+
+    def __enter__(self):
+        self._thread.start()
+        self._ready.wait(timeout=5)
+        return self
+
+    def __exit__(self, *exc):
+        self._loop.call_soon_threadsafe(self._loop.stop)
+        self._thread.join(timeout=5)
+
+    def of_type(self, cls):
+        return [cls.from_event(e) for e in self.events if cls.is_type(e.type)]
+
+
+def received_audio(server):
+    return np.frombuffer(
+        b"".join(chunk.audio for chunk in server.of_type(AudioChunk)), dtype=np.int16
+    )
+
+
+def test_returns_transcript_text():
+    with FakeWyomingServer(reply="hello world") as server:
+        stt = WyomingWhisperSTT(host="127.0.0.1", port=server.port)
+        assert stt.transcribe(np.zeros(1600, dtype=np.int16)) == "hello world"
+
+
+def test_sends_events_in_protocol_order():
+    with FakeWyomingServer() as server:
+        WyomingWhisperSTT(host="127.0.0.1", port=server.port).transcribe(
+            np.zeros(1600, dtype=np.int16)
+        )
+    types = [e.type for e in server.events]
+    assert Transcribe.is_type(types[0])
+    assert AudioStart.is_type(types[1])
+    assert AudioStop.is_type(types[-1])
+    assert len(types) > 3
+    assert all(AudioChunk.is_type(t) for t in types[2:-1])
+
+
+def test_sends_language_and_audio_format():
+    with FakeWyomingServer() as server:
+        WyomingWhisperSTT(host="127.0.0.1", port=server.port).transcribe(
+            np.zeros(1600, dtype=np.int16), language="en"
+        )
+    assert server.of_type(Transcribe)[0].language == "en"
+    start = server.of_type(AudioStart)[0]
+    assert (start.rate, start.width, start.channels) == (SAMPLE_RATE, 2, 1)
+
+
+def test_int16_audio_is_sent_unchanged_in_chunks():
+    audio = np.arange(-2500, 2500, dtype=np.int16)  # 5000 samples
+    with FakeWyomingServer() as server:
+        WyomingWhisperSTT(host="127.0.0.1", port=server.port).transcribe(audio)
+    chunks = server.of_type(AudioChunk)
+    assert len(chunks) == -(-len(audio) // CHUNK_SAMPLES)  # ceiling division
+    assert all(len(c.audio) <= CHUNK_SAMPLES * 2 for c in chunks)
+    np.testing.assert_array_equal(received_audio(server), audio)
+
+
+def test_float_audio_is_clipped_and_converted_to_int16():
+    audio = np.array([0.0, 0.5, -0.5, 1.0, -1.0, 2.0, -2.0], dtype=np.float32)
+    with FakeWyomingServer() as server:
+        WyomingWhisperSTT(host="127.0.0.1", port=server.port).transcribe(audio)
+    np.testing.assert_array_equal(
+        received_audio(server),
+        np.array([0, 16383, -16383, 32767, -32767, 32767, -32767], dtype=np.int16),
+    )
+
+
+def test_server_closing_without_transcript_raises():
+    with FakeWyomingServer(reply=None) as server:
+        stt = WyomingWhisperSTT(host="127.0.0.1", port=server.port)
+        with pytest.raises(ConnectionError):
+            stt.transcribe(np.zeros(1600, dtype=np.int16))

voxport-0.4.0/voxport/stt/base.py

@@ -0,0 +1,26 @@
+"""STTEngine port: the interface every speech-to-text adapter implements.
+
+Callers depend only on this interface, not on any particular engine's
+internals, so swapping the underlying engine later means writing one new
+adapter, not touching any call site.
+"""
+
+from abc import ABC, abstractmethod
+
+
+class STTEngine(ABC):
+    """Transcribes speech to text."""
+
+    #: Sample rate, in Hz, `transcribe()` expects the input audio at.
+    sample_rate: int
+
+    @abstractmethod
+    def transcribe(self, audio) -> str:
+        """Return the transcribed text for `audio`.
+
+        `audio` is a 1-D numpy array of audio samples at `self.sample_rate`.
+        A concrete adapter may accept additional, engine-specific keyword
+        arguments beyond this minimal signature — callers that don't need
+        them can ignore this possibility entirely.
+        """
+        raise NotImplementedError

voxport-0.4.0/voxport/stt/wyoming_whisper.py

@@ -0,0 +1,101 @@
+"""WyomingWhisperSTT: network client to a running Wyoming Whisper server.
+
+Unlike `KokoroDirectTTS` (in-process, model resident in the calling
+process), this is a network client by design — no model loading, no local
+Whisper install, all transcription work happens on the server. That
+matches the actual use case: Home Assistant's own voice pipeline already
+runs a Wyoming Whisper server, so this adapter talks to the same kind of
+server rather than duplicating it.
+"""
+
+import asyncio
+
+try:
+    from wyoming.asr import Transcribe, Transcript
+    from wyoming.audio import AudioChunk, AudioStart, AudioStop
+    from wyoming.client import AsyncTcpClient
+except ImportError as exc:
+    # wyoming is an optional dependency (the `wyoming` extra).
+    raise ImportError(
+        "WyomingWhisperSTT needs the optional Wyoming dependency: "
+        "pip install 'voxport[wyoming]'"
+    ) from exc
+
+from voxport.stt.base import STTEngine
+
+# Wyoming Whisper servers expect 16-bit mono PCM at 16 kHz.
+SAMPLE_RATE = 16000
+SAMPLE_WIDTH = 2  # bytes per sample (16-bit)
+CHANNELS = 1
+
+# Audio is streamed to the server in chunks rather than one giant payload.
+CHUNK_SAMPLES = 1024
+
+
+class WyomingWhisperSTT(STTEngine):
+    """Speech-to-text via a Wyoming-protocol Whisper server (e.g.
+    `rhasspy/wyoming-whisper`) — the same kind of server Home Assistant's
+    own voice pipeline talks to.
+
+    Connects fresh for each `transcribe()` call; the server keeps its
+    model resident, not this client. Host/port are configurable (not
+    hardcoded) since this will eventually point at different hardware —
+    a dedicated always-on machine, rather than localhost — once that
+    exists.
+    """
+
+    sample_rate = SAMPLE_RATE
+
+    def __init__(self, host: str = "localhost", port: int = 10300):
+        self.host = host
+        self.port = port
+
+    def transcribe(self, audio, language: str | None = None) -> str:
+        """Return the transcribed text for `audio`.
+
+        `audio` is a 1-D numpy array at `self.sample_rate` — int16 samples,
+        or float samples in [-1, 1] (auto-converted to int16).
+
+        This runs its own asyncio event loop internally (the Wyoming
+        client library is async-only) — call it from a worker thread
+        (`asyncio.to_thread`) when calling from code that already has an
+        event loop running, the same way `KokoroDirectTTS.synthesize()` is
+        called from loremaster's bot.
+        """
+        return asyncio.run(self._transcribe_async(audio, language))
+
+    async def _transcribe_async(self, audio, language):
+        import numpy as np
+
+        audio = np.asarray(audio)
+        if np.issubdtype(audio.dtype, np.floating):
+            audio = np.clip(audio, -1.0, 1.0)
+            audio = (audio * 32767).astype(np.int16)
+        elif audio.dtype != np.int16:
+            audio = audio.astype(np.int16)
+        audio_bytes = audio.tobytes()
+
+        async with AsyncTcpClient(self.host, self.port) as client:
+            await client.write_event(Transcribe(language=language).event())
+            await client.write_event(
+                AudioStart(rate=self.sample_rate, width=SAMPLE_WIDTH, channels=CHANNELS).event()
+            )
+
+            chunk_bytes = CHUNK_SAMPLES * SAMPLE_WIDTH
+            for offset in range(0, len(audio_bytes), chunk_bytes):
+                chunk = audio_bytes[offset:offset + chunk_bytes]
+                await client.write_event(
+                    AudioChunk(rate=self.sample_rate, width=SAMPLE_WIDTH,
+                               channels=CHANNELS, audio=chunk).event()
+                )
+
+            await client.write_event(AudioStop().event())
+
+            while True:
+                event = await client.read_event()
+                if event is None:
+                    raise ConnectionError(
+                        "Wyoming server closed the connection without sending a transcript."
+                    )
+                if Transcript.is_type(event.type):
+                    return Transcript.from_event(event).text

voxport-0.4.0/voxport/tts/base.py

@@ -0,0 +1,27 @@
+"""TTSEngine port: the interface every text-to-speech adapter implements.
+
+Callers depend only on this interface, not on any particular engine's
+internals, so swapping the underlying engine later means writing one new
+adapter, not touching any call site.
+"""
+
+from abc import ABC, abstractmethod
+
+
+class TTSEngine(ABC):
+    """Synthesizes speech from text."""
+
+    #: Sample rate, in Hz, of the audio returned by `synthesize()`.
+    sample_rate: int
+
+    @abstractmethod
+    def synthesize(self, text: str, voice: str, speed: float = 1.0):
+        """Return synthesized audio for `text` spoken in `voice`.
+
+        Returns a 1-D numpy array of audio samples at `self.sample_rate`.
+        A concrete adapter may accept additional, engine-specific keyword
+        arguments beyond this minimal signature (e.g. `KokoroDirectTTS`
+        accepts an optional `lang_code` override) — callers that don't need
+        them can ignore this possibility entirely.
+        """
+        raise NotImplementedError

voxport-0.4.0/voxport/tts/kokoro_direct.py

@@ -0,0 +1,128 @@
+"""KokoroDirectTTS: in-process Kokoro TTS adapter.
+
+Loads the Kokoro model directly into the calling process (no server, no
+network hop) and keeps it resident in memory, favoring simplicity and lower
+latency over sharing one server across processes. This is the chosen
+approach for all current consumers (podcast generation, loremaster, Home
+Assistant); revisit only if resource use across multiple resident processes
+becomes a real problem.
+"""
+
+import os
+
+# Kokoro and torch are optional dependencies (the `kokoro` extra), so a
+# missing one gets an install hint rather than a bare ModuleNotFoundError.
+_MISSING_EXTRA = (
+    "KokoroDirectTTS needs the optional Kokoro dependencies: "
+    "pip install 'voxport[kokoro]'"
+)
+
+# voxport/tts/kokoro_direct.py -> voxport/tts -> voxport -> repo root
+REPO_ROOT = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+# In a source checkout, an existing `hf_cache/` folder at the repo root is
+# used as the Hugging Face cache (HF_HOME), so a pre-populated cache can be
+# copied between checkouts (e.g. onto a machine that can't reach
+# huggingface.co). Only if that folder already exists: a regular pip install
+# has no repo root (REPO_ROOT is site-packages), and there the standard
+# Hugging Face cache location is used. An HF_HOME already set by the user
+# always wins. Set before any Kokoro-related import.
+_REPO_HF_CACHE = os.path.join(REPO_ROOT, "hf_cache")
+if os.path.isdir(_REPO_HF_CACHE):
+    os.environ.setdefault("HF_HOME", _REPO_HF_CACHE)
+
+# Offline mode is opt-in, not forced here: only a machine that actually needs
+# it (e.g. one behind a firewall that blocks huggingface.co) should set
+# HF_HUB_OFFLINE=1 itself, in its own shell/.env — this module never sets it,
+# so a machine with normal internet access can still download any voice not
+# already in the local hf_cache above.
+
+# In conda/miniforge environments, PyTorch's bundled OpenMP runtime (libomp)
+# can collide with Intel's (libiomp5md, pulled in by MKL), causing "OMP Error
+# #15" and a failed import. Allowing the duplicate runtime is the standard,
+# widely-used workaround for CPU inference. Set before torch is imported
+# (Kokoro imports it lazily, inside _build_pipeline below).
+os.environ.setdefault("KMP_DUPLICATE_LIB_OK", "TRUE")
+
+# Import torch here, at module import time, before any caller has a chance to
+# import numpy/soundfile/kokoro first and pull in Intel's OpenMP (MKL) runtime
+# ahead of torch's own. The reverse order breaks torch's DLL resolution on
+# Windows/conda with a WinError 127 on shm.dll — importing torch as the very
+# first thing this module does, regardless of what a caller does afterward,
+# is what makes that safe to rely on from any consumer.
+try:
+    import torch  # noqa: F401
+except ImportError as exc:
+    raise ImportError(_MISSING_EXTRA) from exc
+
+from voxport.tts.base import TTSEngine
+
+# Kokoro produces audio at a fixed 24 kHz sample rate.
+SAMPLE_RATE = 24000
+
+
+class KokoroDirectTTS(TTSEngine):
+    """In-process Kokoro TTS, model loaded once per language and reused.
+
+    A single instance may be reused across many `synthesize()` calls —
+    pipelines are cached by language code, so a run that mixes accents
+    (e.g. an American and a British voice) loads each accent's model at
+    most once.
+    """
+
+    sample_rate = SAMPLE_RATE
+
+    def __init__(self):
+        self._pipelines = {}
+
+    @staticmethod
+    def _build_pipeline(lang_code):
+        # torch is already imported at module load time (see top of file);
+        # Kokoro is safe to import lazily here, on first actual use.
+        try:
+            from kokoro import KPipeline
+        except ImportError as exc:
+            raise ImportError(_MISSING_EXTRA) from exc
+
+        # Pass repo_id explicitly to suppress Kokoro's "defaulting repo_id"
+        # warning.
+        return KPipeline(lang_code=lang_code, repo_id="hexgrad/Kokoro-82M")
+
+    def _get_pipeline(self, lang_code):
+        if lang_code not in self._pipelines:
+            print(f"Loading Kokoro model for language '{lang_code}'...")
+            self._pipelines[lang_code] = self._build_pipeline(lang_code)
+        return self._pipelines[lang_code]
+
+    def synthesize(self, text: str, voice: str, speed: float = 1.0, lang_code: str | None = None):
+        """Return synthesized audio for `text` as a single numpy array.
+
+        The accent/language pipeline is derived from the voice's first
+        letter ('a' American, 'b' British, ...), matching Kokoro's own
+        voice-naming convention, unless `lang_code` pins one explicitly.
+
+        Kokoro automatically splits `text` into natural segments (on
+        sentence and paragraph boundaries), so there is no character limit
+        to work around; the per-segment audio is concatenated before return.
+        """
+        import numpy as np
+
+        pipeline = self._get_pipeline(lang_code or voice[0])
+
+        print(f"Generating audio locally with Kokoro (voice={voice}, speed={speed})...")
+
+        segments = []
+        generator = pipeline(text, voice=voice, speed=speed)
+        for index, (_graphemes, _phonemes, audio) in enumerate(generator, start=1):
+            print(f"  Segment {index}...")
+            # `audio` may be a torch tensor or a numpy array; normalize to numpy.
+            if hasattr(audio, "detach"):
+                audio = audio.detach().cpu().numpy()
+            else:
+                audio = np.asarray(audio)
+            segments.append(audio)
+
+        if not segments:
+            raise ValueError("Kokoro produced no audio segments for the given text.")
+
+        return np.concatenate(segments)

voxport-0.4.0/voxport.egg-info/PKG-INFO

@@ -0,0 +1,218 @@
+Metadata-Version: 2.4
+Name: voxport
+Version: 0.4.0
+Summary: Text-to-speech and speech-to-text interfaces with swappable engine adapters (Kokoro, Wyoming Whisper).
+Author: Brien Alkire
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/brienalkire/voxport
+Project-URL: Repository, https://github.com/brienalkire/voxport
+Project-URL: Changelog, https://github.com/brienalkire/voxport/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/brienalkire/voxport/issues
+Keywords: tts,stt,text-to-speech,speech-to-text,speech,voice,kokoro,whisper,wyoming
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=2.0
+Provides-Extra: kokoro
+Requires-Dist: kokoro>=0.9.4; extra == "kokoro"
+Requires-Dist: torch>=2.12.0; extra == "kokoro"
+Provides-Extra: wyoming
+Requires-Dist: wyoming>=1.5.0; extra == "wyoming"
+Provides-Extra: all
+Requires-Dist: voxport[kokoro,wyoming]; extra == "all"
+Dynamic: license-file
+
+# voxport
+
+Small Python interfaces for text-to-speech and speech-to-text, with
+swappable engine adapters. Your code calls one method,
+`synthesize()` or `transcribe()`, and never touches an engine's API
+directly, so switching engines means changing one line where the adapter
+is created.
+
+```
+TTSEngine.synthesize(text, voice) -> audio
+STTEngine.transcribe(audio) -> text
+```
+
+Included adapters:
+
+- **`KokoroDirectTTS`**: runs the [Kokoro](https://huggingface.co/hexgrad/Kokoro-82M)
+  TTS model in your own process. The model loads once and stays in
+  memory, with no server and no network hop.
+- **`WyomingWhisperSTT`**: a client for a [Wyoming](https://github.com/OHF-Voice/wyoming)
+  protocol Whisper server, the same kind of server Home Assistant's voice
+  pipeline uses. It loads no model itself; transcription happens on the
+  server.
+
+voxport is a library only: it has no command-line tool or app of its
+own. It is pre-1.0, so the API may still change between minor versions
+(see the [changelog](https://github.com/brienalkire/voxport/blob/main/CHANGELOG.md)).
+
+## Installation
+
+Requires Python 3.10+. Each adapter's dependencies are an optional
+extra, so you install only what you use:
+
+```
+pip install "voxport[kokoro]"    # KokoroDirectTTS
+pip install "voxport[wyoming]"   # WyomingWhisperSTT
+pip install "voxport[all]"       # both
+```
+
+| Extra | Adds | For |
+|---|---|---|
+| `kokoro` | Kokoro, torch (about 2 GB) | `KokoroDirectTTS` |
+| `wyoming` | wyoming | `WyomingWhisperSTT` |
+| `all` | both of the above | everything |
+
+A plain `pip install voxport` includes only the interfaces and numpy.
+Importing an adapter without its extra raises an `ImportError` that
+names the extra to install.
+
+Things voxport doesn't install for you:
+
+- `WyomingWhisperSTT` needs a running Wyoming Whisper server. See
+  [Running a Wyoming Whisper server](#running-a-wyoming-whisper-server).
+- On first use, Kokoro downloads its model weights and voice packs from
+  Hugging Face, and spaCy's `en_core_web_sm` English model. See
+  [Offline use](#offline-use) for machines that can't reach those.
+- `soundfile`, used in the examples below to write WAV files.
+
+## Usage
+
+### Text to speech
+
+```python
+import soundfile as sf
+from voxport.tts.kokoro_direct import KokoroDirectTTS
+
+tts = KokoroDirectTTS()  # reuse one instance; models load once per accent
+audio = tts.synthesize("Hello from voxport.", voice="af_heart", speed=1.0)
+sf.write("hello.wav", audio, tts.sample_rate)  # 24 kHz mono
+```
+
+`synthesize()` returns a 1-D numpy array. The first letter of the voice
+name picks the accent (`a` American, `b` British, ...), following
+Kokoro's voice naming; pass `lang_code=` to override it. Kokoro splits
+long text into segments itself, so there is no length limit.
+
+### Speech to text
+
+```python
+from voxport.stt.wyoming_whisper import WyomingWhisperSTT
+
+stt = WyomingWhisperSTT(host="localhost", port=10300)  # the defaults
+text = stt.transcribe(audio_16k, language="en")
+```
+
+`audio_16k` is a 1-D numpy array of mono audio at `stt.sample_rate`
+(16 kHz), either int16 samples or floats in [-1, 1]. Resample first if
+your audio has a different rate; Kokoro's output, for example, is
+24 kHz. Each call opens a new connection to the server.
+
+### From async code
+
+Both calls block, and `transcribe()` runs its own asyncio event loop, so
+from code that already has a running loop, call them in a worker thread:
+
+```python
+audio = await asyncio.to_thread(tts.synthesize, text, "bm_george")
+text = await asyncio.to_thread(stt.transcribe, audio_16k, "en")
+```
+
+## Writing your own adapter
+
+An adapter subclasses `TTSEngine` or `STTEngine`, sets `sample_rate`,
+and implements the one abstract method:
+
+```python
+import numpy as np
+from voxport.tts.base import TTSEngine
+
+class SilenceTTS(TTSEngine):
+    """A toy engine: one second of silence, whatever the text."""
+
+    sample_rate = 16000
+
+    def synthesize(self, text: str, voice: str, speed: float = 1.0):
+        return np.zeros(self.sample_rate, dtype=np.float32)
+```
+
+Code written against `TTSEngine` works with `SilenceTTS` and
+`KokoroDirectTTS` unchanged. Adapters may accept extra, engine-specific
+keyword arguments (like `KokoroDirectTTS`'s `lang_code`), as long as the
+base signature still works.
+
+## Offline use
+
+By default, Kokoro's weights and voice packs download to Hugging Face's
+standard cache (`~/.cache/huggingface`, or wherever `HF_HOME` points).
+To run on a machine that can't reach huggingface.co:
+
+1. On a machine with internet access, synthesize once with each voice
+   you plan to use, so the model and those voice packs are cached.
+2. Copy that cache to the offline machine, keeping Hugging Face's
+   `hub/models--<org>--<name>/...` layout, and point `HF_HOME` at it.
+3. Set `HF_HUB_OFFLINE=1` on the offline machine. voxport never sets
+   this for you. With it set, only voices already in the cache work; an
+   uncached voice fails with a Hub connection error instead of
+   downloading.
+
+Kokoro's English phonemizer also needs spaCy's `en_core_web_sm` model,
+which downloads from GitHub, not Hugging Face, so `HF_HUB_OFFLINE`
+doesn't cover it. It downloads once per Python environment, so install
+it while online:
+
+```
+python -m spacy download en_core_web_sm
+```
+
+**Repo-local cache (source checkouts only).** If you run voxport from a
+clone, you can keep the cache inside it instead: create an `hf_cache/`
+folder at the repo root (it's gitignored) and `KokoroDirectTTS` uses it
+as `HF_HOME`, unless you've set `HF_HOME` yourself. That makes the
+cache easy to copy along with the checkout.
+
+## Running a Wyoming Whisper server
+
+`WyomingWhisperSTT` needs a server to talk to. For local testing, the
+easiest option is the [`rhasspy/wyoming-whisper`](https://github.com/rhasspy/wyoming-faster-whisper)
+Docker image:
+
+```
+docker run -d --name whisper --restart unless-stopped -p 10300:10300 -v wyoming-data:/data rhasspy/wyoming-whisper --model tiny-int8 --language en
+```
+
+The image is named `rhasspy/wyoming-whisper`, even though its GitHub
+repo is `wyoming-faster-whisper`. `docker logs whisper` shows `Ready`
+once the model has loaded. `tiny-int8` is small and fast but not very
+accurate; use a larger model when transcription quality matters.
+
+If you already run Home Assistant with its Whisper add-on, you can point
+`WyomingWhisperSTT` at that server's host and port instead.
+
+## Development
+
+```
+git clone https://github.com/brienalkire/voxport.git
+cd voxport
+pip install -e ".[all]" pytest
+python -m pytest
+```
+
+The tests need no network, no Whisper server and no Kokoro model:
+`WyomingWhisperSTT` is tested against a fake in-process Wyoming server.
+Installing `.[wyoming]` instead of `.[all]` is enough to run them and
+skips the 2 GB torch download.
+
+## License
+
+[MIT](https://github.com/brienalkire/voxport/blob/main/LICENSE)

voxport-0.4.0/voxport.egg-info/SOURCES.txt

@@ -0,0 +1,18 @@
+LICENSE
+README.md
+pyproject.toml
+tests/test_interfaces.py
+tests/test_optional_extras.py
+tests/test_wyoming_whisper.py
+voxport/__init__.py
+voxport.egg-info/PKG-INFO
+voxport.egg-info/SOURCES.txt
+voxport.egg-info/dependency_links.txt
+voxport.egg-info/requires.txt
+voxport.egg-info/top_level.txt
+voxport/stt/__init__.py
+voxport/stt/base.py
+voxport/stt/wyoming_whisper.py
+voxport/tts/__init__.py
+voxport/tts/base.py
+voxport/tts/kokoro_direct.py

voxport-0.4.0/voxport.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

voxport-0.4.0/voxport.egg-info/requires.txt

@@ -0,0 +1,11 @@
+numpy>=2.0
+
+[all]
+voxport[kokoro,wyoming]
+
+[kokoro]
+kokoro>=0.9.4
+torch>=2.12.0
+
+[wyoming]
+wyoming>=1.5.0

voxport-0.4.0/voxport.egg-info/top_level.txt

@@ -0,0 +1 @@
+voxport