agent-voice 0.5.0__tar.gz

agent_voice-0.5.0/.github/scripts/verify_package.py

@@ -0,0 +1,181 @@
+from __future__ import annotations
+
+import json
+import os
+import platform
+import re
+import subprocess
+import sys
+import time
+import urllib.request
+import wave
+from pathlib import Path
+
+import imageio_ffmpeg
+
+SERVICE_URL = "http://127.0.0.1:18765"
+
+
+def run_cli(cli: Path, *args: str) -> dict[str, object]:
+    completed = subprocess.run(
+        [str(cli), *args],
+        check=True,
+        capture_output=True,
+        text=True,
+    )
+    return json.loads(completed.stdout.strip().splitlines()[-1])
+
+
+def validate_decodable(path: Path) -> None:
+    ffmpeg = imageio_ffmpeg.get_ffmpeg_exe()
+    assert "imageio_ffmpeg" in Path(ffmpeg).as_posix()
+    completed = subprocess.run(
+        [
+            ffmpeg,
+            "-v",
+            "error",
+            "-i",
+            str(path),
+            "-f",
+            "s16le",
+            "-acodec",
+            "pcm_s16le",
+            "pipe:1",
+        ],
+        check=True,
+        capture_output=True,
+    )
+    assert completed.stdout
+
+
+def validate_wav(path: Path) -> None:
+    with wave.open(str(path), "rb") as audio:
+        assert audio.getnchannels() == 1
+        assert audio.getframerate() == 24_000
+        assert audio.getnframes() > 0
+    validate_decodable(path)
+
+
+def validate_mp3(path: Path) -> None:
+    assert path.suffix == ".mp3"
+    validate_decodable(path)
+
+
+def check_doctor(report: dict[str, object], service_status: str) -> None:
+    assert report["ok"] is True
+    checks = {check["name"]: check for check in report["checks"]}
+    assert checks["model"]["status"] == "pass"
+    assert checks["runtime"]["status"] == "pass"
+    assert checks["compressed audio"]["status"] == "pass"
+    assert "bundled by imageio-ffmpeg" in checks["compressed audio"]["detail"]
+    assert checks["playback"]["status"] in {"pass", "warn"}
+    assert "miniaudio" in checks["playback"]["detail"]
+    assert checks["service"]["status"] == service_status
+
+
+def main() -> None:
+    cli = Path(sys.argv[1]).resolve()
+    system = platform.system()
+    output_dir = Path(os.environ["RUNNER_TEMP"]) / "agent-voice-package-e2e"
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    subprocess.run([str(cli), "setup", "--model", "int8"], check=True)
+    offline_doctor = run_cli(cli, "doctor", "--service-url", SERVICE_URL, "--json")
+    check_doctor(offline_doctor, "warn")
+
+    local_wav = output_dir / "local.wav"
+    local = run_cli(
+        cli,
+        "speak",
+        f"{system} generation verification.",
+        "--service",
+        "off",
+        "--output",
+        str(local_wav),
+    )
+    assert local["backend"] == "local"
+    assert local["played"] is False
+    validate_wav(local_wav)
+
+    labeled = run_cli(
+        cli,
+        "speak",
+        f"{system} labeled speed verification.",
+        "--service",
+        "off",
+        "--label",
+        "Package E2E",
+        "--format",
+        "mp3",
+        "--speed",
+        "1.5",
+    )
+    labeled_path = Path(str(labeled["path"]))
+    assert labeled["backend"] == "local"
+    assert labeled["speed"] == 1.5
+    assert re.fullmatch(
+        r"Package-E2E-\d{2}-\d{2}-\d{2}-at-\d{2}-\d{2}\.mp3",
+        labeled_path.name,
+    )
+    assert (
+        labeled_path.parent
+        == (Path(os.environ["AGENT_VOICE_HOME"]) / "recordings").resolve()
+    )
+    validate_mp3(labeled_path)
+
+    log_path = output_dir / "service.log"
+    with log_path.open("w", encoding="utf-8") as log:
+        service = subprocess.Popen(
+            [str(cli), "serve", "--port", "18765"],
+            stdout=log,
+            stderr=subprocess.STDOUT,
+            text=True,
+        )
+        try:
+            for _ in range(120):
+                if service.poll() is not None:
+                    raise RuntimeError(f"service exited with {service.returncode}")
+                try:
+                    with urllib.request.urlopen(
+                        f"{SERVICE_URL}/health", timeout=1
+                    ) as response:
+                        if json.loads(response.read()).get("status") == "ok":
+                            break
+                except OSError:
+                    time.sleep(1)
+            else:
+                raise RuntimeError("service did not become healthy")
+
+            online_doctor = run_cli(
+                cli, "doctor", "--service-url", SERVICE_URL, "--json"
+            )
+            check_doctor(online_doctor, "pass")
+
+            service_wav = output_dir / "service.wav"
+            remote = run_cli(
+                cli,
+                "speak",
+                f"{system} localhost service verification.",
+                "--service",
+                "on",
+                "--service-url",
+                SERVICE_URL,
+                "--output",
+                str(service_wav),
+            )
+            assert remote["backend"] == "service"
+            assert remote["played"] is False
+            validate_wav(service_wav)
+        finally:
+            service.terminate()
+            try:
+                service.wait(timeout=10)
+            except subprocess.TimeoutExpired:
+                service.kill()
+                service.wait(timeout=10)
+    print(log_path.read_text(encoding="utf-8", errors="replace"))
+    print(f"Verified installed package on {system}")
+
+
+if __name__ == "__main__":
+    main()

