Skip to content

Agent Zero AI framework

Add Paradee as the default voice in Local TTS

Alessandroce48667e98ec
diff --git a/plugins/AGENTS.md b/plugins/AGENTS.md
index af059e4b1..372a60925 100644
--- a/plugins/AGENTS.md
+++ b/plugins/AGENTS.md
@@ -86,7 +86,7 @@ Direct child DOX files:
| [_error_retry/AGENTS.md](_error_retry/AGENTS.md) | Critical exception retry lifecycle hooks. |
| [_goal/AGENTS.md](_goal/AGENTS.md) | Built-in chat goal strip, `/goal` slash command, and agent-facing goal tools. |
| [_infection_check/AGENTS.md](_infection_check/AGENTS.md) | Prompt-injection safety analysis before tool execution. |
-| [_kokoro_tts/AGENTS.md](_kokoro_tts/AGENTS.md) | Kokoro text-to-speech integration. |
+| [_kokoro_tts/AGENTS.md](_kokoro_tts/AGENTS.md) | Local Paradee/Kokoro text-to-speech integration. |
| [_memory/AGENTS.md](_memory/AGENTS.md) | Optional persistent recall plugin, knowledge import, tools, and dashboard; do not assume it is enabled outside this plugin. |
| [_migrate_agents/AGENTS.md](_migrate_agents/AGENTS.md) | Built-in migration of chats, projects, memories, instructions, and skills from supported agent harnesses. |
| [_model_config/AGENTS.md](_model_config/AGENTS.md) | Model selection, presets, API-key checks, and scoped overrides. |
diff --git a/plugins/_kokoro_tts/AGENTS.md b/plugins/_kokoro_tts/AGENTS.md
index d9a6f1464..e9c17e4ca 100644
--- a/plugins/_kokoro_tts/AGENTS.md
+++ b/plugins/_kokoro_tts/AGENTS.md
@@ -2,22 +2,27 @@
## Purpose
-- Own built-in Kokoro text-to-speech integration and browser TTS fallback coordination.
+- Own local Paradee/Kokoro text-to-speech integration and browser TTS fallback coordination under the stable `_kokoro_tts` plugin identity.
## Ownership
- `api/` owns synthesize and status endpoints.
-- `helpers/` owns runtime and migration behavior.
-- `hooks.py` owns provider registration/lifecycle behavior.
+- `helpers/runtime.py` owns voice normalization and model dispatch; `helpers/paradee.py` owns the CPU ONNX runtime and phonemizer.
+- `helpers/migration.py` preserves the legacy `tts_kokoro` enable/disable setting.
+- `hooks.py` owns config hooks and idempotent Paradee dependency setup. Plugin-owned startup and enable extensions invoke the same `ensure_dependencies` hook.
- `webui/` owns settings and speech UI integration.
- `default_config.yaml`, `plugin.yaml`, and `README.md` own defaults, metadata, and behavior notes.
## Local Contracts
-- Keep Kokoro dependencies on Docker/bootstrap paths, not opportunistic runtime installs.
+- Additional Paradee dependencies (ONNX Runtime and the English spaCy model) belong to `hooks.py`, targeted at the current framework interpreter. Setup runs on install/update, enabled-plugin startup, and re-enable; already-current environments skip installation. Failures are logged and leave browser fallback available. Never install during synthesis or config reads.
- Preserve browser-native fallback when the plugin is disabled or unavailable.
- Do not expose generated speech artifacts outside intended response paths.
- Preserve `voice` and `speed` configuration compatibility; weighted blends stay in memory and use positive finite weights.
+- `voice: paradee` selects the single American English Heart voice and is the default for unconfigured settings. Saved Kokoro voices, blends, speed, and enable/disable choices remain unchanged; no provider-choice migration or dialog is needed.
+- Valid Kokoro weights take precedence over the voice string. Paradee is never a weighted voice; mixed expressions discard its reserved token and retain the Kokoro selection.
+- Paradee model assets stay under ignored `usr/plugins/_kokoro_tts/paradee/`, pinned to the Hugging Face `v1.0` revision. Long text is split without dropping phonemes and generated audio remains in response memory.
+- Model preload and status must describe the selected engine. The frontend voice picker replaces the selection when crossing between Paradee and Kokoro.
## Work Guidance
@@ -25,7 +30,8 @@
## Verification
-- Smoke-test status, synthesis, configured voice/speed, and disabled fallback behavior after changes.
+- Run `pytest tests/test_kokoro_tts.py tests/test_paradee_tts.py tests/test_speech_plugin_split.py tests/test_framework_dependencies.py`.
+- Smoke-test both engines, voice-picker transitions, speed, status, and disabled browser fallback after changes.
## Child DOX Index
diff --git a/plugins/_kokoro_tts/README.md b/plugins/_kokoro_tts/README.md
index e86092f56..f723f5356 100644
--- a/plugins/_kokoro_tts/README.md
+++ b/plugins/_kokoro_tts/README.md
@@ -1,20 +1,22 @@
-# Kokoro TTS
+# Local TTS (Kokoro & Paradee)
-Built-in speech synthesis plugin backed by Kokoro.
+Built-in local speech synthesis, retaining the `_kokoro_tts` plugin identity.
## Behavior
-- Registers Kokoro as the active TTS provider when the plugin is enabled.
-- Supports single voices, comma-separated equal blends, and optional in-memory weighted blends.
-- Keeps browser-native `speechSynthesis` as the fallback path when disabled.
-- Keeps Python dependencies on the core Docker/bootstrap path. This plugin does not install packages or binaries on demand.
-- Uses Kokoro's existing voice-pack cache and does not create persistent blend files.
+- Defaults to [Paradee-8M v1.0](https://huggingface.co/sahilmahendrakar/Paradee-8M-v1.0), a small CPU model with one American English Heart voice.
+- Select **Paradee · Heart** in the voice picker or choose a Kokoro voice. Paradee cannot be blended; selecting it replaces the current Kokoro selection.
+- Kokoro supports single voices, comma-separated equal blends, and optional in-memory weighted blends.
+- Existing saved voices, blends, speed, and enable/disable preferences are preserved. No startup choice dialog is shown.
+- Keeps browser-native `speechSynthesis` as the fallback path when disabled or synthesis fails.
+- Prepares Paradee's ONNX Runtime and English phonemizer dependencies through `hooks.py` on installation, updates, startup, and re-enable. Already-installed dependencies are reused; speech synthesis never installs packages.
+- Uses Kokoro's existing voice-pack cache and does not create persistent blend files. Paradee downloads its pinned ONNX model and vocabulary on first use into `usr/plugins/_kokoro_tts/paradee/`; later use works offline.
## Config
-- `voice`: Kokoro voice identifier or comma-separated equal blend
+- `voice`: `paradee` (default), a Kokoro voice identifier, or a comma-separated Kokoro blend
- `voice_weights`: optional mapping of voice identifiers to positive weights; when present, it defines the active blend
-- `speed`: Kokoro playback speed multiplier
+- `speed`: playback speed multiplier for either model (default `1.1`)
## Routes
diff --git a/plugins/_kokoro_tts/api/status.py b/plugins/_kokoro_tts/api/status.py
index 3b1321972..cf9093e70 100644
--- a/plugins/_kokoro_tts/api/status.py
+++ b/plugins/_kokoro_tts/api/status.py
@@ -7,25 +7,30 @@ from plugins._kokoro_tts.helpers import migration, runtime
class Status(ApiHandler):
async def process(self, input: dict, request: Request) -> dict | Response:
migration.ensure_migrated()
+ config = runtime.get_config()
+ engine = "paradee" if config["voice"] == "paradee" else "kokoro"
+ package_name = "onnxruntime" if engine == "paradee" else "kokoro"
package_version = ""
package_error = ""
try:
- package_version = importlib.metadata.version("kokoro")
+ package_version = importlib.metadata.version(package_name)
except Exception as e:
package_error = str(e)
return {
"plugin": "_kokoro_tts",
"enabled": runtime.is_globally_enabled(),
- "config": runtime.get_config(),
+ "config": config,
+ "engine": engine,
"model": {
- "ready": await runtime.is_downloaded(),
- "loading": await runtime.is_downloading(),
+ "ready": await runtime.is_downloaded(config),
+ "loading": await runtime.is_downloading(config),
},
"package": {
+ "name": package_name,
"version": package_version,
"error": package_error,
},
- "fallback": "Browser-native speechSynthesis remains the fallback when Kokoro is disabled.",
+ "fallback": "Browser-native speechSynthesis remains the fallback when local TTS is disabled.",
}
diff --git a/plugins/_kokoro_tts/api/synthesize.py b/plugins/_kokoro_tts/api/synthesize.py
index 5530f9003..a24310295 100644
--- a/plugins/_kokoro_tts/api/synthesize.py
+++ b/plugins/_kokoro_tts/api/synthesize.py
@@ -5,7 +5,7 @@ from plugins._kokoro_tts.helpers import runtime
class Synthesize(ApiHandler):
async def process(self, input: dict, request: Request) -> dict | Response:
if not runtime.is_globally_enabled():
- return Response(status=409, response="Kokoro TTS plugin is disabled")
+ return Response(status=409, response="Local TTS plugin is disabled")
text = str(input.get("text") or "").strip()
if not text:
diff --git a/plugins/_kokoro_tts/default_config.yaml b/plugins/_kokoro_tts/default_config.yaml
index bd1c4ec63..dee13493c 100644
--- a/plugins/_kokoro_tts/default_config.yaml
+++ b/plugins/_kokoro_tts/default_config.yaml
@@ -1,3 +1,3 @@
-voice: am_puck,am_onyx
+voice: paradee
voice_weights: {}
speed: 1.1
diff --git a/plugins/_kokoro_tts/extensions/python/_functions/helpers/plugins/toggle_plugin/end/_20_tts_dependencies.py b/plugins/_kokoro_tts/extensions/python/_functions/helpers/plugins/toggle_plugin/end/_20_tts_dependencies.py
new file mode 100644
index 000000000..c37702774
--- /dev/null
+++ b/plugins/_kokoro_tts/extensions/python/_functions/helpers/plugins/toggle_plugin/end/_20_tts_dependencies.py
@@ -0,0 +1,13 @@
+from helpers.extension import Extension
+from helpers.plugins import call_plugin_hook
+
+
+class LocalTtsEnabled(Extension):
+ def execute(self, data: dict, **kwargs):
+ if data.get("exception"):
+ return
+ args, values = data["args"], data["kwargs"]
+ name = values.get("plugin_name", args[0] if args else "")
+ enabled = values.get("enabled", args[1] if len(args) > 1 else False)
+ if name == "_kokoro_tts" and enabled:
+ call_plugin_hook("_kokoro_tts", "ensure_dependencies", raise_on_error=False)
diff --git a/plugins/_kokoro_tts/extensions/python/startup_migration/_20_tts_dependencies.py b/plugins/_kokoro_tts/extensions/python/startup_migration/_20_tts_dependencies.py
new file mode 100644
index 000000000..808fe876a
--- /dev/null
+++ b/plugins/_kokoro_tts/extensions/python/startup_migration/_20_tts_dependencies.py
@@ -0,0 +1,7 @@
+from helpers.extension import Extension
+from helpers.plugins import call_plugin_hook
+
+
+class LocalTtsDependencies(Extension):
+ def execute(self, **kwargs):
+ call_plugin_hook("_kokoro_tts", "ensure_dependencies", raise_on_error=False)
diff --git a/plugins/_kokoro_tts/extensions/webui/voice-settings-main/kokoro-card.html b/plugins/_kokoro_tts/extensions/webui/voice-settings-main/kokoro-card.html
index 84560a9c3..670d91ecb 100644
--- a/plugins/_kokoro_tts/extensions/webui/voice-settings-main/kokoro-card.html
+++ b/plugins/_kokoro_tts/extensions/webui/voice-settings-main/kokoro-card.html
@@ -2,15 +2,19 @@
<div class="voice-plugin-card">
<div class="voice-plugin-card-header">
<div>
- <div class="voice-plugin-title">Kokoro TTS</div>
+ <div class="voice-plugin-title">Local TTS</div>
<div class="voice-plugin-description">
- Server-side speech synthesis plugin. When disabled, Agent Zero falls back to browser-native TTS.
+ Paradee or Kokoro speech synthesis, with browser-native speech as the fallback.
</div>
</div>
<span class="voice-plugin-badge" :class="`is-${$store.kokoroTts?.statusClass || 'warn'}`" x-text="$store.kokoroTts?.statusText || 'Idle'"></span>
</div>
<div class="voice-plugin-meta">
+ <div class="voice-plugin-meta-row">
+ <span>Model</span>
+ <span x-text="$store.kokoroTts?.modelName || ''"></span>
+ </div>
<div class="voice-plugin-meta-row">
<span>Voice</span>
<code x-text="$store.kokoroTts?.voiceSummary || ''"></code>
diff --git a/plugins/_kokoro_tts/helpers/paradee.py b/plugins/_kokoro_tts/helpers/paradee.py
new file mode 100644
index 000000000..7dfbd673e
--- /dev/null
+++ b/plugins/_kokoro_tts/helpers/paradee.py
@@ -0,0 +1,114 @@
+from __future__ import annotations
+
+import base64
+import io
+import json
+import re
+import threading
+from pathlib import Path
+
+import numpy as np
+import soundfile as sf
+
+from helpers import files
+
+MODEL_REPO = "sahilmahendrakar/Paradee-8M-v1.0"
+MODEL_REVISION = "v1.0"
+SAMPLE_RATE = 24000
+MAX_PHONEMES = 510
+
+_model = None
+_loading = False
+_lock = threading.Lock()
+
+
+def model_status() -> dict:
+ return {"ready": _model is not None, "loading": _loading}
+
+
+def preload():
+ with _lock:
+ return _load_model()
+
+
+def _load_model():
+ global _model, _loading
+ if _model is not None:
+ return _model
+ _loading = True
+ try:
+ _model = _initialize_model()
+ return _model
+ finally:
+ _loading = False
+
+
+def _initialize_model():
+ import onnxruntime as ort
+ import spacy
+ from huggingface_hub import hf_hub_download
+ from misaki import en, espeak
+
+ if not spacy.util.is_package("en_core_web_sm"):
+ raise RuntimeError("The English phonemizer model is missing. Re-enable Local TTS to retry dependency setup.")
+
+ model_dir = Path(files.get_abs_path("usr/plugins/_kokoro_tts/paradee"))
+ for filename in ("config.json", "onnx/paradee_int8.onnx"):
+ if not (model_dir / filename).is_file():
+ hf_hub_download(
+ MODEL_REPO, filename, revision=MODEL_REVISION,
+ local_dir=str(model_dir),
+ )
+
+ config = json.loads((model_dir / "config.json").read_text(encoding="utf-8"))
+ if config.get("sample_rate") != SAMPLE_RATE:
+ raise ValueError("Unexpected Paradee model sample rate.")
+ options = ort.SessionOptions()
+ options.intra_op_num_threads = 1
+ options.inter_op_num_threads = 1
+ session = ort.InferenceSession(
+ str(model_dir / "onnx/paradee_int8.onnx"), options,
+ providers=["CPUExecutionProvider"],
+ )
+ g2p = en.G2P(
+ trf=False, british=False,
+ fallback=espeak.EspeakFallback(british=False), unk="",
+ )
+ return session, g2p, config["vocab"]
+
+
+def _phoneme_chunks(text, g2p):
+ for sentence in re.split(r"(?<=[.!?…])\s+|\n+", text.strip()):
+ if not sentence.strip():
+ continue
+ phonemes, _ = g2p(sentence)
+ while len(phonemes) > MAX_PHONEMES:
+ cut = phonemes.rfind(" ", 0, MAX_PHONEMES)
+ cut = cut if cut > 0 else MAX_PHONEMES
+ yield phonemes[:cut]
+ phonemes = phonemes[cut:].lstrip()
+ if phonemes:
+ yield phonemes
+
+
+def synthesize(text: str, speed: float) -> str:
+ with _lock:
+ session, g2p, vocab = _load_model()
+ parts = []
+ for phonemes in _phoneme_chunks(text, g2p):
+ ids = [vocab[c] for c in phonemes if c in vocab]
+ if not ids:
+ continue
+ waveform = session.run(None, {
+ "input_ids": np.array([[0, *ids, 0]], dtype=np.int64),
+ "speed": np.array([speed], dtype=np.float32),
+ })[0][0]
+ parts.append(waveform)
+ if not parts:
+ raise ValueError("Text contains no speakable English content.")
+ audio = np.concatenate(parts)
+ if not audio.size or not np.isfinite(audio).all():
+ raise ValueError("Paradee returned invalid audio.")
+ buffer = io.BytesIO()
+ sf.write(buffer, audio, SAMPLE_RATE, format="WAV", subtype="PCM_16")
+ return base64.b64encode(buffer.getvalue()).decode("ascii")
diff --git a/plugins/_kokoro_tts/helpers/runtime.py b/plugins/_kokoro_tts/helpers/runtime.py
index c8237c6ae..aafbd2918 100644
--- a/plugins/_kokoro_tts/helpers/runtime.py
+++ b/plugins/_kokoro_tts/helpers/runtime.py
@@ -17,7 +17,7 @@ from helpers.notification import (
NotificationType,
)
from helpers.print_style import PrintStyle
-from plugins._kokoro_tts.helpers import migration
+from plugins._kokoro_tts.helpers import migration, paradee
warnings.filterwarnings("ignore", category=FutureWarning)
@@ -26,7 +26,7 @@ warnings.filterwarnings("ignore", category=UserWarning)
PLUGIN_NAME = "_kokoro_tts"
DEFAULT_CONFIG = {
- "voice": "am_puck,am_onyx",
+ "voice": "paradee",
"voice_weights": {},
"speed": 1.1,
}
@@ -60,6 +60,12 @@ def normalize_config(config: dict[str, Any] | None) -> dict[str, Any]:
if normalized["voice_weights"]:
normalized["voice"] = ",".join(normalized["voice_weights"])
+ else:
+ voices = [part.strip() for part in normalized["voice"].split(",")]
+ if any(voice.lower() == "paradee" for voice in voices):
+ normalized["voice"] = ",".join(
+ voice for voice in voices if voice and voice.lower() != "paradee"
+ ) or "paradee"
try:
speed = float(config.get("speed", normalized["speed"]))
@@ -84,6 +90,8 @@ def is_globally_enabled() -> bool:
async def preload(config: dict[str, Any] | None = None):
+ if normalize_config(config if config is not None else get_config())["voice"] == "paradee":
+ return await asyncio.to_thread(paradee.preload)
return await _preload()
@@ -118,11 +126,15 @@ async def _preload():
is_updating_model = False
-async def is_downloading() -> bool:
+async def is_downloading(config: dict[str, Any] | None = None) -> bool:
+ if normalize_config(config if config is not None else get_config())["voice"] == "paradee":
+ return paradee.model_status()["loading"]
return is_updating_model
-async def is_downloaded() -> bool:
+async def is_downloaded(config: dict[str, Any] | None = None) -> bool:
+ if normalize_config(config if config is not None else get_config())["voice"] == "paradee":
+ return paradee.model_status()["ready"]
return _pipeline is not None
@@ -130,6 +142,8 @@ async def synthesize_sentences(
sentences: list[str], config: dict[str, Any] | None = None
) -> str:
cfg = normalize_config(config or get_config())
+ if cfg["voice"] == "paradee" and not cfg["voice_weights"]:
+ return await asyncio.to_thread(paradee.synthesize, "\n".join(sentences), float(cfg["speed"]))
return await _synthesize_sentences(
sentences,
voice=str(cfg["voice"]),
diff --git a/plugins/_kokoro_tts/hooks.py b/plugins/_kokoro_tts/hooks.py
index 036cc75ff..9f443b3ce 100644
--- a/plugins/_kokoro_tts/hooks.py
+++ b/plugins/_kokoro_tts/hooks.py
@@ -1,7 +1,64 @@
from __future__ import annotations
+import importlib
+import importlib.metadata
+import shutil
+import subprocess
+import sys
+import threading
+
+from packaging.requirements import Requirement
+
+from helpers.print_style import PrintStyle
from plugins._kokoro_tts.helpers import migration, runtime
+_DEPENDENCIES = (
+ Requirement("onnxruntime>=1.19.2"),
+ Requirement("en-core-web-sm @ https://github.com/explosion/spacy-models/releases/download/en_core_web_sm-3.8.0/en_core_web_sm-3.8.0-py3-none-any.whl"),
+)
+_SETUP_LOCK = threading.Lock()
+
+
+def _missing_requirements() -> list[str]:
+ missing = []
+ for requirement in _DEPENDENCIES:
+ try:
+ version = importlib.metadata.version(requirement.name)
+ except importlib.metadata.PackageNotFoundError:
+ version = None
+ if version is None or version not in requirement.specifier:
+ missing.append(str(requirement))
+ return missing
+
+
+def ensure_dependencies(raise_on_error: bool = True) -> bool:
+ with _SETUP_LOCK:
+ try:
+ missing = _missing_requirements()
+ if not missing:
+ return True
+ uv = shutil.which("uv")
+ if not uv:
+ raise RuntimeError("Local TTS requires 'uv' to prepare its dependencies.")
+ PrintStyle.info("Local TTS: preparing dependencies:", ", ".join(missing))
+ subprocess.check_call(
+ [uv, "pip", "install", "--python", sys.executable, *missing],
+ timeout=60,
+ )
+ importlib.invalidate_caches()
+ if _missing_requirements():
+ raise RuntimeError("Local TTS dependencies are still unavailable after installation.")
+ return True
+ except Exception as exc:
+ if raise_on_error:
+ raise RuntimeError(f"Local TTS dependency setup failed: {exc}") from exc
+ PrintStyle.error(f"Local TTS dependency setup failed: {exc}")
+ return False
+
+
+def install() -> bool:
+ return ensure_dependencies()
+
def get_plugin_config(default=None, **kwargs):
migration.ensure_migrated()
diff --git a/plugins/_kokoro_tts/plugin.yaml b/plugins/_kokoro_tts/plugin.yaml
index 963e75404..1537e458b 100644
--- a/plugins/_kokoro_tts/plugin.yaml
+++ b/plugins/_kokoro_tts/plugin.yaml
@@ -1,7 +1,7 @@
name: _kokoro_tts
-title: Kokoro TTS
-description: Built-in Kokoro text-to-speech plugin with weighted voice blending and browser fallback.
-version: 1.1.0
+title: Local TTS (Kokoro & Paradee)
+description: Local speech with lightweight Paradee or blended Kokoro voices, with browser fallback.
+version: 1.2.0
always_enabled: false
settings_sections:
- agent
diff --git a/plugins/_kokoro_tts/webui/config.html b/plugins/_kokoro_tts/webui/config.html
index 010baeffa..716f6577b 100644
--- a/plugins/_kokoro_tts/webui/config.html
+++ b/plugins/_kokoro_tts/webui/config.html
@@ -1,11 +1,12 @@
<html>
<head>
- <title>Kokoro TTS</title>
+ <title>Local TTS</title>
</head>
<body>
<div x-data="{
catalog: [
+ { id: 'paradee', label: 'Paradee · Heart', group: 'Paradee' },
{ id: 'af_alloy', label: 'Alloy', group: 'American Female' },
{ id: 'af_aoede', label: 'Aoede', group: 'American Female' },
{ id: 'af_bella', label: 'Bella', group: 'American Female' },
@@ -28,7 +29,7 @@
{ id: 'am_santa', label: 'Santa', group: 'American Male' },
],
initConfig() {
- if (!config.voice) config.voice = 'am_puck,am_onyx';
+ if (!config.voice) config.voice = 'paradee';
const sanitized = {};
const weights = config.voice_weights;
if (weights && typeof weights === 'object' && !Array.isArray(weights)) {
@@ -47,10 +48,12 @@
voiceIds() {
const weighted = Object.keys(config.voice_weights || {});
if (weighted.length) return weighted;
- return String(config.voice || '')
+ const ids = String(config.voice || '')
.split(',')
- .map(id => id.trim())
- .filter(id => /^[a-z]{2}_[a-z0-9_]+$/.test(id));
+ .map(id => id.trim().toLowerCase() === 'paradee' ? 'paradee' : id.trim())
+ .filter(id => id === 'paradee' || /^[a-z]{2}_[a-z0-9_]+$/.test(id));
+ const kokoroIds = ids.filter(id => id !== 'paradee');
+ return ids.includes('paradee') ? (kokoroIds.length ? kokoroIds : ['paradee']) : ids;
},
hasWeights() {
return Object.keys(config.voice_weights || {}).length > 0;
@@ -76,6 +79,7 @@
return total > 0 ? Math.round((this.weightFor(id) / total) * 100) : 0;
},
setWeight(id, rawWeight) {
+ if (id === 'paradee') return;
const next = {};
for (const voiceId of this.voiceIds()) next[voiceId] = this.weightFor(voiceId);
next[id] = Math.min(10, Math.max(0.1, Number(rawWeight) || 1));
@@ -86,8 +90,13 @@
config.voice_weights = {};
},
addVoice(id) {
+ if (id === 'paradee') {
+ config.voice_weights = {};
+ this.syncVoice([id]);
+ return;
+ }
if (!id || !/^[a-z]{2}_[a-z0-9_]+$/.test(id)) return;
- const ids = this.voiceIds();
+ const ids = this.voiceIds().filter(voiceId => voiceId !== 'paradee');
if (!ids.includes(id)) ids.push(id);
if (this.hasWeights()) {
const next = {};
@@ -113,9 +122,9 @@
}">
<template x-if="config">
<div class="plugin-config-page" x-init="initConfig()">
- <div class="section-title">Kokoro TTS</div>
+ <div class="section-title">Local TTS</div>
<div class="section-description">
- Choose a voice or blend several voices in memory. Disabling this plugin
+ Choose Paradee for English speech, or blend Kokoro voices. Disabling this plugin
returns spoken output to the browser speech API.
</div>
@@ -123,16 +132,17 @@
<div class="field-label">
<div class="field-title">Voice expression</div>
<div class="field-description">
- Pick a voice below or enter Kokoro voice identifiers separated by commas for an equal blend.
+ Choose a voice below. Kokoro voice names separated by commas create an equal blend.
</div>
</div>
<div class="field-control">
<input
type="text"
list="kokoro-voice-catalog"
+ aria-label="Voice expression"
x-model.trim="config.voice"
@input="config.voice_weights = {}"
- placeholder="am_puck,am_onyx"
+ placeholder="paradee"
/>
<datalist id="kokoro-voice-catalog">
<template x-for="voice in catalog" :key="voice.id">
@@ -146,12 +156,12 @@
<div class="field-label">
<div class="field-title">Voice blend</div>
<div class="field-description">
- Adjusting a weight enables a weighted blend. Voice packs remain in Kokoro's normal cache; no blend files are created.
+ Kokoro voices can be blended with adjustable weights. Paradee uses its own Heart voice and cannot be blended.
</div>
</div>
<div class="field-control kokoro-blend-editor">
<div class="kokoro-blend-toolbar">
- <span class="kokoro-mode" x-text="hasWeights() ? 'Weighted' : 'Equal weights'"></span>
+ <span class="kokoro-mode" x-text="config.voice === 'paradee' ? 'Single voice' : (hasWeights() ? 'Weighted' : 'Equal weights')"></span>
<button
type="button"
class="button"
@@ -164,7 +174,7 @@
<template x-if="voiceIds().length === 0">
<div class="kokoro-empty">
- Enter a standard Kokoro voice identifier to use the blend editor.
+ Choose Paradee or enter a standard Kokoro voice name.
</div>
</template>
@@ -173,9 +183,9 @@
<div class="kokoro-voice-row">
<div class="kokoro-voice-copy">
<strong x-text="voiceInfo(id).label"></strong>
- <span x-text="`${id} · ${voiceInfo(id).group}`"></span>
+ <span x-text="id === 'paradee' ? 'American English · Single voice' : `${id} · ${voiceInfo(id).group}`"></span>
</div>
- <label class="kokoro-weight">
+ <label class="kokoro-weight" x-show="id !== 'paradee'">
<span x-text="`${weightPercent(id)}%`"></span>
<input
type="range"
@@ -201,8 +211,13 @@
</template>
</div>
- <select @change="addVoice($event.target.value); $event.target.value = ''">
+ <select aria-label="Add a voice" @change="addVoice($event.target.value); $event.target.value = ''">
<option value="">Add a voice...</option>
+ <optgroup label="Paradee">
+ <template x-for="voice in availableVoices('Paradee')" :key="voice.id">
+ <option :value="voice.id" x-text="voice.label"></option>
+ </template>
+ </optgroup>
<optgroup label="American Female">
<template x-for="voice in availableVoices('American Female')" :key="voice.id">
<option :value="voice.id" x-text="`${voice.label} (${voice.id})`"></option>
@@ -229,7 +244,7 @@
max="3"
step="0.1"
x-model.number="config.speed"
- aria-label="Kokoro speech speed"
+ aria-label="Speech speed"
/>
<output x-text="`${Number(config.speed || 1.1).toFixed(1)}×`"></output>
</div>
diff --git a/plugins/_kokoro_tts/webui/kokoro-tts-store.js b/plugins/_kokoro_tts/webui/kokoro-tts-store.js
index 1e32d81fc..8d54813b2 100644
--- a/plugins/_kokoro_tts/webui/kokoro-tts-store.js
+++ b/plugins/_kokoro_tts/webui/kokoro-tts-store.js
@@ -58,7 +58,7 @@ const model = {
this.error = error instanceof Error ? error.message : String(error);
this.unregisterProvider();
if (!suppressError) {
- void toastFrontendError(this.error, "Kokoro TTS");
+ void toastFrontendError(this.error, "Local TTS");
}
} finally {
this.loading = false;
@@ -74,8 +74,9 @@ const model = {
text,
});
if (!result?.success) {
- throw new Error(result?.error || "Kokoro TTS synthesis failed.");
+ throw new Error(result?.error || "Local TTS synthesis failed.");
}
+ this.modelReady = true;
return {
audioBase64: result.audio || "",
@@ -106,6 +107,7 @@ const model = {
},
get voiceSummary() {
+ if (this.config.voice === "paradee") return "Paradee · Heart";
const entries = Object.entries(this.config.voice_weights || {});
if (!entries.length) return this.config.voice || "";
@@ -116,6 +118,10 @@ const model = {
.join(" · ");
},
+ get modelName() {
+ return this.config.voice === "paradee" ? "Paradee-8M" : "Kokoro-82M";
+ },
+
async openConfig() {
const { store } = await import("/components/plugins/plugin-settings-store.js");
await store.openConfig(PLUGIN_NAME);
diff --git a/plugins/_kokoro_tts/webui/main.html b/plugins/_kokoro_tts/webui/main.html
index d9aa54dc2..49b4d8f32 100644
--- a/plugins/_kokoro_tts/webui/main.html
+++ b/plugins/_kokoro_tts/webui/main.html
@@ -1,6 +1,6 @@
<html>
<head>
- <title>Kokoro TTS</title>
+ <title>Local TTS</title>
<script type="module">
import { store } from "/plugins/_kokoro_tts/webui/kokoro-tts-store.js";
</script>
@@ -14,11 +14,10 @@
>
<template x-if="$store.kokoroTts">
<div>
- <div class="section-title">Kokoro TTS</div>
+ <div class="section-title">Local TTS</div>
<div class="section-description">
- Built-in Kokoro speech synthesis. Dependency installation remains on the
- Docker/bootstrap path; disabling this plugin returns spoken output to the
- browser fallback.
+ Local speech synthesis with Paradee or Kokoro. Disabling this plugin
+ returns spoken output to the browser fallback.
</div>
<div class="speech-plugin-grid">
@@ -30,6 +29,10 @@
</div>
<div class="status-row">
<span class="status-key">Model</span>
+ <span class="status-value" x-text="$store.kokoroTts.modelName"></span>
+ </div>
+ <div class="status-row">
+ <span class="status-key">State</span>
<span class="status-badge" :class="$store.kokoroTts.statusClass" x-text="$store.kokoroTts.statusText"></span>
</div>
<div class="status-row" x-show="$store.kokoroTts.packageVersion">
diff --git a/tests/test_paradee_tts.py b/tests/test_paradee_tts.py
new file mode 100644
index 000000000..304421275
--- /dev/null
+++ b/tests/test_paradee_tts.py
@@ -0,0 +1,229 @@
+import asyncio
+import base64
+import io
+import json
+from pathlib import Path
+import shutil
+import subprocess
+import sys
+
+import numpy as np
+import pytest
+import soundfile as sf
+
+from helpers import cache, files, plugins
+from plugins._kokoro_tts import hooks
+from plugins._kokoro_tts.api.status import Status
+from plugins._kokoro_tts.extensions.python.startup_migration import _20_tts_dependencies as startup
+from plugins._kokoro_tts.extensions.python._functions.helpers.plugins.toggle_plugin.end import _20_tts_dependencies as enable
+from plugins._kokoro_tts.helpers import migration, paradee, runtime
+
+PROJECT_ROOT = Path(__file__).resolve().parents[1]
+
+
+def dependency_versions(monkeypatch):
+ versions = {"onnxruntime": "1.19.2", "en-core-web-sm": "3.8.0"}
+
+ def version(name):
+ if name not in versions:
+ raise hooks.importlib.metadata.PackageNotFoundError(name)
+ return versions[name]
+
+ monkeypatch.setattr(hooks.importlib.metadata, "version", version)
+ return versions
+
+
+def test_current_dependencies_skip_installer(monkeypatch, dependency_versions):
+ monkeypatch.setattr(hooks.shutil, "which", lambda name: pytest.fail("Installer lookup"))
+ assert hooks.install()
+
+
[email protected]("package,old_version", [
+ ("onnxruntime", None), ("onnxruntime", "1.17.0"), ("en-core-web-sm", None),
+])
+def test_dependency_setup_installs_only_missing_packages(monkeypatch, dependency_versions, package, old_version):
+ current = dependency_versions.copy()
+ dependency_versions.pop(package)
+ if old_version:
+ dependency_versions[package] = old_version
+ expected = hooks._missing_requirements()
+ calls = []
+ monkeypatch.setattr(hooks.shutil, "which", lambda name: "/usr/bin/uv")
+
+ def install(command, **kwargs):
+ calls.append((command, kwargs))
+ dependency_versions.update(current)
+
+ monkeypatch.setattr(hooks.subprocess, "check_call", install)
+ assert hooks.install()
+ assert hooks.install()
+ assert calls == [(["/usr/bin/uv", "pip", "install", "--python", sys.executable, *expected], {"timeout": 60})]
+ assert len(expected) == 1
+
+
+def test_dependency_failure_logs_without_blocking_startup(monkeypatch, dependency_versions):
+ dependency_versions.pop("onnxruntime")
+ monkeypatch.setattr(hooks.shutil, "which", lambda name: None)
+ assert hooks.ensure_dependencies(raise_on_error=False) is False
+ with pytest.raises(RuntimeError, match="dependency setup failed"):
+ hooks.install()
+
+
+def test_dependency_setup_rechecks_after_install(monkeypatch, dependency_versions):
+ dependency_versions.pop("onnxruntime")
+ monkeypatch.setattr(hooks.shutil, "which", lambda name: "/usr/bin/uv")
+ monkeypatch.setattr(hooks.subprocess, "check_call", lambda *args, **kwargs: None)
+ with pytest.raises(RuntimeError, match="still unavailable"):
+ hooks.install()
+
+
+def test_startup_and_reenable_call_the_plugin_hook(monkeypatch):
+ calls = []
+ call = lambda *args, **kwargs: calls.append((args, kwargs))
+ monkeypatch.setattr(startup, "call_plugin_hook", call)
+ monkeypatch.setattr(enable, "call_plugin_hook", call)
+ startup.LocalTtsDependencies(None).execute()
+ extension = enable.LocalTtsEnabled(None)
+ extension.execute(data={"args": ("_kokoro_tts", True), "kwargs": {}, "exception": None})
+ extension.execute(data={"args": (), "kwargs": {"plugin_name": "_kokoro_tts", "enabled": True}, "exception": None})
+ extension.execute(data={"args": ("_kokoro_tts", False), "kwargs": {}, "exception": None})
+ extension.execute(data={"args": ("_other", True), "kwargs": {}, "exception": None})
+ extension.execute(data={"args": ("_kokoro_tts", True), "kwargs": {}, "exception": RuntimeError()})
+ assert calls == [(("_kokoro_tts", "ensure_dependencies"), {"raise_on_error": False})] * 3
+
+
[email protected]("config,voice,weights", [
+ ({}, "paradee", {}),
+ ({"voice": ""}, "paradee", {}),
+ ({"voice": " Paradee "}, "paradee", {}),
+ ({"voice": "paradee", "voice_weights": {"am_puck": 2}}, "am_puck", {"am_puck": 2.0}),
+ ({"voice": "paradee,am_puck"}, "am_puck", {}),
+ ({"voice": "paradee,custom/voice.pt"}, "custom/voice.pt", {}),
+ ({"voice_weights": {"paradee": 1}}, "paradee", {}),
+ ({"voice": "am_puck,am_onyx"}, "am_puck,am_onyx", {}),
+])
+def test_voice_selection_preserves_kokoro_blends(config, voice, weights):
+ normalized = runtime.normalize_config({**config, "speed": 1.4})
+ assert normalized == {"voice": voice, "voice_weights": weights, "speed": 1.4}
+
+
+def test_saved_kokoro_voice_and_global_toggle_are_preserved(monkeypatch, tmp_path):
+ monkeypatch.setattr(files, "_base_dir", str(tmp_path))
+ monkeypatch.setattr(cache, "_cache", {})
+ monkeypatch.setattr(migration, "LEGACY_SETTINGS_FILE", str(tmp_path / "usr/settings.json"))
+ (tmp_path / "usr/plugins").mkdir(parents=True)
+ bundled = tmp_path / "plugins/_kokoro_tts"
+ bundled.mkdir(parents=True)
+ for name in ("plugin.yaml", "default_config.yaml", "hooks.py"):
+ shutil.copyfile(PROJECT_ROOT / "plugins/_kokoro_tts" / name, bundled / name)
+ assert runtime.get_config()["voice"] == "paradee"
+ assert runtime.is_globally_enabled()
+ saved = tmp_path / "usr/plugins/_kokoro_tts"
+ saved.mkdir(parents=True)
+ config = {"voice": "am_puck,am_onyx", "voice_weights": {"am_puck": 3, "am_onyx": 1}, "speed": 1.6}
+ (saved / "config.json").write_text(json.dumps(config))
+ (saved / ".toggle-0").touch()
+ assert runtime.get_config() == config
+ assert not runtime.is_globally_enabled()
+
+
+def test_paradee_dispatch_never_loads_the_kokoro_pipeline(monkeypatch):
+ calls = []
+ monkeypatch.setattr(paradee, "synthesize", lambda text, speed: calls.append((text, speed)) or "audio")
+ monkeypatch.setattr(runtime, "_synthesize_sentences", lambda *args, **kwargs: pytest.fail("Kokoro dispatch"))
+ result = asyncio.run(runtime.synthesize_sentences(["Hello", "World"], {"voice": "paradee", "speed": 1.4}))
+ assert result == "audio"
+ assert calls == [("Hello\nWorld", 1.4)]
+
+
+def test_preload_and_status_follow_the_selected_model(monkeypatch):
+ monkeypatch.setattr(paradee, "preload", lambda: "paradee-model")
+ monkeypatch.setattr(paradee, "model_status", lambda: {"ready": True, "loading": False})
+ monkeypatch.setattr(runtime, "_pipeline", None)
+ assert asyncio.run(runtime.preload({"voice": "paradee"})) == "paradee-model"
+ assert asyncio.run(runtime.is_downloaded({"voice": "paradee"}))
+ assert not asyncio.run(runtime.is_downloaded({"voice": "af_heart"}))
+ monkeypatch.setattr(runtime, "get_config", lambda: runtime.normalize_config({"voice": "paradee"}))
+ monkeypatch.setattr(runtime, "is_globally_enabled", lambda: True)
+ monkeypatch.setattr(migration, "ensure_migrated", lambda: False)
+ status = asyncio.run(Status(None, None).process({}, None))
+ assert status["engine"] == "paradee"
+ assert status["model"] == {"ready": True, "loading": False}
+ assert status["package"]["name"] == "onnxruntime"
+
+
+def test_phoneme_chunks_keep_all_long_input():
+ for text in ("a" * 1200, "hello " * 300, "hello.\nworld!"):
+ chunks = list(paradee._phoneme_chunks(text, lambda s: (s, None)))
+ assert all(0 < len(chunk) <= 510 for chunk in chunks)
+ assert "".join(chunks).replace(" ", "") == text.replace(" ", "").replace("\n", "")
+
+
+def test_synthesis_produces_wav_and_forwards_speed(monkeypatch):
+ feeds = []
+
+ class Session:
+ def run(self, _, feed):
+ feeds.append(feed)
+ return [np.full((1, 2400), 0.1, dtype=np.float32)]
+
+ monkeypatch.setattr(paradee, "_load_model", lambda: (Session(), lambda s: (s, None), {"a": 1}))
+ audio = paradee.synthesize("a" * 1200, 1.4)
+ wave, rate = sf.read(io.BytesIO(base64.b64decode(audio)))
+ assert rate == 24000 and len(wave) == 7200
+ for feed in feeds:
+ ids = feed["input_ids"]
+ assert ids.shape[1] <= 512 and ids.dtype == np.int64
+ assert ids[0, 0] == ids[0, -1] == 0
+ assert feed["speed"][0] == pytest.approx(1.4)
+ with pytest.raises(ValueError, match="no speakable"):
+ paradee.synthesize("🙂", 1.0)
+
+
+def test_missing_phonemizer_never_installs_packages(monkeypatch):
+ import spacy
+
+ monkeypatch.setattr(spacy.util, "is_package", lambda name: False)
+ monkeypatch.setattr(spacy.cli, "download", lambda *args: pytest.fail("Runtime package installation"))
+ with pytest.raises(RuntimeError, match="phonemizer model is missing"):
+ paradee._initialize_model()
+
+
+def test_failed_load_resets_loading_status(monkeypatch):
+ monkeypatch.setattr(paradee, "_model", None)
+
+ def fail():
+ raise RuntimeError("Model failed")
+
+ monkeypatch.setattr(paradee, "_initialize_model", fail)
+ with pytest.raises(RuntimeError, match="Model failed"):
+ paradee.preload()
+ assert paradee.model_status() == {"ready": False, "loading": False}
+
+
+def test_voice_picker_switches_models_without_cross_model_blends():
+ node = shutil.which("node")
+ if not node:
+ pytest.skip("Node.js unavailable")
+ html = (PROJECT_ROOT / "plugins/_kokoro_tts/webui/config.html").read_text()
+ component = html.split('<div x-data="', 1)[1].split('">', 1)[0]
+ script = "const config = {voice:'am_puck', voice_weights:{am_puck:3}, speed:1.4};\n"
+ script += "const ui = (" + component + ");\n"
+ script += """
+ const assert = (value) => { if (!value) throw new Error('Voice picker assertion'); };
+ ui.initConfig();
+ ui.addVoice('paradee');
+ assert(config.voice === 'paradee' && !ui.hasWeights());
+ assert(ui.voiceIds().join(',') === 'paradee');
+ ui.setWeight('paradee', 2);
+ assert(!ui.hasWeights());
+ ui.addVoice('am_onyx');
+ assert(config.voice === 'am_onyx' && !ui.hasWeights());
+ ui.addVoice('am_puck');
+ ui.setWeight('am_puck', 3);
+ assert(config.voice === 'am_onyx,am_puck' && config.voice_weights.am_puck === 3);
+ ui.addVoice('paradee');
+ assert(config.voice === 'paradee' && !ui.hasWeights() && config.speed === 1.4);
+ """
+ subprocess.run([node, "-"], input=script, text=True, check=True, capture_output=True)