.github/copilot-instructions.md

Copilot Instructions

Running the App

pip install -r requirements.txt
python app.py
# → http://localhost:7860

Requires a GPU (T4 or A10G) for inference. No Docker, no database, no external APIs.

Architecture

Single-process Gradio app (app.py, ~1200 lines) that orchestrates four ML models:

• Qwen3-TTS-1.7B (voice_clone.py) — zero-shot voice cloning from reference audio + cloned voice synthesis
• Supertonic TTS — fast stock-voice fallback when no clone is available
• Qwen2.5-3B-Instruct (inference.py) — story Q&A, 4-bit quantized on T4
• Whisper-small (inference.py) — child speech-to-text (loaded on demand)

tts.py is the unified TTS interface. It delegates to Qwen3-TTS when a voice_profile_id is provided, otherwise falls back to Supertonic. Both backends use background-threaded streaming with a queue (maxsize=2 buffer).

voice_clone.py manages the Qwen3-TTS model and a server-side in-memory cache of voice profiles keyed by UUID. Profiles are created via create_voice_profile(ref_audio_path) and reused for all subsequent synthesis calls.

Stories are plain .txt files in stories/ — title on line 1, blank line, then prose. No metadata DB.

State machine governs playback: playing → paused → playing, playing → asking → answering → resuming → playing. All other transitions are illegal. The UI disables buttons for illegal transitions.

Key Conventions

• All inference is local — no external APIs, no data leaves the server. This is a hard privacy requirement.
• In-memory session cache only — no database, no persistent storage of user data.
• Interruptible chunked streaming — paragraphs are synthesized and played one at a time. Cached chunks enable instant replay/resume.
• Pre-generated Q&A — anticipated questions generated in background during narration for sub-1s cache hits.
• VRAM budget awareness — total 8-9 GB on T4 (16 GB). All models lazy-loaded on demand. Use 4-bit quantization for the LLM. Qwen3-TTS (1.7B) loads only when cloning starts.

Story Pipeline

story_downloader/ contains utilities for acquiring new stories from Project Gutenberg:

1. gutenberg_downloader.py — reusable downloader/parser
2. download_stories.py — fetches stories by Gutenberg ID
3. clean_stories.py — strips headers/footers/illustration tags for TTS-clean output

UI

Gradio 5.x with custom CSS (static/style.css) for a Google Stitch-inspired design. Uses warm palette (#FFB347 accent, #FFF8E7 background), Nunito/Fredoka fonts, rounded cards, and micro-animations.

Deployment

Push to Hugging Face Spaces. The README.md frontmatter configures the Space (sdk: gradio, app_file: app.py).