feat: integrate Supertonic TTS with sentence-level chunk streaming

- Add tts.py: lazy singleton TTS loader, sentence-level text splitter,
and background-threaded generator that synthesizes chunks into a
bounded queue and yields (sample_rate, wav, idx, total, err) per chunk
- Update app.py: add tts_chunks_state; on book select, split full story
text into TTS sentence chunks stored in state
- Switch player_audio_control to streaming=True / type=numpy / autoplay=True
- Replace play_btn handler with stream_tts generator that synthesizes and
streams audio chunks one by one with live chunk progress in the status bar
- Add test_modules: supertonic demo, clone demo, and TTS module spec

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

chore: add .gitattributes for Git LFS binary tracking

Track *.png, *.jpg, *.jpeg, *.wav, *.mp3, *.gif, *.webp via Git LFS
so HuggingFace Space accepts the push.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

app.py

@@ -6,6 +6,8 @@ import gradio as gr
 import time
 from pathlib import Path
 
+from tts import split_into_chunks, generate_audio_stream
+
 # Create directories for sample audio files
 os.makedirs("sample_sounds", exist_ok=True)
 
@@ -352,6 +354,7 @@ with gr.Blocks(css=css_code, title="VoiceBook Gradio Hub") as demo:
     books_state = gr.State(mock_books)
     voices_state = gr.State(mock_voices)
     paragraphs_state = gr.State([])
+    tts_chunks_state = gr.State([])
 
     gr.HTML("""
     <div style="display: flex; align-items: center; justify-content: space-between; padding: 16px 0; border-bottom: 1px solid #ebdccb; margin-bottom: 24px; flex-wrap: wrap; gap: 16px;">
@@ -423,7 +426,10 @@ with gr.Blocks(css=css_code, title="VoiceBook Gradio Hub") as demo:
 
                     player_audio_control = gr.Audio(
                         visible=False, interactive=False,
-                        label="Audio Stream", value="sample_sounds/willow.wav", autoplay=False
+                        label="Audio Stream",
+                        type="numpy",
+                        streaming=True,
+                        autoplay=True,
                     )
 
                     player_status_bar = gr.HTML("""
@@ -623,7 +629,7 @@ with gr.Blocks(css=css_code, title="VoiceBook Gradio Hub") as demo:
     # 2. Book card click → load into player
     def handle_book_select(title_chosen, current_inventory):
         if not title_chosen:
-            return [gr.update()] * 11
+            return [gr.update()] * 12
         selected = next((b for b in current_inventory if b["title"] == title_chosen), current_inventory[0])
 
         player_html = f"""
@@ -636,18 +642,18 @@ with gr.Blocks(css=css_code, title="VoiceBook Gradio Hub") as demo:
         """
         paras = load_paragraphs(selected["story_path"])
         total = max(len(paras) - 1, 0)
-        chunk_html = f"""<div style="margin-top: 8px; font-size: 10px; color: #64748b; font-family: monospace; text-align: center;">Paragraph 1 / {len(paras)} — ready to play</div>"""
+        tts_chunks = split_into_chunks("\n\n".join(paras))
+        chunk_html = f"""<div style="margin-top: 8px; font-size: 10px; color: #64748b; font-family: monospace; text-align: center;">{len(tts_chunks)} chunks ready — tap Play</div>"""
         status_html = """
             <div style="margin-top: 12px; display: flex; align-items: center; gap: 10px; justify-content: center;">
                 <span style="width: 8px; height: 8px; border-radius: 50%; background: #94a3b8; display: inline-block;"></span>
                 <span style="font-size: 11px; color: #94a3b8; font-family: monospace;">READY</span>
             </div>
         """
-        audio = selected["audio_path"] or "sample_sounds/willow.wav"
         story_html = render_story_text(paras, 0)
         return (
             player_html,
-            gr.Audio(value=audio, visible=True),
+            gr.Audio(visible=True),
             status_html,
             chunk_html,
             gr.Button(visible=True),   # play_btn
@@ -655,6 +661,7 @@ with gr.Blocks(css=css_code, title="VoiceBook Gradio Hub") as demo:
             gr.Button(visible=False),  # ask_btn
             gr.HTML(visible=False),    # story_finished_panel
             paras,                     # paragraphs_state
+            tts_chunks,                # tts_chunks_state
             gr.HTML(value=story_html, visible=True),   # story_text_display
             gr.Slider(minimum=0, maximum=total, step=1, value=0, visible=True),  # timeline_slider
         )
@@ -664,7 +671,7 @@ with gr.Blocks(css=css_code, title="VoiceBook Gradio Hub") as demo:
         inputs=[book_selector, books_state],
         outputs=[player_title_info, player_audio_control, player_status_bar, chunk_status,
                  play_btn, pause_btn, ask_btn, story_finished_panel,
-                 paragraphs_state, story_text_display, timeline_slider]
+                 paragraphs_state, tts_chunks_state, story_text_display, timeline_slider]
     )
 
     # 3. Extract vocal weights trigger
@@ -763,28 +770,44 @@ with gr.Blocks(css=css_code, title="VoiceBook Gradio Hub") as demo:
         outputs=[voices_state, cloned_voices_list_grid, cloning_progress_msg, loading_spinner, voice_cloning_success_panel, voice_sample_preview_widget, add_to_library_btn, new_voice_name]
     )
 
-    # 5. Play button — PLAYING state
-    def enter_playing_state(slider_val, paras):
-        total = len(paras) if paras else 1
-        chunk_html = f"""<div style="margin-top: 8px; font-size: 10px; color: #4ade80; font-family: monospace; text-align: center;">Paragraph {int(slider_val) + 1} / {total} — streaming</div>"""
-        status_html = """
+    # 5. Play button — streams TTS audio chunk by chunk
+    def stream_tts(tts_chunks, paras):
+        _status_playing = """
             <div style="margin-top: 12px; display: flex; align-items: center; gap: 10px; justify-content: center;">
                 <span style="width: 8px; height: 8px; border-radius: 50%; background: #4ade80; display: inline-block;"></span>
                 <span style="font-size: 11px; color: #4ade80; font-family: monospace;">PLAYING</span>
             </div>
         """
-        return (
-            status_html,
-            chunk_html,
-            gr.Button(visible=False),
-            gr.Button(visible=True),
-            gr.Button(visible=True),
-        )
+        _status_done = """
+            <div style="margin-top: 12px; display: flex; align-items: center; gap: 10px; justify-content: center;">
+                <span style="width: 8px; height: 8px; border-radius: 50%; background: #94a3b8; display: inline-block;"></span>
+                <span style="font-size: 11px; color: #94a3b8; font-family: monospace;">DONE</span>
+            </div>
+        """
+
+        if not tts_chunks:
+            yield None, _status_done, "<div style='text-align:center;font-size:10px;color:#64748b;font-family:monospace;margin-top:8px;'>No content loaded</div>", gr.Button(visible=True), gr.Button(visible=False), gr.Button(visible=False)
+            return
+
+        n = len(tts_chunks)
+        # Immediately show PLAYING state
+        yield None, _status_playing, f"<div style='text-align:center;font-size:10px;color:#4ade80;font-family:monospace;margin-top:8px;'>Generating chunk 1 / {n}…</div>", gr.Button(visible=False), gr.Button(visible=True), gr.Button(visible=False)
+
+        for sample_rate, wav, i, total, err in generate_audio_stream(tts_chunks):
+            if err:
+                yield None, f"<div style='color:#ef4444;font-size:11px;'>Error on chunk {i+1}: {err}</div>", "", gr.Button(visible=True), gr.Button(visible=False), gr.Button(visible=False)
+                return
+            next_label = f"chunk {i+2} / {total}" if i + 1 < total else "last chunk"
+            chunk_html = f"<div style='text-align:center;font-size:10px;color:#4ade80;font-family:monospace;margin-top:8px;'>▶ Playing chunk {i+1} / {total} — generating {next_label}</div>"
+            yield (sample_rate, wav), _status_playing, chunk_html, gr.Button(visible=False), gr.Button(visible=True), gr.Button(visible=True)
+
+        done_html = f"<div style='text-align:center;font-size:10px;color:#94a3b8;font-family:monospace;margin-top:8px;'>✅ {n} chunks complete</div>"
+        yield None, _status_done, done_html, gr.Button(visible=True), gr.Button(visible=False), gr.Button(visible=False)
 
     play_btn.click(
-        enter_playing_state,
-        inputs=[timeline_slider, paragraphs_state],
-        outputs=[player_status_bar, chunk_status, play_btn, pause_btn, ask_btn]
+        stream_tts,
+        inputs=[tts_chunks_state, paragraphs_state],
+        outputs=[player_audio_control, player_status_bar, chunk_status, play_btn, pause_btn, ask_btn]
     )
 
     # 6. Pause button — PAUSED state

docs/tts-module-spec.md

@@ -0,0 +1,21 @@
+refer to test_modules/app_supertonic_tts_demo.py
+
+- use supertonic tts library
+- in this demo, input text is generated to speech data using supertonic.TTS
+- text is firstly divided into multiple chunk text by statements and stored in buffer list
+- and TTS generation is running for the list of text chunks
+- this is to generate audio quickly for long text book.
+
+TODO
+- make tts.py and make module refering to app_supertonic_tts_demo.py
+- In library menu, "Tap to play" button is clicked and the book text is chuncked and stored in buffer list.
+- user click the play button and the text chunk list is converted to audio one by one.
+
+
+package dependencies
+
+# Supertonic TTS
+supertonic>=1.3.1
+soundfile>=0.12.0
+onnxruntime>=1.18.0
+huggingface-hub>=0.23.0

test_modules/app_supertonic_tts_demo.py

@@ -0,0 +1,243 @@
+"""
+Supertonic TTS Gradio Demo — concurrent chunk streaming with playback sync
+Splits text into statements, synthesizes in a background thread, streams
+audio chunk-by-chunk.  A JS timeupdate listener tracks audio.currentTime
+to bold exactly the chunk currently playing in the browser.
+
+Usage:
+  python app.py
+"""
+import json
+import logging
+import queue
+import re
+import threading
+from pathlib import Path
+
+import gradio as gr
+import numpy as np
+
+from supertonic import TTS, AVAILABLE_LANGUAGES
+
+logger = logging.getLogger(__name__)
+
+CLONED_VOICE_JSON = Path(__file__).resolve().parent / "recorded_voice_supertonic-3.json"
+CLONED_VOICE_LABEL = "Custom (recorded_voice_supertonic-3.json)"
+
+print("Loading Supertonic TTS model...")
+tts = TTS(auto_download=True)
+
+builtin_voices = tts.voice_style_names  # M1-M5, F1-F5
+all_voices = ([CLONED_VOICE_LABEL] + builtin_voices) if CLONED_VOICE_JSON.exists() else builtin_voices
+
+_SENTENCE_SPLIT_RE = re.compile(r'(?<=[.!?;])\s+')
+_SENTINEL = object()
+
+# JavaScript injected once at page load.
+# Watches for changes to the hidden timing component, then attaches a
+# timeupdate listener that bolds whichever .chunk-text span is currently
+# playing based on audio.currentTime.
+_SYNC_JS = """
+() => {
+    function attachAudioSync(chunks) {
+        // Find the streaming audio element — Gradio wraps it inside a
+        // data-testid="audio" block; fall back to first <audio> on the page.
+        const container = document.querySelector('[data-testid="audio"]') ||
+                          document.querySelector('.audio-container');
+        const audio = container ? container.querySelector('audio')
+                                : document.querySelector('audio');
+        if (!audio) {
+            // Audio element not yet in DOM — retry shortly.
+            setTimeout(() => attachAudioSync(chunks), 150);
+            return;
+        }
+
+        // Remove any previous listener we registered.
+        if (audio._ttsSyncHandler) {
+            audio.removeEventListener('timeupdate', audio._ttsSyncHandler);
+        }
+
+        audio._ttsSyncHandler = () => {
+            const t = audio.currentTime;
+            document.querySelectorAll('.chunk-item').forEach((item, i) => {
+                const textEl = item.querySelector('.chunk-text');
+                if (!textEl || i >= chunks.length) return;
+                const active = t >= chunks[i].start && t < chunks[i].end;
+                textEl.style.fontWeight = active ? '700' : 'normal';
+            });
+        };
+
+        audio.addEventListener('timeupdate', audio._ttsSyncHandler);
+    }
+
+    // Observe the hidden timing textbox for value changes.
+    const observer = new MutationObserver(() => {
+        const box = document.querySelector('#tts-timing-box textarea');
+        if (!box || !box.value) return;
+        let chunks;
+        try { chunks = JSON.parse(box.value); } catch(e) { return; }
+        if (chunks.length) attachAudioSync(chunks);
+    });
+    observer.observe(document.body, { childList: true, subtree: true, characterData: true });
+}
+"""
+
+
+def split_into_statements(text: str) -> list[str]:
+    parts = _SENTENCE_SPLIT_RE.split(text.strip())
+    return [p.strip() for p in parts if p.strip()]
+
+
+def _chunks_html(statements: list[str], playing_idx: int, generating_idx: int) -> str:
+    rows = []
+    for i, stmt in enumerate(statements):
+        if i < playing_idx:
+            icon, color = "✅", "#16a34a"
+        elif i == playing_idx:
+            icon, color = "▶️", "#2563eb"
+        elif i == generating_idx:
+            icon, color = "⏳", "#d97706"
+        else:
+            icon, color = "○", "#9ca3af"
+
+        rows.append(
+            f'<div class="chunk-item" style="display:flex;gap:8px;padding:3px 0;">'
+            f'<span style="color:{color};min-width:18px;font-size:13px;">{icon}</span>'
+            f'<span class="chunk-text" style="font-size:13px;color:#374151;line-height:1.4;">{stmt}</span>'
+            f'</div>'
+        )
+    return '<div style="margin-top:8px;">' + "".join(rows) + "</div>"
+
+
+def generate_audio(text: str, voice_name: str, language: str, speed: float, steps: int):
+    text = (text or "").strip()
+    if not text:
+        yield gr.update(), "Please enter some text.", "", "[]"
+        return
+
+    try:
+        style = (
+            tts.get_voice_style_from_path(CLONED_VOICE_JSON)
+            if voice_name == CLONED_VOICE_LABEL
+            else tts.get_voice_style(voice_name)
+        )
+
+        statements = split_into_statements(text) or [text]
+        n = len(statements)
+
+        chunk_q: queue.Queue = queue.Queue(maxsize=2)
+
+        def _worker():
+            for i, stmt in enumerate(statements):
+                try:
+                    wav, _ = tts.synthesize(
+                        stmt,
+                        voice_style=style,
+                        lang=language,
+                        speed=speed,
+                        total_steps=int(steps),
+                    )
+                    chunk_q.put((i, wav.squeeze()))
+                except Exception as exc:
+                    chunk_q.put((i, exc))
+                    return
+            chunk_q.put(_SENTINEL)
+
+        worker = threading.Thread(target=_worker, daemon=True)
+        worker.start()
+
+        yield gr.update(), f"Generating chunk 1/{n}…", _chunks_html(statements, -1, 0), "[]"
+
+        timing: list[dict] = []   # [{start, end}, …] — grows as chunks arrive
+        cumulative = 0.0
+
+        while True:
+            item = chunk_q.get()
+            if item is _SENTINEL:
+                break
+
+            i, payload = item
+            if isinstance(payload, Exception):
+                yield gr.update(), f"Generation failed on chunk {i + 1}: {payload}", "", json.dumps(timing)
+                return
+
+            wav = payload
+            dur = len(wav) / tts.sample_rate
+            timing.append({"start": round(cumulative, 4), "end": round(cumulative + dur, 4)})
+            cumulative += dur
+
+            next_gen = i + 1 if i + 1 < n else -1
+            status = (
+                f"Playing {i + 1}/{n}, generating {next_gen + 1}/{n}…"
+                if next_gen >= 0
+                else f"Playing {i + 1}/{n}"
+            )
+
+            yield (
+                (tts.sample_rate, wav),
+                status,
+                _chunks_html(statements, i, next_gen),
+                json.dumps(timing),   # JS picks this up via MutationObserver
+            )
+
+        worker.join()
+        total_dur = cumulative
+        yield (
+            gr.update(),
+            f"Done — {n} chunks, {total_dur:.1f}s total",
+            _chunks_html(statements, n, -1),
+            json.dumps(timing),
+        )
+
+    except Exception as e:
+        logger.exception("Audio generation failed")
+        yield gr.update(), f"Generation failed: {type(e).__name__}: {e}", "", "[]"
+
+
+with gr.Blocks(title="Supertonic TTS Demo", js=_SYNC_JS) as demo:
+    gr.Markdown(f"# Supertonic TTS Demo\n**Model:** `supertonic-3` · **Voices:** {len(all_voices)}")
+
+    with gr.Row():
+        with gr.Column(scale=2):
+            text_input = gr.Textbox(
+                label="Text",
+                placeholder="Enter text to synthesize…",
+                lines=5,
+            )
+
+            with gr.Row():
+                lang_input = gr.Dropdown(
+                    label="Language",
+                    choices=AVAILABLE_LANGUAGES,
+                    value="en",
+                    interactive=True,
+                )
+                voice_input = gr.Dropdown(
+                    label="Voice Style",
+                    choices=all_voices,
+                    value=all_voices[0],
+                    interactive=True,
+                )
+
+            with gr.Row():
+                speed_input = gr.Slider(label="Speed", minimum=0.7, maximum=2.0, value=1.05, step=0.05)
+                steps_input = gr.Slider(label="Quality Steps", minimum=1, maximum=20, value=8, step=1)
+
+            play_btn = gr.Button("Play", variant="primary", size="lg")
+
+        with gr.Column(scale=3):
+            # streaming=True: each yielded chunk is appended to the playback buffer
+            audio_out = gr.Audio(label="Generated Speech", type="numpy", autoplay=True, streaming=True)
+            status_out = gr.Textbox(label="Status", lines=1, interactive=False)
+            chunks_out = gr.HTML()
+            # Hidden component — carries [{start, end}] timing per chunk to JS
+            timing_out = gr.Textbox(visible=False, elem_id="tts-timing-box")
+
+    play_btn.click(
+        generate_audio,
+        inputs=[text_input, voice_input, lang_input, speed_input, steps_input],
+        outputs=[audio_out, status_out, chunks_out, timing_out],
+    )
+
+if __name__ == "__main__":
+    demo.queue().launch()

test_modules/supertonic_clone_demo.py

@@ -0,0 +1,34 @@
+from supertonic import TTS
+from supertonic import pipeline
+import numpy as np
+from pathlib import Path
+
+tts = TTS(auto_download=True)
+
+# Load a locally downloaded custom voice style JSON.
+json_path = Path(__file__).resolve().parent / "recorded_voice_supertonic-3.json"
+style = pipeline.load_voice_style_from_json_file(str(json_path))
+
+# text = "A gentle breeze moved through the open window while everyone listened to the story."
+# text = "Hello, Bay Area K group Vibe coding members. This is generated by Supertonic model on my local machine"
+# text = "To clarify if this model is locally inferenced, I turned off wifi and generated this audio"
+# text = "Testing my clone model voice TTS in English"
+text = """
+Long before the advent of the printing press or the digital screen, humanity’s fundamental drive to communicate birthed the earliest systems of recorded thought.
+It began with pictographs etched into the cool, unyielding stone of ancient caves, where early storytellers captured the essence of their daily lives, spiritual beliefs, and conquests.
+These simple drawings were not mere decoration;
+they were the very first seeds of human collaboration, allowing knowledge to transcend the boundaries of a single lifetime.
+As human societies grew in complexity, so did their methods of encoding information.
+The transition from crude cave art to structured written systems marked a monumental leap in cognitive evolution.
+In the fertile crescent of Mesopotamia, the need to track agricultural surplus and administrative records led to the development of cuneiform, a system of wedge-shaped marks pressed into damp clay tablets.
+This was the dawn of history—the moment when human thought could be permanently preserved, retrieved, and scrutinized by others.
+"""
+wav, duration = tts.synthesize(text, voice_style=style, lang="en")
+
+# text = "한국어 보이스 클로닝 테스트. 하나둘셋 하나둘셋. 동해물과 백두산이 마르고 닳도록"
+# wav, duration = tts.synthesize(text, voice_style=style, lang="ko")
+
+
+tts.save_audio(wav, "clone_output_04.wav")
+duration_sec = float(np.asarray(duration).reshape(-1)[0])
+print(f"Generated {duration_sec:.2f}s of audio")

tts.py

@@ -0,0 +1,62 @@
+"""
+TTS module — wraps Supertonic TTS with sentence-level chunking and
+background-threaded streaming generation.
+"""
+import logging
+import queue
+import re
+import threading
+
+logger = logging.getLogger(__name__)
+
+_SENTENCE_RE = re.compile(r'(?<=[.!?;])\s+')
+_SENTINEL = object()
+
+_tts_instance = None
+
+
+def get_tts():
+    global _tts_instance
+    if _tts_instance is None:
+        from supertonic import TTS
+        logger.info("Loading Supertonic TTS model…")
+        _tts_instance = TTS(auto_download=True)
+    return _tts_instance
+
+
+def split_into_chunks(text: str) -> list[str]:
+    """Split text into sentence-level chunks suitable for TTS streaming."""
+    parts = _SENTENCE_RE.split(text.strip())
+    return [p.strip() for p in parts if p.strip()]
+
+
+def generate_audio_stream(chunks: list[str], voice_name: str = "F1"):
+    """
+    Generator: synthesizes chunks in a background thread (maxsize=2 buffer).
+    Yields (sample_rate, wav_array, chunk_idx, total_chunks, error_msg).
+    wav_array is None on error.
+    """
+    tts = get_tts()
+    style = tts.get_voice_style(voice_name)
+    n = len(chunks)
+    chunk_q: queue.Queue = queue.Queue(maxsize=2)
+
+    def _worker():
+        for i, stmt in enumerate(chunks):
+            try:
+                wav, _ = tts.synthesize(stmt, voice_style=style)
+                chunk_q.put((i, wav.squeeze(), None))
+            except Exception as exc:
+                logger.exception("TTS synthesis failed on chunk %d", i)
+                chunk_q.put((i, None, str(exc)))
+                return
+        chunk_q.put(_SENTINEL)
+
+    threading.Thread(target=_worker, daemon=True).start()
+
+    while True:
+        item = chunk_q.get()
+        if item is _SENTINEL:
+            break
+        i, wav, err = item
+        yield tts.sample_rate, wav, i, n, err