kenkui 2.3.0__tar.gz → 2.3.2__tar.gz

{kenkui-2.3.0/src/kenkui.egg-info → kenkui-2.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kenkui
-Version: 2.3.0
+Version: 2.3.2
 Summary: Convert Ebooks to Audiobooks with [custom] voice samples
 Author-email: Sumner MacArthur <spn1kolat3sla@gmail.com>
 License-Expression: MIT

{kenkui-2.3.0 → kenkui-2.3.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "kenkui"
-version = "2.3.0"
+version = "2.3.2"
 description = "Convert Ebooks to Audiobooks with [custom] voice samples"
 readme = "README.md"
 authors = [{ name = "Sumner MacArthur", email = "spn1kolat3sla@gmail.com" }]
@@ -59,6 +59,7 @@ server = ["fastapi>=0.115.0", "uvicorn[standard]>=0.30.0", "httpx>=0.27.0"]
 where = ["src"]
 
 [tool.setuptools.package-data]
+"kenkui" = ["voices/*.json"]
 "kenkui.samples" = ["*.epub", "*.pdf"]
 
 [tool.setuptools.exclude-package-data]

{kenkui-2.3.0 → kenkui-2.3.2}/src/kenkui/api.py

@@ -119,7 +119,7 @@ from .workers import worker_process_chapter
 try:
     __version__ = importlib.metadata.version("kenkui")
 except importlib.metadata.PackageNotFoundError:
-    __version__ = "2.3.0"
+    __version__ = "2.3.1"
 
 __author__ = "Sumner MacArthur"
 __license__ = "MIT"

{kenkui-2.3.0 → kenkui-2.3.2}/src/kenkui/models/__init__.py

@@ -53,6 +53,8 @@ from .api import (
     TaskResponse,
     VoiceListResponse,
     VoicePoolResponse,
+    VoicePreviewAssetResponse,
+    VoicePreviewPhraseResponse,
     VoiceResponse,
 )
 from .audio import AudioResult, ProcessingConfig
@@ -148,6 +150,8 @@ __all__ = [
     "TTSExecutionMode",
     "VoiceListResponse",
     "VoicePoolResponse",
+    "VoicePreviewAssetResponse",
+    "VoicePreviewPhraseResponse",
     "VoiceResponse",
     "_migrate_speaker_voices_keys",
     "_normalize_bitrate",

{kenkui-2.3.0 → kenkui-2.3.2}/src/kenkui/models/api.py

@@ -188,6 +188,22 @@ class ProviderModelListResponse(BaseModel):
     models: list[str]
 
 
+class VoicePreviewPhraseResponse(BaseModel):
+    phrase_id: str
+    title: str
+    author: str
+    text: str
+    source_url: str
+
+
+class VoicePreviewAssetResponse(BaseModel):
+    phrase_id: str
+    audio_url: str
+    content_type: str
+    duration_ms: int | None = None
+    sha256: str | None = None
+
+
 class VoiceResponse(BaseModel):
     name: str
     source: str
@@ -198,11 +214,14 @@ class VoiceResponse(BaseModel):
     description: str
     display_label: str
     excluded: bool
+    previews: list[VoicePreviewAssetResponse] = Field(default_factory=list)
 
 
 class VoiceListResponse(BaseModel):
     voices: list[VoiceResponse]
     total: int
+    phrase_catalog: list[VoicePreviewPhraseResponse] = Field(default_factory=list)
+    default_phrase_id: str = ""
 
 
 class AuditionRequest(BaseModel):

{kenkui-2.3.0 → kenkui-2.3.2}/src/kenkui/services/application_service.py

@@ -61,6 +61,8 @@ from kenkui.models.api import (
     TaskResponse,
     VoiceListResponse,
     VoicePoolResponse,
+    VoicePreviewAssetResponse,
+    VoicePreviewPhraseResponse,
     VoiceResponse,
 )
 from kenkui.progress import ProgressEvent
@@ -115,6 +117,31 @@ def _model_dict(value: Any) -> dict[str, Any] | None:
     return {"value": str(value)}
 
 
+def _voice_preview_responses(voice: Any) -> list[VoicePreviewAssetResponse]:
+    from kenkui.voice_registry import PREVIEW_PHRASE_CATALOG
+
+    previews = [
+        VoicePreviewAssetResponse(
+            phrase_id=item.phrase_id,
+            audio_url=item.audio_url,
+            content_type=item.content_type,
+            duration_ms=item.duration_ms,
+            sha256=item.sha256,
+        )
+        for item in voice.previews
+    ]
+    if not previews and voice.preview_url:
+        content_type = "audio/mpeg" if voice.preview_url.lower().endswith(".mp3") else "audio/wav"
+        previews.append(
+            VoicePreviewAssetResponse(
+                phrase_id=PREVIEW_PHRASE_CATALOG.default_phrase_id,
+                audio_url=voice.preview_url,
+                content_type=content_type,
+            )
+        )
+    return previews
+
+
 def _merge_dict(base: dict[str, Any], patch: dict[str, Any]) -> dict[str, Any]:
     result = dict(base)
     for key, value in patch.items():
@@ -860,8 +887,10 @@ class KenkuiService:
         source: str | None = None,
     ) -> VoiceListResponse:
         from kenkui.services.voice_service import list_voices
+        from kenkui.voice_registry import PREVIEW_PHRASE_CATALOG
 
         voices = list_voices(gender=gender, accent=accent, dataset=dataset, origin=source)
+
         return VoiceListResponse(
             voices=[
                 VoiceResponse(
@@ -874,10 +903,22 @@ class KenkuiService:
                     description=v.description,
                     display_label=v.display_label,
                     excluded=not v.pool_enabled,
+                    previews=_voice_preview_responses(v),
                 )
                 for v in voices
             ],
             total=len(voices),
+            phrase_catalog=[
+                VoicePreviewPhraseResponse(
+                    phrase_id=phrase.phrase_id,
+                    title=phrase.title,
+                    author=phrase.author,
+                    text=phrase.text,
+                    source_url=phrase.source_url,
+                )
+                for phrase in PREVIEW_PHRASE_CATALOG.phrases
+            ],
+            default_phrase_id=PREVIEW_PHRASE_CATALOG.default_phrase_id,
         )
 
     def get_voice(self, name: str) -> VoiceResponse | None:
@@ -896,6 +937,7 @@ class KenkuiService:
             description=v.description,
             display_label=v.display_label,
             excluded=not v.pool_enabled,
+            previews=_voice_preview_responses(v),
         )
 
     def set_voice_pool_enabled(self, name: str, enabled: bool) -> VoicePoolResponse:

{kenkui-2.3.0 → kenkui-2.3.2}/src/kenkui/services/voice_service.py

@@ -16,6 +16,7 @@ from kenkui.voice_compiler import compile_audio_prompt_source
 from kenkui.voice_loader import load_voice_conditioning_source
 from kenkui.voice_registry import (
     PREVIEW_TEXT,
+    PreviewAssetInfo,
     VoiceCatalogEntry,
     get_catalog,
     preview_cache_dir,
@@ -55,6 +56,7 @@ class VoiceInfo:
     path: str | None
     preview_path: str | None
     preview_url: str | None
+    previews: tuple[PreviewAssetInfo, ...]
     accent: str | None
     dataset: str | None
     speaker_id: str | None
@@ -102,6 +104,7 @@ def _entry_to_info(v: VoiceCatalogEntry) -> VoiceInfo:
         path=str(v.path) if v.path is not None else None,
         preview_path=v.preview.path,
         preview_url=v.preview.url,
+        previews=v.previews,
         accent=v.accent,
         dataset=v.dataset,
         speaker_id=v.speaker_id,
@@ -217,23 +220,39 @@ def prepare_voice_preview(
     if entry is None:
         raise KeyError(f"Unknown voice_id: {voice_id}")
 
-    if entry.preview.path:
+    requested_text = text if text is not None else entry.preview.text
+    matches_manifest_preview = requested_text == entry.preview.text
+
+    if entry.preview.path and matches_manifest_preview:
         path = Path(entry.preview.path)
         if path.exists() and not force:
-            return AudioPreviewResult(voice_id=voice_id, audio_path=str(path), duration_ms=entry.preview.duration_ms)
+            return AudioPreviewResult(
+                voice_id=voice_id,
+                audio_path=str(path),
+                duration_ms=entry.preview.duration_ms,
+            )
 
-    out_path = preview_cache_dir() / f"{voice_id}.wav"
+    text_hash = hashlib.sha256(requested_text.encode("utf-8")).hexdigest()[:16]
+    out_path = preview_cache_dir() / f"{voice_id}-{text_hash}.wav"
     if out_path.exists() and not force:
-        return AudioPreviewResult(voice_id=voice_id, audio_path=str(out_path), duration_ms=entry.preview.duration_ms)
+        return AudioPreviewResult(
+            voice_id=voice_id,
+            audio_path=str(out_path),
+            duration_ms=entry.preview.duration_ms if matches_manifest_preview else None,
+        )
 
-    if entry.preview.url:
+    if entry.preview.url and matches_manifest_preview:
         try:
             if _download_preview(entry, out_path):
-                return AudioPreviewResult(voice_id=voice_id, audio_path=str(out_path), duration_ms=entry.preview.duration_ms)
+                return AudioPreviewResult(
+                    voice_id=voice_id,
+                    audio_path=str(out_path),
+                    duration_ms=entry.preview.duration_ms,
+                )
         except Exception as exc:
             logger.warning("Failed to download hosted preview for %s: %s", voice_id, exc)
 
-    _synthesize_preview(entry, out_path, text or entry.preview.text)
+    _synthesize_preview(entry, out_path, requested_text)
     return AudioPreviewResult(voice_id=voice_id, audio_path=str(out_path), duration_ms=None)
 
 

{kenkui-2.3.0 → kenkui-2.3.2}/src/kenkui/voice_registry.py

@@ -15,6 +15,7 @@ import re
 from dataclasses import asdict, dataclass, field, replace
 from pathlib import Path
 from typing import Any, Literal
+from urllib.parse import urlparse
 
 from .voice_compiler import is_legacy_audio_prompt_asset
 
@@ -25,16 +26,94 @@ VoiceAssetKind = Literal["pocket_tts_builtin", "safetensors"]
 VoiceStatus = Literal["available", "missing", "downloadable"]
 
 DEFAULT_VOICE_PACK_REPO = "D1zzl3D0p/kenkui-voices"
-DEFAULT_VOICE_PACK_REVISION = "main"
+DEFAULT_VOICE_PACK_REVISION = "b513c6aaa350da3fcaff12c9c0afd2a1e97c92d7"
 VOICE_PACK_FORMAT_VERSION = 2
 MANIFEST_FILENAMES = ("manifest.json", "voice_manifest.json")
 CUSTOM_MANIFEST_FILENAME = "custom_manifest.json"
-PREVIEW_TEXT = (
-    "The rain in Spain stays mainly in the plain. "
-    "How wonderful it is to simply speak and be heard."
-)
 
 _VOICE_ID_RE = re.compile(r"^[a-z0-9][a-z0-9_.-]*$")
+_PHRASE_ID_RE = re.compile(r"^[a-z0-9][a-z0-9-]*$")
+
+
+class VoiceCatalogError(ValueError):
+    """Raised when voice or preview phrase catalog data is invalid."""
+
+
+@dataclass(frozen=True)
+class PreviewPhrase:
+    phrase_id: str
+    title: str
+    author: str
+    text: str
+    source_url: str
+
+
+@dataclass(frozen=True)
+class PreviewPhraseCatalog:
+    version: int
+    default_phrase_id: str
+    phrases: tuple[PreviewPhrase, ...]
+
+    @property
+    def default_phrase(self) -> PreviewPhrase:
+        return next(phrase for phrase in self.phrases if phrase.phrase_id == self.default_phrase_id)
+
+
+def preview_phrase_catalog_path() -> Path:
+    return Path(__file__).resolve().parent / "voices" / "preview_phrases.json"
+
+
+def load_preview_phrase_catalog(path: Path | None = None) -> PreviewPhraseCatalog:
+    source = path or preview_phrase_catalog_path()
+    try:
+        raw = json.loads(source.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        raise VoiceCatalogError(f"Invalid preview phrase catalog {source}") from exc
+    if not isinstance(raw, dict):
+        raise VoiceCatalogError("Preview phrase catalog must be an object")
+    version = raw.get("version")
+    if isinstance(version, bool) or not isinstance(version, int) or version <= 0:
+        raise VoiceCatalogError("Preview phrase catalog version must be a positive integer")
+    default_phrase_id = raw.get("default_phrase_id")
+    if not isinstance(default_phrase_id, str) or not _PHRASE_ID_RE.fullmatch(default_phrase_id):
+        raise VoiceCatalogError("Preview phrase catalog has invalid default_phrase_id")
+    raw_phrases = raw.get("phrases")
+    if not isinstance(raw_phrases, list) or not raw_phrases:
+        raise VoiceCatalogError("Preview phrase catalog must contain a non-empty phrases list")
+
+    phrases: list[PreviewPhrase] = []
+    seen: set[str] = set()
+    for item in raw_phrases:
+        if not isinstance(item, dict):
+            raise VoiceCatalogError("Each preview phrase must be an object")
+        phrase_id = item.get("phrase_id")
+        if not isinstance(phrase_id, str) or not _PHRASE_ID_RE.fullmatch(phrase_id):
+            raise VoiceCatalogError(f"Invalid phrase_id: {phrase_id!r}")
+        if phrase_id in seen:
+            raise VoiceCatalogError(f"Duplicate phrase_id {phrase_id!r}")
+        seen.add(phrase_id)
+        values: dict[str, str] = {}
+        for key in ("title", "author", "text", "source_url"):
+            value = item.get(key)
+            if not isinstance(value, str) or not value.strip():
+                raise VoiceCatalogError(f"Preview phrase {phrase_id!r} has invalid {key}")
+            values[key] = value.strip()
+        parsed_url = urlparse(values["source_url"])
+        if parsed_url.scheme != "https" or not parsed_url.netloc:
+            raise VoiceCatalogError(f"Preview phrase {phrase_id!r} source_url must use HTTPS")
+        phrases.append(PreviewPhrase(phrase_id=phrase_id, **values))
+
+    if default_phrase_id not in seen:
+        raise VoiceCatalogError("Preview phrase catalog default_phrase_id does not identify a phrase")
+    return PreviewPhraseCatalog(
+        version=version,
+        default_phrase_id=default_phrase_id,
+        phrases=tuple(phrases),
+    )
+
+
+PREVIEW_PHRASE_CATALOG = load_preview_phrase_catalog()
+PREVIEW_TEXT = PREVIEW_PHRASE_CATALOG.default_phrase.text
 
 _BUILTIN_VOICE_DATA: dict[str, dict[str, str | None]] = {
     "alba": {"gender": "Male", "accent": "American", "dataset": "Alba-Mackenna", "speaker_id": "casual"},
@@ -68,10 +147,6 @@ _BUILTIN_VOICE_DATA: dict[str, dict[str, str | None]] = {
 BUILTIN_VOICE_NAMES: list[str] = list(_BUILTIN_VOICE_DATA)
 
 
-class VoiceCatalogError(ValueError):
-    """Raised when a voice manifest is invalid."""
-
-
 @dataclass(frozen=True)
 class PreviewInfo:
     text: str = PREVIEW_TEXT
@@ -96,6 +171,69 @@ class PreviewInfo:
         return {k: v for k, v in asdict(self).items() if v is not None}
 
 
+@dataclass(frozen=True)
+class PreviewAssetInfo:
+    phrase_id: str
+    audio_url: str
+    content_type: str
+    duration_ms: int | None = None
+    sha256: str | None = None
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> PreviewAssetInfo:
+        phrase_id = str(data.get("phrase_id") or "").strip()
+        audio_url = str(data.get("audio_url") or data.get("url") or "").strip()
+        content_type = str(data.get("content_type") or "").strip()
+        if not phrase_id or not _PHRASE_ID_RE.fullmatch(phrase_id):
+            raise VoiceCatalogError(f"Invalid preview phrase_id: {phrase_id!r}")
+        parsed_url = urlparse(audio_url)
+        if parsed_url.scheme not in ("http", "https") or not parsed_url.netloc:
+            raise VoiceCatalogError(f"Invalid preview audio_url: {audio_url!r}")
+        if not content_type:
+            raise VoiceCatalogError(f"Preview {phrase_id!r} is missing content_type")
+        return cls(
+            phrase_id=phrase_id,
+            audio_url=audio_url,
+            content_type=content_type,
+            duration_ms=data.get("duration_ms"),
+            sha256=data.get("sha256"),
+        )
+
+
+def _load_preview_assets(data: dict[str, Any]) -> tuple[PreviewAssetInfo, ...]:
+    raw_previews = data.get("previews")
+    if raw_previews is not None:
+        if not isinstance(raw_previews, list):
+            raise VoiceCatalogError("Voice previews must be a list")
+        previews = tuple(PreviewAssetInfo.from_dict(item) for item in raw_previews)
+        phrase_ids = [preview.phrase_id for preview in previews]
+        if len(phrase_ids) != len(set(phrase_ids)):
+            raise VoiceCatalogError("Voice previews contain duplicate phrase_id values")
+        return previews
+
+    # Read the singular preview field written by voice-pack manifests before the
+    # multi-preview contract. Local path-only previews remain available through
+    # PreviewInfo but are not exposed as public URL assets.
+    legacy = data.get("preview")
+    if isinstance(legacy, dict) and legacy.get("url"):
+        url = str(legacy["url"])
+        content_type = str(legacy.get("content_type") or "")
+        if not content_type:
+            content_type = "audio/mpeg" if urlparse(url).path.lower().endswith(".mp3") else "audio/wav"
+        return (
+            PreviewAssetInfo.from_dict(
+                {
+                    "phrase_id": PREVIEW_PHRASE_CATALOG.default_phrase_id,
+                    "audio_url": url,
+                    "content_type": content_type,
+                    "duration_ms": legacy.get("duration_ms"),
+                    "sha256": legacy.get("sha256"),
+                }
+            ),
+        )
+    return ()
+
+
 @dataclass(frozen=True)
 class VoiceCatalogEntry:
     voice_id: str
@@ -107,6 +245,7 @@ class VoiceCatalogEntry:
     path: Path | None = None
     status: VoiceStatus = "available"
     preview: PreviewInfo = field(default_factory=PreviewInfo)
+    previews: tuple[PreviewAssetInfo, ...] = ()
     accent: str | None = None
     dataset: str | None = None
     speaker_id: str | None = None
@@ -178,6 +317,7 @@ class VoiceCatalogEntry:
             path=path,
             status=status,  # type: ignore[arg-type]
             preview=PreviewInfo.from_dict(data.get("preview")),
+            previews=_load_preview_assets(data),
             accent=data.get("accent"),
             dataset=data.get("dataset"),
             speaker_id=data.get("speaker_id"),
@@ -216,6 +356,8 @@ class VoiceCatalogEntry:
         preview = self.preview.to_dict()
         if preview:
             data["preview"] = preview
+        if self.previews:
+            data["previews"] = [asdict(item) for item in self.previews]
         return data
 
 
@@ -600,8 +742,12 @@ __all__ = [
     "DEFAULT_VOICE_PACK_REPO",
     "DEFAULT_VOICE_PACK_REVISION",
     "VOICE_PACK_FORMAT_VERSION",
+    "PREVIEW_PHRASE_CATALOG",
     "PREVIEW_TEXT",
+    "PreviewAssetInfo",
     "PreviewInfo",
+    "PreviewPhrase",
+    "PreviewPhraseCatalog",
     "VoiceCatalog",
     "VoiceCatalogEntry",
     "VoiceCatalogError",
@@ -612,7 +758,9 @@ __all__ = [
     "get_catalog",
     "get_registry",
     "load_manifest",
+    "load_preview_phrase_catalog",
     "preview_cache_dir",
+    "preview_phrase_catalog_path",
     "validate_manifest",
     "voice_pack_manifest_is_current",
     "verify_manifest_assets",