Merge pull request #31 from ronibhakta1/fix/changes-to-service-and-demo

refactor: update voice response model and improve demo interface

Author: ronibhakta1

app/api/routes/voices.py

@@ -10,14 +10,16 @@
 @router.get(
     "/voices",
     response_model=list[Voice],
-    response_model_exclude_none=True,
+    response_model_exclude_defaults=True,
     dependencies=[Depends(require_ready)],
     summary="List available TTS voices",
     description=(
         "The voices **actually installed** on this deployment (realtime) — each voice's "
         "`language` and `otherLanguages` reflect what's loaded now, bounded by `LANGUAGES` + "
-        "`VOICE_LANGUAGES`. Model-level `quality`/`controls` are merged in per voice; `controls` "
-        "lists only the enabled ones. Optionally filtered by language or provider; supports "
+        "`VOICE_LANGUAGES`. Fields left at their default (e.g. no `gender`, no cross-language "
+        "`otherLanguages`) are omitted from the response. `quality` is the provider's default "
+        "merged into each voice; `controls` is provider-wide only and lives on `GET /service`, "
+        "not here. Optionally filtered by language or provider; supports "
         "pagination via `offset` and `limit`. Response headers `X-Total-Count`, `X-Offset`, "
         "`X-Limit` reflect the full result set size."
     ),
@@ -40,15 +42,8 @@
                                         "provider": "pocket",
                                         "identifier": "urn:readium:tts:pocket:alba",
                                         "language": "en-US",
-                                        "otherLanguages": [],
                                         "gender": "male",
                                         "quality": "veryHigh",
-                                        "controls": {
-                                            "pitch": False,
-                                            "speed": False,
-                                            "ssml": False,
-                                            "boundary": False,
-                                        },
                                     }
                                 ],
                             }

app/core/synthesizer.py

@@ -66,7 +66,7 @@ async def synthesize(
             )
 
         provider, voice = self._catalog.resolve(voice_ref)
