Add Podify AI podcast generator app

Two-phase Gradio app:
- Phase 1: LangGraph research agents (HF Inference LLM + DuckDuckGo) write a script
- Phase 2: Fish Audio OpenAudio S1-mini TTS on ZeroGPU with presets + voice cloning

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

.gitattributes

@@ -1,35 +1,3 @@
-*.7z filter=lfs diff=lfs merge=lfs -text
-*.arrow filter=lfs diff=lfs merge=lfs -text
-*.bin filter=lfs diff=lfs merge=lfs -text
-*.bz2 filter=lfs diff=lfs merge=lfs -text
-*.ckpt filter=lfs diff=lfs merge=lfs -text
-*.ftz filter=lfs diff=lfs merge=lfs -text
-*.gz filter=lfs diff=lfs merge=lfs -text
-*.h5 filter=lfs diff=lfs merge=lfs -text
-*.joblib filter=lfs diff=lfs merge=lfs -text
-*.lfs.* filter=lfs diff=lfs merge=lfs -text
-*.mlmodel filter=lfs diff=lfs merge=lfs -text
-*.model filter=lfs diff=lfs merge=lfs -text
-*.msgpack filter=lfs diff=lfs merge=lfs -text
-*.npy filter=lfs diff=lfs merge=lfs -text
-*.npz filter=lfs diff=lfs merge=lfs -text
-*.onnx filter=lfs diff=lfs merge=lfs -text
-*.ot filter=lfs diff=lfs merge=lfs -text
-*.parquet filter=lfs diff=lfs merge=lfs -text
-*.pb filter=lfs diff=lfs merge=lfs -text
-*.pickle filter=lfs diff=lfs merge=lfs -text
-*.pkl filter=lfs diff=lfs merge=lfs -text
-*.pt filter=lfs diff=lfs merge=lfs -text
-*.pth filter=lfs diff=lfs merge=lfs -text
-*.rar filter=lfs diff=lfs merge=lfs -text
-*.safetensors filter=lfs diff=lfs merge=lfs -text
-saved_model/**/* filter=lfs diff=lfs merge=lfs -text
-*.tar.* filter=lfs diff=lfs merge=lfs -text
-*.tar filter=lfs diff=lfs merge=lfs -text
-*.tflite filter=lfs diff=lfs merge=lfs -text
-*.tgz filter=lfs diff=lfs merge=lfs -text
-*.wasm filter=lfs diff=lfs merge=lfs -text
-*.xz filter=lfs diff=lfs merge=lfs -text
-*.zip filter=lfs diff=lfs merge=lfs -text
-*.zst filter=lfs diff=lfs merge=lfs -text
-*tfevents* filter=lfs diff=lfs merge=lfs -text
+*.wav filter=lfs diff=lfs merge=lfs -text
+*.mp3 filter=lfs diff=lfs merge=lfs -text
+*.flac filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,4 @@
+__pycache__/
+*.pyc
+.venv/
+*.wav.tmp

README.md

@@ -1,14 +1,70 @@
 ---
-title: Podify
-emoji: 📚
-colorFrom: purple
-colorTo: indigo
+title: Podify - AI Podcast Generator
+emoji: 🎙️
+colorFrom: indigo
+colorTo: purple
 sdk: gradio
-sdk_version: 6.17.3
-python_version: '3.12'
+sdk_version: 4.44.0
 app_file: app.py
+python_version: "3.10"
+hardware: zero-a10g
+suggested_hardware: zero-a10g
 pinned: false
-short_description: A Brilliant Podcast Generator with multiple voices
+short_description: Research a topic and turn it into a voiced podcast
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# 🎙️ Podify — AI Podcast Generator
+
+Turn any topic into a finished, voiced podcast in two phases:
+
+1. **Content** — research agents (LangGraph) use a HuggingFace-hosted LLM plus live
+   DuckDuckGo web search to research the topic and write a speaker-tagged script.
+2. **Audio** — the self-hosted **Fish Audio / OpenAudio S1-mini** model speaks the
+   script, with selectable preset voices and zero-shot **voice cloning** from an
+   uploaded clip or a live mic recording.
+
+Everything runs inside this single Gradio Space; the TTS model runs on **ZeroGPU**.
+
+## Architecture
+
+```
+Topic ─▶ LangGraph: plan ─▶ DDG search ─▶ outline ─▶ write ─▶ Script
+Script ─▶ Fish Audio S1-mini (@spaces.GPU): per-line synth ─▶ stitched podcast WAV
+```
+
+- `app.py` — Gradio Blocks UI (two tabs) wiring both phases.
+- `research/` — `llm.py` (HF Inference client), `search.py` (DuckDuckGo), `graph.py`
+  (LangGraph research graph).
+- `tts/` — `engine.py` (model load + GPU synthesis + multi-speaker stitching),
+  `voices.py` (preset voice registry).
+
+## Configuration
+
+Set these as **Space secrets / variables** (Settings → Variables and secrets):
+
+| Name        | Required | Purpose                                                        |
+|-------------|----------|----------------------------------------------------------------|
+| `HF_TOKEN`  | ✅       | LLM inference (Inference Providers) + model download.          |
+| `LLM_MODEL` | optional | Override the content LLM (default `meta-llama/Llama-3.3-70B-Instruct`). |
+| `TTS_MODEL_REPO` | optional | Override the TTS model repo (default `fishaudio/openaudio-s1-mini`). |
+
+**ZeroGPU** requires a HuggingFace **PRO** account on the Space owner.
+
+## Run locally
+
+```bash
+pip install -r requirements.txt
+export HF_TOKEN=hf_xxx          # PowerShell: $env:HF_TOKEN="hf_xxx"
+python app.py
+```
+
+Phase 1 (research + script) runs on CPU. Phase 2 (TTS) needs a GPU and the
+`fish-speech` package; on CPU-only machines the UI loads but synthesis is disabled.
+
+## Deploy to a Space
+
+```bash
+huggingface-cli login
+huggingface-cli upload <user>/podify . --repo-type=space
+# or: git push to the Space remote (preset .wav files tracked via Git LFS)
+```

app.py

@@ -0,0 +1,199 @@
+"""Podify — AI Podcast Generator (Gradio + HuggingFace Spaces).
+
+Phase 1: research agents (LangGraph + HF LLM + DuckDuckGo) write a script.
+Phase 2: Fish Audio (OpenAudio S1-mini) voices the script, with presets + cloning.
+"""
+
+from __future__ import annotations
+
+from typing import List, Tuple
+
+import gradio as gr
+
+from research.graph import generate_script, parse_script
+from tts import voices as voice_lib
+from tts import engine as tts_engine
+
+MAX_SPEAKERS = 4
+STYLES = ["conversational", "interview", "storytelling", "educational", "debate", "news"]
+
+
+# ------------------------------------------------------------------- Phase 1 handler
+def run_research(topic, style, duration, num_speakers, progress=gr.Progress()):
+    topic = (topic or "").strip()
+    if not topic:
+        raise gr.Error("Please enter a topic for the podcast.")
+    progress(0.1, desc="Planning research…")
+    state = generate_script(
+        topic,
+        style=style,
+        duration_min=int(duration),
+        num_speakers=int(num_speakers),
+    )
+    progress(0.9, desc="Finalizing script…")
+    script = state.get("script", "")
+    sources = state.get("sources", [])
+    sources_md = (
+        "### Sources\n" + "\n".join(f"- {u}" for u in sources)
+        if sources
+        else "_No web sources were retrieved (the script was written from model knowledge)._"
+    )
+    return script, script, sources_md
+
+
+# ------------------------------------------------------- set up per-speaker voice rows
+def setup_voices(script_text):
+    lines = parse_script(script_text or "")
+    # unique speakers in order of appearance
+    speakers: List[str] = []
+    for spk, _ in lines:
+        if spk not in speakers:
+            speakers.append(spk)
+    speakers = speakers[:MAX_SPEAKERS]
+
+    updates = [lines, speakers]  # lines_state, speakers_state
+    presets = voice_lib.list_presets()
+    for i in range(MAX_SPEAKERS):
+        if i < len(speakers):
+            # row visibility, speaker label (markdown), preset dropdown
+            updates.append(gr.update(visible=True))
+            updates.append(gr.update(value=f"### 🎤 Voice for “{speakers[i]}”"))
+            default_choice = presets[min(i + 1, len(presets) - 1)] if len(presets) > 1 else presets[0]
+            updates.append(gr.update(choices=presets, value=default_choice))
+        else:
+            updates.append(gr.update(visible=False))
+            updates.append(gr.update())
+            updates.append(gr.update())
+    return updates
+
+
+# ------------------------------------------------------------------- Phase 2 handler
+def run_tts(lines, speakers, *voice_inputs, progress=gr.Progress()):
+    if not tts_engine.is_available():
+        raise gr.Error(
+            "The TTS stack (fish-speech + GPU) is not available in this environment. "
+            "Deploy to a ZeroGPU Space to generate audio."
+        )
+    if not lines:
+        raise gr.Error("No script is loaded. Generate or paste a script, then click "
+                       "“Prepare voices”.")
+
+    # voice_inputs is flattened: [preset0..N, clone0..N, text0..N]
+    presets = list(voice_inputs[0:MAX_SPEAKERS])
+    clones = list(voice_inputs[MAX_SPEAKERS:2 * MAX_SPEAKERS])
+    texts = list(voice_inputs[2 * MAX_SPEAKERS:3 * MAX_SPEAKERS])
+
+    voice_map = {}
+    for i, speaker in enumerate(speakers):
+        clone_path = clones[i]
+        if clone_path:  # cloning overrides preset
+            voice_map[speaker] = tts_engine.VoiceConfig(
+                ref_audio=clone_path, ref_text=(texts[i] or "").strip()
+            )
+        else:
+            v = voice_lib.get_voice(presets[i])
+            voice_map[speaker] = tts_engine.VoiceConfig(ref_audio=v.ref_audio, ref_text=v.ref_text)
+
+    sr, audio = tts_engine.generate_podcast(lines, voice_map, progress=progress)
+    return (sr, audio), tts_engine.write_wav(sr, audio)
+
+
+# ----------------------------------------------------------------------------- UI
+def build_ui():
+    with gr.Blocks(title="Podify — AI Podcast Generator", theme=gr.themes.Soft()) as demo:
+        gr.Markdown(
+            "# 🎙️ Podify — AI Podcast Generator\n"
+            "**Phase 1** researches your topic and writes a script. "
+            "**Phase 2** voices it with Fish Audio, with presets or your own cloned voice."
+        )
+
+        lines_state = gr.State([])
+        speakers_state = gr.State([])
+
+        with gr.Tab("1 · Script"):
+            with gr.Row():
+                with gr.Column(scale=2):
+                    topic = gr.Textbox(
+                        label="Podcast topic",
+                        placeholder="e.g. How CRISPR is changing medicine",
+                        lines=2,
+                    )
+                    with gr.Row():
+                        style = gr.Dropdown(STYLES, value="conversational", label="Style")
+                        duration = gr.Slider(1, 20, value=5, step=1, label="Length (min)")
+                        num_speakers = gr.Slider(1, MAX_SPEAKERS, value=2, step=1, label="Speakers")
+                    research_btn = gr.Button("🔎 Research & Write Script", variant="primary")
+                with gr.Column(scale=1):
+                    sources_md = gr.Markdown("Sources will appear here after research.")
+            script_box = gr.Textbox(
+                label="Generated script (editable — use `Speaker: text` per line)",
+                lines=16,
+            )
+
+        with gr.Tab("2 · Audio"):
+            gr.Markdown(
+                "Edit the script if needed, click **Prepare voices**, assign a preset or "
+                "clone a voice per speaker (upload a clip or record from mic), then generate."
+            )
+            script_box2 = gr.Textbox(label="Script to voice", lines=12)
+            prepare_btn = gr.Button("🎚️ Prepare voices from script")
+
+            preset_dropdowns, clone_audios, clone_texts = [], [], []
+            speaker_rows, speaker_labels = [], []
+            for i in range(MAX_SPEAKERS):
+                with gr.Group(visible=False) as row:
+                    speaker_label = gr.Markdown(f"### Speaker {i + 1}")
+                    with gr.Row():
+                        preset = gr.Dropdown(
+                            voice_lib.list_presets(),
+                            value=voice_lib.list_presets()[0],
+                            label="Preset voice",
+                        )
+                        clone = gr.Audio(
+                            sources=["upload", "microphone"],
+                            type="filepath",
+                            label="…or clone a voice (10–30s reference)",
+                        )
+                    ref_text = gr.Textbox(
+                        label="Reference transcript (optional, improves cloning)",
+                        lines=1,
+                    )
+                speaker_rows.append(row)
+                speaker_labels.append(speaker_label)
+                preset_dropdowns.append(preset)
+                clone_audios.append(clone)
+                clone_texts.append(ref_text)
+
+            generate_btn = gr.Button("🎧 Generate Podcast", variant="primary")
+            audio_out = gr.Audio(label="Podcast", type="numpy")
+            file_out = gr.File(label="Download (.wav)")
+
+        # ---- wiring ----
+        # Phase 1: research -> fill both script boxes + sources, then set up voice rows.
+        setup_outputs = [lines_state, speakers_state]
+        for i in range(MAX_SPEAKERS):
+            setup_outputs += [speaker_rows[i], speaker_labels[i], preset_dropdowns[i]]
+
+        research_btn.click(
+            run_research,
+            inputs=[topic, style, duration, num_speakers],
+            outputs=[script_box, script_box2, sources_md],
+        ).then(
+            setup_voices,
+            inputs=[script_box2],
+            outputs=setup_outputs,
+        )
+
+        prepare_btn.click(setup_voices, inputs=[script_box2], outputs=setup_outputs)
+
+        generate_btn.click(
+            run_tts,
+            inputs=[lines_state, speakers_state] + preset_dropdowns + clone_audios + clone_texts,
+            outputs=[audio_out, file_out],
+        )
+
+    return demo
+
+
+if __name__ == "__main__":
+    build_ui().launch()