agent_voice-0.5.0/.github/workflows/ci.yml

@@ -0,0 +1,110 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: ${{ matrix.os }} / Python ${{ matrix.python-version }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python-version: ["3.11", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        with:
+          enable-cache: true
+          python-version: ${{ matrix.python-version }}
+
+      - name: Cache verified Kokoro model
+        if: matrix.python-version == '3.13'
+        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
+        with:
+          path: ${{ runner.temp }}/agent-voice-data/models
+          key: kokoro-v1-int8-${{ runner.os }}-${{ runner.arch }}
+
+      - name: Lint
+        if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.11'
+        run: uv run --frozen ruff check src tests .github/scripts
+
+      - name: Test
+        run: uv run --frozen pytest -q
+
+      - name: Build package
+        if: matrix.python-version == '3.13'
+        run: uv build
+
+      - name: Install built wheel
+        if: matrix.python-version == '3.13'
+        run: |
+          uv venv --python ${{ matrix.python-version }} .ci-venv
+          uv pip install --python .ci-venv/bin/python dist/*.whl
+
+      - name: Verify installed package with real model, audio, doctor, and service
+        if: matrix.python-version == '3.13'
+        env:
+          AGENT_VOICE_HOME: ${{ runner.temp }}/agent-voice-data
+        run: |
+          .ci-venv/bin/python .github/scripts/verify_package.py .ci-venv/bin/agent-voice
+
+  windows:
+    name: windows-latest / Python ${{ matrix.python-version }}
+    runs-on: windows-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        with:
+          enable-cache: true
+          python-version: ${{ matrix.python-version }}
+
+      - name: Cache verified Kokoro model
+        if: matrix.python-version == '3.13'
+        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
+        with:
+          path: ${{ runner.temp }}/agent-voice-data/models
+          key: kokoro-v1-int8-${{ runner.os }}-${{ runner.arch }}
+
+      - name: Test
+        run: uv run --frozen pytest -q
+
+      - name: Build package
+        if: matrix.python-version == '3.13'
+        run: uv build
+
+      - name: Install built wheel
+        if: matrix.python-version == '3.13'
+        shell: pwsh
+        run: |
+          uv venv --python ${{ matrix.python-version }} .ci-venv
+          $wheel = (Get-ChildItem dist\*.whl).FullName
+          uv pip install --python .ci-venv\Scripts\python.exe $wheel
+
+      - name: Verify installed package with real model, audio, doctor, and service
+        if: matrix.python-version == '3.13'
+        shell: pwsh
+        env:
+          AGENT_VOICE_HOME: ${{ runner.temp }}/agent-voice-data
+        run: |
+          .ci-venv\Scripts\python.exe .github\scripts\verify_package.py .ci-venv\Scripts\agent-voice.exe

agent_voice-0.5.0/.github/workflows/publish.yml

@@ -0,0 +1,51 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+
+      - name: Build wheel and source distribution
+        run: uv build
+
+      - name: Validate package metadata
+        run: uvx twine check dist/*
+
+      - name: Upload distribution
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  publish:
+    name: Publish distribution
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/agent-voice
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Download distribution
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

agent_voice-0.5.0/.gitignore

@@ -0,0 +1,21 @@
+.venv/
+.DS_Store
+__pycache__/
+.pytest_cache/
+.ruff_cache/
+.agents/
+skills-lock.json
+*.pyc
+*.egg-info/
+dist/
+config.json
+service-start.lock
+viewer.lock
+viewer.json
+models/*.onnx
+models/*.bin
+models/*.lock
+recordings/*
+IDEAS.md
+!models/.gitkeep
+!recordings/.gitkeep

agent_voice-0.5.0/.python-version

@@ -0,0 +1 @@
+3.11

agent_voice-0.5.0/LICENSE

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

agent_voice-0.5.0/PKG-INFO

@@ -0,0 +1,200 @@
+Metadata-Version: 2.4
+Name: agent-voice
+Version: 0.5.0
+Summary: Local, free voice artifacts for AI agents
+Project-URL: Repository, https://github.com/yoav0gal/agent-voice
+Project-URL: Issues, https://github.com/yoav0gal/agent-voice/issues
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,audio,cli,kokoro,speech,text-to-speech,tts
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+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: Topic :: Multimedia :: Sound/Audio :: Speech
+Requires-Python: <3.14,>=3.11
+Requires-Dist: filelock<4,>=3.20
+Requires-Dist: imageio-ffmpeg==0.6.0
+Requires-Dist: kokoro-onnx==0.5.0
+Requires-Dist: miniaudio==1.71
+Requires-Dist: numpy<3,>=2
+Description-Content-Type: text/markdown
+
+# Agent Voice
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="assets/brand/agent-voice-logo-voiceprint-dark.svg">
+  <source media="(prefers-color-scheme: light)" srcset="assets/brand/agent-voice-logo-voiceprint.svg">
+  <img src="assets/brand/agent-voice-logo-voiceprint.svg" alt="Agent Voice logo" width="720">
+</picture>
+
+https://github.com/user-attachments/assets/975dcfd0-17ec-4912-b3b1-ec084077f858
+
+Local text-to-speech for people and AI agents, powered by
+[Kokoro-82M](https://huggingface.co/hexgrad/Kokoro-82M) (only English is supported).
+
+Agent Voice creates WAV, MP3, Opus, or M4A recordings on macOS, Linux, and
+Windows without an API key.
+
+Prebuilt dependencies cover macOS arm64/x64, Linux x64, and Windows x64.
+Linux arm64 currently needs a C build toolchain for miniaudio. Native Windows
+arm64 lacks an `imageio-ffmpeg` wheel; use x64 Python under Windows emulation.
+
+## Quick start
+
+```sh
+uv tool install agent-voice
+agent-voice setup
+agent-voice speak "Hello from Agent Voice." --play
+```
+
+`agent-voice setup` downloads and verifies the speech model.
+
+## How to use
+
+```sh
+# See every recording option
+agent-voice speak --help
+
+# Create a recording
+agent-voice speak "The build is finished."
+
+# Play an existing recording
+agent-voice play "/absolute/path/recording.mp3"
+
+# Create an MP3 with a readable filename
+agent-voice speak "Here is your summary." --format mp3 --label summary
+
+# Choose a voice, speed, and exact output
+agent-voice speak "A slower reading." \
+  --voice bf_emma --speed 0.85 --output recording.opus
+
+# Safely pass agent text through stdin
+printf '%s' "$VISIBLE_TEXT" |
+  agent-voice speak --format mp3
+```
+
+Every `agent-voice speak` command prints one machine-readable JSON receipt
+containing the recording's absolute `path`, percent-encoded `file_uri`, audio
+metadata, and a `delivery` object with optional `browser_url`, `audio_url`, and
+`recording_path` viewer facts.
+
+Agent Voice stores the recording plus private transcript metadata in its managed
+recordings directory. A lightweight localhost viewer renders the branded player
+document—with the recording name, native audio controls, and response text—and
+serves the actual WAV, MP3, Opus, or M4A recording. It starts automatically on
+port `8779`, or on a free port when `8779` is occupied.
+
+Agents use exactly two delivery routes:
+
+1. Render `path` with the current surface's native audio player.
+2. Otherwise render the installed skill's editable `recording-delivery.md`
+   template using the structured receipt values:
+
+   ````markdown
+   Agent Voice recording recording.mp3
+   Listen: [web player](http://127.0.0.1:8779/player/recording.html) · [media app](file:///absolute/path/recording.mp3) · [web audio](http://127.0.0.1:8779/recordings/recording.mp3)
+   ```sh
+   agent-voice play "/absolute/path/recording.mp3"
+   ```
+   ````
+
+The CLI owns delivery facts, not agent-facing recording prose. Each
+independently installable skill carries `references/recording-delivery.md`,
+where its wording can be customized. The skill derives the media link and
+playback command from the receipt's `file_uri` and `path`, omitting viewer links
+when those optional delivery facts are unavailable.
+
+The viewer prefers port `8779` so links survive restarts. If that port is
+occupied, it selects a free port and reports it in the receipt. The web player
+renders the complete branded document, the media-app link opens the local file
+with the operating system default, and web audio serves the recording directly
+over HTTP.
+
+The virtual player URL uses the recording name with an `.html` extension. If
+that name already belongs to another format, Agent Voice adds `-2`, `-3`, and
+so on.
+
+Manage the lightweight viewer explicitly when needed:
+
+```sh
+agent-voice viewer start
+agent-voice viewer stop
+```
+
+`--output` still writes the exact requested path. For HTTP delivery, Agent
+Voice copies that audio into the managed recordings directory instead of
+serving arbitrary filesystem paths or creating symlinks.
+
+Explore the available voices and models, manage defaults, or check that Agent
+Voice is ready:
+
+```sh
+agent-voice voices
+agent-voice models
+agent-voice config --voice bf_emma --speed 1.15
+agent-voice doctor --json
+```
+
+## Defaults
+
+Run `agent-voice config` to view the active persisted settings and their
+configuration file.
+
+| Setting | Built-in default | Save as default | Override once |
+| --- | --- | --- | --- |
+| Voice | `af_heart` | `config --voice NAME` | `speak --voice NAME` |
+| Speed | `1.0×` | `config --speed NUMBER` | `speak --speed NUMBER` |
+| Audio format | MP3 | `config --format FORMAT` | `speak --format FORMAT` |
+| Recording directory | Agent Voice's `recordings/` directory | `config --output-dir DIR` | `speak --output-dir DIR` |
+| Service | `timed` for `10` minutes | `config --service MODE [--service-timeout MINUTES]` | `speak --service MODE [--service-timeout MINUTES]` |
+
+`on` leaves the service running, `off` uses embedded inference, and `timed`
+stops the service after the configured number of idle minutes.
+
+The service setting is stored as one object. Timed mode includes its duration:
+
+```json
+{
+  "service": {
+    "mode": "timed",
+    "timeout_minutes": 10
+  }
+}
+```
+
+## Agent skills
+
+[View Agent Voice on skills.sh](https://skills.sh/b/yoav0gal/agent-voice).
+
+```sh
+# Create speech recordings or read text aloud
+npx skills add yoav0gal/agent-voice --skill create-speech-recording --global --agent codex --yes
+
+# Add audio to requested written responses
+npx skills add yoav0gal/agent-voice --skill spoken-response --global --agent codex --yes
+```
+
+Use `--agent '*'` instead of `--agent codex` to install the same skills for all
+agent destinations recognized by the skills CLI.
+
+## Local speech API
+
+```sh
+agent-voice serve
+
+curl http://127.0.0.1:8765/v1/audio/speech \
+  -H 'Content-Type: application/json' \
+  -d '{"input":"The task is complete.","voice":"af_heart","response_format":"mp3"}' \
+  --output speech.mp3
+```
+
+The speech API binds only to localhost. It is separate from the lightweight
+recording viewer. `agent-voice speak` uses the speech API automatically when
+available and falls back to embedded inference.