Upload folder using huggingface_hub

.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.py[cod]
+.venv/
+.pytest_cache/
+.gradio/
+*.nemo
+*.wav
+*.mp3
+.DS_Store

AGENTS.md

@@ -0,0 +1,7 @@
+# Project instructions
+
+- Keep this project deployable as a Hugging Face Gradio Space on ZeroGPU.
+- Preserve the import order in `app.py`: set CUDA-related environment variables, import `spaces`, then import libraries that may touch CUDA.
+- Never commit Hugging Face tokens, API keys, generated audio, model checkpoints, or caches.
+- Run `python -m unittest discover -s tests -v` and `python -m py_compile app.py studio.py` after changes.
+- Update `docs/FEATURES.md` whenever features are added, edited, removed, renamed, made reachable, made unreachable, or newly covered by automated tests. Every feature must state its coverage and link to the exact test file when covered.

README.md

@@ -1,13 +1,53 @@
 ---
-title: Magpie Tts Studio
-emoji: ⚡
-colorFrom: indigo
-colorTo: red
+title: Magpie Voice Studio
+emoji: 🎙️
+colorFrom: yellow
+colorTo: green
 sdk: gradio
 sdk_version: 6.24.0
-python_version: '3.12'
 app_file: app.py
+python_version: "3.12"
+startup_duration_timeout: 1h
 pinned: false
