gortium
cfe9e9c4b9
- Moved __init__.py and plugin.yaml into hermes_piper_plugin/ package directory - Added pyproject.toml with build config and entry point registration - Updated tests to reference new subdirectory paths - Updated README with pip-based installation instructions This converts the plugin from a flat layout (loaded via hermes plugins install) to a proper pip package with the 'hermes_agent.plugins' entry point.
80 lines
2.5 KiB
Markdown
80 lines
2.5 KiB
Markdown
# Hermes Piper Plugin
|
|
|
|
Makes Piper TTS the default provider instead of Microsoft Edge TTS.
|
|
|
|
**Zero modifications to the Hermes repo.** No fork required. The plugin
|
|
monkey-patches `tools.tts_tool.DEFAULT_PROVIDER` at plugin load time.
|
|
|
|
## Why
|
|
|
|
- Piper is local, free, CPU-only — no API key, no cloud dependency
|
|
- Edge TTS requires internet access and ffmpeg for Telegram voice bubbles
|
|
- This eliminates the need to maintain a fork just to change the default
|
|
|
|
## How it works
|
|
|
|
```python
|
|
# At plugin load time, this single line runs:
|
|
tools.tts_tool.DEFAULT_PROVIDER = "piper"
|
|
```
|
|
|
|
That's it. `DEFAULT_PROVIDER` is read at call time, so changing it after
|
|
import is safe. The plugin also logs the effective default at session start.
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
# Install from the internal Hermes package registry
|
|
pip install hermes-piper-plugin
|
|
|
|
# Or install in editable mode for development
|
|
git clone https://code.lazyworkhorse.net/gortium/hermes-piper-plugin.git
|
|
cd hermes-piper-plugin
|
|
pip install -e .
|
|
```
|
|
|
|
> **Note:** The plugin used to be installed via `hermes plugins install` from the
|
|
> old flat layout. It is now a proper pip package. The entry point
|
|
> `hermes_agent.plugins` is registered automatically when you install the
|
|
> package — Hermes discovers it on next startup.
|
|
|
|
## Testing
|
|
|
|
```bash
|
|
cd /path/to/hermes-piper-plugin
|
|
pip install pytest pyyaml
|
|
python -m pytest tests/ -v
|
|
```
|
|
|
|
Tests cover:
|
|
|
|
- **Manifest validation** — confirms plugin.yaml structure and required fields
|
|
- **Monkey-patch logic** — verifies DEFAULT_PROVIDER is changed to 'piper'
|
|
- **Idempotency** — calling `_apply_piper_patch()` twice is safe
|
|
- **Error handling** — import failures and exceptions are caught gracefully
|
|
- **Lifecycle hooks** — on_session_start fires without errors
|
|
- **Plugin registration** — register() wires tools, hooks, and logging correctly
|
|
|
|
## Config
|
|
|
|
The plugin changes the **default** provider. You can still override per
|
|
session by setting `tts.provider` in `~/.hermes/config.yaml`:
|
|
|
|
```yaml
|
|
tts:
|
|
provider: elevenlabs # override per-session
|
|
voice: "Adam" # ElevenLabs voice
|
|
```
|
|
|
|
## Requires
|
|
|
|
- `piper-tts` Python package (installed via pip)
|
|
- Piper voice models (downloaded automatically on first use, ~50MB each)
|
|
|
|
## Safety
|
|
|
|
- If `piper-tts` is not installed, the TTS tool returns an error asking
|
|
the user to install it — no silent fallback to Edge
|
|
- Removing the plugin restores the original Hermes default (Edge)
|
|
- No data loss risk. No changes to any file in the Hermes repo.
|