-        boundaries_supported = voice.controls.boundary
+        boundaries_supported = provider.default_controls.boundary
 
         out = request.output
         logger.info(

app/providers/base.py

@@ -16,8 +16,9 @@ class TTSProvider(ABC):
     # Empty (default) = language-agnostic; list_voices() returns all voices unfiltered.
     supported_languages: ClassVar[frozenset[str]] = frozenset()
 
-    # Model-level defaults merged into every voice this provider serves, unless a
-    # voice overrides them (see app/providers/voice_loading.py).
+    # Model-level defaults. default_quality is merged into every voice this
+    # provider serves (see app/providers/voice_loading.py) and also surfaced
+    # server-wide via GET /service; default_controls is service-wide only.
     default_quality: ClassVar[Quality | None] = None
     default_controls: ClassVar[Controls] = Controls()
 

app/providers/elevenlabs.py

@@ -152,7 +152,7 @@ def _alignment_to_marks(
 
 class ElevenLabsProvider(TTSProvider):
     id = "elevenlabs"
-    default_quality: ClassVar[Quality] = Quality.HIGH
+    default_quality: ClassVar[Quality] = Quality.VERY_HIGH
     # v2 has no pitch and only partial SSML; speed maps to voice_settings.speed,
     # boundary comes from the /with-timestamps alignment.
     default_controls: ClassVar[Controls] = Controls(
@@ -214,9 +214,7 @@ async def load(self) -> None:
                 continue
             default_lang, installed = plan
             other_langs = installed - frozenset({primary})
-            voice = build_voice(
-                entry, self.id, other_langs, self.default_quality, self.default_controls
-            )
+            voice = build_voice(entry, self.id, other_langs, self.default_quality)
             self._voices.append(voice)
             self._voice_default_lang[voice.identifier] = default_lang
             self._voice_langs[voice.identifier] = installed

app/providers/pocket_tts.py

@@ -124,9 +124,7 @@ def _load_sync(self) -> bool:
                 continue
             default_lang, installed = plan
             other_langs = installed - frozenset({primary})
-            voice = build_voice(
-                entry, self.id, other_langs, self.default_quality, self.default_controls
-            )
+            voice = build_voice(entry, self.id, other_langs, self.default_quality)
             self._voices.append(voice)
             self._voice_default_lang[voice.identifier] = default_lang
             self._voice_langs[voice.identifier] = installed

app/providers/voice_loading.py

@@ -1,17 +1,7 @@
 from pydantic import BaseModel
 
 from app.domain.enums import Gender, Quality
-from app.schemas.voice import Controls, Voice
-
-
-class ControlsOverride(BaseModel):
-    """Partial per-voice override of a provider's default Controls. Unset (None)
-    fields fall back to the provider default — see merge_controls()."""
-
-    pitch: bool | None = None
-    speed: bool | None = None
-    ssml: bool | None = None
-    boundary: bool | None = None
+from app.schemas.voice import Voice
 
 
 class VoiceEntry(BaseModel):
@@ -25,7 +15,6 @@ class VoiceEntry(BaseModel):
     otherLanguages: list[str] = []
     gender: Gender | None = None
     quality: Quality | None = None
-    controls: ControlsOverride | None = None
 
 
 def _lang_prefix(lang: str) -> str:
@@ -84,23 +73,11 @@ def plan_install(
     return default_lang, installed
 
 
-def merge_controls(default: Controls, override: ControlsOverride | None) -> Controls:
-    if override is None:
-        return default
-    return Controls(
-        pitch=override.pitch if override.pitch is not None else default.pitch,
-        speed=override.speed if override.speed is not None else default.speed,
-        ssml=override.ssml if override.ssml is not None else default.ssml,
-        boundary=override.boundary if override.boundary is not None else default.boundary,
-    )
-
-
 def build_voice(
     entry: VoiceEntry,
     provider_id: str,
     installed_other: frozenset[str],
     default_quality: Quality | None,
-    default_controls: Controls,
 ) -> Voice:
     """The merge point where 'possible' (voices.json) becomes 'installed'
     (served via /voices): otherLanguages is installed_other, not entry.otherLanguages."""
@@ -113,5 +90,4 @@ def build_voice(
         otherLanguages=sorted(installed_other),
         gender=entry.gender,
         quality=entry.quality or default_quality,
-        controls=merge_controls(default_controls, entry.controls),
     )

app/schemas/voice.py

@@ -1,26 +1,17 @@
-from pydantic import BaseModel, model_serializer
+from pydantic import BaseModel
 
 from app.domain.enums import Gender, Quality
 
 
 class Controls(BaseModel):
-    """Which prosody/format controls a voice accepts. Provider-level defaults,
-    overridable per voice (see app/providers/voice_loading.py).
-
-    Serializes only the controls that are ENABLED — a control the voice doesn't
-    support is simply absent, not `false`. Keeps `/voices` and `/service` lean and
-    works the same for any provider (pocket → `{}`, an SSML voice → `{"ssml": true}`).
-    Internal Python access (e.g. `voice.controls.boundary`) still sees all fields."""
+    """Which prosody/format controls a provider supports. Server-wide per provider —
+    see GET /service — not per voice."""
 
     pitch: bool = False
     speed: bool = False
     ssml: bool = False
     boundary: bool = False  # true when the provider returns word-level timing marks
 
-    @model_serializer
-    def _serialize_enabled_only(self) -> dict[str, bool]:
-        return {k: True for k, v in self.__dict__.items() if v}
-
     def as_dict(self) -> dict[str, bool]:
         """Full booleans, including disabled ones — unlike the enabled-only JSON
         serialization above. Used by GET /service to show what a provider CAN do,
@@ -46,7 +37,6 @@ class Voice(BaseModel):
 
     # --- server extensions (not in ReadiumSpeechVoice) ---
     provider: str
-    controls: Controls = Controls()
 
 
 def voice_language_prefixes(voice: Voice) -> frozenset[str]: