Add optional LFM3-Audio-2B engine (off unless LFM3_ENABLED=1)

README.md

@@ -1,11 +1,36 @@
----
-title: Kokoro TTS
-emoji: 🗣️
-colorFrom: indigo
-colorTo: purple
-sdk: gradio
-sdk_version: 6.6.0
-app_file: app.py
-pinned: false
-python_version: "3.10"
----
+---
+title: Kokoro TTS
+emoji: 🗣️
+colorFrom: indigo
+colorTo: purple
+sdk: gradio
+sdk_version: 6.6.0
+app_file: app.py
+pinned: false
+python_version: "3.11"
+---
+
+# Kokoro TTS (and optional LFM3 for comparison)
+
+Kokoro-82M answers on `/` (Gradio) and `POST /tts/stream` (raw PCM16 mono, streamed).
+
+## Optional second engine: LFM3-Audio-2B
+
+Off by default. To compare it with Kokoro in the same Space, set the Space variable
+`LFM3_ENABLED=1`. It adds routes with the same contract under `/lfm3/tts`:
+
+- `POST /lfm3/tts/stream`: `{"text", "voice": "female" | "male" | "af_heart"-style, "sample_rate": 16000 | 24000}`;
+  `speed` is ignored (LFM3 has no speed control).
+- `POST /lfm3/tts/bench`: seconds spent synthesizing vs seconds of audio, per piece.
+  The first call loads the model, so read the second.
+- `GET /lfm3/tts/health`.
+
+The ~8 GB model (float32 on CPU) loads on the first LFM3 request, not at start-up, so Kokoro
+is unaffected until then. LFM3 and Kokoro share the 2 vCPUs: benchmark them one at a time.
+`TTS_API_KEY`, when set, protects both engines' POST routes.
+
+To make the tutor use LFM3, point `KOKORO_HF_SPACE_URL` at `https://<space>.hf.space/lfm3`
+(the client appends `/tts/stream`). Compare both with
+`python -m scripts.compare_tts_spaces --space kokoro=https://<space>.hf.space --space lfm3=https://<space>.hf.space/lfm3`.
+
+License of the model: LFM Open License v1.0 (commercial use only below US$10M annual revenue).

app.py