+license: other
+license_name: nvidia-open-model-license
+license_link: https://www.nvidia.com/en-us/agreements/enterprise-software/nvidia-open-model-license
+short_description: Multilingual speech in five voices and 12 languages
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Magpie Voice Studio
+
+A polished ZeroGPU demo for NVIDIA's [MagpieTTS Multilingual 357M](https://huggingface.co/nvidia/magpie_tts_multilingual_357m) model. Write a short script, choose one of 12 languages and five fixed voices, and render 22.05 kHz speech in the browser.
+
+The app exposes a stable `/synthesize` Gradio API and MCP tool in addition to its visual interface. It does not support voice cloning.
+
+## Run locally
+
+Use Python 3.12 with an NVIDIA CUDA GPU:
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+python app.py
+```
+
+The model checkpoint is downloaded from Hugging Face on first launch. If model access requires authentication, set `HF_TOKEN` to a read token with access to the repository.
+
+## Test
+
+The fast test suite covers configuration, validation, ZeroGPU contracts, and Space metadata without loading the 5.5 GB model:
+
+```bash
+python -m unittest discover -s tests -v
+```
+
+See the exhaustive [feature inventory and automated test coverage matrix](docs/FEATURES.md).
+
+## Model and license
+
+- [MagpieTTS model card](https://huggingface.co/nvidia/magpie_tts_multilingual_357m)
+- [NanoCodec decoder](https://huggingface.co/nvidia/nemo-nano-codec-22khz-1.89kbps-21.5fps)
+- [NVIDIA Open Model License](https://www.nvidia.com/en-us/agreements/enterprise-software/nvidia-open-model-license)
+
+Model outputs may contain errors or accents. Review generated audio before production use.

app.py

@@ -0,0 +1,400 @@
+"""Magpie Voice Studio — a multilingual TTS demo for Hugging Face Spaces."""
+
+import os
+import time
+import traceback
+
+os.environ.setdefault("NUMBA_DISABLE_CUDA", "1")
+os.environ.setdefault("OMP_NUM_THREADS", "2")
+os.environ.setdefault("PYTORCH_CUDA_ALLOC_CONF", "expandable_segments:True")
+
+import spaces
+import gradio as gr
+from huggingface_hub import hf_hub_download
+from nemo.collections.tts.modules.magpietts_inference.utils import (
+    ModelLoadConfig,
+    load_magpie_model,
+)
+
+from studio import (
+    LANGUAGE_MAP,
+    SAMPLE_RATE,
+    SPEAKER_MAP,
+    estimate_gpu_duration,
+    result_summary,
+    validate_request,
+)
+
+
+MODEL_ID = "nvidia/magpie_tts_multilingual_357m"
+MODEL_FILENAME = "magpie_tts_multilingual_357m.nemo"
+CODEC_MODEL_ID = "nvidia/nemo-nano-codec-22khz-1.89kbps-21.5fps"
+
+checkpoint_path = hf_hub_download(
+    repo_id=MODEL_ID,
+    filename=MODEL_FILENAME,
+    token=os.environ.get("HF_TOKEN"),
+)
+model_config = ModelLoadConfig(
+    nemo_file=checkpoint_path,
+    codecmodel_path=CODEC_MODEL_ID,
+    legacy_codebooks=False,
+    legacy_text_conditioning=False,
+    hparams_from_wandb=None,
+)
+
+print(f"Loading {MODEL_ID} from {checkpoint_path}")
+model, _ = load_magpie_model(model_config)
+model.eval().to("cuda")
+print("MagpieTTS loaded and ready.")
+
+
+@spaces.GPU(duration=estimate_gpu_duration)
+def synthesize(
+    text: str,
+    language: str = "English",
+    speaker: str = "Sofia",
+    apply_text_normalization: bool = True,
+) -> tuple[tuple[int, object], str]:
+    """Synthesize mono WAV-quality speech from text with NVIDIA MagpieTTS.
+
+    Args:
+        text: UTF-8 text to speak, up to 600 characters.
+        language: One of the 12 language labels shown in the app.
+        speaker: One of Aria, Jason, John, Leo, or Sofia.
+        apply_text_normalization: Expand numbers and abbreviations before synthesis.
+
+    Returns:
+        An audio sample tuple and a short generation summary.
+    """
+
+    try:
+        request = validate_request(
+            text, language, speaker, apply_text_normalization
+        )
+    except ValueError as exc:
+        raise gr.Error(str(exc)) from exc
+
+    started_at = time.perf_counter()
+    try:
+        audio, audio_length = model.do_tts(
+            request.text,
+            language=request.language_code,
+            apply_TN=request.apply_text_normalization,
+            speaker_index=request.speaker_index,
+        )
+        audio_samples = audio[0, : int(audio_length[0])].detach().cpu().numpy()
+    except Exception as exc:
+        traceback.print_exc()
+        raise gr.Error(f"Speech synthesis failed: {exc}") from exc
+
+    elapsed = time.perf_counter() - started_at
+    print(
+        f"Synthesized {len(request.text)} chars in {elapsed:.2f}s "
+        f"({request.language_code}, speaker={request.speaker_index})"
+    )
+    return (
+        (SAMPLE_RATE, audio_samples),
+        result_summary(language, speaker, len(request.text), elapsed),
+    )
+
+
+CSS = """
+@import url('https://fonts.googleapis.com/css2?family=DM+Mono:wght@400;500&family=Instrument+Serif:ital@0;1&display=swap');
+
+:root {
+  --ink: #171714;
+  --paper: #f3f0e8;
+  --paper-2: #e7e2d6;
+  --acid: #c8ff38;
+  --orange: #ff6838;
+  --line: rgba(23, 23, 20, 0.2);
+}
+
+body, .gradio-container {
+  background:
+    radial-gradient(circle at 85% 4%, rgba(255, 104, 56, .16), transparent 24rem),
+    linear-gradient(rgba(23,23,20,.035) 1px, transparent 1px),
+    linear-gradient(90deg, rgba(23,23,20,.035) 1px, transparent 1px),
+    var(--paper) !important;
+  background-size: auto, 32px 32px, 32px 32px, auto !important;
+  color: var(--ink) !important;
+  font-family: 'DM Mono', monospace !important;
+}
+
+.dark .gradio-container { color: var(--body-text-color); }
+.gradio-container { max-width: 1240px !important; margin: 0 auto !important; }
+.contain, main { max-width: 1240px !important; margin-inline: auto !important; }
+.wrap { gap: 0 !important; }
+
+.hero {
+  position: relative;
+  overflow: hidden;
+  min-height: 350px;
+  padding: 38px 42px 34px;
+  border: 1.5px solid var(--ink);
+  border-radius: 4px 4px 0 0;
+  background: var(--ink);
+  color: var(--paper);
+}
+.hero::after {
+  content: '';
+  position: absolute;
+  width: 380px;
+  height: 380px;
+  right: -75px;
+  top: -135px;
+  border: 1px solid rgba(243,240,232,.34);
+  border-radius: 50%;
+  box-shadow: 0 0 0 54px rgba(243,240,232,.055), 0 0 0 108px rgba(243,240,232,.035);
+}
+.eyebrow, .panel-index {
+  color: var(--acid);
+  font: 500 12px/1.2 'DM Mono', monospace;
+  letter-spacing: .16em;
+  text-transform: uppercase;
+}
+.hero h1 {
+  max-width: 860px;
+  margin: 52px 0 20px;
+  font: 400 clamp(55px, 8vw, 102px)/.82 'Instrument Serif', serif;
+  letter-spacing: -.055em;
+}
+.hero h1 em { color: var(--acid); font-weight: 400; }
+.hero-copy {
+  max-width: 670px;
+  margin: 0;
+  color: rgba(243,240,232,.72);
+  font-size: 14px;
+  line-height: 1.65;
+}
+.signal {
+  position: absolute;
+  right: 44px;
+  bottom: 34px;
+  display: flex;
+  align-items: end;
+  gap: 5px;
+  height: 54px;
+}
+.signal i { width: 5px; background: var(--acid); animation: pulse 1.3s ease-in-out infinite alternate; }
+.signal i:nth-child(1), .signal i:nth-child(7) { height: 18px; }
+.signal i:nth-child(2), .signal i:nth-child(6) { height: 33px; animation-delay: -.4s; }
+.signal i:nth-child(3), .signal i:nth-child(5) { height: 47px; animation-delay: -.8s; }
+.signal i:nth-child(4) { height: 25px; animation-delay: -.2s; }
+@keyframes pulse { to { transform: scaleY(.45); opacity: .55; } }
+
+.stats {
+  display: grid;
+  grid-template-columns: repeat(4, 1fr);
+  border: 1.5px solid var(--ink);
+  border-top: 0;
+  background: var(--acid);
+}
+.stat { padding: 15px 20px; border-right: 1px solid var(--ink); }
+.stat:last-child { border-right: 0; }
+.stat b { display:block; font-size: 18px; }
+.stat span { font-size: 10px; text-transform: uppercase; letter-spacing: .1em; opacity: .65; }
+
+#studio-shell {
+  gap: 0 !important;
+  border: 1.5px solid var(--ink);
+  border-top: 0;
+  background: rgba(243,240,232,.86);
+}
+#controls-panel, #output-panel { padding: 30px !important; }
+#controls-panel { border-right: 1.5px solid var(--ink); }
+.panel-head { margin: 0 0 22px; }
+.panel-head h2 { margin: 8px 0 0; font: 400 37px/1 'Instrument Serif', serif; }
+.panel-index { color: rgba(23,23,20,.52); }
+
+.gradio-container label span, .gradio-container .label-wrap span {
+  font-family: 'DM Mono', monospace !important;
+  text-transform: uppercase;
+  letter-spacing: .08em;
+  font-size: 10px !important;
+}
+.gradio-container textarea, .gradio-container input {
+  font-family: 'DM Mono', monospace !important;
+}
+.gradio-container .block {
+  border-color: var(--line) !important;
+  border-radius: 2px !important;
+  box-shadow: none !important;
+}
+#script-box textarea { min-height: 190px !important; font-size: 16px !important; line-height: 1.6 !important; }
+#generate-btn {
+  min-height: 58px;
+  margin-top: 8px;
+  border: 1.5px solid var(--ink) !important;
+  border-radius: 2px !important;
+  background: var(--ink) !important;
+  color: var(--acid) !important;
+  font: 500 13px 'DM Mono', monospace !important;
+  letter-spacing: .12em;
+  text-transform: uppercase;
+  transition: transform .18s ease, box-shadow .18s ease !important;
+}
+#generate-btn:hover { transform: translate(-3px,-3px); box-shadow: 6px 6px 0 var(--orange) !important; }
+
+#audio-output { margin-top: 6px; min-height: 245px; background: var(--paper-2) !important; }
+#result-meta { min-height: 42px; border: 0 !important; background: transparent !important; }
+#result-meta p { font-size: 11px; letter-spacing: .03em; }
+.output-note { margin-top: 20px; padding: 17px; border-left: 4px solid var(--orange); background: rgba(255,104,56,.09); font-size: 11px; line-height: 1.6; }
+
+#examples-wrap { border: 1.5px solid var(--ink); border-top: 0; padding: 28px; }
+#examples-wrap h3 { margin: 0 0 4px; font: 400 29px 'Instrument Serif', serif; }
+#examples-wrap p { margin-top: 0; opacity: .65; font-size: 11px; }
+
+.footer {
+  display: flex;
+  justify-content: space-between;
+  gap: 24px;
+  padding: 21px 2px;
+  color: rgba(23,23,20,.66);
+  font-size: 10px;
+  line-height: 1.6;
+  text-transform: uppercase;
+  letter-spacing: .07em;
+}
+.footer a { color: var(--ink) !important; text-decoration: underline; text-underline-offset: 3px; }
+
+@media (max-width: 780px) {
+  .hero { min-height: 405px; padding: 28px 24px; }
+  .hero h1 { margin-top: 46px; font-size: 57px; }
+  .signal { right: 25px; bottom: 24px; transform: scale(.75); transform-origin: bottom right; }
+  .stats { grid-template-columns: repeat(2, 1fr); }
+  .stat:nth-child(2) { border-right: 0; }
+  .stat:nth-child(-n+2) { border-bottom: 1px solid var(--ink); }
+  #controls-panel { border-right: 0; border-bottom: 1.5px solid var(--ink); }
+  #controls-panel, #output-panel { padding: 24px !important; }
+  .footer { flex-direction: column; padding-inline: 5px; }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .signal i { animation: none; }
+  #generate-btn { transition: none !important; }
+}
+"""
+
+HERO = """
+<header class="hero">
+  <div class="eyebrow">Magpie / Voice Lab &nbsp;—&nbsp; NVIDIA NeMo</div>
+  <h1>Give text a<br><em>global voice.</em></h1>
+  <p class="hero-copy">A multilingual speech studio powered by MagpieTTS 357M. Write once, then hear one of five consistent voices speak across twelve languages.</p>
+  <div class="signal" aria-hidden="true"><i></i><i></i><i></i><i></i><i></i><i></i><i></i></div>
+</header>
+<div class="stats">
+  <div class="stat"><b>12</b><span>languages</span></div>
+  <div class="stat"><b>05</b><span>fixed voices</span></div>
+  <div class="stat"><b>22.05</b><span>kHz output</span></div>
+  <div class="stat"><b>357M</b><span>parameters</span></div>
+</div>
+"""
+
+FOOTER = """
+<footer class="footer">
+  <span>Built with MagpieTTS · No voice cloning · ZeroGPU</span>
+  <span><a href="https://huggingface.co/nvidia/magpie_tts_multilingual_357m" target="_blank">Model card ↗</a> &nbsp; <a href="https://www.nvidia.com/en-us/agreements/enterprise-software/nvidia-open-model-license" target="_blank">License ↗</a></span>
+</footer>
+"""
+
+EXAMPLES = [
+    ["Welcome to Magpie Voice Studio, where one voice can travel the world.", "English"],
+    ["Bienvenue dans le studio vocal multilingue de Magpie.", "French · Français"],
+    ["La tecnología puede acercar las voces y las culturas.", "Spanish · Español"],
+    ["音声技術で、ことばの世界をもっと身近に。", "Japanese · 日本語"],
+    ["언어의 경계를 넘어, 자연스러운 목소리를 만나보세요.", "Korean · 한국어"],
+    ["A tecnologia de voz conecta pessoas em todo o mundo.", "Portuguese · Português"],
+]
+
+
+with gr.Blocks(theme=gr.themes.Base(), css=CSS, title="Magpie Voice Studio") as demo:
+    gr.HTML(HERO)
+
+    with gr.Row(elem_id="studio-shell"):
+        with gr.Column(scale=6, elem_id="controls-panel"):
+            gr.HTML(
+                '<div class="panel-head"><span class="panel-index">01 / Script</span>'
+                '<h2>Compose your take</h2></div>'
+            )
+            script = gr.Textbox(
+                label="Text to synthesize",
+                placeholder="Type a sentence, a product line, or a short narration…",
+                lines=7,
+                max_lines=12,
+                max_length=600,
+                elem_id="script-box",
+            )
+            with gr.Row():
+                language = gr.Dropdown(
+                    choices=list(LANGUAGE_MAP),
+                    value="English",
+                    label="Language",
+                    scale=3,
+                )
+                speaker = gr.Dropdown(
+                    choices=list(SPEAKER_MAP),
+                    value="Sofia",
+                    label="Voice",
+                    scale=2,
+                )
+            normalize = gr.Checkbox(
+                value=True,
+                label="Normalize numbers and abbreviations",
+                info="Recommended. Turn off when using custom IPA between | pipes |.",
+            )
+            generate = gr.Button("Generate voice  →", variant="primary", elem_id="generate-btn")
+
+        with gr.Column(scale=5, elem_id="output-panel"):
+            gr.HTML(
+                '<div class="panel-head"><span class="panel-index">02 / Playback</span>'
+                '<h2>Listen to the take</h2></div>'
+            )
+            audio = gr.Audio(
+                label="Generated speech",
+                type="numpy",
+                interactive=False,
+                elem_id="audio-output",
+            )
+            metadata = gr.Markdown(
+                "**STANDING BY** &nbsp;·&nbsp; Your rendered take will appear here.",
+                elem_id="result-meta",
+            )
+            gr.HTML(
+                '<div class="output-note"><b>Studio note.</b> The five speakers are fixed model voices—not cloned voices. Non-English speech may retain an English accent.</div>'
+            )
+
+    with gr.Column(elem_id="examples-wrap"):
+        gr.HTML(
+            "<h3>Try a phrase</h3><p>Pick an example to load its text and language, then generate your take.</p>"
+        )
+        gr.Examples(
+            examples=EXAMPLES,
+            inputs=[script, language],
+            outputs=[audio, metadata],
+            fn=synthesize,
+            cache_examples=True,
+            cache_mode="lazy",
+        )
+
+    gr.HTML(FOOTER)
+
+    generate.click(
+        fn=synthesize,
+        inputs=[script, language, speaker, normalize],
+        outputs=[audio, metadata],
+        api_name="synthesize",
+        concurrency_limit=1,
+    )
+    script.submit(
+        fn=synthesize,
+        inputs=[script, language, speaker, normalize],
+        outputs=[audio, metadata],
+        api_name=False,
+        concurrency_limit=1,
+    )
+
+
+if __name__ == "__main__":
+    demo.launch(mcp_server=True)

docs/FEATURES.md

@@ -0,0 +1,26 @@
+# Feature inventory and automated test coverage
+
+Status reflects the current `main` branch. “Covered” means at least one automated test exercises the feature or its deploy-time contract; “Untested” is explicit by design.
+
+| Area | Feature | Reachability | Automated coverage |
+|---|---|---|---|
+| Synthesis | Generate speech from UTF-8 text | UI, Enter key, `/synthesize` API, MCP | Untested end-to-end; requires live ZeroGPU inference |
+| Synthesis | Twelve supported language mappings | UI, API, MCP | Covered: [`tests/test_studio.py`](../tests/test_studio.py) |
+| Synthesis | Five fixed speaker voices | UI, API, MCP | Covered: [`tests/test_studio.py`](../tests/test_studio.py) |
+| Synthesis | Optional text normalization | UI, API, MCP | Covered request mapping: [`tests/test_studio.py`](../tests/test_studio.py); model behavior untested |
+| Synthesis | Automatic terminal punctuation | UI, API, MCP | Covered: [`tests/test_studio.py`](../tests/test_studio.py) |
+| Synthesis | Empty and whitespace-only input rejection | UI, API, MCP | Covered: [`tests/test_studio.py`](../tests/test_studio.py) |
+| Synthesis | 600-character input limit | UI, API, MCP | Covered: [`tests/test_studio.py`](../tests/test_studio.py) |
+| Synthesis | 22.05 kHz mono audio output | UI, API, MCP | Constant covered: [`tests/test_studio.py`](../tests/test_studio.py); waveform format untested locally |
+| Runtime | NVIDIA MagpieTTS 357M and NanoCodec loading | Space startup | Untested locally; verified from live Space logs after deployment |
+| Runtime | Dynamic, bounded ZeroGPU reservation | All synthesis routes | Covered: [`tests/test_studio.py`](../tests/test_studio.py) |
+| Runtime | CUDA-safe import order and no forbidden Space runtime pins | Space startup | Covered: [`tests/test_space_contract.py`](../tests/test_space_contract.py) |
+| Runtime | Serialized inference to protect shared model state | UI and API queue | Covered by source contract: [`tests/test_space_contract.py`](../tests/test_space_contract.py) |
+| Interface | Responsive editorial voice-studio layout | Browser UI | Untested (visual) |
+| Interface | Language, voice, and normalization controls | Browser UI | Untested (browser interaction) |
+| Interface | Audio playback and downloadable Gradio audio | Browser UI | Untested (browser interaction) |
+| Interface | Six multilingual example prompts with lazy caching | Browser UI | Covered by source contract: [`tests/test_space_contract.py`](../tests/test_space_contract.py); clicks untested |
+| Interface | Reduced-motion accessibility behavior | Browser UI | Covered by source contract: [`tests/test_space_contract.py`](../tests/test_space_contract.py) |
+| Interface | Model limitations, license, and source links | Browser UI, README | Untested (content review) |
+| Integration | Stable `/synthesize` Gradio endpoint | API | Covered by source contract: [`tests/test_space_contract.py`](../tests/test_space_contract.py); live call required for e2e |
+| Integration | MCP server exposing documented synthesis tool | MCP | Covered by source contract: [`tests/test_space_contract.py`](../tests/test_space_contract.py); MCP client call untested |

requirements.txt

@@ -0,0 +1,3 @@
+nemo_toolkit[tts] @ git+https://github.com/NVIDIA-NeMo/Speech.git@24c4f58a764350a62248094c70e487892e9d1a00
+git+https://github.com/NVIDIA/NeMo-text-processing.git@1f1263579fe57ba7ed783cad3dddee710fcc5064
+kaldialign

studio.py

@@ -0,0 +1,95 @@
+"""Pure configuration and validation helpers for Magpie Voice Studio."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+MAX_TEXT_LENGTH = 600
+SAMPLE_RATE = 22_050
+
+SPEAKER_MAP = {
+    "Aria": 0,
+    "Jason": 1,
+    "John": 2,
+    "Leo": 3,
+    "Sofia": 4,
+}
+
+LANGUAGE_MAP = {
+    "Arabic · العربية": "ar-MSA",
+    "Chinese · 中文": "zh",
+    "English": "en",
+    "French · Français": "fr",
+    "German · Deutsch": "de",
+    "Hindi · हिन्दी": "hi",
+    "Italian · Italiano": "it",
+    "Japanese · 日本語": "ja",
+    "Korean · 한국어": "ko",
+    "Portuguese · Português": "pt-BR",
+    "Spanish · Español": "es",
+    "Vietnamese · Tiếng Việt": "vi",
+}
+
+
+@dataclass(frozen=True)
+class SynthesisRequest:
+    """A validated speech synthesis request."""
+
+    text: str
+    language_code: str
+    speaker_index: int
+    apply_text_normalization: bool
+
+
+def validate_request(
+    text: str | None,
+    language: str,
+    speaker: str,
+    apply_text_normalization: bool,
+) -> SynthesisRequest:
+    """Validate and normalize values received from the Gradio API."""
+
+    clean_text = (text or "").strip()
+    if not clean_text:
+        raise ValueError("Enter some text to synthesize.")
+    if len(clean_text) > MAX_TEXT_LENGTH:
+        raise ValueError(
+            f"Keep the script under {MAX_TEXT_LENGTH} characters for this demo."
+        )
+    if language not in LANGUAGE_MAP:
+        raise ValueError("Choose one of the supported languages.")
+    if speaker not in SPEAKER_MAP:
+        raise ValueError("Choose one of the available Magpie voices.")
+
+    if clean_text[-1] not in ".?!。！？":
+        clean_text += "."
+
+    return SynthesisRequest(
+        text=clean_text,
+        language_code=LANGUAGE_MAP[language],
+        speaker_index=SPEAKER_MAP[speaker],
+        apply_text_normalization=bool(apply_text_normalization),
+    )
+
+
+def estimate_gpu_duration(text: str | None, *_args: object, **_kwargs: object) -> int:
+    """Estimate a bounded ZeroGPU reservation from the requested text length."""
+
+    character_count = len((text or "").strip())
+    return min(180, max(75, 55 + character_count // 3))
+
+
+def result_summary(
+    language: str,
+    speaker: str,
+    character_count: int,
+    elapsed_seconds: float,
+) -> str:
+    """Create the compact result metadata displayed under the audio player."""
+
+    return (
+        f"**READY**  ·  {language}  ·  {speaker}  ·  "
+        f"{character_count} chars  ·  {SAMPLE_RATE / 1000:g} kHz  ·  "
+        f"{elapsed_seconds:.1f}s inference"
+    )

tests/test_space_contract.py

@@ -0,0 +1,50 @@
+from pathlib import Path
+import unittest
+
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+class SpaceContractTests(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):
+        cls.app = (ROOT / "app.py").read_text()
+        cls.readme = (ROOT / "README.md").read_text()
+        cls.requirements = (ROOT / "requirements.txt").read_text()
+
+    def test_spaces_import_precedes_cuda_touching_libraries(self):
+        self.assertLess(self.app.index("import spaces"), self.app.index("import gradio"))
+        self.assertLess(self.app.index("import spaces"), self.app.index("from nemo"))
+
+    def test_gpu_function_is_bound_to_stable_api(self):
+        self.assertIn("@spaces.GPU(duration=estimate_gpu_duration)", self.app)
+        self.assertIn('api_name="synthesize"', self.app)
+        self.assertIn("concurrency_limit=1", self.app)
+
+    def test_examples_use_lazy_cache(self):
+        self.assertIn('cache_mode="lazy"', self.app)
+        self.assertIn("cache_examples=True", self.app)
+
+    def test_mcp_server_and_accessibility_contracts_are_enabled(self):
+        self.assertIn("demo.launch(mcp_server=True)", self.app)
+        self.assertIn("prefers-reduced-motion", self.app)
+
+    def test_runtime_managed_packages_are_not_pinned(self):
+        package_names = {
+            line.split("=", 1)[0].strip().lower()
+            for line in self.requirements.splitlines()
+            if line.strip() and not line.startswith("#")
+        }
+        self.assertNotIn("gradio", package_names)
+        self.assertNotIn("spaces", package_names)
+        self.assertNotIn("huggingface_hub", package_names)
+
+    def test_space_metadata_and_feature_inventory_link_exist(self):
+        self.assertIn("sdk: gradio", self.readme)
+        self.assertIn('python_version: "3.12"', self.readme)
+        self.assertIn("docs/FEATURES.md", self.readme)
+        self.assertTrue((ROOT / "docs" / "FEATURES.md").is_file())
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_studio.py

@@ -0,0 +1,77 @@
+import unittest
+
+from studio import (
+    LANGUAGE_MAP,
+    MAX_TEXT_LENGTH,
+    SAMPLE_RATE,
+    SPEAKER_MAP,
+    estimate_gpu_duration,
+    result_summary,
+    validate_request,
+)
+
+
+class StudioConfigurationTests(unittest.TestCase):
+    def test_all_twelve_languages_are_exposed(self):
+        self.assertEqual(len(LANGUAGE_MAP), 12)
+        self.assertEqual(
+            set(LANGUAGE_MAP.values()),
+            {"ar-MSA", "de", "en", "es", "fr", "hi", "it", "ja", "ko", "pt-BR", "vi", "zh"},
+        )
+
+    def test_all_five_voices_map_to_unique_indices(self):
+        self.assertEqual(set(SPEAKER_MAP), {"Aria", "Jason", "John", "Leo", "Sofia"})
+        self.assertEqual(set(SPEAKER_MAP.values()), set(range(5)))
+
+    def test_sample_rate_is_22050_hz(self):
+        self.assertEqual(SAMPLE_RATE, 22_050)
+
+
+class RequestValidationTests(unittest.TestCase):
+    def test_valid_request_is_stripped_and_punctuated(self):
+        request = validate_request("  Hello world  ", "English", "Sofia", True)
+        self.assertEqual(request.text, "Hello world.")
+        self.assertEqual(request.language_code, "en")
+        self.assertEqual(request.speaker_index, 4)
+        self.assertTrue(request.apply_text_normalization)
+
+    def test_supported_non_latin_punctuation_is_preserved(self):
+        request = validate_request("こんにちは。", "Japanese · 日本語", "Aria", False)
+        self.assertEqual(request.text, "こんにちは。")
+        self.assertFalse(request.apply_text_normalization)
+
+    def test_empty_input_is_rejected(self):
+        for value in (None, "", "   "):
+            with self.subTest(value=value), self.assertRaisesRegex(ValueError, "Enter some text"):
+                validate_request(value, "English", "Sofia", True)
+
+    def test_too_long_input_is_rejected(self):
+        with self.assertRaisesRegex(ValueError, str(MAX_TEXT_LENGTH)):
+            validate_request("x" * (MAX_TEXT_LENGTH + 1), "English", "Sofia", True)
+
+    def test_unknown_language_is_rejected(self):
+        with self.assertRaisesRegex(ValueError, "supported languages"):
+            validate_request("Hello", "Klingon", "Sofia", True)
+
+    def test_unknown_speaker_is_rejected(self):
+        with self.assertRaisesRegex(ValueError, "available Magpie voices"):
+            validate_request("Hello", "English", "Unknown", True)
+
+
+class RuntimeHelperTests(unittest.TestCase):
+    def test_duration_estimate_is_bounded_and_scales(self):
+        self.assertEqual(estimate_gpu_duration("short"), 75)
+        self.assertGreater(estimate_gpu_duration("x" * 300), 75)
+        self.assertEqual(estimate_gpu_duration("x" * 10_000), 180)
+
+    def test_result_summary_contains_generation_metadata(self):
+        summary = result_summary("English", "Sofia", 42, 3.26)
+        self.assertIn("English", summary)
+        self.assertIn("Sofia", summary)
+        self.assertIn("42 chars", summary)
+        self.assertIn("22.05 kHz", summary)
+        self.assertIn("3.3s inference", summary)
+
+
+if __name__ == "__main__":
+    unittest.main()