packages.txt

@@ -0,0 +1,2 @@
+ffmpeg
+libsndfile1

requirements.txt

@@ -0,0 +1,20 @@
+# --- Core app ---
+# Keep gradio pinned to the README `sdk_version` so the Space runtime and pip agree.
+gradio==4.44.0
+spaces>=0.30.0
+
+# --- Phase 1: research / content generation ---
+langgraph>=0.2.0
+langchain-core>=0.3.0
+huggingface_hub>=0.25.0
+ddgs>=6.0.0
+
+# --- Phase 2: Fish Audio (OpenAudio S1-mini) TTS ---
+# fish-speech provides the inference engine + model code. It is installed from the
+# upstream repo (no stable PyPI release). Pin to a known-good commit when deploying.
+fish-speech @ git+https://github.com/fishaudio/fish-speech.git
+
+torch>=2.4.0
+torchaudio>=2.4.0
+numpy>=1.26.0
+soundfile>=0.12.1

research/__init__.py

@@ -0,0 +1 @@
+"""Phase 1: research + podcast-script generation."""

research/graph.py

@@ -0,0 +1,210 @@
+"""LangGraph research graph: plan -> research -> outline -> write.
+
+Produces a speaker-tagged podcast script from a topic, grounded in live DuckDuckGo
+search results. Kept deliberately linear and lightweight so it runs fast on a CPU Space.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from typing import List, Tuple, TypedDict
+
+from langgraph.graph import StateGraph, START, END
+
+from .llm import complete
+from .search import web_search, SearchResult
+
+
+class ResearchState(TypedDict, total=False):
+    topic: str
+    style: str
+    duration_min: int
+    num_speakers: int
+    speaker_names: List[str]
+    queries: List[str]
+    findings: str
+    sources: List[str]
+    outline: str
+    script: str
+
+
+# --------------------------------------------------------------------------- nodes
+
+
+def plan_node(state: ResearchState) -> dict:
+    topic = state["topic"]
+    raw = complete(
+        system=(
+            "You are a research planner. Given a podcast topic, produce 3-6 focused web "
+            "search queries that together cover the key angles. Respond ONLY with a JSON "
+            'array of strings, e.g. ["query one", "query two"].'
+        ),
+        user=f"Topic: {topic}",
+        temperature=0.4,
+        max_tokens=400,
+    )
+    queries = _parse_json_list(raw) or [topic]
+    return {"queries": queries[:6]}
+
+
+def research_node(state: ResearchState) -> dict:
+    blocks: List[str] = []
+    sources: List[str] = []
+    for q in state.get("queries", []):
+        results: List[SearchResult] = web_search(q, max_results=4)
+        if not results:
+            continue
+        blocks.append(f"### Query: {q}\n" + "\n".join(r.as_markdown() for r in results))
+        sources.extend(r.url for r in results)
+    findings = "\n\n".join(blocks) if blocks else "(No web results were available.)"
+    # De-duplicate sources, preserve order.
+    seen, uniq = set(), []
+    for u in sources:
+        if u not in seen:
+            seen.add(u)
+            uniq.append(u)
+    return {"findings": findings, "sources": uniq}
+
+
+def outline_node(state: ResearchState) -> dict:
+    outline = complete(
+        system=(
+            "You are a podcast producer. Using the research findings, write a tight "
+            "outline (intro, 3-5 segments, outro) for the podcast. Use markdown bullets."
+        ),
+        user=(
+            f"Topic: {state['topic']}\n"
+            f"Style: {state.get('style', 'conversational')}\n"
+            f"Target length: ~{state.get('duration_min', 5)} minutes\n\n"
+            f"Research findings:\n{state.get('findings', '')}"
+        ),
+        temperature=0.6,
+        max_tokens=800,
+    )
+    return {"outline": outline}
+
+
+def write_node(state: ResearchState) -> dict:
+    speakers = state.get("speaker_names") or _default_speakers(state.get("num_speakers", 2))
+    speaker_list = ", ".join(speakers)
+    fmt = "\n".join(f"{s}: <what they say>" for s in speakers)
+    script = complete(
+        system=(
+            "You are a professional podcast scriptwriter. Write a natural, engaging, "
+            "factually-grounded podcast script based on the outline and findings.\n"
+            f"Speakers: {speaker_list}.\n"
+            "Format STRICTLY as one line per turn, prefixed with the speaker name and a "
+            f"colon, like:\n{fmt}\n"
+            "Do not include stage directions, markdown, or headings - only spoken dialogue "
+            "lines. Keep each line to a few sentences. Open with a hook and close with a "
+            "sign-off."
+        ),
+        user=(
+            f"Topic: {state['topic']}\n"
+            f"Style: {state.get('style', 'conversational')}\n"
+            f"Target length: ~{state.get('duration_min', 5)} minutes\n\n"
+            f"Outline:\n{state.get('outline', '')}\n\n"
+            f"Findings:\n{state.get('findings', '')}"
+        ),
+        temperature=0.8,
+        max_tokens=3000,
+    )
+    return {"script": script.strip()}
+
+
+# --------------------------------------------------------------------------- helpers
+
+
+def _parse_json_list(text: str) -> List[str]:
+    match = re.search(r"\[.*\]", text, re.DOTALL)
+    if not match:
+        return [line.strip("-* ").strip() for line in text.splitlines() if line.strip()]
+    try:
+        data = json.loads(match.group(0))
+        return [str(x).strip() for x in data if str(x).strip()]
+    except json.JSONDecodeError:
+        return []
+
+
+def _default_speakers(n: int) -> List[str]:
+    names = ["Host", "Guest", "Co-host", "Expert"]
+    if n <= 1:
+        return ["Narrator"]
+    return names[:n]
+
+
+def parse_script(script: str) -> List[Tuple[str, str]]:
+    """Turn a 'Speaker: text' transcript into [(speaker, text), ...]."""
+    lines: List[Tuple[str, str]] = []
+    pattern = re.compile(r"^\s*([\w .'-]{1,30}?)\s*:\s*(.+)$")
+    for raw in script.splitlines():
+        raw = raw.strip()
+        if not raw:
+            continue
+        m = pattern.match(raw)
+        if m:
+            lines.append((m.group(1).strip(), m.group(2).strip()))
+        elif lines:  # continuation of previous speaker's line
+            spk, txt = lines[-1]
+            lines[-1] = (spk, f"{txt} {raw}")
+    return lines
+
+
+# --------------------------------------------------------------------------- graph
+
+
+def build_graph():
+    g = StateGraph(ResearchState)
+    g.add_node("plan", plan_node)
+    g.add_node("research", research_node)
+    g.add_node("outline", outline_node)
+    g.add_node("write", write_node)
+    g.add_edge(START, "plan")
+    g.add_edge("plan", "research")
+    g.add_edge("research", "outline")
+    g.add_edge("outline", "write")
+    g.add_edge("write", END)
+    return g.compile()
+
+
+_GRAPH = None
+
+
+def generate_script(
+    topic: str,
+    *,
+    style: str = "conversational",
+    duration_min: int = 5,
+    num_speakers: int = 2,
+    speaker_names: List[str] | None = None,
+) -> dict:
+    """Run the full research graph and return the final state."""
+    global _GRAPH
+    if _GRAPH is None:
+        _GRAPH = build_graph()
+    speakers = speaker_names or _default_speakers(num_speakers)
+    result = _GRAPH.invoke(
+        {
+            "topic": topic,
+            "style": style,
+            "duration_min": duration_min,
+            "num_speakers": num_speakers,
+            "speaker_names": speakers,
+        }
+    )
+    return result
+
+
+if __name__ == "__main__":  # manual smoke test (needs HF_TOKEN)
+    import sys
+
+    t = sys.argv[1] if len(sys.argv) > 1 else "The history and future of electric cars"
+    out = generate_script(t, duration_min=3)
+    print("\n=== SCRIPT ===\n")
+    print(out["script"])
+    print("\n=== SOURCES ===\n")
+    print("\n".join(out.get("sources", [])))
+    print("\n=== PARSED LINES ===\n")
+    for spk, txt in parse_script(out["script"]):
+        print(f"[{spk}] {txt[:80]}")

research/llm.py

@@ -0,0 +1,54 @@
+"""Thin wrapper around HuggingFace Inference Providers (chat completions).
+
+Reads ``HF_TOKEN`` from the environment and exposes a single ``chat()`` helper used by
+the research graph. The model id is configurable via ``LLM_MODEL``.
+"""
+
+from __future__ import annotations
+
+import os
+from functools import lru_cache
+from typing import List, Dict
+
+from huggingface_hub import InferenceClient
+
+DEFAULT_MODEL = os.environ.get("LLM_MODEL", "meta-llama/Llama-3.3-70B-Instruct")
+
+
+@lru_cache(maxsize=1)
+def _client() -> InferenceClient:
+    token = os.environ.get("HF_TOKEN") or os.environ.get("HUGGING_FACE_HUB_TOKEN")
+    if not token:
+        raise RuntimeError(
+            "HF_TOKEN is not set. Add it as a Space secret (or export it locally) so the "
+            "research agents can call HuggingFace Inference Providers."
+        )
+    return InferenceClient(token=token)
+
+
+def chat(
+    messages: List[Dict[str, str]],
+    *,
+    model: str | None = None,
+    temperature: float = 0.7,
+    max_tokens: int = 2048,
+) -> str:
+    """Run a chat completion and return the assistant text."""
+    resp = _client().chat_completion(
+        messages=messages,
+        model=model or DEFAULT_MODEL,
+        temperature=temperature,
+        max_tokens=max_tokens,
+    )
+    return resp.choices[0].message.content or ""
+
+
+def complete(system: str, user: str, **kwargs) -> str:
+    """Convenience for a single system+user turn."""
+    return chat(
+        [
+            {"role": "system", "content": system},
+            {"role": "user", "content": user},
+        ],
+        **kwargs,
+    )

research/search.py

@@ -0,0 +1,54 @@
+"""DuckDuckGo web search tool for the research agents (free, no API key).
+
+Uses the maintained ``ddgs`` package. Degrades gracefully on rate limits / empty
+results so the writing step can still proceed from whatever was gathered.
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+from typing import List
+
+
+@dataclass
+class SearchResult:
+    title: str
+    url: str
+    snippet: str
+
+    def as_markdown(self) -> str:
+        return f"- [{self.title}]({self.url})\n  {self.snippet}"
+
+
+def web_search(query: str, max_results: int = 5, *, retries: int = 2) -> List[SearchResult]:
+    """Return up to ``max_results`` results for ``query``. Never raises."""
+    try:
+        from ddgs import DDGS
+    except ImportError:  # pragma: no cover - older package name fallback
+        try:
+            from duckduckgo_search import DDGS  # type: ignore
+        except ImportError:
+            return []
+
+    last_err: Exception | None = None
+    for attempt in range(retries + 1):
+        try:
+            with DDGS() as ddgs:
+                hits = ddgs.text(query, max_results=max_results)
+            results = [
+                SearchResult(
+                    title=h.get("title", "").strip(),
+                    url=h.get("href") or h.get("url", ""),
+                    snippet=(h.get("body") or h.get("snippet") or "").strip(),
+                )
+                for h in (hits or [])
+            ]
+            return [r for r in results if r.url]
+        except Exception as exc:  # rate limit / network hiccup
+            last_err = exc
+            if attempt < retries:
+                time.sleep(1.5 * (attempt + 1))
+    # Give up quietly; caller handles empty findings.
+    print(f"[search] '{query}' failed after {retries + 1} attempts: {last_err}")
+    return []

tts/__init__.py

@@ -0,0 +1 @@
+"""Phase 2: Fish Audio (OpenAudio S1-mini) text-to-speech + voice cloning."""

tts/engine.py

@@ -0,0 +1,195 @@
+"""Fish Audio (OpenAudio S1-mini) inference engine.
+
+Loads the model once (cached), exposes a ZeroGPU-decorated ``synthesize()`` for a single
+utterance with optional zero-shot voice cloning, and ``generate_podcast()`` to stitch a
+multi-speaker script into one waveform.
+
+Heavy deps (torch / fish_speech) are imported lazily so this module can be imported on a
+CPU-only / local machine (Phase 1 development) without them installed.
+"""
+
+from __future__ import annotations
+
+import os
+import tempfile
+from dataclasses import dataclass
+from typing import List, Optional, Tuple
+
+import numpy as np
+
+# ----------------------------------------------------------------- ZeroGPU decorator
+try:
+    import spaces  # provided in HF Spaces runtime
+
+    GPU = spaces.GPU
+except Exception:  # local / non-Space: no-op decorator
+
+    def GPU(*dargs, **dkwargs):
+        def _wrap(fn):
+            return fn
+
+        # support both @GPU and @GPU(duration=...)
+        if len(dargs) == 1 and callable(dargs[0]) and not dkwargs:
+            return dargs[0]
+        return _wrap
+
+
+TTS_MODEL_REPO = os.environ.get("TTS_MODEL_REPO", "fishaudio/openaudio-s1-mini")
+# Filenames inside the model repo — verify against the repo if it changes.
+DECODER_CHECKPOINT = os.environ.get("TTS_DECODER_CKPT", "codec.pth")
+DECODER_CONFIG = os.environ.get("TTS_DECODER_CONFIG", "modded_dac_vq")
+
+_ENGINE = None  # cached TTSInferenceEngine
+_SAMPLE_RATE = 44100
+
+
+@dataclass
+class VoiceConfig:
+    """Resolved voice for one speaker: a reference clip+text, or model default."""
+
+    ref_audio: Optional[str] = None
+    ref_text: str = ""
+
+
+def is_available() -> bool:
+    """True if the TTS stack can run (fish_speech + torch importable)."""
+    try:
+        import torch  # noqa: F401
+        import fish_speech  # noqa: F401
+
+        return True
+    except Exception:
+        return False
+
+
+def _load_engine():
+    """Build and cache the TTSInferenceEngine. Runs on the GPU worker."""
+    global _ENGINE, _SAMPLE_RATE
+    if _ENGINE is not None:
+        return _ENGINE
+
+    import torch
+    from huggingface_hub import snapshot_download
+    from fish_speech.models.text2semantic.inference import launch_thread_safe_queue
+    from fish_speech.models.dac.inference import load_model as load_decoder_model
+    from fish_speech.inference_engine import TTSInferenceEngine
+
+    device = "cuda" if torch.cuda.is_available() else "cpu"
+    precision = torch.half if device == "cuda" else torch.float32
+
+    checkpoint_dir = snapshot_download(repo_id=TTS_MODEL_REPO)
+
+    llama_queue = launch_thread_safe_queue(
+        checkpoint_path=checkpoint_dir,
+        device=device,
+        precision=precision,
+        compile=False,
+    )
+    decoder_model = load_decoder_model(
+        config_name=DECODER_CONFIG,
+        checkpoint_path=os.path.join(checkpoint_dir, DECODER_CHECKPOINT),
+        device=device,
+    )
+
+    engine = TTSInferenceEngine(
+        llama_queue=llama_queue,
+        decoder_model=decoder_model,
+        compile=False,
+        precision=precision,
+    )
+    try:
+        _SAMPLE_RATE = int(decoder_model.sample_rate)
+    except Exception:
+        _SAMPLE_RATE = 44100
+    _ENGINE = engine
+    return engine
+
+
+def _build_request(text: str, voice: VoiceConfig):
+    from fish_speech.utils.schema import ServeTTSRequest, ServeReferenceAudio
+
+    references = []
+    if voice.ref_audio and os.path.isfile(voice.ref_audio):
+        with open(voice.ref_audio, "rb") as f:
+            audio_bytes = f.read()
+        references = [ServeReferenceAudio(audio=audio_bytes, text=voice.ref_text or "")]
+
+    return ServeTTSRequest(
+        text=text,
+        references=references,
+        reference_id=None,
+        max_new_tokens=1024,
+        chunk_length=200,
+        top_p=0.8,
+        repetition_penalty=1.1,
+        temperature=0.8,
+        format="wav",
+    )
+
+
+@GPU(duration=120)
+def synthesize(text: str, voice: VoiceConfig) -> Tuple[int, np.ndarray]:
+    """Synthesize one utterance. Returns (sample_rate, float32 mono waveform)."""
+    engine = _load_engine()
+    request = _build_request(text, voice)
+
+    audio_chunks: List[np.ndarray] = []
+    sample_rate = _SAMPLE_RATE
+    for result in engine.inference(request):
+        code = getattr(result, "code", None)
+        if code == "final" and getattr(result, "audio", None) is not None:
+            sample_rate, audio = result.audio
+            audio_chunks.append(np.asarray(audio, dtype=np.float32).reshape(-1))
+        elif code == "error":
+            raise RuntimeError(f"TTS inference error: {getattr(result, 'error', 'unknown')}")
+
+    if not audio_chunks:
+        raise RuntimeError("TTS produced no audio.")
+    return int(sample_rate), np.concatenate(audio_chunks)
+
+
+@GPU(duration=300)
+def generate_podcast(
+    lines: List[Tuple[str, str]],
+    voice_map: dict,
+    *,
+    gap_seconds: float = 0.4,
+    progress=None,
+) -> Tuple[int, np.ndarray]:
+    """Synthesize each (speaker, text) line and stitch into one waveform.
+
+    ``voice_map`` maps speaker name -> VoiceConfig. The whole loop runs inside a single
+    GPU allocation so the model is loaded once per podcast.
+    """
+    engine = _load_engine()
+    segments: List[np.ndarray] = []
+    sample_rate = _SAMPLE_RATE
+    default_voice = VoiceConfig()
+
+    total = len(lines)
+    for i, (speaker, text) in enumerate(lines):
+        if not text.strip():
+            continue
+        if progress is not None:
+            progress((i / max(total, 1)), desc=f"Voicing line {i + 1}/{total} ({speaker})")
+        voice = voice_map.get(speaker, default_voice)
+        request = _build_request(text, voice)
+        for result in engine.inference(request):
+            if getattr(result, "code", None) == "final" and getattr(result, "audio", None):
+                sample_rate, audio = result.audio
+                segments.append(np.asarray(audio, dtype=np.float32).reshape(-1))
+        if gap_seconds > 0:
+            segments.append(np.zeros(int(sample_rate * gap_seconds), dtype=np.float32))
+
+    if not segments:
+        raise RuntimeError("No audio was generated for this script.")
+    return int(sample_rate), np.concatenate(segments)
+
+
+def write_wav(sample_rate: int, audio: np.ndarray) -> str:
+    """Write a waveform to a temp .wav file and return its path (for download)."""
+    import soundfile as sf
+
+    path = tempfile.mktemp(suffix=".wav")
+    sf.write(path, audio, sample_rate)
+    return path

tts/voices.py

@@ -0,0 +1,63 @@
+"""Preset voice registry.
+
+OpenAudio S1-mini does zero-shot cloning, so a "preset" is simply a curated short
+reference clip plus its transcript. Drop matching ``<id>.wav`` / ``<id>.txt`` files into
+``tts/voices/`` and they are picked up automatically; entries declared in ``PRESETS``
+without a bundled clip act as "model default" voices (no reference passed).
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from typing import Dict, List, Optional
+
+_VOICES_DIR = os.path.join(os.path.dirname(__file__), "voices")
+
+
+@dataclass
+class Voice:
+    id: str
+    label: str
+    ref_audio: Optional[str]  # path to reference .wav, or None for model default
+    ref_text: str = ""
+
+
+# Declared presets. ref_audio is resolved from tts/voices/<id>.wav if present.
+PRESETS: List[Dict[str, str]] = [
+    {"id": "default", "label": "Model default (no clone)"},
+    {"id": "narrator_warm", "label": "Warm Narrator"},
+    {"id": "host_energetic", "label": "Energetic Host"},
+    {"id": "guest_calm", "label": "Calm Guest"},
+]
+
+
+def _resolve(voice_id: str) -> Voice:
+    label = next((p["label"] for p in PRESETS if p["id"] == voice_id), voice_id)
+    wav = os.path.join(_VOICES_DIR, f"{voice_id}.wav")
+    txt = os.path.join(_VOICES_DIR, f"{voice_id}.txt")
+    ref_audio = wav if os.path.isfile(wav) else None
+    ref_text = ""
+    if os.path.isfile(txt):
+        with open(txt, "r", encoding="utf-8") as f:
+            ref_text = f.read().strip()
+    return Voice(id=voice_id, label=label, ref_audio=ref_audio, ref_text=ref_text)
+
+
+def list_presets() -> List[str]:
+    """Labels for the UI dropdown."""
+    return [p["label"] for p in PRESETS]
+
+
+def label_to_id(label: str) -> str:
+    for p in PRESETS:
+        if p["label"] == label:
+            return p["id"]
+    return "default"
+
+
+def get_voice(label_or_id: str) -> Voice:
+    vid = label_to_id(label_or_id)
+    if vid == label_or_id and vid not in {p["id"] for p in PRESETS}:
+        vid = "default"
+    return _resolve(vid)

tts/voices/README.md

@@ -0,0 +1,10 @@
+# Preset reference clips
+
+Drop voice presets here as pairs:
+
+- `<id>.wav` — a clean 10–30s reference clip of the target voice
+- `<id>.txt` — the exact transcript of that clip (improves cloning quality)
+
+The `<id>` must match an entry in `tts/voices.py::PRESETS` (e.g. `narrator_warm.wav`).
+A preset declared in `PRESETS` without a `.wav` here falls back to the model's default
+voice (no cloning reference). `.wav` files are tracked via Git LFS (see `.gitattributes`).