@@ -1,278 +1,277 @@
-"""Kokoro-82M TTS Space: Gradio UI + a streaming HTTP endpoint.
-
-- Gradio UI and its API (/generate_tts) are unchanged, so existing clients
-  (gradio_client.predict) keep working.
-- POST /tts/stream returns raw PCM16 mono audio WHILE it is being generated:
-  the text is cut into pieces (the first sentence at its first clause, so the
-  first audio is short), each piece is synthesized and sent as soon as it is
-  ready. No Gradio queue, no WAV file to download, resampled to 16 kHz here.
-
-Engine (KOKORO_ENGINE): "onnx" (default) runs the same Kokoro-82M v1.0
-weights through ONNX Runtime (kokoro-onnx), with phonemes from Kokoro's own
-G2P (misaki) so pronunciation is unchanged; "torch" is the original
-PyTorch KPipeline. If ONNX can't start, it falls back to torch.
-
-The Space runs on 2 shared vCPUs: one synthesis at a time (a lock per piece,
-so concurrent requests interleave piece by piece instead of waiting for a
-whole reply).
-"""
-import os
-import re
-import threading
-import time
-import urllib.request
-
-import gradio as gr
-import numpy as np
-import torch
-import uvicorn
-from fastapi import FastAPI, HTTPException, Request
-from fastapi.responses import JSONResponse, StreamingResponse
-from kokoro import KPipeline
-from scipy.signal import resample_poly
-
-def _cpu_quota() -> int:
-    """CPUs this container may really use. os.cpu_count() reports the host
-    (16 on HF cpu-basic, which gives 2 vCPUs): that many threads would fight
-    over 2 cores. Reads the cgroup quota; KOKORO_THREADS overrides."""
-    env = os.getenv("KOKORO_THREADS", "").strip()
-    if env.isdigit() and int(env) > 0:
-        return int(env)
-    try:
-        quota, period = open("/sys/fs/cgroup/cpu.max").read().split()[:2]
-        if quota != "max":
-            return max(1, int(int(quota) / int(period)))
-    except (OSError, ValueError):
-        pass
-    try:
-        q = int(open("/sys/fs/cgroup/cpu/cpu.cfs_quota_us").read())
-        p = int(open("/sys/fs/cgroup/cpu/cpu.cfs_period_us").read())
-        if q > 0:
-            return max(1, q // p)
-    except (OSError, ValueError):
-        pass
-    try:
-        return max(1, len(os.sched_getaffinity(0)))
-    except AttributeError:
-        return max(1, os.cpu_count() or 1)
-
-
-THREADS = _cpu_quota()
-torch.set_num_threads(THREADS)
-
-# Optional shared secret (Space secret TTS_API_KEY): when set, /tts/stream
-# requires the X-API-Key header. The Gradio UI stays public as before.
-API_KEY = os.getenv("TTS_API_KEY", "").strip()
-MAX_CHARS = 600
-FIRST_PIECE_MAX = 60  # first sentence longer than this is cut at its first clause
-SAMPLE_RATE = 24000   # Kokoro output
-
-_LANGS = {"a": ("af_", "am_"), "b": ("bf_", "bm_"), "p": ("pf_", "pm_")}
-_pipelines: dict = {}
-_pipelines_lock = threading.Lock()
-_synth_lock = threading.Lock()
-
-# ---------------------------------------------------------------- engine
-
-ONNX_RELEASE = "https://github.com/thewh1teagle/kokoro-onnx/releases/download/model-files-v1.0"
-ONNX_FILES = ("kokoro-v1.0.onnx", "voices-v1.0.bin")
-MODEL_DIR = os.getenv("KOKORO_MODEL_DIR", os.path.join(os.path.dirname(os.path.abspath(__file__)), "models"))
-ENGINE = os.getenv("KOKORO_ENGINE", "onnx").strip().lower()
-_onnx = None  # kokoro_onnx.Kokoro when the ONNX engine is active
-
-
-def _start_onnx():
-    import onnxruntime as ort
-    from kokoro_onnx import Kokoro
-
-    os.makedirs(MODEL_DIR, exist_ok=True)
-    for name in ONNX_FILES:
-        path = os.path.join(MODEL_DIR, name)
-        if not os.path.exists(path) or os.path.getsize(path) == 0:
-            t0 = time.perf_counter()
-            urllib.request.urlretrieve(f"{ONNX_RELEASE}/{name}", path + ".part")
-            os.replace(path + ".part", path)
-            print(f"[TTS] downloaded {name} in {time.perf_counter() - t0:.1f}s")
-    opts = ort.SessionOptions()
-    opts.intra_op_num_threads = THREADS
-    opts.inter_op_num_threads = 1
-    opts.graph_optimization_level = ort.GraphOptimizationLevel.ORT_ENABLE_ALL
-    session = ort.InferenceSession(
-        os.path.join(MODEL_DIR, ONNX_FILES[0]), sess_options=opts, providers=["CPUExecutionProvider"]
-    )
-    return Kokoro.from_session(session, os.path.join(MODEL_DIR, ONNX_FILES[1]))
-
-
-if ENGINE == "onnx":
-    try:
-        _onnx = _start_onnx()
-        print(f"[TTS] engine: onnx ({THREADS} threads)")
-    except Exception as e:
-        print(f"[TTS] onnx failed ({e}); falling back to torch")
-        ENGINE = "torch"
-if ENGINE != "onnx":
-    print(f"[TTS] engine: torch ({THREADS} threads)")
-
-
-def get_pipeline_for_voice(voice_id: str) -> KPipeline:
-    """American English is loaded at start-up; British / Portuguese on first
-    use. With ONNX the pipeline is G2P only (model=False)."""
-    lang = next((code for code, prefixes in _LANGS.items() if voice_id.startswith(prefixes)), "a")
-    with _pipelines_lock:
-        if lang not in _pipelines:
-            _pipelines[lang] = KPipeline(lang_code=lang, repo_id="hexgrad/Kokoro-82M", model=_onnx is None)
-        return _pipelines[lang]
-
-
-get_pipeline_for_voice("af_heart")
-
-
-def _synth(text: str, voice_id: str, speed: float) -> np.ndarray:
-    """Float32 mono audio at 24 kHz for one piece of text."""
-    pipeline = get_pipeline_for_voice(voice_id)
-    segments = []
-    with _synth_lock:
-        if _onnx is not None:
-            for result in pipeline(text, voice=voice_id, split_pattern=None):
-                if result.phonemes:
-                    audio, _sr = _onnx.create(result.phonemes, voice=voice_id, speed=speed, is_phonemes=True)
-                    segments.append(np.asarray(audio, dtype=np.float32))
-        else:
-            for _gs, _ps, audio in pipeline(text, voice=voice_id, speed=speed, split_pattern=None):
-                seg = np.asarray(audio, dtype=np.float32)
-                if seg.ndim > 1:
-                    seg = seg.mean(axis=-1)
-                if seg.size:
-                    segments.append(seg)
-    return np.concatenate(segments) if segments else np.zeros(0, dtype=np.float32)
-
-
-_SENTENCE = re.compile(r"(?<=[.!?…])\s+")
-_CLAUSE = re.compile(r"(?<=[,;:])\s+")
-
-
-def split_for_streaming(text: str) -> list:
-    """Sentences, with the first one cut at its first clause when long, so
-    the first audio arrives after synthesizing only a few words."""
-    sentences = [s.strip() for s in _SENTENCE.split(text) if s.strip()]
-    if not sentences:
-        return []
-    first = sentences[0]
-    if len(first) > FIRST_PIECE_MAX:
-        parts = _CLAUSE.split(first, maxsplit=1)
-        if len(parts) == 2 and len(parts[0]) >= 12 and len(parts[1]) >= 12:
-            return [parts[0], parts[1]] + sentences[1:]
-    return sentences
-
-
-def _to_pcm16(audio: np.ndarray, rate: int) -> bytes:
-    if rate == 16000:
-        audio = resample_poly(audio, 2, 3)  # 24 kHz -> 16 kHz
-    return (np.clip(audio, -1.0, 1.0) * 32767).astype(np.int16).tobytes()
-
-
-# ---------------------------------------------------------------- Gradio UI
-
-
-def generate_tts(text: str, voice_id: str, speed: float):
-    try:
-        text = (text or "").strip()[:MAX_CHARS]
-        if not text:
-            return None
-        audio = np.concatenate([_synth(p, voice_id, speed) for p in split_for_streaming(text)])
-        return (SAMPLE_RATE, audio) if audio.size else None
-    except Exception as e:
-        print(f"[TTS] Erro: {e}")
-        return None
-
-
-VOICES = [
-    "af_heart", "af_alloy", "af_aoede", "af_bella", "af_jessica",
-    "af_kore", "af_nicole", "af_nova", "af_river", "af_sarah", "af_sky",
-    "am_adam", "am_echo", "am_eric", "am_fenrir", "am_liam",
-    "am_michael", "am_onyx", "am_orion", "am_puck",
-    "bf_alice", "bf_emma", "bf_isabella",
-    "bm_george", "bm_lewis",
-    "pf_dora", "pm_alex", "pm_santa",
-]
-
-demo = gr.Interface(
-    fn=generate_tts,
-    inputs=[
-        gr.Textbox(label="Texto", lines=3, placeholder="Digite o texto aqui..."),
-        gr.Dropdown(choices=VOICES, value="af_heart", label="Voz"),
-        gr.Slider(minimum=0.5, maximum=2.0, value=1.0, step=0.1, label="Velocidade"),
-    ],
-    outputs=gr.Audio(label="Audio Gerado"),
-    title="Kokoro-82M TTS",
-    description="Ingles Americano / Britanico e Portugues Brasileiro.",
-)
-
-# ---------------------------------------------------------------- HTTP API
-
-app = FastAPI()
-
-
-@app.get("/tts/health")
-def tts_health():
-    return {"ok": True, "engine": ENGINE, "threads": THREADS, "voices": len(VOICES), "loaded": sorted(_pipelines)}
-
-
-@app.post("/tts/stream")
-async def tts_stream(request: Request):
-    """Body: {"text", "voice"="af_heart", "speed"=1.0, "sample_rate"=16000}.
-    Response: raw PCM16 mono little-endian, streamed piece by piece."""
-    if API_KEY and request.headers.get("x-api-key") != API_KEY:
-        raise HTTPException(status_code=401, detail="invalid api key")
-    try:
-        body = await request.json()
-    except Exception:
-        raise HTTPException(status_code=400, detail="json body required")
-    text = str(body.get("text") or "").strip()[:MAX_CHARS]
-    voice = str(body.get("voice") or "af_heart")
-    if voice not in VOICES:
-        raise HTTPException(status_code=400, detail="unknown voice")
-    try:
-        speed = min(2.0, max(0.5, float(body.get("speed") or 1.0)))
-        rate = int(body.get("sample_rate") or 16000)
-    except (TypeError, ValueError):
-        raise HTTPException(status_code=400, detail="invalid speed or sample_rate")
-    if rate not in (16000, 24000):
-        raise HTTPException(status_code=400, detail="sample_rate must be 16000 or 24000")
-    if not text:
-        return JSONResponse({"detail": "empty text"}, status_code=400)
-
-    pieces = split_for_streaming(text)
-
-    def generate():
-        t0 = time.perf_counter()
-        for i, piece in enumerate(pieces):
-            pcm = _to_pcm16(_synth(piece, voice, speed), rate)
-            if i == 0:
-                print(f"[TTS stream] first piece in {time.perf_counter() - t0:.2f}s ({len(piece)} chars)")
-            yield pcm
-
-    return StreamingResponse(
-        generate(),  # sync generator: Starlette runs it in a worker thread
-        media_type="application/octet-stream",
-        headers={"X-Sample-Rate": str(rate), "X-Pieces": str(len(pieces)), "Cache-Control": "no-store"},
-    )
-
-
-app = gr.mount_gradio_app(app, demo, path="/")
-
-
-def _warmup():
-    try:
-        _synth("Hello there.", "af_heart", 1.0)
-        print("[TTS] warm-up done")
-    except Exception as e:
-        print(f"[TTS] warm-up failed: {e}")
-
-
-threading.Thread(target=_warmup, daemon=True).start()
-
-if __name__ == "__main__":
-    # HF Spaces (Gradio SDK) expose GRADIO_SERVER_PORT (7860); 7861 is taken
-    # by the platform there, so PORT is not used.
-    uvicorn.run(app, host="0.0.0.0", port=int(os.getenv("GRADIO_SERVER_PORT", "7860")))
+"""Kokoro-82M TTS Space: Gradio UI + a streaming HTTP endpoint.
+
+- Gradio UI and its API (/generate_tts) are unchanged, so existing clients
+  (gradio_client.predict) keep working.
+- POST /tts/stream returns raw PCM16 mono audio WHILE it is being generated:
+  the text is cut into pieces (the first sentence at its first clause, so the
+  first audio is short), each piece is synthesized and sent as soon as it is
+  ready. No Gradio queue, no WAV file to download, resampled to 16 kHz here.
+
+Engine (KOKORO_ENGINE): "onnx" (default) runs the same Kokoro-82M v1.0
+weights through ONNX Runtime (kokoro-onnx), with phonemes from Kokoro's own
+G2P (misaki) so pronunciation is unchanged; "torch" is the original
+PyTorch KPipeline. If ONNX can't start, it falls back to torch.
+
+The Space runs on 2 shared vCPUs: one synthesis at a time (a lock per piece,
+so concurrent requests interleave piece by piece instead of waiting for a
+whole reply).
+"""
+import os
+import threading
+import time
+import urllib.request
+
+import gradio as gr
+import numpy as np
+import torch
+import uvicorn
+from fastapi import FastAPI, HTTPException, Request
+from fastapi.responses import JSONResponse, StreamingResponse
+from kokoro import KPipeline
+from scipy.signal import resample_poly
+
+import lfm3_engine
+from pieces import split_for_streaming
+
+def _cpu_quota() -> int:
+    """CPUs this container may really use. os.cpu_count() reports the host
+    (16 on HF cpu-basic, which gives 2 vCPUs): that many threads would fight
+    over 2 cores. Reads the cgroup quota; KOKORO_THREADS overrides."""
+    env = os.getenv("KOKORO_THREADS", "").strip()
+    if env.isdigit() and int(env) > 0:
+        return int(env)
+    try:
+        quota, period = open("/sys/fs/cgroup/cpu.max").read().split()[:2]
+        if quota != "max":
+            return max(1, int(int(quota) / int(period)))
+    except (OSError, ValueError):
+        pass
+    try:
+        q = int(open("/sys/fs/cgroup/cpu/cpu.cfs_quota_us").read())
+        p = int(open("/sys/fs/cgroup/cpu/cpu.cfs_period_us").read())
+        if q > 0:
+            return max(1, q // p)
+    except (OSError, ValueError):
+        pass
+    try:
+        return max(1, len(os.sched_getaffinity(0)))
+    except AttributeError:
+        return max(1, os.cpu_count() or 1)
+
+
+THREADS = _cpu_quota()
+torch.set_num_threads(THREADS)
+
+# Optional shared secret (Space secret TTS_API_KEY): when set, /tts/stream
+# requires the X-API-Key header. The Gradio UI stays public as before.
+API_KEY = os.getenv("TTS_API_KEY", "").strip()
+MAX_CHARS = 600
+SAMPLE_RATE = 24000   # Kokoro output
+
+_LANGS = {"a": ("af_", "am_"), "b": ("bf_", "bm_"), "p": ("pf_", "pm_")}
+_pipelines: dict = {}
+_pipelines_lock = threading.Lock()
+_synth_lock = threading.Lock()
+
+# ---------------------------------------------------------------- engine
+
+ONNX_RELEASE = "https://github.com/thewh1teagle/kokoro-onnx/releases/download/model-files-v1.0"
+ONNX_FILES = ("kokoro-v1.0.onnx", "voices-v1.0.bin")
+MODEL_DIR = os.getenv("KOKORO_MODEL_DIR", os.path.join(os.path.dirname(os.path.abspath(__file__)), "models"))
+ENGINE = os.getenv("KOKORO_ENGINE", "onnx").strip().lower()
+_onnx = None  # kokoro_onnx.Kokoro when the ONNX engine is active
+
+
+def _start_onnx():
+    import onnxruntime as ort
+    from kokoro_onnx import Kokoro
+
+    os.makedirs(MODEL_DIR, exist_ok=True)
+    for name in ONNX_FILES:
+        path = os.path.join(MODEL_DIR, name)
+        if not os.path.exists(path) or os.path.getsize(path) == 0:
+            t0 = time.perf_counter()
+            urllib.request.urlretrieve(f"{ONNX_RELEASE}/{name}", path + ".part")
+            os.replace(path + ".part", path)
+            print(f"[TTS] downloaded {name} in {time.perf_counter() - t0:.1f}s")
+    opts = ort.SessionOptions()
+    opts.intra_op_num_threads = THREADS
+    opts.inter_op_num_threads = 1
+    opts.graph_optimization_level = ort.GraphOptimizationLevel.ORT_ENABLE_ALL
+    session = ort.InferenceSession(
+        os.path.join(MODEL_DIR, ONNX_FILES[0]), sess_options=opts, providers=["CPUExecutionProvider"]
+    )
+    return Kokoro.from_session(session, os.path.join(MODEL_DIR, ONNX_FILES[1]))
+
+
+if ENGINE == "onnx":
+    try:
+        _onnx = _start_onnx()
+        print(f"[TTS] engine: onnx ({THREADS} threads)")
+    except Exception as e:
+        print(f"[TTS] onnx failed ({e}); falling back to torch")
+        ENGINE = "torch"
+if ENGINE != "onnx":
+    print(f"[TTS] engine: torch ({THREADS} threads)")
+
+
+def get_pipeline_for_voice(voice_id: str) -> KPipeline:
+    """American English is loaded at start-up; British / Portuguese on first
+    use. With ONNX the pipeline is G2P only (model=False)."""
+    lang = next((code for code, prefixes in _LANGS.items() if voice_id.startswith(prefixes)), "a")
+    with _pipelines_lock:
+        if lang not in _pipelines:
+            _pipelines[lang] = KPipeline(lang_code=lang, repo_id="hexgrad/Kokoro-82M", model=_onnx is None)
+        return _pipelines[lang]
+
+
+get_pipeline_for_voice("af_heart")
+
+
+def _synth(text: str, voice_id: str, speed: float) -> np.ndarray:
+    """Float32 mono audio at 24 kHz for one piece of text."""
+    pipeline = get_pipeline_for_voice(voice_id)
+    segments = []
+    with _synth_lock:
+        if _onnx is not None:
+            for result in pipeline(text, voice=voice_id, split_pattern=None):
+                if result.phonemes:
+                    audio, _sr = _onnx.create(result.phonemes, voice=voice_id, speed=speed, is_phonemes=True)
+                    segments.append(np.asarray(audio, dtype=np.float32))
+        else:
+            for _gs, _ps, audio in pipeline(text, voice=voice_id, speed=speed, split_pattern=None):
+                seg = np.asarray(audio, dtype=np.float32)
+                if seg.ndim > 1:
+                    seg = seg.mean(axis=-1)
+                if seg.size:
+                    segments.append(seg)
+    return np.concatenate(segments) if segments else np.zeros(0, dtype=np.float32)
+
+
+def _to_pcm16(audio: np.ndarray, rate: int) -> bytes:
+    if rate == 16000:
+        audio = resample_poly(audio, 2, 3)  # 24 kHz -> 16 kHz
+    return (np.clip(audio, -1.0, 1.0) * 32767).astype(np.int16).tobytes()
+
+
+# ---------------------------------------------------------------- Gradio UI
+
+
+def generate_tts(text: str, voice_id: str, speed: float):
+    try:
+        text = (text or "").strip()[:MAX_CHARS]
+        if not text:
+            return None
+        audio = np.concatenate([_synth(p, voice_id, speed) for p in split_for_streaming(text)])
+        return (SAMPLE_RATE, audio) if audio.size else None
+    except Exception as e:
+        print(f"[TTS] Erro: {e}")
+        return None
+
+
+VOICES = [
+    "af_heart", "af_alloy", "af_aoede", "af_bella", "af_jessica",
+    "af_kore", "af_nicole", "af_nova", "af_river", "af_sarah", "af_sky",
+    "am_adam", "am_echo", "am_eric", "am_fenrir", "am_liam",
+    "am_michael", "am_onyx", "am_orion", "am_puck",
+    "bf_alice", "bf_emma", "bf_isabella",
+    "bm_george", "bm_lewis",
+    "pf_dora", "pm_alex", "pm_santa",
+]
+
+demo = gr.Interface(
+    fn=generate_tts,
+    inputs=[
+        gr.Textbox(label="Texto", lines=3, placeholder="Digite o texto aqui..."),
+        gr.Dropdown(choices=VOICES, value="af_heart", label="Voz"),
+        gr.Slider(minimum=0.5, maximum=2.0, value=1.0, step=0.1, label="Velocidade"),
+    ],
+    outputs=gr.Audio(label="Audio Gerado"),
+    title="Kokoro-82M TTS",
+    description="Ingles Americano / Britanico e Portugues Brasileiro.",
+)
+
+# ---------------------------------------------------------------- HTTP API
+
+app = FastAPI()
+
+
+@app.get("/tts/health")
+def tts_health():
+    return {"ok": True, "engine": ENGINE, "threads": THREADS, "voices": len(VOICES), "loaded": sorted(_pipelines)}
+
+
+@app.post("/tts/stream")
+async def tts_stream(request: Request):
+    """Body: {"text", "voice"="af_heart", "speed"=1.0, "sample_rate"=16000}.
+    Response: raw PCM16 mono little-endian, streamed piece by piece."""
+    if API_KEY and request.headers.get("x-api-key") != API_KEY:
+        raise HTTPException(status_code=401, detail="invalid api key")
+    try:
+        body = await request.json()
+    except Exception:
+        raise HTTPException(status_code=400, detail="json body required")
+    text = str(body.get("text") or "").strip()[:MAX_CHARS]
+    voice = str(body.get("voice") or "af_heart")
+    if voice not in VOICES:
+        raise HTTPException(status_code=400, detail="unknown voice")
+    try:
+        speed = min(2.0, max(0.5, float(body.get("speed") or 1.0)))
+        rate = int(body.get("sample_rate") or 16000)
+    except (TypeError, ValueError):
+        raise HTTPException(status_code=400, detail="invalid speed or sample_rate")
+    if rate not in (16000, 24000):
+        raise HTTPException(status_code=400, detail="sample_rate must be 16000 or 24000")
+    if not text:
+        return JSONResponse({"detail": "empty text"}, status_code=400)
+
+    pieces = split_for_streaming(text)
+
+    def generate():
+        t0 = time.perf_counter()
+        for i, piece in enumerate(pieces):
+            pcm = _to_pcm16(_synth(piece, voice, speed), rate)
+            if i == 0:
+                print(f"[TTS stream] first piece in {time.perf_counter() - t0:.2f}s ({len(piece)} chars)")
+            yield pcm
+
+    return StreamingResponse(
+        generate(),  # sync generator: Starlette runs it in a worker thread
+        media_type="application/octet-stream",
+        headers={"X-Sample-Rate": str(rate), "X-Pieces": str(len(pieces)), "Cache-Control": "no-store"},
+    )
+
+
+# Optional second engine (LFM3-Audio-2B) for A/B tests: routes under /lfm3/tts,
+# model loaded on first use. Off unless the Space variable LFM3_ENABLED=1.
+if lfm3_engine.enabled():
+    def _check_key(request: Request) -> None:
+        if API_KEY and request.headers.get("x-api-key") != API_KEY:
+            raise HTTPException(status_code=401, detail="invalid api key")
+
+    app.include_router(lfm3_engine.build_router(
+        engine=lfm3_engine.Lfm3Engine(THREADS),
+        check_key=_check_key,
+        split=split_for_streaming,
+        to_pcm16=_to_pcm16,
+        max_chars=MAX_CHARS,
+    ))
+    print("[TTS] LFM3 routes enabled at /lfm3/tts (model loads on first request)")
+
+app = gr.mount_gradio_app(app, demo, path="/")
+
+
+def _warmup():
+    try:
+        _synth("Hello there.", "af_heart", 1.0)
+        print("[TTS] warm-up done")
+    except Exception as e:
+        print(f"[TTS] warm-up failed: {e}")
+
+
+threading.Thread(target=_warmup, daemon=True).start()
+
+if __name__ == "__main__":
+    # HF Spaces (Gradio SDK) expose GRADIO_SERVER_PORT (7860); 7861 is taken
+    # by the platform there, so PORT is not used.
+    uvicorn.run(app, host="0.0.0.0", port=int(os.getenv("GRADIO_SERVER_PORT", "7860")))

lfm3_engine.py

@@ -0,0 +1,204 @@
+"""LFM3-Audio-2B as an optional second engine of the Kokoro Space (for A/B tests).
+
+Off unless the Space variable LFM3_ENABLED=1. When on, the routes below sit
+beside the Kokoro ones with the same contract (a client only changes the path):
+
+  POST /lfm3/tts/stream   {"text", "voice", "sample_rate"}  -> raw PCM16 mono
+  POST /lfm3/tts/bench    {"text", "voice"}                 -> seconds per piece
+  GET  /lfm3/tts/health
+
+The model (about 8 GB in float32 on CPU) loads on the first request, not at
+start-up, so Kokoro boots and answers exactly as before; transformers is not
+imported until then. One LFM3 synthesis at a time. "speed" is ignored (LFM3 has
+no speed control; X-Speed-Ignored says so). Voices: "female", "male" or a
+Kokoro id such as "af_heart" (see pieces.parse_voice).
+
+LiquidAI/LFM3-Audio-2B is under the LFM Open License v1.0: commercial use only
+below US$10M annual revenue.
+"""
+import asyncio
+import os
+import threading
+import time
+from typing import Callable
+
+import numpy as np
+from fastapi import APIRouter, HTTPException, Request
+from fastapi.responses import JSONResponse, StreamingResponse
+
+from pieces import parse_voice, system_prompt
+
+MODEL_ID = os.getenv("LFM3_MODEL_ID", "LiquidAI/LFM3-Audio-2B")
+MAX_NEW_TOKENS = int(os.getenv("LFM3_MAX_NEW_TOKENS", "256"))  # audio frames per piece
+SAMPLE_RATE = 24000  # LFM3 codec output
+
+
+def enabled() -> bool:
+    return os.getenv("LFM3_ENABLED", "").strip().lower() in ("1", "true", "yes")
+
+
+class Lfm3Engine:
+    """Lazy, thread-safe LFM3 text-to-speech."""
+
+    def __init__(self, threads: int) -> None:
+        self.threads = threads
+        self.device = "cpu"
+        self.dtype = "float32"
+        self._model = None
+        self._processor = None
+        self._codec = None
+        self._load_lock = threading.Lock()
+        self._synth_lock = threading.Lock()
+
+    @property
+    def loaded(self) -> bool:
+        return self._model is not None
+
+    def _load(self) -> None:
+        with self._load_lock:
+            if self._model is not None:
+                return
+            import torch
+            from transformers import AutoModelForMultimodalLM, AutoProcessor
+
+            started = time.perf_counter()
+            self.device = "cuda" if torch.cuda.is_available() else "cpu"
+            dtype = torch.bfloat16 if self.device == "cuda" else torch.float32
+            self.dtype = str(dtype).replace("torch.", "")
+            model = AutoModelForMultimodalLM.from_pretrained(
+                MODEL_ID, dtype=dtype, device_map=self.device, trust_remote_code=True
+            ).eval()
+            processor = AutoProcessor.from_pretrained(MODEL_ID, trust_remote_code=True)
+            self._codec = processor.audio_tokenizer.to(device=self.device).eval()
+            self._processor = processor
+            self._model = model  # set last: `loaded` means everything is ready
+            print(f"[LFM3] loaded {MODEL_ID} on {self.device} ({self.dtype}) in {time.perf_counter() - started:.1f}s")
+
+    def synth(self, text: str, language: str, gender: str) -> np.ndarray:
+        """Float32 mono audio at 24 kHz for one piece of text."""
+        import torch
+
+        self._load()
+        conversation = [
+            {"role": "system", "content": system_prompt(language, gender)},
+            {"role": "user", "content": text},
+            {"role": "assistant", "content": "<|audio_start|>"},
+        ]
+        with self._synth_lock, torch.no_grad():
+            inputs = self._processor.apply_chat_template(
+                conversation,
+                continue_final_message=True,
+                tokenize=True,
+                return_dict=True,
+                return_tensors="pt",
+            ).to(self.device)
+            outputs = self._model.generate(
+                **inputs,
+                max_new_tokens=MAX_NEW_TOKENS,
+                audio_temperature=1.0,
+                audio_top_k=128,
+                audio_repetition_penalty=1.1,
+                audio_repetition_window=4096,
+                return_dict_in_generate=True,
+            )
+            waveform = self._codec.decode(
+                outputs.audio_codes[:1, :, : outputs.audio_lengths[0]]
+            ).audio_values[0]
+        return waveform.float().cpu().numpy().reshape(-1)
+
+
+def build_router(
+    *,
+    engine: Lfm3Engine,
+    check_key: Callable[[Request], None],
+    split: Callable[[str], list],
+    to_pcm16: Callable[[np.ndarray, int], bytes],
+    max_chars: int,
+) -> APIRouter:
+    """Routes that share the Kokoro Space's API-key check, text splitting and
+    PCM conversion."""
+    router = APIRouter(prefix="/lfm3/tts")
+
+    async def read_body(request: Request) -> dict:
+        try:
+            body = await request.json()
+        except Exception:
+            raise HTTPException(status_code=400, detail="json body required")
+        if not isinstance(body, dict):
+            raise HTTPException(status_code=400, detail="json object required")
+        return body
+
+    def voice_or_400(body: dict):
+        parsed = parse_voice(str(body.get("voice") or "female"))
+        if parsed is None:
+            raise HTTPException(
+                status_code=400, detail="unknown voice: use female, male or an a?_/b?_ Kokoro id"
+            )
+        return parsed
+
+    @router.get("/health")
+    def health():
+        return {"ok": True, "engine": "lfm3", "model": MODEL_ID, "loaded": engine.loaded,
+                "device": engine.device, "dtype": engine.dtype, "threads": engine.threads}
+
+    @router.post("/stream")
+    async def stream(request: Request):
+        check_key(request)
+        body = await read_body(request)
+        text = str(body.get("text") or "").strip()[:max_chars]
+        language, gender = voice_or_400(body)
+        try:
+            rate = int(body.get("sample_rate") or 16000)
+        except (TypeError, ValueError):
+            raise HTTPException(status_code=400, detail="invalid sample_rate")
+        if rate not in (16000, 24000):
+            raise HTTPException(status_code=400, detail="sample_rate must be 16000 or 24000")
+        if not text:
+            return JSONResponse({"detail": "empty text"}, status_code=400)
+
+        pieces = split(text)
+
+        def generate():
+            started = time.perf_counter()
+            for i, piece in enumerate(pieces):
+                pcm = to_pcm16(engine.synth(piece, language, gender), rate)
+                if i == 0:
+                    print(f"[LFM3 stream] first piece in {time.perf_counter() - started:.2f}s ({len(piece)} chars)")
+                yield pcm
+
+        return StreamingResponse(
+            generate(),  # sync generator: Starlette runs it in a worker thread
+            media_type="application/octet-stream",
+            headers={"X-Sample-Rate": str(rate), "X-Pieces": str(len(pieces)),
+                     "X-Speed-Ignored": "1", "Cache-Control": "no-store"},
+        )
+
+    @router.post("/bench")
+    async def bench(request: Request):
+        """Seconds spent synthesizing against seconds of audio, per piece
+        (rtf below 1 is faster than real time). The first call also loads the
+        model, so run it twice and read the second."""
+        check_key(request)
+        body = await read_body(request)
+        text = str(body.get("text") or "").strip()[:max_chars]
+        language, gender = voice_or_400(body)
+        if not text:
+            return JSONResponse({"detail": "empty text"}, status_code=400)
+
+        def run():
+            rows = []
+            for piece in split(text):
+                started = time.perf_counter()
+                audio = engine.synth(piece, language, gender)
+                took = time.perf_counter() - started
+                seconds = audio.size / SAMPLE_RATE
+                rows.append({"chars": len(piece), "synth_seconds": round(took, 3),
+                             "audio_seconds": round(seconds, 3),
+                             "rtf": round(took / seconds, 3) if seconds else None})
+            return rows
+
+        rows = await asyncio.to_thread(run)
+        return {"device": engine.device, "threads": engine.threads, "pieces": rows,
+                "first_piece_seconds": rows[0]["synth_seconds"] if rows else None}
+
+    return router

pieces.py

@@ -0,0 +1,51 @@
+"""Pure helpers of the LFM3 Space (no model, no network): text pieces and voices.
+
+Kept apart from app.py so they can be unit-tested without torch or transformers.
+"""
+import re
+
+FIRST_PIECE_MAX = 60  # first sentence longer than this is cut at its first clause
+
+_SENTENCE = re.compile(r"(?<=[.!?…])\s+")
+_CLAUSE = re.compile(r"(?<=[,;:])\s+")
+
+# The Kokoro voice ids the app already sends (af_heart, bm_george, ...) are
+# accepted, so the same client can be pointed at either Space. LFM3 has no
+# named voices: only a language/locale and a female or male voice.
+_KOKORO_LANG = {"a": "American English", "b": "British English"}
+_GENDER = {"f": "female", "m": "male"}
+_KOKORO_VOICE = re.compile(r"^([ab])([fm])_[a-z]+$")
+
+
+def split_for_streaming(text: str) -> list:
+    """Sentences, with the first one cut at its first clause when long, so
+    the first audio arrives after synthesizing only a few words."""
+    sentences = [s.strip() for s in _SENTENCE.split(text) if s.strip()]
+    if not sentences:
+        return []
+    first = sentences[0]
+    if len(first) > FIRST_PIECE_MAX:
+        parts = _CLAUSE.split(first, maxsplit=1)
+        if len(parts) == 2 and len(parts[0]) >= 12 and len(parts[1]) >= 12:
+            return [parts[0], parts[1]] + sentences[1:]
+    return sentences
+
+
+def parse_voice(voice: str):
+    """(language, gender) for a voice id, or None when it is not supported.
+
+    "female" / "male" mean American English; "af_heart"-style ids map the
+    first letter to American (a) or British (b) English and the second to the
+    gender. Portuguese Kokoro voices (pf_, pm_) are not mapped on purpose:
+    this Space is for comparing English."""
+    voice = (voice or "").strip().lower()
+    if voice in ("female", "male"):
+        return "American English", voice
+    match = _KOKORO_VOICE.match(voice)
+    if match:
+        return _KOKORO_LANG[match.group(1)], _GENDER[match.group(2)]
+    return None
+
+
+def system_prompt(language: str, gender: str) -> str:
+    return f"Perform TTS in {language} using a {gender} voice."

requirements.txt

@@ -1,10 +1,14 @@
-kokoro>=0.9.4
-kokoro-onnx>=0.4.9
-onnxruntime>=1.20
-soundfile>=0.12.1
-numpy>=1.24.0
-gradio>=4.0.0
-torch
-scipy
-fastapi
-uvicorn
+kokoro>=0.9.4
+kokoro-onnx>=0.4.9
+onnxruntime>=1.20
+soundfile>=0.12.1
+numpy>=1.24.0
+gradio>=4.0.0
+torch
+scipy
+fastapi
+uvicorn
+# Optional LFM3-Audio-2B engine (LFM3_ENABLED=1). transformers 5 needs Python 3.11+.
+transformers>=5.20.2
+accelerate
+librosa