Upload 27 files

.gitattributes

@@ -1,35 +1,36 @@
-*.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
+*.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
+assets/placeholder.jpg filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,14 @@
+__pycache__/
+*.py[cod]
+*$py.class
+
+.venv/
+venv/
+env/
+.env
+.env.*
+
+.gradio/
+.cache/
+
+outputs/melodies/*.wav

README.md

@@ -1,15 +1,264 @@
 ---
-title: WhistleBloom
-emoji: 🐢
-colorFrom: red
+title: Whistle Coach
+colorFrom: green
 colorTo: purple
 sdk: gradio
-sdk_version: 6.18.0
-python_version: '3.12'
 app_file: app.py
 pinned: false
-license: mit
-short_description: Whistle coach
+license: apache-2.0
+tags:
+  - build-small
+  - backyard-ai
+  - off-brand
+  - tiny-titan
+  - best-agent
+  - best-demo
+  - openai-codex
+  - nvidia-nemotron
+  - voice
+  - audio
+  - audio-classification
+  - gradio
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Whistle Coach
+
+**Whistle Coach is an audio-first AI practice coach for one tiny human skill: learning your first whistle.**
+
+Most people learn to whistle through awkward trial and error: round the lips, blow too hard, lose the shape, try again. Whistle Coach turns that loop into a small, live, embodied AI coach. It watches only the visible lower-face posture needed for guidance, listens for breath and pitch, diagnoses the current blocker, and grows a tiny garden as the first stable whistle turns into a melody.
+
+This is intentionally small. It is not a giant general assistant. It is a narrow feedback system for one body skill, built from small models, signal processing, browser-side feature extraction, and a compact coach policy.
+
+## Submission Links
+
+- **Live Space:** this Hugging Face Space
+- **Demo video:** TODO - paste public demo video link before final submission
+- **Social post:** TODO - paste public social post link before final submission
+- **Primary track:** Backyard AI
+- **Requested bonus consideration:** Off Brand, Tiny Titan, Best Agent, Best Demo, OpenAI Codex
+- **Sponsor path:** NVIDIA / Nemotron policy path is included; enable the Nemotron endpoint secrets before final judging if entering the NVIDIA sponsor prize.
+
+## Why It Fits Build Small
+
+Build Small is about useful, local-feeling, tinkerable AI under the 32B parameter cap. Whistle Coach fits that spirit in four ways:
+
+1. **A small personal problem:** learning to whistle is tiny, specific, and surprisingly hard to debug alone.
+2. **Small models do real work:** the runtime audio classifier is MIT AST at 86.6M parameters; the optional coach policy path targets Nemotron Nano 4B.
+3. **AI is core, not decorative:** the app converts live sensor signals into practice states, then chooses the next micro-drill.
+4. **The UI is custom, playful, and not default Gradio:** the live camera stage, listening panel, coach overlays, garden reward, and melody export are a bespoke browser experience served through a Gradio Space.
+
+## What Judges Should Try
+
+1. Open the Space and click **Start practice**.
+2. Allow camera and microphone access.
+3. Put your mouth in the dotted oval.
+4. Try a soft "yuh yuh yuh" breath with rounded lips.
+5. Watch the listening panel update:
+   - airflow
+   - whistle confidence
+   - pitch detected
+   - stability
+6. Follow the coach's one-step correction.
+7. Hold a stable pitch long enough to grow the garden and unlock a tiny melody preview.
+
+Even if the room is noisy or the microphone is imperfect, the app should still show why it is coaching the next action.
+
+## The Core Loop
+
+```text
+camera + microphone
+        |
+        v
+browser feature extraction
+        |
+        v
+practice state
+        |
+        v
+coach policy
+        |
+        v
+one micro-drill + visual cue + audio feedback
+        |
+        v
+garden progress + melody reward
+```
+
+The goal is not to give a lecture about whistling. The goal is to keep the user inside a tight practice loop: observe, diagnose, adjust, try again.
+
+## Model And Signal Stack
+
+| Layer | Role | Why it is small |
+| --- | --- | --- |
+| `MIT/ast-finetuned-audioset-10-10-0.4593` | Whistle-like audio confidence | 86.6M parameters |
+| `librosa.pyin` | F0 / pitch stability | deterministic signal processing |
+| MediaPipe Face Landmarker | visible lower-face posture guidance | browser-side visual assistant |
+| Nemotron Nano 4B policy path | optional coach reasoning / LoRA target | under the 32B cap |
+| Rule fallback | deterministic coach when no hosted policy is configured | keeps the Space reliable |
+
+The deployed app does not fake model confidence. If AST is unavailable, the UI reports that clearly and falls back to pitch/airflow coaching rather than pretending a whistle score exists.
+
+## What Makes The AI Core
+
+Whistle Coach is not a static tutorial and not a camera filter. The app builds a structured practice state from live features:
+
+- face visible and centered
+- mouth opening ratio
+- lip roundness
+- mouth symmetry
+- jaw stability
+- audio airflow estimate
+- whistle confidence
+- pitch stability
+- stable duration
+
+The coach then maps that state to the next action:
+
+```json
+{
+  "state": "airflow_no_tone",
+  "active_step": "narrow_air_stream",
+  "coach_message": "You are close. Make the air stream narrower.",
+  "overlay_cues": [{"type": "air_stream", "direction": "narrower"}],
+  "next_drill": "narrow_air_stream"
+}
+```
+
+That is the AI-native part: every coaching sentence is grounded in the current attempt rather than prewritten lesson order.
+
+## Agentic Coach Trace
+
+The optional coach policy is shaped as a compact agent:
+
+```text
+Observe -> Diagnose -> Plan -> Act
+```
+
+Every response can include a trace like:
+
+```json
+[
+  {"step": "Observe", "action": "read_state", "detail": "mouth 76%, airflow 68%, tone 18%"},
+  {"step": "Diagnose", "action": "airflow_no_tone", "detail": "Air is moving but pitch is not stable."},
+  {"step": "Plan", "action": "narrow_air_stream", "detail": "Ask for a thinner air channel."},
+  {"step": "Act", "action": "coach_message", "detail": "You are close. Make the air stream narrower."}
+]
+```
+
+This makes the app eligible for Best Agent consideration: the coach is not just a chatbot, it is a stateful sensor-to-action loop with explicit decisions.
+
+## Tiny Titan Angle
+
+The core runtime is intentionally tiny:
+
+- MIT AST: 86.6M parameters
+- optional Nemotron Nano policy: 4B target
+- no model in the app exceeds the 32B Build Small limit
+- the SFT scaffold trains a narrow LoRA adapter on structured features, not raw media
+
+The project is designed around the idea that a small, specialized model can be better for embodied coaching than a huge general model.
+
+## Off Brand / Custom UI
+
+The experience intentionally pushes past default Gradio:
+
+- full custom HTML/CSS/JS frontend mounted inside Gradio
+- responsive three-panel practice layout
+- live camera stage with mouth target and lower-face overlays
+- audio listening panel with live confidence meters
+- garden growth reward
+- generated downloadable melody from the user's pitch contour
+
+The UI is meant to feel like a small practice companion, not a dashboard wrapped around a model endpoint.
+
+## Privacy And Safety
+
+Whistle Coach is playful, but it is careful:
+
+- webcam frames stay in the browser for MediaPipe feature extraction
+- the app uses derived mouth-shape features for coaching, not stored face images
+- microphone snippets are analyzed for whistle confidence and pitch, but not saved as a dataset
+- the included training data stores only structured practice states and coach decisions
+- the app does not claim tongue detection
+- this is not medical, speech therapy, or professional voice training software
+
+## Repository Map
+
+```text
+app.py                         Gradio Space, AST loading, audio analysis, pYIN, melody API
+frontend/index.html            custom Gradio-mounted UI shell
+frontend/style.css             responsive custom interface
+frontend/whistle_coach.js      camera/audio loop, garden, overlays, API calls
+frontend/audio_features.js     browser audio feature payload helpers
+frontend/face_features.js      mouth-shape feature payload helpers
+frontend/overlay_renderer.js   practice-state messages and overlay cues
+backend/state_classifier.py    deterministic practice-state classifier
+backend/coach_model.py         optional Nemotron-compatible coach policy wrapper
+backend/melody_generator.py    pitch contour to downloadable WAV melody
+data/coach_policy_sft.jsonl    seed SFT data for coach policy
+training/finetune_nemotron_policy.py  LoRA fine-tuning scaffold
+```
+
+## Running Locally
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+python app.py
+```
+
+Open the local Gradio URL. Camera and microphone access require `localhost` or HTTPS in modern browsers.
+
+## Optional Nemotron Coach Policy
+
+The Space works without external secrets. By default, the deterministic fallback keeps the live coach reliable.
+
+To enable a hosted Nemotron-compatible coach endpoint, configure these Space secrets:
+
+```text
+NEMOTRON_API_URL
+NEMOTRON_API_KEY
+NEMOTRON_MODEL
+```
+
+The recommended fine-tuning target is:
+
+```text
+nvidia/NVIDIA-Nemotron-3-Nano-4B-BF16
+```
+
+The training scaffold maps:
+
+```text
+practice_state history -> coach_response JSON
+```
+
+This keeps the learning problem narrow, auditable, and small.
+
+## Known Limitations
+
+- Whistle confidence depends on microphone quality and background noise.
+- "Airflow" is inferred from audio energy and breath-like spectral features; it is not physical airflow measurement.
+- Pitch detection works best once a stable tone appears.
+- MediaPipe can guide visible mouth posture, but it cannot detect tongue position.
+- Some browsers ask for camera and microphone permissions differently; the UI is responsive, but permissions remain browser-controlled.
+
+## Hackathon Checklist
+
+- [x] Gradio Space
+- [x] Custom UI beyond default Gradio
+- [x] Models under 32B parameters
+- [x] Audio-first AI loop
+- [x] Agent-style coach trace
+- [x] Privacy notes
+- [x] Local run instructions
+- [ ] Public demo video link
+- [ ] Public social post link
+- [ ] Final confirmation that requested frontmatter tags match the exact awards being entered
+
+## Credits
+
+Built for the Build Small Hackathon.
+
+Whistle Coach was developed with OpenAI Codex as a coding partner, with the goal of showing how a small, embodied AI loop can make one tiny real-world skill easier, more delightful, and more teachable.

app.py

@@ -0,0 +1,669 @@
+'''Whistle Coach - audio-first Hugging Face Space.
+
+The app uses MIT AST audio classification for whistle confidence and
+librosa.pyin for pitch tracking. Camera guidance is intentionally visual-only.
+'''
+
+from __future__ import annotations
+
+import base64
+import io
+import json
+import math
+from pathlib import Path
+from typing import Any
+
+import gradio as gr
+import librosa
+import numpy as np
+import soundfile as sf
+from scipy.signal import resample_poly
+from transformers import pipeline
+
+try:
+    import spaces
+except Exception:
+    class _SpacesFallback:
+        @staticmethod
+        def GPU(*decorator_args, **decorator_kwargs):
+            if (
+                decorator_args
+                and callable(decorator_args[0])
+                and len(decorator_args) == 1
+                and not decorator_kwargs
+            ):
+                return decorator_args[0]
+
+            def decorator(function):
+                return function
+
+            return decorator
+
+    spaces = _SpacesFallback()
+
+MODEL_ID = "MIT/ast-finetuned-audioset-10-10-0.4593"
+AST_PARAMETERS = "86.6M"
+AST_DEVICE = "cpu"
+TARGET_SR = 16_000
+MIN_AUDIO_SECONDS = 0.25
+MAX_ANALYSIS_SECONDS = 4.0
+
+BASE_DIR = Path(__file__).resolve().parent
+MELODY_DIR = BASE_DIR / "outputs" / "melodies"
+MELODY_DIR.mkdir(parents=True, exist_ok=True)
+
+MODEL_LOAD_ERROR: str | None = None
+try:
+    audio_classifier = pipeline(
+        "audio-classification",
+        model=MODEL_ID,
+        device=-1,
+    )
+except Exception as exc:
+    audio_classifier = None
+    MODEL_LOAD_ERROR = f"{type(exc).__name__}: {exc}"
+
+NOTE_NAMES = ["C", "C#", "D", "D#", "E", "F", "F#", "G", "G#", "A", "A#", "B"]
+STATE_ORDER = ["no_sound", "breath_noise", "tiny_whistle", "stable_pitch", "melody_ready"]
+STATE_LABELS = {
+    "no_sound": "No sound",
+    "breath_noise": "Breath noise",
+    "tiny_whistle": "Tiny whistle",
+    "stable_pitch": "Stable pitch",
+    "melody_ready": "Melody",
+}
+GARDEN_STAGES = {
+    "no_sound": ("soil", "Soil", "Rest, breathe, and start softly."),
+    "breath_noise": ("wind", "Wind", "Air is moving. Make the opening smaller."),
+    "tiny_whistle": ("sprout", "Sprout", "A tiny tone appeared. Freeze that shape."),
+    "stable_pitch": ("flower", "Flower", "Hold the tone and keep it gentle."),
+    "melody_ready": ("melody", "Melody flower", "You can shape notes into a melody."),
+}
+
+
+def clamp(value: float, minimum: float = 0.0, maximum: float = 100.0) -> float:
+    return float(min(maximum, max(minimum, value)))
+
+
+def hz_to_note(hz: float | None) -> str:
+    if hz is None or not np.isfinite(hz) or hz <= 0:
+        return "--"
+    midi = int(round(69 + 12 * math.log2(float(hz) / 440.0)))
+    octave = midi // 12 - 1
+    return f"{NOTE_NAMES[midi % 12]}{octave}"
+
+
+def hz_to_midi(hz: float) -> int:
+    return int(round(69 + 12 * math.log2(float(hz) / 440.0)))
+
+
+def midi_to_hz(midi: int) -> float:
+    return 440.0 * (2 ** ((midi - 69) / 12))
+
+
+def normalize_audio_array(data: np.ndarray) -> np.ndarray:
+    y = np.asarray(data)
+    if y.ndim > 1:
+        y = np.mean(y, axis=1)
+    if np.issubdtype(y.dtype, np.integer):
+        peak = float(np.iinfo(y.dtype).max)
+        y = y.astype(np.float32) / max(peak, 1.0)
+    else:
+        y = y.astype(np.float32)
+        max_abs = float(np.max(np.abs(y))) if y.size else 0.0
+        if max_abs > 1.5:
+            y = y / max_abs
+    y = np.nan_to_num(y, nan=0.0, posinf=0.0, neginf=0.0)
+    return np.clip(y, -1.0, 1.0).astype(np.float32)
+
+
+def load_audio_input(audio_input: Any) -> tuple[int, np.ndarray]:
+    '''Accept Gradio Audio numpy tuples, file paths, or path dictionaries.'''
+    if audio_input is None:
+        return TARGET_SR, np.zeros(0, dtype=np.float32)
+
+    if isinstance(audio_input, tuple) and len(audio_input) == 2:
+        sample_rate, data = audio_input
+        return int(sample_rate), normalize_audio_array(np.asarray(data))
+
+    if isinstance(audio_input, dict):
+        path = audio_input.get("path") or audio_input.get("name")
+        if path:
+            data, sample_rate = sf.read(path, always_2d=False)
+            return int(sample_rate), normalize_audio_array(np.asarray(data))
+
+    if isinstance(audio_input, (str, Path)):
+        data, sample_rate = sf.read(str(audio_input), always_2d=False)
+        return int(sample_rate), normalize_audio_array(np.asarray(data))
+
+    return TARGET_SR, np.zeros(0, dtype=np.float32)
+
+
+def resample_to_target(sample_rate: int, y: np.ndarray) -> np.ndarray:
+    if y.size == 0:
+        return y.astype(np.float32)
+    if sample_rate == TARGET_SR:
+        return y.astype(np.float32)
+    gcd = math.gcd(int(sample_rate), TARGET_SR)
+    up = TARGET_SR // gcd
+    down = int(sample_rate) // gcd
+    return resample_poly(y, up, down).astype(np.float32)
+
+
+def latest_window(y: np.ndarray, seconds: float = MAX_ANALYSIS_SECONDS) -> np.ndarray:
+    max_samples = int(TARGET_SR * seconds)
+    if y.size <= max_samples:
+        return y
+    return y[-max_samples:]
+
+
+def classify_with_ast(y16: np.ndarray) -> tuple[float, list[dict[str, Any]], str | None]:
+    '''Run the real HF AST classifier and return whistle confidence.'''
+    if audio_classifier is None:
+        return 0.0, [], MODEL_LOAD_ERROR or "Audio model is not loaded."
+    if y16.size < int(TARGET_SR * MIN_AUDIO_SECONDS):
+        return 0.0, [], None
+
+    try:
+        predictions = audio_classifier(
+            {"array": y16.astype(np.float32), "sampling_rate": TARGET_SR},
+            top_k=8,
+        )
+    except TypeError:
+        predictions = audio_classifier(
+            {"array": y16.astype(np.float32), "sampling_rate": TARGET_SR}
+        )
+    except Exception as exc:
+        return 0.0, [], f"AST inference failed: {type(exc).__name__}: {exc}"
+
+    if isinstance(predictions, dict):
+        predictions = [predictions]
+    if predictions and isinstance(predictions[0], list):
+        predictions = predictions[0]
+
+    labels: list[dict[str, Any]] = []
+    whistle_score = 0.0
+    top_non_whistle = 0.0
+    for item in predictions[:8]:
+        label = str(item.get("label", ""))
+        score = float(item.get("score", 0.0) or 0.0)
+        labels.append({"label": label, "score": round(score, 4)})
+        normalized = label.lower().replace("_", " ").replace("-", " ")
+        if "whistl" in normalized or "whistle" in normalized:
+            whistle_score = max(whistle_score, score)
+        else:
+            top_non_whistle = max(top_non_whistle, score)
+
+    if whistle_score > 0:
+        confidence = whistle_score * 100.0
+    else:
+        confidence = clamp((1.0 - top_non_whistle) * 12.0, 0.0, 12.0)
+    return round(confidence, 2), labels, None
+
+
+def longest_stable_duration(f0: np.ndarray, voiced: np.ndarray, hop_length: int) -> float:
+    longest = 0.0
+    current: list[float] = []
+
+    def finish_run(values: list[float]) -> float:
+        if len(values) < 3:
+            return 0.0
+        arr = np.asarray(values, dtype=np.float64)
+        center = float(np.nanmedian(arr))
+        if center <= 0:
+            return 0.0
+        cents = 1200.0 * np.log2(arr / center)
+        if float(np.nanstd(cents)) > 95.0:
+            return 0.0
+        return len(values) * hop_length / TARGET_SR
+
+    for hz, is_voiced in zip(f0, voiced):
+        if bool(is_voiced) and np.isfinite(hz) and hz > 0:
+            current.append(float(hz))
+        else:
+            longest = max(longest, finish_run(current))
+            current = []
+    longest = max(longest, finish_run(current))
+    return round(float(longest), 2)
+
+
+def analyze_pitch(y16: np.ndarray) -> dict[str, Any]:
+    hop_length = 256
+    frame_length = 2048
+    if y16.size < frame_length:
+        return {
+            "pitch_detected": False,
+            "pitch_note": "--",
+            "mean_pitch_hz": None,
+            "stability_score": 0,
+            "stable_duration": 0.0,
+            "pitch_contour": [],
+            "voiced_ratio": 0.0,
+            "pitch_std_cents": None,
+            "pitch_movement_semitones": 0.0,
+        }
+
+    try:
+        f0, voiced_flag, voiced_prob = librosa.pyin(
+            y16,
+            fmin=librosa.note_to_hz("C5"),
+            fmax=librosa.note_to_hz("C8"),
+            sr=TARGET_SR,
+            frame_length=frame_length,
+            hop_length=hop_length,
+        )
+    except Exception:
+        return {
+            "pitch_detected": False,
+            "pitch_note": "--",
+            "mean_pitch_hz": None,
+            "stability_score": 0,
+            "stable_duration": 0.0,
+            "pitch_contour": [],
+            "voiced_ratio": 0.0,
+            "pitch_std_cents": None,
+            "pitch_movement_semitones": 0.0,
+        }
+
+    voiced = np.asarray(voiced_flag, dtype=bool) & np.isfinite(f0)
+    valid_f0 = np.asarray(f0)[voiced]
+    voiced_ratio = float(np.mean(voiced)) if len(voiced) else 0.0
+    pitch_detected = bool(valid_f0.size >= 3 and voiced_ratio >= 0.06)
+
+    mean_pitch: float | None = None
+    pitch_std_cents: float | None = None
+    pitch_movement = 0.0
+    if valid_f0.size:
+        mean_pitch = float(np.nanmedian(valid_f0))
+        if mean_pitch > 0 and valid_f0.size > 1:
+            cents = 1200.0 * np.log2(valid_f0 / mean_pitch)
+            pitch_std_cents = float(np.nanstd(cents))
+            pitch_movement = float(np.nanmax(cents) - np.nanmin(cents)) / 100.0
+
+    std_score = 0.0
+    if pitch_std_cents is not None:
+        std_score = clamp(100.0 - (pitch_std_cents * 1.35), 0.0, 100.0)
+    stability_score = clamp((voiced_ratio * 62.0) + (std_score * 0.38))
+    stable_duration = longest_stable_duration(np.asarray(f0), voiced, hop_length)
+
+    times = librosa.frames_to_time(np.arange(len(f0)), sr=TARGET_SR, hop_length=hop_length)
+    contour: list[dict[str, Any]] = []
+    valid_indices = np.where(np.isfinite(f0) & voiced)[0]
+    if valid_indices.size:
+        step = max(1, int(math.ceil(valid_indices.size / 90)))
+        for idx in valid_indices[::step]:
+            hz = float(f0[idx])
+            contour.append({
+                "time_ms": int(round(float(times[idx]) * 1000)),
+                "hz": round(hz, 2),
+                "note": hz_to_note(hz),
+            })
+
+    return {
+        "pitch_detected": pitch_detected,
+        "pitch_note": hz_to_note(mean_pitch),
+        "mean_pitch_hz": round(mean_pitch, 2) if mean_pitch else None,
+        "stability_score": int(round(stability_score)) if pitch_detected else 0,
+        "stable_duration": stable_duration if pitch_detected else 0.0,
+        "pitch_contour": contour,
+        "voiced_ratio": round(voiced_ratio, 3),
+        "pitch_std_cents": round(pitch_std_cents, 2) if pitch_std_cents is not None else None,
+        "pitch_movement_semitones": round(pitch_movement, 2),
+    }
+
+
+def analyze_airflow(y16: np.ndarray) -> dict[str, float]:
+    if y16.size == 0:
+        return {"rms": 0.0, "db": -120.0, "airflow_score": 0.0, "noise_score": 0.0}
+    rms = float(np.sqrt(np.mean(np.square(y16))))
+    db = float(20.0 * np.log10(rms + 1e-9))
+    airflow_score = clamp((db + 55.0) / 32.0 * 100.0)
+    try:
+        flatness = float(np.nanmean(librosa.feature.spectral_flatness(y=y16, n_fft=1024, hop_length=256)))
+        zcr = float(np.nanmean(librosa.feature.zero_crossing_rate(y16, frame_length=1024, hop_length=256)))
+    except Exception:
+        flatness = 0.0
+        zcr = 0.0
+    noise_score = clamp((flatness * 180.0) + (zcr * 110.0))
+    return {
+        "rms": round(rms, 5),
+        "db": round(db, 2),
+        "airflow_score": int(round(airflow_score)),
+        "noise_score": round(noise_score, 2),
+    }
+
+
+def choose_state_and_feedback(result: dict[str, Any]) -> tuple[str, str, str]:
+    airflow = float(result["airflow_score"])
+    confidence = float(result["whistle_confidence"])
+    pitch_detected = bool(result["pitch_detected"])
+    stable_duration = float(result["stable_duration"] or 0.0)
+    noise_score = float(result.get("noise_score", 0.0) or 0.0)
+    movement = float(result.get("pitch_movement_semitones", 0.0) or 0.0)
+
+    if pitch_detected and stable_duration >= 1.0 and movement >= 2.0:
+        return (
+            "melody_ready",
+            "Nice - you are changing notes. Try making a melody.",
+            "Move the pitch slowly, like stepping between two nearby notes.",
+        )
+    if pitch_detected and stable_duration >= 1.0:
+        return (
+            "stable_pitch",
+            "Great! Hold this tone longer.",
+            "Stay still for one more second before trying to move the pitch.",
+        )
+    if pitch_detected:
+        return (
+            "tiny_whistle",
+            "Tiny whistle found. Freeze this mouth shape.",
+            "Use less air now; keep the same lip opening and hold it steady.",
+        )
+    if airflow < 10:
+        return (
+            "no_sound",
+            "Blow a little more, but stay gentle.",
+            "Keep your lips relaxed, then send a small stream of air through the center.",
+        )
+    if confidence >= 25:
+        return (
+            "tiny_whistle",
+            "You are close. Make the air stream narrower.",
+            "Round the lips a little more and soften the airflow.",
+        )
+    if airflow >= 35 or noise_score >= 18:
+        return (
+            "breath_noise",
+            "You are producing air noise. Make the lip opening smaller and soften the airflow.",
+            "Try a quiet 'yuh yuh yuh' breath with a smaller opening.",
+        )
+    return (
+        "no_sound",
+        "Blow a little more, but stay gentle.",
+        "Stay relaxed. The first goal is a soft, steady stream of air.",
+    )
+
+
+def analyze_audio(audio_input: Any) -> dict[str, Any]:
+    '''Analyze a Gradio Audio input using AST and librosa.pyin.'''
+    sample_rate, y = load_audio_input(audio_input)
+    y16 = latest_window(resample_to_target(sample_rate, y))
+    duration = y16.size / TARGET_SR if TARGET_SR else 0.0
+
+    airflow = analyze_airflow(y16)
+    whistle_confidence, ast_labels, ast_error = classify_with_ast(y16)
+    pitch = analyze_pitch(y16)
+
+    result: dict[str, Any] = {
+        "airflow_score": int(airflow["airflow_score"]),
+        "whistle_confidence": int(round(whistle_confidence)),
+        "pitch_detected": bool(pitch["pitch_detected"]),
+        "pitch_note": pitch["pitch_note"],
+        "mean_pitch_hz": pitch["mean_pitch_hz"],
+        "stability_score": int(pitch["stability_score"]),
+        "stable_duration": float(pitch["stable_duration"]),
+        "state": "no_sound",
+        "coach_feedback": "Blow a little more, but stay gentle.",
+        "next_tip": "Start with a soft, narrow stream of air.",
+        "pitch_contour": pitch["pitch_contour"],
+        "audio_seconds": round(duration, 2),
+        "rms": airflow["rms"],
+        "db": airflow["db"],
+        "noise_score": airflow["noise_score"],
+        "voiced_ratio": pitch["voiced_ratio"],
+        "pitch_std_cents": pitch["pitch_std_cents"],
+        "pitch_movement_semitones": pitch["pitch_movement_semitones"],
+        "ast_top_labels": ast_labels,
+        "ast_error": ast_error,
+        "model_stack": {
+            "audio_model": f"{MODEL_ID} ({AST_PARAMETERS}, {AST_DEVICE})",
+            "pitch_tracking": "librosa.pyin C5-C8",
+            "visual_assistant": "MediaPipe visible mouth guidance only; no tongue detection",
+        },
+    }
+
+    state, feedback, next_tip = choose_state_and_feedback(result)
+    result["state"] = state
+    result["coach_feedback"] = feedback
+    result["next_tip"] = next_tip
+    return result
+
+
+def contour_to_note_sequence(contour: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    notes: list[dict[str, Any]] = []
+    current_midi: int | None = None
+    start_ms = 0
+    last_ms = 0
+    for sample in contour:
+        hz = float(sample.get("hz", sample.get("frequency_hz", 0)) or 0)
+        t_ms = int(sample.get("time_ms", sample.get("t", 0)) or 0)
+        if hz < 120:
+            continue
+        midi = hz_to_midi(hz)
+        if current_midi is None:
+            current_midi = midi
+            start_ms = t_ms
+        elif abs(midi - current_midi) > 1:
+            notes.append({"midi": current_midi, "duration_ms": max(180, last_ms - start_ms)})
+            current_midi = midi
+            start_ms = t_ms
+        last_ms = t_ms
+    if current_midi is not None:
+        notes.append({"midi": current_midi, "duration_ms": max(260, last_ms - start_ms)})
+    return notes[:12]
+
+
+def generate_melody_from_contour(contour: list[dict[str, Any]]) -> tuple[str | None, str]:
+    notes = contour_to_note_sequence(contour)
+    if not notes:
+        return None, ""
+    sample_rate = 22_050
+    samples: list[np.ndarray] = []
+    for note in notes:
+        hz = midi_to_hz(int(note["midi"]))
+        duration = min(0.75, max(0.18, int(note["duration_ms"]) / 1000.0))
+        t = np.linspace(0.0, duration, int(sample_rate * duration), endpoint=False)
+        tone = np.sin(2 * np.pi * hz * t) + 0.25 * np.sin(2 * np.pi * hz * 2 * t)
+        fade = min(220, max(12, len(tone) // 8))
+        envelope = np.ones_like(tone)
+        envelope[:fade] = np.linspace(0.0, 1.0, fade)
+        envelope[-fade:] = np.linspace(1.0, 0.0, fade)
+        samples.append((tone * envelope * 0.23).astype(np.float32))
+        samples.append(np.zeros(int(sample_rate * 0.045), dtype=np.float32))
+    wav = np.concatenate(samples) if samples else np.zeros(1, dtype=np.float32)
+    output_path = MELODY_DIR / "whistle_melody.wav"
+    sf.write(output_path, wav, sample_rate)
+    names = [hz_to_note(midi_to_hz(int(note["midi"]))) for note in notes]
+    return str(output_path), " - ".join(names)
+
+
+FRONTEND_DIR = BASE_DIR / "frontend"
+HTML_PATH = FRONTEND_DIR / "index.html"
+STYLE_PATH = FRONTEND_DIR / "style.css"
+SCRIPT_PATHS = [
+    FRONTEND_DIR / "policy.js",
+    FRONTEND_DIR / "landmarks.js",
+    FRONTEND_DIR / "audio_features.js",
+    FRONTEND_DIR / "face_features.js",
+    FRONTEND_DIR / "overlay_renderer.js",
+    FRONTEND_DIR / "whistle_coach.js",
+]
+
+
+def load_frontend_html() -> str:
+    return HTML_PATH.read_text(encoding="utf-8")
+
+
+def load_frontend_css() -> str:
+    return STYLE_PATH.read_text(encoding="utf-8") if STYLE_PATH.exists() else ""
+
+
+def load_js_bundle() -> str:
+    parts: list[str] = []
+    for script_path in SCRIPT_PATHS:
+        if script_path.exists():
+            parts.append(script_path.read_text(encoding="utf-8"))
+    return "\n\n".join(parts)
+
+
+@spaces.GPU(duration=1)
+def zerogpu_startup_probe() -> str:
+    """Tiny hidden hook so ZeroGPU Spaces start without charging live audio calls."""
+    return "ready"
+
+
+def analyze_audio_window(audio_payload_json: str) -> dict[str, Any]:
+    """Decode a browser-captured WAV window and run the real AST/librosa stack."""
+    if not audio_payload_json:
+        result = empty_result()
+        result["ast_error"] = MODEL_LOAD_ERROR
+        return result
+
+    try:
+        payload = json.loads(audio_payload_json)
+        encoded = payload.get("data_base64") or ""
+        audio_bytes = base64.b64decode(encoded)
+        data, sample_rate = sf.read(io.BytesIO(audio_bytes), always_2d=False)
+    except Exception as exc:
+        result = empty_result()
+        result["ast_error"] = f"Audio decode failed: {type(exc).__name__}: {exc}"
+        result["coach_feedback"] = "The microphone window could not be decoded. Try again."
+        result["next_tip"] = "Keep the browser microphone permission enabled."
+        return result
+
+    result = analyze_audio((int(sample_rate), data))
+    result["source"] = "browser_live_window"
+    return result
+
+
+def empty_result() -> dict[str, Any]:
+    return {
+        "airflow_score": 0,
+        "whistle_confidence": 0,
+        "pitch_detected": False,
+        "pitch_note": "--",
+        "mean_pitch_hz": None,
+        "stability_score": 0,
+        "stable_duration": 0.0,
+        "state": "no_sound",
+        "coach_feedback": "Ready when you are.",
+        "next_tip": "The coach listens to each audio window and updates feedback.",
+        "pitch_contour": [],
+        "rms": 0,
+        "db": -120,
+        "voiced_ratio": 0,
+        "pitch_std_cents": None,
+        "pitch_movement_semitones": 0,
+        "ast_top_labels": [],
+        "ast_error": MODEL_LOAD_ERROR,
+        "model_stack": {
+            "audio_model": f"{MODEL_ID} ({AST_PARAMETERS}, {AST_DEVICE})",
+            "pitch_tracking": "librosa.pyin C5-C8",
+            "visual_assistant": "MediaPipe visible mouth guidance only; no tongue detection",
+        },
+    }
+
+
+def coach_reason(practice_state_json: str, history_json: str = "[]") -> dict[str, Any]:
+    """Small rule-based policy kept for the old frontend trace panel."""
+    try:
+        practice_state = json.loads(practice_state_json or "{}")
+    except json.JSONDecodeError:
+        practice_state = {}
+    state_name = practice_state.get("state", "idle")
+    audio = practice_state.get("audio", {}) if isinstance(practice_state, dict) else {}
+    airflow = float(audio.get("airflow_score", 0) or 0)
+    stability = float(audio.get("pitch_stability_score", 0) or 0)
+
+    if stability >= 0.58:
+        message = "Great! Hold this tone longer."
+        drill = "Hold a steady tone"
+        success = True
+    elif airflow >= 0.55:
+        message = "You are producing air noise. Make the lip opening smaller and soften the airflow."
+        drill = "Make the air stream narrower"
+        success = False
+    elif airflow >= 0.25:
+        message = "You are close. Make the air stream narrower."
+        drill = "Gentle airflow"
+        success = False
+    else:
+        message = "Blow a little more, but stay gentle."
+        drill = "Gentle airflow"
+        success = False
+
+    return {
+        "coach_message": message,
+        "next_drill": drill,
+        "success_trigger": success,
+        "model_source": "local rule fallback; AST/librosa panel uses live audio model",
+        "agent_trace": [
+            {"step": "Observe", "detail": f"Browser practice state: {state_name}."},
+            {"step": "Listen", "detail": "Backend AST/librosa analyzes one-second audio windows."},
+            {"step": "Coach", "detail": drill},
+        ],
+    }
+
+
+def generate_melody(pitch_contour_json: str) -> dict[str, Any]:
+    try:
+        contour = json.loads(pitch_contour_json or "[]")
+    except json.JSONDecodeError:
+        contour = []
+    path, sequence = generate_melody_from_contour(contour if isinstance(contour, list) else [])
+    return {"path": path, "sequence": sequence, "ready": bool(path)}
+
+
+with gr.Blocks(
+    title="Whistle Coach",
+    fill_width=True,
+) as demo:
+    gr.HTML(load_frontend_html(), container=False, padding=False)
+
+    zerogpu_trigger = gr.Button(visible=False)
+    zerogpu_status = gr.Textbox(visible=False)
+    zerogpu_trigger.click(
+        zerogpu_startup_probe,
+        outputs=zerogpu_status,
+        api_name="zerogpu_startup_probe",
+        show_progress="hidden",
+    )
+
+    audio_payload = gr.Textbox(visible=False)
+    audio_result = gr.JSON(visible=False)
+    audio_payload.submit(
+        analyze_audio_window,
+        inputs=audio_payload,
+        outputs=audio_result,
+        api_name="analyze_audio_window",
+        show_progress="hidden",
+    )
+
+    practice_state = gr.Textbox(visible=False)
+    coach_history = gr.Textbox(visible=False)
+    coach_output = gr.JSON(visible=False)
+    practice_state.submit(
+        coach_reason,
+        inputs=[practice_state, coach_history],
+        outputs=coach_output,
+        api_name="coach_reason",
+        show_progress="hidden",
+    )
+
+    melody_contour = gr.Textbox(visible=False)
+    melody_output = gr.JSON(visible=False)
+    melody_contour.submit(
+        generate_melody,
+        inputs=melody_contour,
+        outputs=melody_output,
+        api_name="generate_melody",
+        show_progress="hidden",
+    )
+
+
+if __name__ == "__main__":
+    demo.queue(default_concurrency_limit=1).launch(
+        theme=gr.themes.Soft(),
+        css=load_frontend_css(),
+        js=load_js_bundle(),
+    )

backend/__init__.py

@@ -0,0 +1 @@
+"""Backend modules for Whistle Coach."""

backend/coach_model.py

@@ -0,0 +1,156 @@
+"""Nemotron coach reasoning wrapper with rule-based fallback."""
+
+from __future__ import annotations
+
+import json
+import os
+import urllib.request
+from typing import Any
+
+from .prompts import SYSTEM_PROMPT, build_coach_prompt
+from .schemas import CoachResponse
+
+
+class NemotronCoach:
+    """Small replaceable coach-reasoning module.
+
+    V1 keeps this optional. Set NEMOTRON_API_URL, NEMOTRON_API_KEY, and
+    NEMOTRON_MODEL to call a hosted Nemotron-compatible chat endpoint. Without
+    those variables, the deterministic fallback keeps the Space fully working.
+    """
+
+    def __init__(self) -> None:
+        self.api_url = os.getenv("NEMOTRON_API_URL", "").strip()
+        self.api_key = os.getenv("NEMOTRON_API_KEY", "").strip()
+        self.model = os.getenv("NEMOTRON_MODEL", "nvidia/nemotron-nano-4b-v1")
+
+    def reason(self, practice_state: dict[str, Any], history: list[dict[str, Any]]) -> dict[str, Any]:
+        if self.api_url and self.api_key:
+            try:
+                return self._call_nemotron(practice_state, history)
+            except Exception as error:  # noqa: BLE001 - fallback is intentional.
+                fallback = self._fallback(practice_state)
+                fallback["diagnosis"] += f" Nemotron fallback used: {error.__class__.__name__}."
+                return fallback
+        return self._fallback(practice_state)
+
+    def _call_nemotron(self, practice_state: dict[str, Any], history: list[dict[str, Any]]) -> dict[str, Any]:
+        payload = {
+            "model": self.model,
+            "messages": [
+                {"role": "system", "content": SYSTEM_PROMPT},
+                {"role": "user", "content": build_coach_prompt(practice_state, history)},
+            ],
+            "temperature": 0.2,
+            "max_tokens": 220,
+        }
+        request = urllib.request.Request(
+            self.api_url,
+            data=json.dumps(payload).encode("utf-8"),
+            headers={
+                "Authorization": f"Bearer {self.api_key}",
+                "Content-Type": "application/json",
+            },
+            method="POST",
+        )
+        with urllib.request.urlopen(request, timeout=10) as response:
+            raw = json.loads(response.read().decode("utf-8"))
+
+        content = raw.get("choices", [{}])[0].get("message", {}).get("content", "{}")
+        parsed = self._parse_model_json(content)
+        parsed["model_source"] = "nemotron"
+        return self._normalize_response(parsed, practice_state)
+
+    def _parse_model_json(self, content: str) -> dict[str, Any]:
+        """Parse strict JSON, tolerating fenced responses from hosted endpoints."""
+        content = content.strip()
+        if content.startswith("```"):
+            content = content.strip("`")
+            if content.startswith("json"):
+                content = content[4:].strip()
+        start = content.find("{")
+        end = content.rfind("}")
+        if start >= 0 and end > start:
+            content = content[start : end + 1]
+        return json.loads(content)
+
+    def _normalize_response(self, response: dict[str, Any], practice_state: dict[str, Any]) -> dict[str, Any]:
+        fallback = self._fallback(practice_state)
+        normalized = {**fallback, **response}
+        normalized["overlay_cues"] = list(normalized.get("overlay_cues") or [])
+        normalized["agent_trace"] = list(normalized.get("agent_trace") or fallback["agent_trace"])
+        normalized["success_trigger"] = bool(practice_state.get("success_trigger", normalized.get("success_trigger", False)))
+        return normalized
+
+    def _fallback(self, practice_state: dict[str, Any]) -> dict[str, Any]:
+        state = practice_state.get("state", "idle")
+        active_step = practice_state.get("active_step", "start")
+        success = bool(practice_state.get("success_trigger", False))
+        face = practice_state.get("face", {}) or {}
+        audio = practice_state.get("audio", {}) or {}
+
+        messages = {
+            "idle": "Press Start Practice when you are ready.",
+            "no_face": "Please face the camera and center your mouth in the frame.",
+            "mouth_too_open": "Make the opening smaller and relax your jaw.",
+            "not_rounded": "Pull both lip corners inward, like saying 'u'.",
+            "asymmetric_mouth": "Keep both lip corners level and centered.",
+            "mouth_ready_no_airflow": "Good mouth shape. Now blow gently.",
+            "airflow_no_tone": "You are close. Make the air stream narrower.",
+            "stable_whistle": "Great! Hold that whistle steady.",
+        }
+        drills = {
+            "idle": "start_session",
+            "no_face": "center_face",
+            "mouth_too_open": "small_opening_hold",
+            "not_rounded": "lip_rounding",
+            "asymmetric_mouth": "corner_leveling",
+            "mouth_ready_no_airflow": "gentle_airflow",
+            "airflow_no_tone": "narrow_air_stream",
+            "stable_whistle": "steady_tone_hold",
+        }
+        cues = {
+            "mouth_too_open": [{"type": "mouth_opening", "direction": "smaller"}],
+            "not_rounded": [{"type": "lip_corners", "direction": "inward"}],
+            "asymmetric_mouth": [{"type": "symmetry", "direction": "level"}],
+            "airflow_no_tone": [{"type": "air_stream", "direction": "narrower"}],
+            "stable_whistle": [{"type": "success", "direction": "hold"}],
+        }
+        trace = [
+            {
+                "step": "Observe",
+                "action": "read_state",
+                "detail": (
+                    f"mouth {round(float(face.get('mouth_shape_score', 0)) * 100)}%, "
+                    f"airflow {round(float(audio.get('airflow_score', 0)) * 100)}%, "
+                    f"tone {round(float(audio.get('pitch_stability_score', 0)) * 100)}%"
+                ),
+            },
+            {
+                "step": "Diagnose",
+                "action": state,
+                "detail": f"Current blocker is {state}.",
+            },
+            {
+                "step": "Plan",
+                "action": drills.get(state, "observe"),
+                "detail": f"Focus on one micro-drill: {drills.get(state, 'observe')}.",
+            },
+            {
+                "step": "Act",
+                "action": "coach_message",
+                "detail": messages.get(state, "Keep adjusting one small thing at a time."),
+            },
+        ]
+        response = CoachResponse(
+            coach_message=messages.get(state, "Keep adjusting one small thing at a time."),
+            diagnosis=f"Rule fallback classified state as {state}.",
+            overlay_cues=cues.get(state, []),
+            active_step=active_step,
+            agent_trace=trace,
+            next_drill=drills.get(state, "observe"),
+            difficulty_adjustment="easier" if state in {"no_face", "mouth_too_open"} else "hold",
+            success_trigger=success,
+            model_source="rule_fallback",
+        )
+        return response.to_dict()

backend/melody_generator.py

@@ -0,0 +1,89 @@
+"""Whistle pitch contour to simple downloadable WAV melody."""
+
+from __future__ import annotations
+
+import math
+import wave
+from pathlib import Path
+from typing import Iterable
+
+
+SAMPLE_RATE = 22050
+A4_HZ = 440.0
+
+
+def hz_to_midi(hz: float) -> int:
+    if hz <= 0:
+        return 69
+    return int(round(69 + 12 * math.log2(hz / A4_HZ)))
+
+
+def midi_to_hz(midi: int) -> float:
+    return A4_HZ * (2 ** ((midi - 69) / 12))
+
+
+def quantize_pitch_contour(pitch_contour: Iterable[dict]) -> list[dict]:
+    """Convert browser pitch samples into a compact note list."""
+    notes: list[dict] = []
+    current_midi: int | None = None
+    start_ms = 0
+    last_ms = 0
+
+    for sample in pitch_contour:
+        hz = float(sample.get("frequency_hz", sample.get("hz", 0)) or 0)
+        t_ms = int(sample.get("time_ms", sample.get("t", 0)) or 0)
+        if hz < 120:
+            continue
+        midi = hz_to_midi(hz)
+        if current_midi is None:
+            current_midi = midi
+            start_ms = t_ms
+        elif abs(midi - current_midi) > 1:
+            duration = max(160, last_ms - start_ms)
+            notes.append({"midi": current_midi, "duration_ms": duration})
+            current_midi = midi
+            start_ms = t_ms
+        last_ms = t_ms
+
+    if current_midi is not None:
+        notes.append({"midi": current_midi, "duration_ms": max(300, last_ms - start_ms)})
+
+    if not notes:
+        notes = [
+            {"midi": 72, "duration_ms": 360},
+            {"midi": 76, "duration_ms": 360},
+            {"midi": 79, "duration_ms": 520},
+        ]
+    return notes[:12]
+
+
+def generate_melody_wav(pitch_contour: list[dict], output_path: Path) -> Path:
+    """Generate a tiny sine-wave arrangement from quantized whistle notes."""
+    notes = quantize_pitch_contour(pitch_contour)
+    samples: list[int] = []
+    amplitude = 0.24
+
+    for note in notes:
+        hz = midi_to_hz(int(note["midi"]))
+        duration_samples = int(SAMPLE_RATE * (int(note["duration_ms"]) / 1000))
+        fade_samples = max(1, int(SAMPLE_RATE * 0.025))
+        for index in range(duration_samples):
+            envelope = 1.0
+            if index < fade_samples:
+                envelope = index / fade_samples
+            elif duration_samples - index < fade_samples:
+                envelope = (duration_samples - index) / fade_samples
+            value = math.sin(2 * math.pi * hz * index / SAMPLE_RATE)
+            value += 0.35 * math.sin(2 * math.pi * hz * 2 * index / SAMPLE_RATE)
+            samples.append(int(32767 * amplitude * envelope * value))
+
+        samples.extend([0] * int(SAMPLE_RATE * 0.04))
+
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    with wave.open(str(output_path), "wb") as wav:
+        wav.setnchannels(1)
+        wav.setsampwidth(2)
+        wav.setframerate(SAMPLE_RATE)
+        for sample in samples:
+            wav.writeframesraw(int(sample).to_bytes(2, "little", signed=True))
+    return output_path

backend/prompts.py

@@ -0,0 +1,25 @@
+"""Prompt templates for the Nemotron coach reasoning model."""
+
+SYSTEM_PROMPT = """You are Whistle Coach, a tiny body-skill coach.
+You receive structured real-time practice_state JSON from a browser pipeline.
+Act as a compact embodied-skill policy model: observe the face/audio state,
+diagnose the blocker, choose exactly one next drill, and produce a traceable
+coaching action.
+
+Be playful but concrete. Do not make medical claims. Do not mention hidden
+model internals. Keep output JSON-only with these keys:
+coach_message, diagnosis, overlay_cues, active_step, agent_trace, next_drill,
+difficulty_adjustment, success_trigger.
+
+agent_trace must be a list of 4 compact objects with step/action/detail:
+Observe, Diagnose, Plan, Act."""
+
+
+def build_coach_prompt(practice_state: dict, history: list[dict]) -> str:
+    return (
+        "Current practice_state JSON:\n"
+        f"{practice_state}\n\n"
+        "Short history, newest last:\n"
+        f"{history[-6:]}\n\n"
+        "Return compact JSON only."
+    )

backend/schemas.py

@@ -0,0 +1,56 @@
+"""Shared schemas for Whistle Coach's embodied AI pipeline."""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from typing import Any
+
+
+@dataclass
+class FaceFeatures:
+    face_visible: bool = False
+    face_centered: bool = False
+    mouth_opening_ratio: float = 0.0
+    lip_roundness_score: float = 0.0
+    upper_lip_lift_score: float = 0.0
+    jaw_stability_score: float = 0.0
+    mouth_symmetry_score: float = 0.0
+    mouth_shape_score: float = 0.0
+
+
+@dataclass
+class AudioFeatures:
+    rms_volume: float = 0.0
+    airflow_score: float = 0.0
+    peak_frequency_hz: float = 0.0
+    pitch_stability_score: float = 0.0
+    stable_duration_ms: int = 0
+
+
+@dataclass
+class PracticeState:
+    state: str = "idle"
+    active_step: str = "start"
+    face: FaceFeatures = field(default_factory=FaceFeatures)
+    audio: AudioFeatures = field(default_factory=AudioFeatures)
+    success_trigger: bool = False
+    confidence: float = 0.0
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+@dataclass
+class CoachResponse:
+    coach_message: str
+    diagnosis: str
+    overlay_cues: list[dict[str, Any]]
+    active_step: str
+    agent_trace: list[dict[str, Any]] = field(default_factory=list)
+    next_drill: str = "observe"
+    difficulty_adjustment: str = "hold"
+    success_trigger: bool = False
+    model_source: str = "rule_fallback"
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)

backend/state_classifier.py

@@ -0,0 +1,91 @@
+"""Rule-based state classifier for browser-extracted face and audio features."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .schemas import AudioFeatures, FaceFeatures, PracticeState
+
+
+def _num(value: Any, default: float = 0.0) -> float:
+    try:
+        return float(value)
+    except (TypeError, ValueError):
+        return default
+
+
+def classify_practice_state(payload: dict[str, Any]) -> dict[str, Any]:
+    """Convert raw feature JSON into a stable practice state.
+
+    This is intentionally simple and deterministic. Nemotron can reason over
+    the resulting state, but the app still works when no model is available.
+    """
+    face_payload = payload.get("face", payload.get("face_features", {})) or {}
+    audio_payload = payload.get("audio", payload.get("audio_features", {})) or {}
+
+    face = FaceFeatures(
+        face_visible=bool(face_payload.get("face_visible", face_payload.get("visible", False))),
+        face_centered=bool(face_payload.get("face_centered", face_payload.get("centered", False))),
+        mouth_opening_ratio=_num(face_payload.get("mouth_opening_ratio", face_payload.get("openingRatio"))),
+        lip_roundness_score=_num(face_payload.get("lip_roundness_score", face_payload.get("puckerScore"))),
+        upper_lip_lift_score=_num(face_payload.get("upper_lip_lift_score", face_payload.get("upperLipLiftScore"))),
+        jaw_stability_score=_num(face_payload.get("jaw_stability_score", face_payload.get("jawScore"))),
+        mouth_symmetry_score=_num(face_payload.get("mouth_symmetry_score", face_payload.get("symmetry"))),
+        mouth_shape_score=_num(face_payload.get("mouth_shape_score", face_payload.get("score"))),
+    )
+    audio = AudioFeatures(
+        rms_volume=_num(audio_payload.get("rms_volume", audio_payload.get("rms"))),
+        airflow_score=_num(audio_payload.get("airflow_score", audio_payload.get("airflow"))),
+        peak_frequency_hz=_num(audio_payload.get("peak_frequency_hz", audio_payload.get("peakFrequency"))),
+        pitch_stability_score=_num(audio_payload.get("pitch_stability_score", audio_payload.get("tone"))),
+        stable_duration_ms=int(_num(audio_payload.get("stable_duration_ms", audio_payload.get("stableDurationMs")), 0)),
+    )
+
+    state = "idle"
+    active_step = "start"
+    confidence = 0.0
+
+    if not face.face_visible or not face.face_centered:
+        state = "no_face"
+        active_step = "align_face"
+        confidence = 0.75
+    elif face.mouth_opening_ratio > 0.34 or face.jaw_stability_score < 0.45:
+        state = "mouth_too_open"
+        active_step = "small_opening"
+        confidence = 0.72
+    elif face.lip_roundness_score < 0.52:
+        state = "not_rounded"
+        active_step = "round_lips"
+        confidence = 0.74
+    elif face.mouth_symmetry_score < 0.58:
+        state = "asymmetric_mouth"
+        active_step = "center_mouth"
+        confidence = 0.62
+    elif audio.airflow_score < 0.32:
+        state = "mouth_ready_no_airflow"
+        active_step = "gentle_airflow"
+        confidence = 0.7
+    elif audio.pitch_stability_score < 0.58:
+        state = "airflow_no_tone"
+        active_step = "narrow_air_stream"
+        confidence = 0.68
+    else:
+        state = "stable_whistle"
+        active_step = "record_melody"
+        confidence = 0.84
+
+    success_trigger = (
+        state == "stable_whistle"
+        and audio.stable_duration_ms >= 2000
+        and audio.peak_frequency_hz >= 700
+    )
+
+    practice_state = PracticeState(
+        state=state,
+        active_step=active_step,
+        face=face,
+        audio=audio,
+        success_trigger=success_trigger,
+        confidence=confidence,
+    )
+    return practice_state.to_dict()

data/coach_policy_sft.jsonl

@@ -0,0 +1,8 @@
+{"input":"You are Whistle Coach. Current practice_state JSON: {\"state\":\"no_face\",\"active_step\":\"align_face\",\"face\":{\"face_visible\":false,\"face_centered\":false,\"mouth_shape_score\":0.0},\"audio\":{\"airflow_score\":0.0,\"pitch_stability_score\":0.0},\"success_trigger\":false}. Short history: []. Return compact JSON only.","output":"{\"coach_message\":\"Center your face first, then we will tune the mouth shape.\",\"diagnosis\":\"The coach cannot see a centered lower face, so mouth feedback would be unreliable.\",\"overlay_cues\":[],\"active_step\":\"align_face\",\"agent_trace\":[{\"step\":\"Observe\",\"action\":\"read_state\",\"detail\":\"No centered face is visible; mouth and audio scores are near zero.\"},{\"step\":\"Diagnose\",\"action\":\"no_face\",\"detail\":\"The blocker is sensor alignment, not whistle technique.\"},{\"step\":\"Plan\",\"action\":\"center_face\",\"detail\":\"Ask for a stable camera view before coaching lips or airflow.\"},{\"step\":\"Act\",\"action\":\"coach_message\",\"detail\":\"Center your face first, then we will tune the mouth shape.\"}],\"next_drill\":\"center_face\",\"difficulty_adjustment\":\"easier\",\"success_trigger\":false}"}
+{"input":"You are Whistle Coach. Current practice_state JSON: {\"state\":\"mouth_too_open\",\"active_step\":\"small_opening\",\"face\":{\"face_visible\":true,\"face_centered\":true,\"mouth_opening_ratio\":0.44,\"lip_roundness_score\":0.61,\"jaw_stability_score\":0.38,\"mouth_symmetry_score\":0.82,\"mouth_shape_score\":0.45},\"audio\":{\"airflow_score\":0.12,\"pitch_stability_score\":0.0},\"success_trigger\":false}. Short history: [{\"state\":\"no_face\"}]. Return compact JSON only.","output":"{\"coach_message\":\"Make the opening smaller and let your jaw float instead of dropping.\",\"diagnosis\":\"The lips are visible but the aperture is too large for a narrow whistle jet.\",\"overlay_cues\":[{\"type\":\"mouth_opening\",\"direction\":\"smaller\",\"label\":\"Smaller opening\"}],\"active_step\":\"small_opening\",\"agent_trace\":[{\"step\":\"Observe\",\"action\":\"read_state\",\"detail\":\"Mouth opening is high and jaw stability is low.\"},{\"step\":\"Diagnose\",\"action\":\"mouth_too_open\",\"detail\":\"A wide aperture spreads the air stream before tone can form.\"},{\"step\":\"Plan\",\"action\":\"small_opening_hold\",\"detail\":\"Coach one small adjustment: reduce opening without clenching.\"},{\"step\":\"Act\",\"action\":\"coach_message\",\"detail\":\"Make the opening smaller and let your jaw float instead of dropping.\"}],\"next_drill\":\"small_opening_hold\",\"difficulty_adjustment\":\"easier\",\"success_trigger\":false}"}
+{"input":"You are Whistle Coach. Current practice_state JSON: {\"state\":\"not_rounded\",\"active_step\":\"round_lips\",\"face\":{\"face_visible\":true,\"face_centered\":true,\"mouth_opening_ratio\":0.18,\"lip_roundness_score\":0.31,\"jaw_stability_score\":0.76,\"mouth_symmetry_score\":0.85,\"mouth_shape_score\":0.48},\"audio\":{\"airflow_score\":0.05,\"pitch_stability_score\":0.0},\"success_trigger\":false}. Short history: [{\"state\":\"mouth_too_open\"}]. Return compact JSON only.","output":"{\"coach_message\":\"Pull both lip corners inward like a tiny 'u', but keep the opening relaxed.\",\"diagnosis\":\"The opening is small enough, but the lips are not rounded enough to focus airflow.\",\"overlay_cues\":[{\"type\":\"lip_corners\",\"direction\":\"inward\",\"label\":\"Rounder lips\"}],\"active_step\":\"round_lips\",\"agent_trace\":[{\"step\":\"Observe\",\"action\":\"read_state\",\"detail\":\"Opening is controlled, roundness is low, and tone is absent.\"},{\"step\":\"Diagnose\",\"action\":\"not_rounded\",\"detail\":\"The air has no focused lip tunnel yet.\"},{\"step\":\"Plan\",\"action\":\"lip_rounding\",\"detail\":\"Keep the aperture small while moving the corners inward.\"},{\"step\":\"Act\",\"action\":\"coach_message\",\"detail\":\"Pull both lip corners inward like a tiny 'u', but keep the opening relaxed.\"}],\"next_drill\":\"lip_rounding\",\"difficulty_adjustment\":\"hold\",\"success_trigger\":false}"}
+{"input":"You are Whistle Coach. Current practice_state JSON: {\"state\":\"asymmetric_mouth\",\"active_step\":\"center_mouth\",\"face\":{\"face_visible\":true,\"face_centered\":true,\"mouth_opening_ratio\":0.17,\"lip_roundness_score\":0.68,\"jaw_stability_score\":0.73,\"mouth_symmetry_score\":0.41,\"mouth_shape_score\":0.53},\"audio\":{\"airflow_score\":0.22,\"pitch_stability_score\":0.0},\"success_trigger\":false}. Short history: [{\"state\":\"not_rounded\"}]. Return compact JSON only.","output":"{\"coach_message\":\"Level the two mouth corners, then blow through the center line.\",\"diagnosis\":\"Lip roundness is improving, but asymmetric corners push the air stream sideways.\",\"overlay_cues\":[{\"type\":\"symmetry\",\"direction\":\"level\",\"label\":\"Level corners\"}],\"active_step\":\"center_mouth\",\"agent_trace\":[{\"step\":\"Observe\",\"action\":\"read_state\",\"detail\":\"Roundness is acceptable but mouth symmetry is low.\"},{\"step\":\"Diagnose\",\"action\":\"asymmetric_mouth\",\"detail\":\"The air stream is likely off center.\"},{\"step\":\"Plan\",\"action\":\"corner_leveling\",\"detail\":\"Stabilize both corners before adding more airflow.\"},{\"step\":\"Act\",\"action\":\"coach_message\",\"detail\":\"Level the two mouth corners, then blow through the center line.\"}],\"next_drill\":\"corner_leveling\",\"difficulty_adjustment\":\"hold\",\"success_trigger\":false}"}
+{"input":"You are Whistle Coach. Current practice_state JSON: {\"state\":\"mouth_ready_no_airflow\",\"active_step\":\"gentle_airflow\",\"face\":{\"face_visible\":true,\"face_centered\":true,\"mouth_opening_ratio\":0.15,\"lip_roundness_score\":0.77,\"jaw_stability_score\":0.81,\"mouth_symmetry_score\":0.86,\"mouth_shape_score\":0.78},\"audio\":{\"airflow_score\":0.08,\"pitch_stability_score\":0.0},\"success_trigger\":false}. Short history: [{\"state\":\"asymmetric_mouth\"}]. Return compact JSON only.","output":"{\"coach_message\":\"Nice shape. Add a soft, steady breath without changing your lips.\",\"diagnosis\":\"The mouth shape is ready, but there is not enough detected airflow to create tone.\",\"overlay_cues\":[{\"type\":\"air_stream\",\"direction\":\"gentle\",\"label\":\"Gentle breath\"}],\"active_step\":\"gentle_airflow\",\"agent_trace\":[{\"step\":\"Observe\",\"action\":\"read_state\",\"detail\":\"Mouth score is high and airflow is low.\"},{\"step\":\"Diagnose\",\"action\":\"mouth_ready_no_airflow\",\"detail\":\"The next blocker is breath initiation, not lip shape.\"},{\"step\":\"Plan\",\"action\":\"gentle_airflow\",\"detail\":\"Ask for a soft steady exhale while preserving shape.\"},{\"step\":\"Act\",\"action\":\"coach_message\",\"detail\":\"Nice shape. Add a soft, steady breath without changing your lips.\"}],\"next_drill\":\"gentle_airflow\",\"difficulty_adjustment\":\"hold\",\"success_trigger\":false}"}
+{"input":"You are Whistle Coach. Current practice_state JSON: {\"state\":\"airflow_no_tone\",\"active_step\":\"narrow_air_stream\",\"face\":{\"face_visible\":true,\"face_centered\":true,\"mouth_opening_ratio\":0.16,\"lip_roundness_score\":0.72,\"jaw_stability_score\":0.8,\"mouth_symmetry_score\":0.88,\"mouth_shape_score\":0.76},\"audio\":{\"airflow_score\":0.68,\"pitch_stability_score\":0.18,\"peak_frequency_hz\":0},\"success_trigger\":false}. Short history: [{\"state\":\"mouth_ready_no_airflow\"},{\"state\":\"airflow_no_tone\"}]. Return compact JSON only.","output":"{\"coach_message\":\"You have airflow; make it thinner, like threading it through a pinhole.\",\"diagnosis\":\"Airflow is strong enough, but it is too broad or noisy to lock into a stable pitch.\",\"overlay_cues\":[{\"type\":\"air_stream\",\"direction\":\"narrower\",\"label\":\"Narrower air\"}],\"active_step\":\"narrow_air_stream\",\"agent_trace\":[{\"step\":\"Observe\",\"action\":\"read_state\",\"detail\":\"Airflow is high while pitch stability remains low.\"},{\"step\":\"Diagnose\",\"action\":\"airflow_no_tone\",\"detail\":\"The breath exists but is not focused into tone.\"},{\"step\":\"Plan\",\"action\":\"narrow_air_stream\",\"detail\":\"Reduce the air channel instead of blowing harder.\"},{\"step\":\"Act\",\"action\":\"coach_message\",\"detail\":\"You have airflow; make it thinner, like threading it through a pinhole.\"}],\"next_drill\":\"narrow_air_stream\",\"difficulty_adjustment\":\"hold\",\"success_trigger\":false}"}
+{"input":"You are Whistle Coach. Current practice_state JSON: {\"state\":\"tone_starting\",\"active_step\":\"hold_tone\",\"face\":{\"face_visible\":true,\"face_centered\":true,\"mouth_opening_ratio\":0.15,\"lip_roundness_score\":0.78,\"jaw_stability_score\":0.82,\"mouth_symmetry_score\":0.9,\"mouth_shape_score\":0.83},\"audio\":{\"airflow_score\":0.62,\"pitch_stability_score\":0.64,\"peak_frequency_hz\":1260,\"stable_duration_ms\":900},\"success_trigger\":false}. Short history: [{\"state\":\"airflow_no_tone\"},{\"state\":\"tone_starting\"}]. Return compact JSON only.","output":"{\"coach_message\":\"That is the tone. Freeze the shape and hold it for one more second.\",\"diagnosis\":\"A whistle tone has started, but the hold time is not long enough for success.\",\"overlay_cues\":[{\"type\":\"success\",\"direction\":\"hold\",\"label\":\"Hold tone\"}],\"active_step\":\"hold_tone\",\"agent_trace\":[{\"step\":\"Observe\",\"action\":\"read_state\",\"detail\":\"Pitch is present and stable for under two seconds.\"},{\"step\":\"Diagnose\",\"action\":\"tone_starting\",\"detail\":\"The skill is emerging; changing shape now would break it.\"},{\"step\":\"Plan\",\"action\":\"steady_tone_hold\",\"detail\":\"Reinforce stillness and duration rather than new corrections.\"},{\"step\":\"Act\",\"action\":\"coach_message\",\"detail\":\"That is the tone. Freeze the shape and hold it for one more second.\"}],\"next_drill\":\"steady_tone_hold\",\"difficulty_adjustment\":\"harder\",\"success_trigger\":false}"}
+{"input":"You are Whistle Coach. Current practice_state JSON: {\"state\":\"stable_whistle\",\"active_step\":\"record_melody\",\"face\":{\"face_visible\":true,\"face_centered\":true,\"mouth_opening_ratio\":0.15,\"lip_roundness_score\":0.78,\"jaw_stability_score\":0.84,\"mouth_symmetry_score\":0.9,\"mouth_shape_score\":0.83},\"audio\":{\"airflow_score\":0.64,\"pitch_stability_score\":0.82,\"peak_frequency_hz\":1760,\"stable_duration_ms\":2400},\"success_trigger\":true}. Short history: [{\"state\":\"airflow_no_tone\"},{\"state\":\"tone_starting\"},{\"state\":\"stable_whistle\"}]. Return compact JSON only.","output":"{\"coach_message\":\"Great, keep it steady while I turn that whistle into a tiny melody.\",\"diagnosis\":\"The mouth shape, airflow, pitch stability, and hold duration meet the success condition.\",\"overlay_cues\":[{\"type\":\"success\",\"direction\":\"hold\",\"label\":\"Melody ready\"}],\"active_step\":\"record_melody\",\"agent_trace\":[{\"step\":\"Observe\",\"action\":\"read_state\",\"detail\":\"Stable pitch has held for more than two seconds.\"},{\"step\":\"Diagnose\",\"action\":\"stable_whistle\",\"detail\":\"The user reached the target whistle condition.\"},{\"step\":\"Plan\",\"action\":\"record_melody\",\"detail\":\"Capture the pitch contour as the reward artifact.\"},{\"step\":\"Act\",\"action\":\"coach_message\",\"detail\":\"Great, keep it steady while I turn that whistle into a tiny melody.\"}],\"next_drill\":\"record_melody\",\"difficulty_adjustment\":\"complete\",\"success_trigger\":true}"}

data/sample_coach_states.jsonl

@@ -0,0 +1,4 @@
+{"state":"no_face","active_step":"align_face","face":{"face_visible":false,"face_centered":false,"mouth_shape_score":0.0},"audio":{"airflow_score":0.0,"pitch_stability_score":0.0},"success_trigger":false}
+{"state":"not_rounded","active_step":"round_lips","face":{"face_visible":true,"face_centered":true,"mouth_opening_ratio":0.18,"lip_roundness_score":0.31,"mouth_shape_score":0.48},"audio":{"airflow_score":0.05,"pitch_stability_score":0.0},"success_trigger":false}
+{"state":"airflow_no_tone","active_step":"narrow_air_stream","face":{"face_visible":true,"face_centered":true,"mouth_opening_ratio":0.16,"lip_roundness_score":0.71,"mouth_shape_score":0.76},"audio":{"airflow_score":0.68,"pitch_stability_score":0.18,"peak_frequency_hz":0},"success_trigger":false}
+{"state":"stable_whistle","active_step":"record_melody","face":{"face_visible":true,"face_centered":true,"mouth_opening_ratio":0.15,"lip_roundness_score":0.78,"mouth_shape_score":0.83},"audio":{"airflow_score":0.64,"pitch_stability_score":0.82,"peak_frequency_hz":1760,"stable_duration_ms":2400},"success_trigger":true}

frontend/audio_features.js

@@ -0,0 +1,41 @@
+window.WhistleCoach = window.WhistleCoach || {};
+
+window.WhistleCoach.AudioFeatures = (() => {
+  const clamp = (value, minimum = 0, maximum = 1) =>
+    Math.min(maximum, Math.max(minimum, value));
+
+  function toFeaturePayload(audio, stableDurationMs = 0) {
+    return {
+      rms_volume: Number(audio?.rms || 0),
+      airflow_score: Number(audio?.airflow || 0),
+      peak_frequency_hz: Number(audio?.peakFrequency || 0),
+      pitch_stability_score: Number(audio?.tone || 0),
+      stable_duration_ms: Math.round(stableDurationMs || 0),
+    };
+  }
+
+  function classifyAudio(features) {
+    if (features.airflow_score < 0.32) return "no_airflow";
+    if (features.pitch_stability_score < 0.58) return "airflow_no_tone";
+    if (features.stable_duration_ms >= 2000) return "stable_whistle";
+    return "tone_starting";
+  }
+
+  function pitchToMidi(frequencyHz) {
+    if (!frequencyHz || frequencyHz <= 0) return null;
+    return Math.round(69 + 12 * Math.log2(frequencyHz / 440));
+  }
+
+  function midiToName(midi) {
+    if (midi === null) return "";
+    const names = ["C", "C#", "D", "D#", "E", "F", "F#", "G", "G#", "A", "A#", "B"];
+    return `${names[((midi % 12) + 12) % 12]}${Math.floor(midi / 12) - 1}`;
+  }
+
+  return {
+    toFeaturePayload,
+    classifyAudio,
+    pitchToMidi,
+    midiToName,
+  };
+})();

frontend/face_features.js

@@ -0,0 +1,47 @@
+window.WhistleCoach = window.WhistleCoach || {};
+
+window.WhistleCoach.FaceFeatures = (() => {
+  const clamp = (value, minimum = 0, maximum = 1) =>
+    Math.min(maximum, Math.max(minimum, value));
+
+  function toFeaturePayload(face) {
+    return {
+      face_visible: Boolean(face?.visible),
+      face_centered: Boolean(face?.centered),
+      mouth_opening_ratio: Number(face?.openingRatio || 0),
+      lip_roundness_score: Number(face?.puckerScore || 0),
+      upper_lip_lift_score: Number(face?.upperLipLiftScore || 0),
+      jaw_stability_score: Number(face?.jawScore || 0),
+      mouth_symmetry_score: Number(face?.symmetry || 0),
+      mouth_shape_score: Number(face?.score || 0),
+    };
+  }
+
+  function classifyMouthShape(features) {
+    if (!features.face_visible || !features.face_centered) return "no_face";
+    if (features.mouth_opening_ratio > 0.34 || features.jaw_stability_score < 0.45) {
+      return "mouth_too_open";
+    }
+    if (features.lip_roundness_score < 0.52) return "not_rounded";
+    if (features.mouth_symmetry_score < 0.58) return "asymmetric_mouth";
+    if (features.mouth_shape_score >= 0.62) return "mouth_ready";
+    return "adjust_mouth";
+  }
+
+  function smoothFeature(previous, next, alpha = 0.28) {
+    if (!previous) return next;
+    const output = { ...next };
+    for (const [key, value] of Object.entries(next)) {
+      if (typeof value === "number") {
+        output[key] = clamp(previous[key] * (1 - alpha) + value * alpha);
+      }
+    }
+    return output;
+  }
+
+  return {
+    toFeaturePayload,
+    classifyMouthShape,
+    smoothFeature,
+  };
+})();

frontend/index.html

@@ -0,0 +1,122 @@
+<main id="whistle-coach-app" class="whistle-app">
+  <header class="wc-header">
+    <div class="brand-lockup">
+      <div class="brand-mark" aria-hidden="true">
+        <svg viewBox="0 0 64 64" role="img">
+          <path d="M15 36c7-10 18-15 33-12" fill="none" stroke="currentColor" stroke-width="6" stroke-linecap="round"/>
+          <path d="M16 47c10-8 22-10 35-6" fill="none" stroke="currentColor" stroke-width="6" stroke-linecap="round" opacity=".58"/>
+          <circle cx="13" cy="29" r="5" fill="currentColor"/>
+        </svg>
+      </div>
+      <div>
+        <h1 style="color:#17213a">Whistle Coach <span>🌱</span></h1>
+        <p style="color:#52607d">Audio-first AI coach for your first whistle</p>
+      </div>
+    </div>
+  </header>
+
+  <section class="wc-layout" aria-label="Whistle Coach live practice">
+    <aside class="left-rail">
+      <section class="side-card flow-card">
+        <p class="card-kicker">🌱 BEGINNER FLOW</p>
+        <ol class="flow-list">
+          <li class="done"><span>1</span>Relax & posture</li>
+          <li class="done"><span>2</span>Round your lips</li>
+          <li class="done"><span>3</span>Small opening</li>
+          <li class="active"><span>4</span>Gentle airflow</li>
+          <li><span>5</span>Find tiny whistle</li>
+          <li><span>6</span>Hold a steady tone</li>
+          <li><span>7</span>Play a simple melody</li>
+        </ol>
+        <div class="steps-progress"><strong>4 / 7 steps</strong><span><i></i></span></div>
+      </section>
+
+      <section class="side-card journey-card">
+        <p class="card-kicker">🌱 YOUR WHISTLE JOURNEY</p>
+        <div class="journey-row">
+          <div class="progress-ring"><strong id="garden-growth">0%</strong></div>
+          <div>
+            <strong id="journey-title">You’re growing!</strong>
+            <p id="coach-message" aria-live="polite">Your flowers grow each time you hold a whistle.</p>
+          </div>
+          <div class="plant-pot" aria-hidden="true" data-growth-stage="seed">
+            <span class="plant-stem"></span>
+            <span class="plant-leaf plant-leaf-left"></span>
+            <span class="plant-leaf plant-leaf-right"></span>
+            <span class="plant-flower"></span>
+            <span class="plant-soil"></span>
+          </div>
+        </div>
+      </section>
+    </aside>
+
+    <section class="center-stage">
+      <article id="camera-stage" class="camera-card" data-feedback="red" tabindex="0" aria-label="Start live whistle practice">
+        <video id="practice-video" autoplay muted playsinline aria-label="Live webcam preview"></video>
+        <div id="camera-placeholder" class="camera-placeholder">
+          <div class="start-panel">
+            <div class="placeholder-face" aria-hidden="true"></div>
+            <strong>Start practice</strong>
+            <span>Put your mouth in the dotted oval, round your lips, then blow gently.</span>
+            <button id="center-start-practice" class="center-start-button" type="button">Start</button>
+          </div>
+        </div>
+        <canvas id="mouth-overlay" aria-hidden="true"></canvas>
+        <canvas id="garden-canvas" aria-hidden="true"></canvas>
+        <div class="live-guide" aria-hidden="true">
+          <strong>Put your mouth in the oval</strong>
+          <span>Round your lips, keep the opening small, then blow softly.</span>
+        </div>
+
+        <span id="session-state" class="live-chip" data-state="idle"><i></i><span class="session-copy">Ready</span></span>
+        <div id="coach-card" class="coach-bubble" data-state="idle"><span>🌱</span><strong id="hero-feedback">Ready for live practice</strong></div>
+        <div id="permission-note" class="permission-note">Camera and microphone stay in your browser.</div>
+      </article>
+    </section>
+
+    <aside class="right-rail">
+      <section class="listening-panel">
+        <div class="panel-heading"><span>▮▮</span><div><strong>AI LISTENING PANEL</strong><p>Audio is the core signal</p></div></div>
+
+        <section id="airflow-indicator" class="indicator-card green" data-state="red">
+          <div class="indicator-topline"><div class="indicator-name">≋ <span>Airflow</span></div><strong class="indicator-score"><span>0</span><small>/100</small></strong></div>
+          <div class="score-track"><span class="score-fill"></span></div>
+          <p class="indicator-detail">Waiting for microphone</p>
+        </section>
+
+        <section id="whistle-indicator" class="indicator-card orange" data-state="red">
+          <div class="indicator-topline"><div class="indicator-name">✧ <span>Whistle confidence (AST)</span></div><strong class="indicator-score"><span>0</span><small>/100</small></strong></div>
+          <div class="score-track"><span class="score-fill"></span></div>
+          <p class="indicator-detail">MIT AST listens for whistle-like sound.</p>
+        </section>
+
+        <section id="tone-indicator" class="indicator-card purple" data-state="red">
+          <div class="indicator-topline"><div class="indicator-name">♫ <span>Pitch detected (F0)</span></div><strong class="indicator-score"><span>0</span><small></small></strong></div>
+          <div class="score-track"><span class="score-fill"></span></div>
+          <p class="indicator-detail">librosa.pyin waits for F0.</p>
+        </section>
+
+        <section id="stability-indicator" class="indicator-card blue" data-state="red">
+          <div class="indicator-topline"><div class="indicator-name">≋ <span>Stability</span></div><strong class="indicator-score"><span>0</span><small>/100</small></strong></div>
+          <div class="score-track"><span class="score-fill"></span></div>
+          <p class="indicator-detail">Keep airflow steady.</p>
+        </section>
+
+        <p id="technical-status" class="technical-status">Detection loads when live practice begins.</p>
+      </section>
+    </aside>
+  </section>
+
+  <section id="mouth-indicator" class="indicator-card hidden-meter" data-state="red" aria-hidden="true">
+    <div class="indicator-topline"><div class="indicator-name"><span>Mouth shape</span></div><strong class="indicator-score"><span>0</span><small>/100</small></strong></div>
+    <div class="score-track"><span class="score-fill"></span></div>
+    <p class="indicator-detail">Waiting for a face</p>
+  </section>
+
+  <code id="practice-state-json" hidden>{"state":"idle"}</code>
+  <ol id="coach-trace-list" hidden></ol>
+  <span id="garden-growth-stage" hidden>0%</span>
+  <span id="garden-growth-fill" hidden></span>
+  <span id="garden-plants" hidden>0</span>
+  <span id="garden-streak" hidden>0.0</span>
+</main>

frontend/overlay_renderer.js

@@ -0,0 +1,86 @@
+window.WhistleCoach = window.WhistleCoach || {};
+
+window.WhistleCoach.OverlayRenderer = (() => {
+  function overlayCuesForState(practiceState) {
+    const state = practiceState?.state || "idle";
+    if (state === "mouth_too_open") {
+      return [{ type: "mouth_opening", direction: "smaller", label: "Smaller opening" }];
+    }
+    if (state === "not_rounded") {
+      return [{ type: "lip_corners", direction: "inward", label: "Rounder" }];
+    }
+    if (state === "asymmetric_mouth") {
+      return [{ type: "symmetry", direction: "level", label: "Level corners" }];
+    }
+    if (state === "airflow_no_tone") {
+      return [{ type: "air_stream", direction: "narrower", label: "Narrower air" }];
+    }
+    if (state === "stable_whistle") {
+      return [{ type: "success", direction: "hold", label: "Hold tone" }];
+    }
+    return [];
+  }
+
+  function messageForState(practiceState) {
+    const state = practiceState?.state || "idle";
+    const messages = {
+      idle: "Ready when you are.",
+      no_face: "Please face the camera and center your mouth.",
+      mouth_too_open: "Make the opening smaller and relax your jaw.",
+      not_rounded: "Pull both lip corners inward, like saying 'u'.",
+      asymmetric_mouth: "Keep both lip corners level and centered.",
+      adjust_mouth: "Make the opening smaller and rounder.",
+      mouth_ready_no_airflow: "Good mouth shape. Now blow gently.",
+      airflow_no_tone: "You are close. Make the air stream narrower.",
+      tone_starting: "Nice. Hold the tone steady.",
+      stable_whistle: "Great! You made a stable whistle.",
+    };
+    return messages[state] || messages.idle;
+  }
+
+  function buildPracticeState(faceFeatures, audioFeatures) {
+    let state = "idle";
+    let activeStep = "start";
+
+    if (!faceFeatures.face_visible || !faceFeatures.face_centered) {
+      state = "no_face";
+      activeStep = "align_face";
+    } else if (faceFeatures.mouth_opening_ratio > 0.34 || faceFeatures.jaw_stability_score < 0.45) {
+      state = "mouth_too_open";
+      activeStep = "small_opening";
+    } else if (faceFeatures.lip_roundness_score < 0.52) {
+      state = "not_rounded";
+      activeStep = "round_lips";
+    } else if (faceFeatures.mouth_symmetry_score < 0.58) {
+      state = "asymmetric_mouth";
+      activeStep = "center_mouth";
+    } else if (audioFeatures.airflow_score < 0.32) {
+      state = "mouth_ready_no_airflow";
+      activeStep = "gentle_airflow";
+    } else if (audioFeatures.pitch_stability_score < 0.58) {
+      state = "airflow_no_tone";
+      activeStep = "narrow_air_stream";
+    } else if (audioFeatures.stable_duration_ms < 2000) {
+      state = "tone_starting";
+      activeStep = "hold_tone";
+    } else {
+      state = "stable_whistle";
+      activeStep = "record_melody";
+    }
+
+    return {
+      state,
+      active_step: activeStep,
+      face: faceFeatures,
+      audio: audioFeatures,
+      overlay_cues: overlayCuesForState({ state }),
+      success_trigger: state === "stable_whistle",
+    };
+  }
+
+  return {
+    overlayCuesForState,
+    messageForState,
+    buildPracticeState,
+  };
+})();

frontend/style.css

@@ -0,0 +1,472 @@
+:root {
+  --ink: #17213a;
+  --muted: #3f4b64;
+  --line: #e3e7f1;
+  --purple: #6b4df6;
+  --purple-soft: #efeaff;
+  --green: #48b95e;
+  --green-soft: #e8f8ea;
+  --orange: #ff7a34;
+  --blue: #4387f4;
+  --panel: rgba(255,255,255,.92);
+  --shadow: 0 18px 45px rgba(74, 61, 128, .12);
+  font-family: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+}
+
+html,
+body,
+gradio-app,
+.gradio-container,
+.main,
+.wrap,
+.contain {
+  background: #fbfcff !important;
+}
+
+html,
+body {
+  min-height: 100%;
+  margin: 0;
+  color: var(--ink);
+}
+
+.gradio-container {
+  max-width: none !important;
+  min-height: 100vh !important;
+  padding: 0 !important;
+}
+
+footer,
+.footer {
+  display: none !important;
+}
+
+.whistle-app,
+.whistle-app * {
+  box-sizing: border-box;
+}
+.whistle-app {
+  --wc-page-pad: clamp(16px, 1.65vw, 30px);
+  --wc-gap: clamp(14px, 1.15vw, 22px);
+  width: 100%;
+  max-width: none;
+  min-height: 100vh;
+  margin: 0;
+  display: grid;
+  grid-template-rows: auto 1fr;
+  color: var(--ink) !important;
+  padding: var(--wc-page-pad);
+  overflow: visible;
+  background: radial-gradient(circle at 18% 8%, rgba(126, 96, 255, .10), transparent 27%), radial-gradient(circle at 86% 18%, rgba(77, 185, 94, .10), transparent 26%), #fbfcff;
+}
+
+.wc-header { width: min(100%, 1800px); margin: 0 auto clamp(18px, 2vh, 28px); display: flex; justify-content: flex-start; align-items: center; gap: 22px; }
+.brand-lockup { display: flex; align-items: center; gap: 18px; min-width: 0; }
+.brand-mark { width: 72px; height: 72px; display: grid; place-items: center; border-radius: 20px; background: linear-gradient(145deg, #8c6bff, #5945e8); color: #121c33; box-shadow: 0 18px 32px rgba(91, 69, 232, .28); }
+.brand-mark svg { width: 42px; height: 42px; }
+.brand-lockup h1 { color: var(--ink); margin: 0 0 4px; font-size: 30px; line-height: 1.05; letter-spacing: 0; }
+.brand-lockup p { margin: 0; color: #38435c !important; font-size: 17px; font-weight: 650; }
+.wc-layout { width: min(100%, 1800px); margin: 0 auto; display: grid; grid-template-columns: minmax(250px, .78fr) minmax(460px, 1.75fr) minmax(270px, .86fr); gap: var(--wc-gap); align-items: stretch; min-height: 0; overflow: visible; }
+.left-rail, .right-rail { min-width: 0; display: grid; gap: 16px; align-content: start; overflow: visible; padding-bottom: 4px; }
+.center-stage { min-width: 0; overflow: visible; }
+.side-card, .listening-panel, .garden-panel { color: var(--ink); border: 1px solid var(--line); border-radius: 22px; background: var(--panel); box-shadow: var(--shadow); }
+.whistle-app .side-card,
+.whistle-app .listening-panel,
+.whistle-app .garden-panel {
+  opacity: 1 !important;
+}
+.side-card h2,
+.side-card strong,
+.side-card p,
+.side-card li,
+.listening-panel strong,
+.listening-panel p,
+.indicator-name,
+.indicator-score,
+.garden-panel h3,
+.garden-panel strong,
+.garden-panel small {
+  opacity: 1 !important;
+}
+.side-card h2,
+.panel-heading strong,
+.indicator-name,
+.garden-panel h3 {
+  color: var(--ink) !important;
+}
+.whistle-app .card-kicker,
+.whistle-app .panel-heading strong,
+.whistle-app .indicator-name,
+.whistle-app .indicator-name span,
+.whistle-app .indicator-score,
+.whistle-app .journey-row strong,
+.whistle-app .steps-progress strong {
+  color: #111a33 !important;
+  opacity: 1 !important;
+}
+.whistle-app .indicator-card .indicator-topline,
+.whistle-app .indicator-card .indicator-topline * {
+  opacity: 1 !important;
+}
+.side-card p,
+.flow-list li,
+.panel-heading p,
+.indicator-detail,
+.technical-status,
+.garden-step,
+.melody-card {
+  color: #36425c !important;
+}
+.side-card { padding: clamp(18px, 1.4vw, 24px) clamp(16px, 1.25vw, 22px); }
+.current-card { background: linear-gradient(145deg, rgba(246,241,255,.96), rgba(255,255,255,.94)); }
+.card-kicker { margin: 0 0 18px; font-size: 13px; font-weight: 900; letter-spacing: .08em; color: #17213a; }
+.current-card h2 { margin: 0 0 12px; font-size: 22px; color: #111a33 !important; letter-spacing: 0; }
+.step-copy { margin: 0 0 18px; font-size: 18px; line-height: 1.45; color: #344061 !important; }
+.focus-chip { display: inline-flex; align-items: center; gap: 8px; padding: 10px 15px; border-radius: 999px; background: #e7ddff; color: #5a3ce7 !important; font-weight: 900; }
+.flow-list { list-style: none; padding: 0; margin: 0; display: grid; gap: 7px; }
+.flow-list li { min-height: 31px; display: grid; grid-template-columns: 28px 1fr 20px; align-items: center; gap: 10px; color: #36425c; font-weight: 800; border-radius: 15px; padding: 3px 7px; }
+.flow-list li span { width: 25px; height: 25px; display: grid; place-items: center; border-radius: 50%; background: #f0f2f6; color: #1b243a; font-size: 13px; font-weight: 900; }
+.flow-list li.done::after { content: "✓"; width: 22px; height: 22px; display: grid; place-items: center; border-radius: 50%; background: #ddf4e3; color: #38a750; }
+.flow-list li.active { background: #ebe4ff; color: #5a3ce7 !important; }
+.flow-list li.active span { background: var(--purple); color: white; }
+.flow-list li:not(.done):not(.active)::after { content: ""; width: 12px; height: 12px; border: 2px solid #9faabd; border-radius: 50%; justify-self: center; }
+.steps-progress { display: flex; align-items: center; gap: 16px; margin-top: 18px; color: #35415a; }
+.steps-progress span { flex: 1; height: 7px; background: #e7e9ef; border-radius: 999px; overflow: hidden; }
+.steps-progress i { display: block; width: 57%; height: 100%; background: var(--purple); border-radius: inherit; }
+.journey-row { display: grid; grid-template-columns: minmax(68px, 86px) minmax(0, 1fr) 56px; align-items: center; gap: 14px; }
+.progress-ring { width: 76px; height: 76px; border-radius: 50%; display: grid; place-items: center; background: conic-gradient(var(--green) 0deg, var(--green) 0deg, #e9edf3 0deg); border: 9px solid #eef1f5; color: var(--green); font-size: 20px; transition: background .3s ease; }
+.journey-row p { margin: 8px 0 0; line-height: 1.45; color: #35415a; font-weight: 750; }
+.plant-pot {
+  --stem-growth: .08;
+  --leaf-growth: .1;
+  --leaf-opacity: 0;
+  --flower-growth: 0;
+  --flower-opacity: 0;
+  position: relative;
+  width: 58px;
+  height: 76px;
+  justify-self: center;
+}
+.plant-stem {
+  position: absolute;
+  left: 50%;
+  bottom: 20px;
+  width: 8px;
+  height: 50px;
+  border-radius: 999px;
+  background: linear-gradient(#93dd45, #3aa85d);
+  transform: translateX(-50%) scaleY(var(--stem-growth));
+  transform-origin: bottom;
+  transition: transform .35s ease;
+}
+.plant-leaf {
+  position: absolute;
+  left: 50%;
+  bottom: 39px;
+  width: 30px;
+  height: 17px;
+  border-radius: 999px 0 999px 0;
+  background: linear-gradient(135deg, #afe85b, #58bd43);
+  opacity: var(--leaf-opacity);
+  transition: opacity .25s ease, transform .35s ease;
+}
+.plant-leaf-left {
+  transform: translateX(-95%) rotate(200deg) scale(var(--leaf-growth));
+  transform-origin: right center;
+}
+.plant-leaf-right {
+  transform: translateX(-6%) rotate(-20deg) scale(var(--leaf-growth));
+  transform-origin: left center;
+}
+.plant-flower {
+  position: absolute;
+  left: 50%;
+  top: 1px;
+  width: 30px;
+  height: 30px;
+  opacity: var(--flower-opacity);
+  transform: translateX(-50%) scale(var(--flower-growth));
+  transition: opacity .25s ease, transform .35s ease;
+}
+.plant-flower::before {
+  content: "";
+  position: absolute;
+  inset: 0;
+  border-radius: 50%;
+  background:
+    radial-gradient(circle at 50% 50%, #8d5b20 0 18%, transparent 19%),
+    radial-gradient(ellipse at 50% 8%, #ffd95f 0 24%, transparent 25%),
+    radial-gradient(ellipse at 92% 50%, #ff8a65 0 24%, transparent 25%),
+    radial-gradient(ellipse at 50% 92%, #f05a9b 0 24%, transparent 25%),
+    radial-gradient(ellipse at 8% 50%, #87d8ff 0 24%, transparent 25%);
+}
+.plant-soil {
+  position: absolute;
+  left: 50%;
+  bottom: 3px;
+  width: 42px;
+  height: 24px;
+  border-radius: 24px 24px 6px 6px;
+  background: linear-gradient(145deg, #8f594f, #65443f);
+  transform: translateX(-50%);
+  box-shadow: inset 0 3px 8px rgba(255, 255, 255, .12);
+}
+.plant-pot[data-growth-stage="bloom"] .plant-flower {
+  filter: drop-shadow(0 5px 8px rgba(240, 90, 155, .25));
+}
+
+.camera-card { position: relative; height: clamp(500px, calc(100vh - 170px), 720px); min-height: 0; overflow: hidden; border-radius: 22px; border: 1px solid #d7dce7; background: linear-gradient(145deg, #f8fbff, #eaf4ef); box-shadow: var(--shadow); cursor: pointer; }
+@supports (height: 100svh) {
+  .camera-card { height: clamp(500px, calc(100svh - 170px), 720px); }
+}
+.camera-card::before {
+  content: "";
+  position: absolute;
+  inset: 0;
+  z-index: 2;
+  pointer-events: none;
+  opacity: 0;
+  background:
+    linear-gradient(180deg, rgba(255, 255, 255, .22), rgba(246, 252, 248, .1)),
+    radial-gradient(circle at 50% 58%, rgba(255, 255, 255, .2), transparent 42%);
+  transition: opacity .25s ease;
+}
+.camera-card:focus-visible { outline: 4px solid rgba(107, 77, 246, .32); outline-offset: 4px; }
+.camera-card[data-active="true"] { cursor: default; }
+.camera-card[data-active="true"]::before { opacity: 1; }
+#practice-video, #mouth-overlay, #garden-canvas, .camera-placeholder { position: absolute; inset: 0; width: 100%; height: 100%; }
+#practice-video { z-index: 0; object-fit: cover; filter: grayscale(.82) contrast(.96) brightness(1.12); display: none; transform: scaleX(-1); }
+#mouth-overlay, #garden-canvas { pointer-events: none; z-index: 4; }
+#garden-canvas { opacity: 0; transition: opacity .35s ease; }
+#garden-canvas[data-visible="true"] { opacity: .94; }
+.camera-placeholder { display: grid; place-items: center; color: #14203a; background: linear-gradient(135deg, #f7f9ff, #e9f7ef); z-index: 3; text-align: center; padding: clamp(24px, 4vh, 42px) clamp(20px, 3vw, 34px) 88px; }
+.start-panel { width: min(520px, 92%); display: grid; justify-items: center; gap: clamp(10px, 1.4vh, 14px); }
+.placeholder-face {
+  position: relative;
+  width: min(190px, 42vw);
+  height: min(220px, 30vh);
+  min-height: 150px;
+  border-radius: 48% 48% 42% 42%;
+  background: linear-gradient(#dce4ee, #9baabd);
+  opacity: .92;
+  filter: grayscale(1);
+}
+.placeholder-face::after {
+  content: "";
+  position: absolute;
+  left: 50%;
+  top: 67%;
+  width: 76px;
+  height: 46px;
+  border: 4px dashed rgba(107, 77, 246, .72);
+  border-radius: 50%;
+  transform: translate(-50%, -50%);
+}
+.whistle-app .camera-placeholder .start-panel strong { color: #111a33 !important; font-size: clamp(28px, 4vw, 44px); line-height: 1.05; font-weight: 950; text-shadow: none !important; }
+.whistle-app .camera-placeholder .start-panel span { max-width: 460px; color: #33405a !important; font-size: clamp(16px, 1.35vw, 18px); line-height: 1.45; font-weight: 800; text-shadow: none !important; }
+.center-start-button {
+  min-width: 148px;
+  height: 54px;
+  margin-top: 8px;
+  border: 0;
+  border-radius: 999px;
+  color: white;
+  background: linear-gradient(145deg, #7f62ff, #4d38db);
+  box-shadow: 0 14px 28px rgba(0, 0, 0, .28);
+  font: inherit;
+  font-size: 18px;
+  font-weight: 900;
+  cursor: pointer;
+}
+.center-start-button:focus-visible { outline: 3px solid rgba(255, 255, 255, .62); outline-offset: 3px; }
+.live-guide {
+  position: absolute;
+  left: 50%;
+  bottom: 28px;
+  z-index: 8;
+  width: min(480px, calc(100% - 48px));
+  padding: 14px 18px;
+  border: 1px solid rgba(107, 77, 246, .24);
+  border-radius: 18px;
+  background: rgba(255, 255, 255, .98);
+  color: #101a31 !important;
+  text-align: center;
+  pointer-events: none;
+  opacity: 0;
+  transform: translateX(-50%) translateY(8px);
+  transition: opacity .2s ease, transform .2s ease;
+  backdrop-filter: blur(12px);
+  box-shadow: 0 16px 32px rgba(34, 43, 72, .18);
+  text-shadow: none !important;
+}
+.whistle-app .camera-card .live-guide,
+.whistle-app .camera-card .live-guide * {
+  color: #101a31 !important;
+  text-shadow: none !important;
+}
+.whistle-app .camera-card .live-guide strong {
+  display: block;
+  font-size: 20px;
+  line-height: 1.2;
+  font-weight: 950;
+}
+.whistle-app .camera-card .live-guide span {
+  display: block;
+  margin-top: 6px;
+  color: #24304a !important;
+  line-height: 1.35;
+  font-weight: 850;
+}
+.camera-card[data-active="true"] .live-guide {
+  opacity: 1;
+  transform: translateX(-50%) translateY(0);
+}
+.camera-card[data-mouth-in-oval="true"] .live-guide {
+  opacity: 0 !important;
+  transform: translateX(-50%) translateY(8px);
+  visibility: hidden !important;
+}
+.live-chip { position: absolute; top: 24px; left: 24px; z-index: 8; display: inline-flex; align-items: center; gap: 8px; height: 38px; padding: 0 14px; border-radius: 999px; background: rgba(255,255,255,.9); color: #14203a; font-weight: 900; backdrop-filter: blur(16px); box-shadow: 0 10px 24px rgba(31, 42, 68, .14); }
+.live-chip i { width: 13px; height: 13px; border-radius: 50%; background: #32d45d; box-shadow: 0 0 0 7px rgba(50,212,93,.16); }
+.camera-rule { position: absolute; top: 24px; right: 20px; z-index: 8; padding: 10px 13px; border-radius: 999px; background: rgba(30,30,30,.62); color: white; font-weight: 800; backdrop-filter: blur(12px); }
+.camera-rule b { display: inline-grid; place-items: center; width: 20px; height: 20px; margin-left: 9px; border: 1px solid rgba(255,255,255,.75); border-radius: 50%; font-size: 13px; }
+.coach-bubble { position: absolute; z-index: 8; top: 48px; left: 50%; transform: translateX(-50%); width: min(560px, 68%); min-height: 105px; padding: 20px 30px; display: grid; place-items: center; text-align: center; border-radius: 28px; border: 3px solid #84e295; background: linear-gradient(145deg, rgba(39,119,49,.94), rgba(23,92,42,.94)); color: white; font-size: 26px; line-height: 1.28; box-shadow: 0 14px 28px rgba(21, 52, 30, .28); text-shadow: 0 1px 2px rgba(0,0,0,.22); }
+.coach-bubble span { position: absolute; top: -20px; font-size: 31px; }
+.permission-note { position: absolute; left: 24px; bottom: 138px; z-index: 7; color: #17213a; background: rgba(255,255,255,.9); border: 1px solid rgba(107,77,246,.16); padding: 9px 12px; border-radius: 14px; font-weight: 800; box-shadow: 0 10px 24px rgba(31,42,68,.1); }
+.camera-card:not([data-active="true"]) .permission-note { left: 50%; bottom: 22px; width: min(520px, calc(100% - 48px)); transform: translateX(-50%); text-align: center; }
+.mouth-tips { position: absolute; z-index: 8; left: 28px; top: 285px; display: grid; gap: 14px; }
+.mouth-tips span { width: 170px; height: 54px; display: flex; align-items: center; gap: 12px; padding: 0 16px; border-radius: 14px; background: rgba(255,255,255,.22); color: white; border: 1px solid rgba(255,255,255,.58); font-weight: 800; backdrop-filter: blur(10px); }
+.mouth-tips i { width: 23px; height: 23px; border-radius: 50%; border: 3px solid #7de785; box-shadow: inset 0 0 0 4px rgba(92,83,221,.58); }
+.mouth-tips .face-dot::after { content: ""; display: block; width: 5px; height: 5px; margin: 6px auto; border-radius: 50%; background: #7de785; }
+.practice-dock { position: absolute; z-index: 9; left: 9%; right: 9%; bottom: 22px; min-height: 108px; display: grid; grid-template-columns: 88px minmax(170px, 1fr) 300px 146px 58px; align-items: center; gap: 16px; padding: 18px 20px; border-radius: 25px; background: rgba(20,22,27,.80); color: white; backdrop-filter: blur(16px); box-shadow: 0 18px 35px rgba(0,0,0,.35); }
+.mic-orb { width: 76px; height: 76px; border: 10px solid rgba(117,95,236,.42); border-radius: 50%; background: linear-gradient(145deg, #8565ff, #5d43de); color: white; font-size: 33px; cursor: pointer; }
+.dock-copy strong { display: block; font-size: 22px; margin-bottom: 8px; }
+.dock-copy p { margin: 0; color: rgba(255,255,255,.95); font-weight: 650; }
+.pulse-wave { height: 44px; display: flex; align-items: center; justify-content: center; gap: 5px; }
+.pulse-wave span { width: 4px; height: 12px; border-radius: 999px; background: #7b5dff; animation: pulse 1s ease-in-out infinite; }
+.pulse-wave span:nth-child(2n) { height: 24px; animation-delay: .1s; }
+.pulse-wave span:nth-child(3n) { height: 34px; animation-delay: .2s; }
+.rest-pill, .reset-button { height: 50px; border: 1px solid rgba(255,255,255,.72); border-radius: 999px; background: rgba(255,255,255,.09); color: white; font-size: 15px; font-weight: 900; cursor: pointer; }
+.rest-pill:disabled { opacity: .55; cursor: not-allowed; }
+.reset-button { width: 58px; font-size: 12px; }
+@keyframes pulse { 50% { transform: scaleY(1.8); opacity: .72; } }
+
+.listening-panel { padding: clamp(18px, 1.35vw, 22px) clamp(14px, 1vw, 16px); display: grid; gap: 12px; align-content: start; overflow: visible; }
+.panel-heading { display: flex; gap: 12px; align-items: start; padding: 0 10px 8px; }
+.panel-heading > span { color: var(--purple); font-weight: 900; }
+.panel-heading strong { letter-spacing: .06em; }
+.panel-heading p { margin: 7px 0 0; color: #35415a; font-weight: 700; }
+.indicator-card { padding: 20px 18px; border: 1px solid var(--line); border-radius: 15px; background: white; box-shadow: 0 8px 20px rgba(32,41,75,.04); }
+.indicator-topline { display: flex; justify-content: space-between; align-items: flex-start; gap: 14px; }
+.indicator-name { min-width: 0; display: flex; align-items: center; gap: 9px; font-size: clamp(17px, 1.25vw, 18px); font-weight: 900; }
+.indicator-score { flex: 0 0 auto; font-size: clamp(21px, 1.6vw, 24px); color: var(--green); }
+.indicator-score small { font-size: 14px; color: #4b5871; margin-left: 3px; font-weight: 850; }
+.score-track { height: 12px; background: #e8ebf1; border-radius: 999px; overflow: hidden; margin: 18px 0 12px; }
+.score-fill { display: block; width: 0; height: 100%; border-radius: inherit; background: var(--green); transition: width .25s ease; }
+.indicator-card.orange .indicator-score { color: var(--orange); }
+.indicator-card.orange .score-fill { background: var(--orange); }
+.indicator-card.purple .indicator-score { color: var(--purple); }
+.indicator-card.purple .score-fill { background: var(--purple); }
+.indicator-card.blue .indicator-score { color: var(--blue); }
+.indicator-card.blue .score-fill { background: var(--blue); }
+.indicator-detail { margin: 0; color: #303c56; line-height: 1.45; min-height: 22px; font-weight: 750; }
+.stack-note { margin-top: 8px; display: grid; grid-template-columns: 42px 1fr; gap: 12px; align-items: center; padding: 17px; border: 1px solid #e3dcff; border-radius: 16px; background: #f7f3ff; color: #33405a; line-height: 1.45; font-weight: 700; }
+.stack-note span { width: 36px; height: 36px; display: grid; place-items: center; border-radius: 50%; background: #efe8ff; color: var(--purple); }
+.stack-note p, .technical-status { margin: 0; }
+.technical-status { color: #46526a; padding: 0 10px; font-size: 13px; font-weight: 650; }
+
+.garden-panel { margin-top: 18px; padding: 25px 30px; max-width: calc(100% - 366px); margin-left: 342px; }
+.garden-panel h3 { margin: 0 0 20px; font-size: 15px; letter-spacing: .06em; }
+.garden-line { position: relative; display: grid; grid-template-columns: repeat(5, 1fr); gap: 20px; align-items: end; }
+.garden-line::before { content: ""; position: absolute; left: 7%; right: 7%; top: 52px; height: 3px; background: #cbd2dd; }
+.garden-step { position: relative; z-index: 1; display: grid; justify-items: center; gap: 8px; color: #414c64; }
+.garden-step i { font-style: normal; font-size: 42px; filter: grayscale(.55); opacity: .7; }
+.garden-step small { font-size: 15px; font-weight: 800; }
+.garden-step .soil { width: 15px; height: 15px; display: grid; place-items: center; border-radius: 50%; color: transparent; background: #c5ccd7; border: 3px solid white; box-shadow: 0 0 0 2px #c5ccd7; order: 2; }
+.garden-step.reached i, .garden-step.active i { filter: none; opacity: 1; }
+.garden-step.reached .soil, .garden-step.active .soil { background: var(--green); box-shadow: 0 0 0 2px var(--green); }
+.melody-card { margin-top: 16px; display: flex; align-items: center; gap: 14px; color: #34405a; font-weight: 700; }
+.melody-card button, .melody-card a { border: 1px solid var(--line); background: white; color: var(--purple); border-radius: 999px; padding: 8px 14px; font-weight: 900; text-decoration: none; }
+.melody-card button:disabled { color: #667187; }
+.hidden-meter { display: none !important; }
+
+@media (max-width: 1500px) {
+  .wc-layout {
+    grid-template-columns: minmax(240px, .72fr) minmax(440px, 1.58fr) minmax(260px, .82fr);
+  }
+  .flow-list li { grid-template-columns: 26px minmax(0, 1fr) 18px; }
+  .journey-row { grid-template-columns: 74px minmax(0, 1fr) 48px; gap: 12px; }
+  .progress-ring { width: 70px; height: 70px; font-size: 18px; }
+  .plant-pot { width: 50px; }
+  .indicator-card { padding: 18px 16px; }
+}
+
+@media (max-height: 760px) and (min-width: 901px) {
+  .whistle-app { --wc-page-pad: clamp(12px, 1.3vw, 22px); --wc-gap: clamp(12px, 1vw, 18px); }
+  .wc-header { margin-bottom: 14px; }
+  .brand-mark { width: 58px; height: 58px; border-radius: 17px; }
+  .brand-mark svg { width: 34px; height: 34px; }
+  .brand-lockup h1 { font-size: 25px; }
+  .brand-lockup p { font-size: 15px; }
+  .camera-card { height: clamp(430px, calc(100vh - 112px), 600px); }
+  .side-card { padding: 16px 15px; }
+  .flow-list { gap: 4px; }
+  .flow-list li { min-height: 28px; }
+  .listening-panel { padding: 16px 14px; gap: 10px; }
+  .indicator-card { padding: 16px 14px; }
+  .score-track { margin: 12px 0 10px; }
+}
+
+@media (max-width: 1280px) {
+  .wc-layout { grid-template-columns: minmax(260px, 300px) minmax(420px, 1fr); align-items: start; overflow-y: auto; }
+  .right-rail { grid-column: 1 / -1; }
+  .listening-panel { height: auto; min-height: auto; grid-template-columns: repeat(4, minmax(0, 1fr)); }
+  .panel-heading, .stack-note, .technical-status { grid-column: 1 / -1; }
+  .garden-panel { max-width: none; margin-left: 0; }
+  .camera-card { height: clamp(480px, calc(100vh - 160px), 680px); }
+}
+@media (max-width: 900px) {
+  .whistle-app {
+    height: auto;
+    min-height: 0;
+    max-height: none;
+    overflow: visible;
+    padding: 18px;
+  }
+  .wc-header, .wc-layout { display: grid; grid-template-columns: 1fr; }
+  .wc-layout { min-height: 0; align-items: start; overflow: visible; padding-bottom: 18px; }
+  .left-rail,
+  .right-rail,
+  .center-stage {
+    overflow: visible;
+  }
+  .brand-lockup { min-width: 0; }
+  .brand-mark { width: 60px; height: 60px; }
+  .camera-card { height: clamp(420px, 62vh, 540px); }
+  .camera-placeholder { padding-bottom: 82px; }
+  .practice-dock { left: 14px; right: 14px; grid-template-columns: 64px 1fr 112px; }
+  .pulse-wave, .reset-button { display: none; }
+  .mic-orb { width: 58px; height: 58px; border-width: 7px; font-size: 24px; }
+  .listening-panel { height: auto; overflow: visible; grid-template-columns: 1fr; }
+  .garden-line { gap: 6px; }
+}
+
+@media (max-width: 620px) {
+  .whistle-app { --wc-page-pad: 12px; }
+  .brand-lockup { gap: 12px; }
+  .brand-mark { width: 52px; height: 52px; border-radius: 15px; }
+  .brand-mark svg { width: 31px; height: 31px; }
+  .brand-lockup h1 { font-size: 24px; }
+  .brand-lockup p { font-size: 14px; }
+  .side-card,
+  .listening-panel { border-radius: 18px; }
+  .journey-row { grid-template-columns: 68px minmax(0, 1fr); }
+  .plant-pot { display: none; }
+  .camera-card { height: clamp(390px, 68vh, 500px); border-radius: 18px; }
+  .placeholder-face { width: min(150px, 48vw); height: min(176px, 28vh); }
+  .camera-card:not([data-active="true"]) .permission-note { width: calc(100% - 28px); bottom: 14px; }
+}
+
+@media (max-height: 760px) and (min-width: 901px) {
+  .camera-card { height: clamp(430px, calc(100vh - 112px), 600px); }
+}

notebooks/01_feature_schema_and_state_classifier.ipynb

@@ -0,0 +1,34 @@
+{
+  "cells": [
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "# Feature schema and state classifier\n",
+        "\n",
+        "This notebook documents the V1 feature schema used by Whistle Coach: lower-face features from MediaPipe, audio features from WebAudio, and the rule-based practice state classifier."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "from backend.state_classifier import classify_practice_state\n",
+        "\n",
+        "sample = {\n",
+        "    'face': {'face_visible': True, 'face_centered': True, 'mouth_opening_ratio': 0.16, 'lip_roundness_score': 0.72, 'jaw_stability_score': 0.8, 'mouth_symmetry_score': 0.9, 'mouth_shape_score': 0.78},\n",
+        "    'audio': {'airflow_score': 0.65, 'pitch_stability_score': 0.2, 'peak_frequency_hz': 0, 'stable_duration_ms': 0},\n",
+        "}\n",
+        "classify_practice_state(sample)\n"
+      ]
+    }
+  ],
+  "metadata": {
+    "kernelspec": {"display_name": "Python 3", "language": "python", "name": "python3"},
+    "language_info": {"name": "python", "version": "3.10"}
+  },
+  "nbformat": 4,
+  "nbformat_minor": 5
+}

notebooks/02_build_coach_policy_dataset.ipynb

@@ -0,0 +1,32 @@
+{
+  "cells": [
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "# Build a coach policy dataset\n",
+        "\n",
+        "V1 uses base Nemotron plus a rule fallback. Later, this notebook can turn recorded `practice_state -> coach_response` pairs into a small supervised dataset for a LoRA coach policy."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "import json\n",
+        "from pathlib import Path\n",
+        "\n",
+        "rows = [json.loads(line) for line in Path('data/sample_coach_states.jsonl').read_text().splitlines()]\n",
+        "rows[:2]\n"
+      ]
+    }
+  ],
+  "metadata": {
+    "kernelspec": {"display_name": "Python 3", "language": "python", "name": "python3"},
+    "language_info": {"name": "python", "version": "3.10"}
+  },
+  "nbformat": 4,
+  "nbformat_minor": 5
+}

notebooks/03_whistle_pitch_to_melody.ipynb

@@ -0,0 +1,32 @@
+{
+  "cells": [
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "# Whistle pitch to melody\n",
+        "\n",
+        "This notebook sketches the pitch-contour-to-melody module. The app records a short stable whistle contour, quantizes it into notes, then writes a small WAV arrangement."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "from pathlib import Path\n",
+        "from backend.melody_generator import generate_melody_wav, quantize_pitch_contour\n",
+        "\n",
+        "contour = [{'time_ms': i * 120, 'frequency_hz': hz} for i, hz in enumerate([880, 900, 990, 990, 1175, 1175])]\n",
+        "quantize_pitch_contour(contour), generate_melody_wav(contour, Path('outputs/sample_melodies/notebook_demo.wav'))\n"
+      ]
+    }
+  ],
+  "metadata": {
+    "kernelspec": {"display_name": "Python 3", "language": "python", "name": "python3"},
+    "language_info": {"name": "python", "version": "3.10"}
+  },
+  "nbformat": 4,
+  "nbformat_minor": 5
+}

outputs/sample_melodies/.gitkeep

@@ -0,0 +1 @@
+

requirements.txt

@@ -0,0 +1,11 @@
+gradio
+spaces
+transformers
+torch
+torchaudio
+librosa
+numpy
+scipy
+soundfile
+mediapipe
+opencv-python

style.css

@@ -0,0 +1,1667 @@
+:root {
+  --wc-ink: #17263b;
+  --wc-muted: #657083;
+  --wc-cream: #fffaf0;
+  --wc-paper: #ffffff;
+  --wc-border: #eadfce;
+  --wc-red: #f05a4f;
+  --wc-red-soft: #fff0ed;
+  --wc-yellow: #f3b51b;
+  --wc-yellow-soft: #fff7d9;
+  --wc-green: #20a879;
+  --wc-green-soft: #e9f8f2;
+  --wc-blue: #62c9e8;
+  --wc-navy: #1c3150;
+  --wc-shadow: 0 20px 60px rgba(28, 49, 80, 0.12);
+}
+
+body,
+.gradio-container {
+  background:
+    radial-gradient(circle at 10% 3%, rgba(243, 181, 27, 0.18), transparent 28rem),
+    radial-gradient(circle at 92% 14%, rgba(98, 201, 232, 0.14), transparent 30rem),
+    radial-gradient(circle at 70% 100%, rgba(32, 168, 121, 0.12), transparent 30rem),
+    #f8f5ed !important;
+  color: var(--wc-ink);
+}
+
+.gradio-container,
+.main,
+.wrap {
+  max-width: none !important;
+  padding: 0 !important;
+}
+
+.whistle-app,
+.whistle-app * {
+  box-sizing: border-box;
+}
+
+.whistle-app {
+  width: 100%;
+  min-width: 1080px;
+  min-height: 100vh;
+  padding: 24px clamp(24px, 3vw, 48px) 18px;
+  color: var(--wc-ink);
+  font-family:
+    Inter, ui-rounded, "SF Pro Rounded", "Segoe UI", system-ui, -apple-system,
+    BlinkMacSystemFont, sans-serif;
+}
+
+.app-header {
+  width: min(1540px, 100%);
+  margin: 0 auto 18px;
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 24px;
+}
+
+.brand-lockup {
+  display: flex;
+  align-items: center;
+  gap: 15px;
+}
+
+.brand-mark {
+  width: 60px;
+  height: 60px;
+  display: grid;
+  place-items: center;
+  flex: 0 0 auto;
+  border-radius: 20px;
+  color: white;
+  background: linear-gradient(145deg, var(--wc-red), #ff875d);
+  box-shadow: 0 11px 26px rgba(240, 90, 79, 0.26);
+  transform: rotate(-3deg);
+}
+
+.brand-mark svg {
+  width: 40px;
+  height: 40px;
+}
+
+.eyebrow,
+.step-label {
+  margin: 0 0 3px;
+  color: var(--wc-red);
+  font-size: 0.7rem;
+  font-weight: 850;
+  letter-spacing: 0.13em;
+  text-transform: uppercase;
+}
+
+.app-header h1 {
+  margin: 0;
+  color: var(--wc-navy);
+  font-size: clamp(1.9rem, 2.6vw, 2.75rem);
+  font-weight: 900;
+  letter-spacing: -0.045em;
+  line-height: 1;
+}
+
+.subtitle {
+  margin: 7px 0 0;
+  color: var(--wc-muted);
+  font-size: 0.98rem;
+  font-weight: 650;
+}
+
+.controls {
+  display: flex;
+  align-items: center;
+  gap: 9px;
+  padding: 7px;
+  border: 1px solid var(--wc-border);
+  border-radius: 18px;
+  background: rgba(255, 255, 255, 0.84);
+  box-shadow: 0 8px 28px rgba(28, 49, 80, 0.06);
+  backdrop-filter: blur(12px);
+}
+
+.control-button {
+  min-height: 44px;
+  padding: 0 17px;
+  border: 0;
+  border-radius: 12px;
+  cursor: pointer;
+  font: inherit;
+  font-size: 0.88rem;
+  font-weight: 850;
+  transition:
+    transform 150ms ease,
+    box-shadow 150ms ease,
+    opacity 150ms ease;
+}
+
+.control-button:hover:not(:disabled) {
+  transform: translateY(-1px);
+}
+
+.control-button:focus-visible {
+  outline: 3px solid rgba(28, 49, 80, 0.22);
+  outline-offset: 2px;
+}
+
+.control-button:disabled {
+  cursor: not-allowed;
+  opacity: 0.45;
+}
+
+.control-button.primary {
+  color: white;
+  background: var(--wc-navy);
+  box-shadow: 0 7px 16px rgba(28, 49, 80, 0.2);
+}
+
+.control-button.secondary {
+  color: #9b342f;
+  background: var(--wc-red-soft);
+}
+
+.control-button.ghost {
+  color: var(--wc-navy);
+  background: transparent;
+}
+
+.workspace {
+  width: min(1540px, 100%);
+  margin: 0 auto;
+}
+
+.garden-workspace {
+  display: grid;
+  grid-template-columns: minmax(720px, 1fr) minmax(320px, 0.35fr);
+  gap: 18px;
+  align-items: stretch;
+}
+
+.panel {
+  min-width: 0;
+  padding: 18px;
+  border: 1px solid rgba(234, 223, 206, 0.96);
+  border-radius: 27px;
+  background: rgba(255, 255, 255, 0.92);
+  box-shadow: var(--wc-shadow);
+}
+
+.game-panel {
+  padding: 20px;
+}
+
+.side-stack {
+  display: grid;
+  gap: 18px;
+  grid-template-rows: auto auto;
+  align-content: start;
+}
+
+.panel-heading {
+  min-height: 50px;
+  margin-bottom: 13px;
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 12px;
+}
+
+.panel-heading.compact {
+  min-height: auto;
+  justify-content: flex-start;
+}
+
+.panel-heading h2 {
+  margin: 0;
+  color: var(--wc-navy);
+  font-size: 1.22rem;
+  font-weight: 900;
+  letter-spacing: -0.025em;
+}
+
+.session-pill {
+  display: inline-flex;
+  align-items: center;
+  gap: 7px;
+  padding: 7px 10px;
+  border-radius: 999px;
+  color: var(--wc-muted);
+  background: #f3f1ec;
+  font-size: 0.73rem;
+  font-weight: 850;
+}
+
+.session-dot {
+  width: 8px;
+  height: 8px;
+  border-radius: 50%;
+  background: #a6a39c;
+}
+
+.session-pill[data-state="loading"] {
+  color: #876307;
+  background: var(--wc-yellow-soft);
+}
+
+.session-pill[data-state="loading"] .session-dot {
+  background: var(--wc-yellow);
+  animation: wc-pulse 1s infinite;
+}
+
+.session-pill[data-state="live"] {
+  color: #116d50;
+  background: var(--wc-green-soft);
+}
+
+.session-pill[data-state="live"] .session-dot {
+  background: var(--wc-green);
+  box-shadow: 0 0 0 4px rgba(32, 168, 121, 0.15);
+}
+
+.session-pill[data-state="error"] {
+  color: #9b342f;
+  background: var(--wc-red-soft);
+}
+
+.session-pill[data-state="error"] .session-dot {
+  background: var(--wc-red);
+}
+
+@keyframes wc-pulse {
+  50% {
+    opacity: 0.35;
+  }
+}
+
+.camera-stage {
+  position: relative;
+  aspect-ratio: 16 / 9;
+  overflow: hidden;
+  border: 5px solid var(--wc-red);
+  border-radius: 25px;
+  background:
+    linear-gradient(180deg, rgba(23, 38, 59, 0.12), rgba(23, 38, 59, 0.42)),
+    #182536;
+  box-shadow: inset 0 -100px 90px rgba(5, 18, 20, 0.3);
+  transition:
+    border-color 180ms ease,
+    box-shadow 180ms ease;
+}
+
+.camera-stage[data-feedback="yellow"] {
+  border-color: var(--wc-yellow);
+  box-shadow:
+    0 0 0 5px rgba(243, 181, 27, 0.13),
+    inset 0 -100px 90px rgba(5, 18, 20, 0.25);
+}
+
+.camera-stage[data-feedback="green"] {
+  border-color: var(--wc-green);
+  box-shadow:
+    0 0 0 5px rgba(32, 168, 121, 0.14),
+    inset 0 -100px 90px rgba(5, 18, 20, 0.18);
+}
+
+#camera-placeholder,
+#practice-video,
+#mouth-overlay,
+#garden-canvas {
+  position: absolute;
+  inset: 0;
+  width: 100%;
+  height: 100%;
+}
+
+#camera-placeholder {
+  z-index: 1;
+  display: grid;
+  place-items: center;
+  padding: clamp(22px, 4vw, 52px);
+  overflow: hidden;
+}
+
+.start-screen {
+  background:
+    radial-gradient(circle at 28% 28%, rgba(98, 201, 232, 0.28), transparent 13rem),
+    radial-gradient(circle at 77% 78%, rgba(32, 168, 121, 0.3), transparent 14rem),
+    linear-gradient(135deg, #182536, #263a58 52%, #203143);
+  color: white;
+}
+
+.start-orbit {
+  position: absolute;
+  inset: 16%;
+  border: 1px dashed rgba(255, 255, 255, 0.24);
+  border-radius: 999px;
+  animation: wc-orbit 9s linear infinite;
+}
+
+.start-orbit span {
+  position: absolute;
+  width: 16px;
+  height: 16px;
+  border-radius: 50%;
+  background: #98f1c5;
+  box-shadow: 0 0 28px rgba(152, 241, 197, 0.8);
+}
+
+.start-orbit span:nth-child(1) {
+  top: -8px;
+  left: 48%;
+}
+
+.start-orbit span:nth-child(2) {
+  right: 8%;
+  bottom: 14%;
+  background: #ffe27a;
+}
+
+.start-orbit span:nth-child(3) {
+  left: 9%;
+  bottom: 19%;
+  background: #8ad7ff;
+}
+
+.start-copy {
+  position: relative;
+  z-index: 2;
+  width: min(560px, 88%);
+  padding: 28px 30px;
+  border: 1px solid rgba(255, 255, 255, 0.28);
+  border-radius: 26px;
+  background: rgba(23, 38, 59, 0.66);
+  box-shadow: 0 18px 60px rgba(0, 0, 0, 0.22);
+  text-align: center;
+  backdrop-filter: blur(13px);
+}
+
+.start-kicker {
+  margin: 0 0 8px;
+  color: #98f1c5;
+  font-size: 0.72rem;
+  font-weight: 900;
+  letter-spacing: 0.14em;
+  text-transform: uppercase;
+}
+
+.start-copy h3 {
+  margin: 0;
+  font-size: clamp(1.4rem, 3vw, 2.35rem);
+  font-weight: 950;
+  letter-spacing: -0.045em;
+  line-height: 1.04;
+}
+
+.start-copy p:last-child {
+  margin: 13px auto 0;
+  max-width: 440px;
+  color: rgba(255, 255, 255, 0.76);
+  font-size: 0.84rem;
+  font-weight: 650;
+  line-height: 1.55;
+}
+
+@keyframes wc-orbit {
+  to {
+    transform: rotate(360deg);
+  }
+}
+
+#practice-video {
+  z-index: 2;
+  display: none;
+  object-fit: cover;
+  transform: scaleX(-1);
+}
+
+#mouth-overlay {
+  z-index: 4;
+  pointer-events: none;
+}
+
+#garden-canvas {
+  z-index: 3;
+  pointer-events: none;
+}
+
+.permission-note {
+  position: absolute;
+  z-index: 7;
+  left: 50%;
+  bottom: 92px;
+  width: min(88%, 430px);
+  padding: 13px 16px;
+  border: 1px solid rgba(255, 255, 255, 0.32);
+  border-radius: 16px;
+  color: white;
+  background: rgba(23, 38, 59, 0.82);
+  box-shadow: 0 8px 24px rgba(0, 0, 0, 0.18);
+  text-align: center;
+  transform: translateX(-50%);
+  backdrop-filter: blur(9px);
+}
+
+.permission-note strong,
+.permission-note span {
+  display: block;
+}
+
+.permission-note strong {
+  margin-bottom: 3px;
+  font-size: 0.82rem;
+}
+
+.permission-note span {
+  color: rgba(255, 255, 255, 0.78);
+  font-size: 0.72rem;
+}
+
+.target-legend {
+  position: absolute;
+  z-index: 6;
+  top: 13px;
+  left: 13px;
+  display: flex;
+  align-items: center;
+  gap: 7px;
+  padding: 7px 10px;
+  border-radius: 999px;
+  color: white;
+  background: rgba(23, 38, 59, 0.66);
+  font-size: 0.68rem;
+  font-weight: 800;
+  backdrop-filter: blur(8px);
+}
+
+.legend-swatch {
+  width: 18px;
+  height: 9px;
+  border: 2px dashed white;
+  border-radius: 50%;
+}
+
+.garden-hud {
+  position: absolute;
+  z-index: 6;
+  right: 14px;
+  bottom: 14px;
+  width: min(310px, calc(100% - 28px));
+  padding: 13px;
+  border: 1px solid rgba(255, 255, 255, 0.35);
+  border-radius: 18px;
+  color: white;
+  background: rgba(23, 38, 59, 0.72);
+  box-shadow: 0 10px 30px rgba(0, 0, 0, 0.2);
+  backdrop-filter: blur(10px);
+}
+
+.garden-hud > div:first-child,
+.garden-stats {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 12px;
+}
+
+.garden-hud-label,
+.garden-stats {
+  color: rgba(255, 255, 255, 0.72);
+  font-size: 0.69rem;
+  font-weight: 750;
+}
+
+#garden-growth {
+  color: #98f1c5;
+  font-size: 1.25rem;
+  font-weight: 950;
+}
+
+.garden-track {
+  height: 8px;
+  margin: 10px 0 9px;
+  overflow: hidden;
+  border-radius: 999px;
+  background: rgba(255, 255, 255, 0.18);
+}
+
+#garden-growth-fill {
+  display: block;
+  width: 0;
+  height: 100%;
+  border-radius: inherit;
+  background: linear-gradient(90deg, #7ee7a7, #ffe27a, #ff9d6e);
+  transition: width 120ms linear;
+}
+
+.garden-stats strong {
+  color: white;
+  font-size: 0.82rem;
+}
+
+.camera-hint {
+  margin: 13px 3px 0;
+  color: var(--wc-muted);
+  font-size: 0.78rem;
+  line-height: 1.55;
+}
+
+.status-panel,
+.coach-panel {
+  display: flex;
+  flex-direction: column;
+}
+
+.coach-panel {
+  order: -1;
+}
+
+.indicator-stack {
+  display: grid;
+  gap: 11px;
+}
+
+.indicator-card {
+  --indicator: var(--wc-red);
+  --indicator-soft: var(--wc-red-soft);
+  padding: 14px;
+  border: 1px solid color-mix(in srgb, var(--indicator) 24%, white);
+  border-radius: 17px;
+  background: var(--indicator-soft);
+  transition:
+    border-color 180ms ease,
+    background 180ms ease;
+}
+
+.indicator-card[data-state="yellow"] {
+  --indicator: var(--wc-yellow);
+  --indicator-soft: var(--wc-yellow-soft);
+}
+
+.indicator-card[data-state="green"] {
+  --indicator: var(--wc-green);
+  --indicator-soft: var(--wc-green-soft);
+}
+
+.indicator-topline,
+.indicator-name {
+  display: flex;
+  align-items: center;
+}
+
+.indicator-topline {
+  justify-content: space-between;
+  gap: 10px;
+}
+
+.indicator-name {
+  gap: 8px;
+  color: var(--wc-navy);
+  font-size: 0.81rem;
+  font-weight: 850;
+}
+
+.status-light {
+  width: 10px;
+  height: 10px;
+  border-radius: 50%;
+  background: var(--indicator);
+  box-shadow: 0 0 0 4px color-mix(in srgb, var(--indicator) 17%, transparent);
+}
+
+.indicator-score {
+  color: var(--indicator);
+  font-size: 1.12rem;
+  font-weight: 950;
+}
+
+.indicator-score small {
+  margin-left: 2px;
+  color: var(--wc-muted);
+  font-size: 0.6rem;
+  font-weight: 750;
+}
+
+.score-track {
+  height: 7px;
+  margin: 12px 0 9px;
+  overflow: hidden;
+  border-radius: 99px;
+  background: rgba(23, 38, 59, 0.09);
+}
+
+.score-fill {
+  display: block;
+  width: 0;
+  height: 100%;
+  border-radius: inherit;
+  background: var(--indicator);
+  transition: width 140ms linear;
+}
+
+.indicator-detail {
+  min-height: 1.1em;
+  margin: 0;
+  color: var(--wc-muted);
+  font-size: 0.68rem;
+  font-weight: 650;
+}
+
+.signal-note {
+  margin-top: 13px;
+  padding: 13px 14px;
+  border: 1px dashed #ded7ca;
+  border-radius: 15px;
+  background: #faf8f3;
+}
+
+.signal-note strong,
+.signal-note span {
+  display: block;
+}
+
+.signal-note strong {
+  margin-bottom: 3px;
+  color: var(--wc-navy);
+  font-size: 0.73rem;
+}
+
+.signal-note span {
+  color: var(--wc-muted);
+  font-size: 0.67rem;
+  line-height: 1.45;
+}
+
+.coach-card {
+  position: relative;
+  min-height: 150px;
+  padding: 20px 18px;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  gap: 14px;
+  overflow: hidden;
+  border-radius: 21px;
+  background:
+    radial-gradient(circle at 85% 12%, rgba(243, 181, 27, 0.32), transparent 5rem),
+    var(--wc-yellow-soft);
+  text-align: center;
+  transition: background 180ms ease;
+}
+
+.coach-card[data-state="red"] {
+  background:
+    radial-gradient(circle at 85% 12%, rgba(240, 90, 79, 0.2), transparent 5rem),
+    var(--wc-red-soft);
+}
+
+.coach-card[data-state="green"] {
+  background:
+    radial-gradient(circle at 85% 12%, rgba(32, 168, 121, 0.2), transparent 5rem),
+    var(--wc-green-soft);
+}
+
+.coach-face {
+  position: relative;
+  width: 60px;
+  height: 54px;
+  flex: 0 0 auto;
+  border: 3px solid var(--wc-navy);
+  border-radius: 48% 48% 44% 44%;
+  background: #ffd970;
+  box-shadow: 5px 6px 0 rgba(28, 49, 80, 0.11);
+  transform: rotate(-2deg);
+}
+
+.coach-eye {
+  position: absolute;
+  top: 19px;
+  width: 6px;
+  height: 7px;
+  border-radius: 50%;
+  background: var(--wc-navy);
+}
+
+.coach-eye.left {
+  left: 15px;
+}
+
+.coach-eye.right {
+  right: 15px;
+}
+
+.coach-mouth {
+  position: absolute;
+  left: 50%;
+  bottom: 10px;
+  width: 10px;
+  height: 8px;
+  border: 3px solid var(--wc-navy);
+  border-radius: 50%;
+  transform: translateX(-50%);
+}
+
+#coach-message {
+  max-width: 290px;
+  margin: 0;
+  color: var(--wc-navy);
+  font-size: clamp(0.98rem, 1.25vw, 1.16rem);
+  font-weight: 900;
+  line-height: 1.35;
+  letter-spacing: -0.02em;
+}
+
+.mini-guide {
+  margin-top: 13px;
+  padding: 15px;
+  border: 1px solid var(--wc-border);
+  border-radius: 18px;
+  background: #fcfbf8;
+}
+
+.mini-guide-title {
+  margin: 0 0 10px;
+  color: var(--wc-navy);
+  font-size: 0.74rem;
+  font-weight: 900;
+  text-transform: uppercase;
+  letter-spacing: 0.08em;
+}
+
+.mini-guide ol {
+  display: grid;
+  gap: 9px;
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+.mini-guide li {
+  display: flex;
+  align-items: center;
+  gap: 9px;
+  color: var(--wc-muted);
+  font-size: 0.73rem;
+  font-weight: 650;
+}
+
+.mini-guide li span {
+  width: 22px;
+  height: 22px;
+  display: grid;
+  place-items: center;
+  flex: 0 0 auto;
+  border-radius: 8px;
+  color: white;
+  background: var(--wc-navy);
+  font-size: 0.65rem;
+  font-weight: 850;
+}
+
+.technical-status {
+  margin: auto 3px 0;
+  padding-top: 13px;
+  color: var(--wc-muted);
+  font-size: 0.65rem;
+  line-height: 1.45;
+}
+
+.app-footer {
+  width: min(1540px, 100%);
+  margin: 14px auto 0;
+  color: #858a93;
+  font-size: 0.68rem;
+  text-align: center;
+}
+
+@media (max-width: 1220px) {
+  .whistle-app {
+    padding-inline: 20px;
+  }
+
+  .garden-workspace {
+    grid-template-columns: minmax(650px, 1fr) 310px;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .whistle-app *,
+  .whistle-app *::before,
+  .whistle-app *::after {
+    scroll-behavior: auto !important;
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.01ms !important;
+  }
+}
+
+/* Reference-style UI refresh: centered camera, left coach, right signal cards. */
+.whistle-app {
+  min-width: 1180px;
+  padding: 26px 34px 16px;
+  background: rgba(255, 255, 255, 0.72);
+}
+
+.app-header {
+  width: min(1500px, 100%);
+  margin-bottom: 18px;
+}
+
+.brand-mark {
+  border-radius: 16px;
+  background: linear-gradient(145deg, #5147ff, #6b5cff);
+  box-shadow: 0 14px 28px rgba(81, 71, 255, 0.22);
+  transform: none;
+}
+
+.eyebrow {
+  display: none;
+}
+
+.app-header h1 {
+  color: #121328;
+  font-size: clamp(2.2rem, 3vw, 3.3rem);
+}
+
+.subtitle {
+  color: #4f46e5;
+  font-size: 1.05rem;
+}
+
+.header-badges {
+  display: flex;
+  align-items: center;
+  gap: 14px;
+}
+
+.tech-badge,
+.about-badge {
+  min-height: 40px;
+  display: inline-flex;
+  align-items: center;
+  gap: 8px;
+  padding: 0 18px;
+  border: 1px solid rgba(226, 232, 240, 0.9);
+  border-radius: 999px;
+  color: #25283b;
+  background: rgba(255, 255, 255, 0.9);
+  box-shadow: 0 10px 30px rgba(17, 24, 39, 0.06);
+  font-size: 0.78rem;
+  font-weight: 850;
+}
+
+.about-badge::before {
+  content: "i";
+  width: 18px;
+  height: 18px;
+  display: grid;
+  place-items: center;
+  border: 2px solid currentColor;
+  border-radius: 50%;
+  font-size: 0.72rem;
+  font-weight: 950;
+}
+
+.coach-workspace {
+  display: grid;
+  grid-template-columns: 280px minmax(980px, 1fr);
+  gap: 18px;
+  align-items: stretch;
+}
+
+.coach-sidebar,
+.signal-sidebar {
+  min-width: 0;
+}
+
+.coach-sidebar {
+  display: flex;
+  flex-direction: column;
+  gap: 15px;
+  padding: 18px;
+}
+
+.camera-card {
+  min-width: 0;
+  position: relative;
+}
+
+.camera-stage {
+  border: 0;
+  border-radius: 26px;
+  background: #101827;
+  box-shadow:
+    0 22px 64px rgba(15, 23, 42, 0.16),
+    inset 0 -110px 90px rgba(5, 18, 20, 0.26);
+}
+
+.camera-stage[data-feedback="yellow"],
+.camera-stage[data-feedback="green"] {
+  border-color: transparent;
+}
+
+#mouth-overlay {
+  z-index: 5;
+}
+
+#garden-canvas {
+  z-index: 4;
+}
+
+.live-pill {
+  position: absolute;
+  z-index: 8;
+  top: 16px;
+  left: 16px;
+  color: white;
+  background: rgba(15, 23, 42, 0.78);
+  backdrop-filter: blur(12px);
+}
+
+.target-legend {
+  top: auto;
+  left: 18px;
+  bottom: 18px;
+  width: 210px;
+  border-radius: 14px;
+  background: rgba(15, 23, 42, 0.78);
+}
+
+.legend-swatch {
+  border-color: #32eb84;
+}
+
+.garden-hud {
+  right: 18px;
+  bottom: 18px;
+  width: 310px;
+  border-radius: 20px;
+  background: rgba(255, 255, 255, 0.83);
+  color: #121328;
+}
+
+.garden-hud-label,
+.garden-stats {
+  color: #5f6678;
+}
+
+#garden-growth-stage {
+  color: var(--wc-green);
+}
+
+.camera-hint {
+  position: absolute;
+  z-index: 8;
+  left: 50%;
+  bottom: 14px;
+  width: min(500px, 62%);
+  margin: 0;
+  padding: 10px 15px;
+  border-radius: 12px;
+  color: white;
+  background: rgba(15, 23, 42, 0.76);
+  text-align: center;
+  transform: translateX(-50%);
+  backdrop-filter: blur(10px);
+}
+
+.coach-card {
+  min-height: 116px;
+  padding: 16px;
+  flex-direction: row;
+  justify-content: flex-start;
+  text-align: left;
+  border: 1px solid rgba(34, 197, 94, 0.18);
+  background: #eafff0;
+}
+
+.coach-card[data-state="red"] {
+  background: #fff1ed;
+}
+
+.coach-card[data-state="green"] {
+  background: #eafff0;
+}
+
+.coach-face {
+  width: 42px;
+  height: 40px;
+  border-width: 2px;
+  border-radius: 16px;
+  background: #d8ffe4;
+  box-shadow: none;
+}
+
+.coach-eye {
+  top: 14px;
+}
+
+.coach-eye.left {
+  left: 10px;
+}
+
+.coach-eye.right {
+  right: 10px;
+}
+
+.coach-mouth {
+  bottom: 7px;
+}
+
+#coach-message {
+  font-size: 0.94rem;
+  line-height: 1.45;
+}
+
+.mini-guide {
+  margin-top: 0;
+  border-color: rgba(226, 232, 240, 0.9);
+  background: rgba(255, 255, 255, 0.82);
+}
+
+.mini-guide li {
+  padding: 8px 9px;
+  border-radius: 11px;
+  background: #f8fafc;
+}
+
+.mini-guide li span {
+  background: #dffbea;
+  color: #138a5a;
+}
+
+.progress-card {
+  display: flex;
+  align-items: center;
+  gap: 14px;
+  padding: 15px;
+  border: 1px solid rgba(226, 232, 240, 0.9);
+  border-radius: 18px;
+  background: rgba(255, 255, 255, 0.82);
+}
+
+.progress-ring {
+  width: 70px;
+  height: 70px;
+  display: grid;
+  place-items: center;
+  flex: 0 0 auto;
+  border: 8px solid #e6e8ff;
+  border-top-color: #5b50ff;
+  border-radius: 50%;
+}
+
+.progress-ring strong {
+  color: #4f46e5;
+  font-size: 1rem;
+  font-weight: 950;
+}
+
+.progress-card p:last-child {
+  margin: 3px 0 0;
+  color: var(--wc-muted);
+  font-size: 0.73rem;
+  line-height: 1.45;
+}
+
+.melody-card,
+.state-card,
+.trace-card {
+  padding: 15px;
+  border: 1px solid rgba(226, 232, 240, 0.9);
+  border-radius: 18px;
+  background: rgba(255, 255, 255, 0.82);
+}
+
+.melody-card p:nth-child(2),
+.state-card code {
+  margin: 3px 0 0;
+  color: var(--wc-muted);
+  font-size: 0.72rem;
+  line-height: 1.45;
+}
+
+.melody-download {
+  display: inline-flex;
+  margin-top: 10px;
+  padding: 9px 12px;
+  border-radius: 999px;
+  color: white;
+  background: linear-gradient(135deg, #554bff, #6b5cff);
+  font-size: 0.75rem;
+  font-weight: 900;
+  text-decoration: none;
+}
+
+.state-card code {
+  display: block;
+  white-space: pre-wrap;
+  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+}
+
+.trace-card ol {
+  display: grid;
+  gap: 9px;
+  margin: 10px 0 0;
+  padding: 0;
+  list-style: none;
+}
+
+.trace-card li {
+  display: grid;
+  gap: 3px;
+  padding: 10px 11px;
+  border: 1px solid rgba(148, 163, 184, 0.2);
+  border-radius: 14px;
+  background: rgba(248, 250, 252, 0.86);
+}
+
+.trace-card strong {
+  color: #334155;
+  font-size: 0.72rem;
+  font-weight: 950;
+  text-transform: uppercase;
+}
+
+.trace-card span {
+  color: var(--wc-muted);
+  font-size: 0.72rem;
+  line-height: 1.35;
+}
+
+.signal-sidebar {
+  display: flex;
+  flex-direction: column;
+  gap: 14px;
+}
+
+.indicator-stack {
+  gap: 14px;
+}
+
+.indicator-card {
+  padding: 18px;
+  border: 1px solid rgba(226, 232, 240, 0.86);
+  border-radius: 22px;
+  background: rgba(255, 255, 255, 0.78);
+  box-shadow: 0 18px 44px rgba(15, 23, 42, 0.1);
+  backdrop-filter: blur(12px);
+}
+
+.indicator-name {
+  font-size: 0.95rem;
+}
+
+.indicator-score {
+  font-size: 1.5rem;
+}
+
+.score-track {
+  height: 8px;
+  margin: 14px 0 10px;
+  background: linear-gradient(90deg, #2bd873, #ffe45e, #ff444a);
+}
+
+.score-fill {
+  background: rgba(255, 255, 255, 0.82);
+  box-shadow: -999px 0 0 999px var(--indicator);
+}
+
+.signal-note {
+  margin-top: 0;
+  background: rgba(255, 255, 255, 0.82);
+}
+
+.bottom-controls {
+  width: min(1120px, 100%);
+  margin: 20px auto 0;
+  display: grid;
+  grid-template-columns: 1fr 1fr 0.65fr;
+  gap: 18px;
+  padding: 0;
+  border: 0;
+  background: transparent;
+  box-shadow: none;
+}
+
+.bottom-controls .control-button {
+  min-height: 56px;
+  border-radius: 17px;
+  font-size: 1rem;
+}
+
+.bottom-controls .primary {
+  background: linear-gradient(135deg, #554bff, #6b5cff);
+}
+
+.bottom-controls .secondary {
+  color: white;
+  background: linear-gradient(135deg, #ff4048, #ff3038);
+}
+
+.bottom-controls .ghost {
+  color: #33384f;
+  background: white;
+  box-shadow: 0 14px 34px rgba(15, 23, 42, 0.08);
+}
+
+/* Game-like UI pass inspired by the provided reference. */
+.whistle-app {
+  background:
+    radial-gradient(circle at 50% 0%, rgba(107, 92, 255, 0.08), transparent 34rem),
+    #fbfaf8;
+}
+
+.coach-workspace {
+  grid-template-columns: 270px minmax(1040px, 1fr);
+}
+
+.camera-stage {
+  border: 7px solid rgba(255, 255, 255, 0.92);
+  border-radius: 30px;
+  background: #111;
+  box-shadow:
+    0 30px 72px rgba(21, 24, 40, 0.16),
+    0 0 0 1px rgba(20, 25, 38, 0.08);
+}
+
+.camera-stage[data-feedback="yellow"],
+.camera-stage[data-feedback="green"] {
+  box-shadow:
+    0 30px 72px rgba(21, 24, 40, 0.16),
+    0 0 0 1px rgba(20, 25, 38, 0.08);
+}
+
+#practice-video {
+  filter: grayscale(1) contrast(1.12) brightness(0.88);
+  transform: scaleX(-1);
+}
+
+#mouth-overlay,
+#garden-canvas {
+  mix-blend-mode: normal;
+}
+
+.target-legend {
+  bottom: auto;
+  top: 17px;
+  left: auto;
+  right: 18px;
+  width: auto;
+  min-width: 150px;
+  justify-content: center;
+  color: white;
+  background: rgba(14, 18, 26, 0.72);
+}
+
+.garden-hud,
+.compact-signals,
+.state-card {
+  display: none;
+}
+
+.camera-hint {
+  bottom: 138px;
+  width: min(520px, 58%);
+  background: rgba(15, 17, 24, 0.72);
+}
+
+.live-pill {
+  background: rgba(255, 255, 255, 0.86);
+  color: #111827;
+}
+
+.live-pill .session-dot {
+  background: #4ade80;
+}
+
+.action-sidebar {
+  display: flex;
+  flex-direction: column;
+  gap: 18px;
+}
+
+.action-stack {
+  display: grid;
+  gap: 18px;
+}
+
+.melody-action {
+  min-height: 122px;
+  display: grid;
+  grid-template-columns: 62px 1fr;
+  align-items: center;
+  gap: 18px;
+  padding: 22px;
+  border: 1px solid rgba(226, 232, 240, 0.9);
+  border-radius: 24px;
+  color: #182039;
+  background: rgba(255, 255, 255, 0.92);
+  box-shadow: 0 18px 48px rgba(20, 24, 40, 0.08);
+  text-align: left;
+  text-decoration: none;
+  font: inherit;
+}
+
+.melody-action strong {
+  font-size: 1.05rem;
+  font-weight: 900;
+}
+
+.melody-action small,
+.melody-action select {
+  grid-column: 2;
+  color: #71798b;
+  font-size: 0.73rem;
+}
+
+.melody-action select {
+  width: 100%;
+  margin-top: 8px;
+  padding: 8px 10px;
+  border: 1px solid #e5e7eb;
+  border-radius: 12px;
+  background: #f8fafc;
+  font-weight: 800;
+}
+
+.action-icon {
+  width: 62px;
+  height: 62px;
+  display: grid;
+  place-items: center;
+  border-radius: 50%;
+  font-size: 1.7rem;
+  font-weight: 950;
+}
+
+.record-action .action-icon {
+  color: #ff4052;
+  background: #ffe4e8;
+  box-shadow: inset 0 0 0 1px rgba(255, 64, 82, 0.25);
+}
+
+.style-action .action-icon {
+  color: #9656ff;
+  background: #efe5ff;
+}
+
+.generating-action .action-icon {
+  color: #615dff;
+  background: #e8e8ff;
+}
+
+.generating-action[data-active="true"] .action-icon {
+  animation: wc-pulse 0.8s infinite;
+}
+
+.generating-action[data-active="done"] .action-icon,
+.play-action .action-icon {
+  color: #20b970;
+  background: #ddfaeb;
+}
+
+.download-action .action-icon {
+  color: #228be6;
+  background: #e1f1ff;
+}
+
+.melody-action:disabled,
+.download-action[aria-disabled="true"] {
+  opacity: 0.58;
+  cursor: not-allowed;
+}
+
+.download-action.ready {
+  opacity: 1;
+}
+
+.signal-note {
+  display: none;
+}
+
+/* Mobile and compact pass: keep the game view usable on phones. */
+.whistle-app {
+  min-width: 0;
+  font-family:
+    "Avenir Next", Avenir, "DIN Alternate", "Arial Rounded MT Bold",
+    "Helvetica Neue", Arial, system-ui, sans-serif;
+  letter-spacing: 0.005em;
+}
+
+.app-header h1,
+.melody-action strong,
+.coach-card,
+.mini-guide,
+.control-button {
+  letter-spacing: 0.01em;
+}
+
+@media (max-width: 980px) {
+  body,
+  .gradio-container {
+    overflow-x: hidden !important;
+  }
+
+  .whistle-app {
+    width: 100%;
+    min-width: 0;
+    padding: 12px;
+  }
+
+  .app-header {
+    align-items: flex-start;
+    flex-direction: column;
+    gap: 12px;
+    margin-bottom: 12px;
+  }
+
+  .brand-lockup {
+    gap: 11px;
+  }
+
+  .brand-mark {
+    width: 46px;
+    height: 46px;
+    border-radius: 15px;
+  }
+
+  .brand-mark svg {
+    width: 31px;
+    height: 31px;
+  }
+
+  .app-header h1 {
+    font-size: 1.75rem;
+    letter-spacing: -0.035em;
+  }
+
+  .subtitle {
+    margin-top: 4px;
+    font-size: 0.84rem;
+  }
+
+  .header-badges {
+    width: 100%;
+    justify-content: flex-start;
+    gap: 8px;
+    overflow-x: auto;
+    padding-bottom: 2px;
+  }
+
+  .tech-badge,
+  .about-badge {
+    min-height: 34px;
+    flex: 0 0 auto;
+    padding: 0 12px;
+    border-radius: 999px;
+    font-size: 0.68rem;
+    white-space: nowrap;
+  }
+
+  .coach-workspace {
+    width: 100%;
+    min-width: 0;
+    display: grid;
+    grid-template-columns: minmax(0, 1fr);
+    gap: 12px;
+  }
+
+  .camera-card {
+    order: 1;
+    min-width: 0;
+  }
+
+  .coach-sidebar {
+    order: 2;
+    min-width: 0;
+    padding: 12px;
+    border-radius: 20px;
+  }
+
+  .action-sidebar {
+    order: 3;
+    min-width: 0;
+  }
+
+  .camera-stage {
+    width: 100%;
+    min-width: 0;
+    aspect-ratio: 9 / 12.8;
+    border-width: 4px;
+    border-radius: 22px;
+  }
+
+  .live-pill,
+  .target-legend {
+    top: 10px;
+    padding: 6px 9px;
+    border-radius: 12px;
+    font-size: 0.62rem;
+  }
+
+  .live-pill {
+    left: 10px;
+  }
+
+  .target-legend {
+    right: 10px;
+    min-width: 0;
+  }
+
+  .camera-hint {
+    bottom: 88px;
+    width: min(86%, 410px);
+    padding: 8px 10px;
+    border-radius: 12px;
+    font-size: 0.62rem;
+  }
+
+  .coach-card {
+    min-height: 96px;
+    padding: 16px;
+    border-radius: 18px;
+  }
+
+  #coach-message {
+    font-size: 0.84rem;
+  }
+
+  .mini-guide ol {
+    grid-template-columns: 1fr 1fr;
+    gap: 8px;
+  }
+
+  .progress-card,
+  .melody-card {
+    padding: 14px;
+    border-radius: 18px;
+  }
+
+  .action-stack {
+    display: grid;
+    grid-template-columns: repeat(5, minmax(86px, 1fr));
+    gap: 10px;
+    overflow-x: auto;
+    padding-bottom: 2px;
+  }
+
+  .melody-action {
+    min-height: 88px;
+    grid-template-columns: 1fr;
+    justify-items: center;
+    gap: 7px;
+    padding: 12px 10px;
+    border-radius: 18px;
+    text-align: center;
+  }
+
+  .action-icon {
+    width: 42px;
+    height: 42px;
+    font-size: 1.1rem;
+  }
+
+  .melody-action strong {
+    font-size: 0.72rem;
+  }
+
+  .melody-action small,
+  .melody-action select {
+    grid-column: 1;
+    margin-top: 0;
+    font-size: 0.58rem;
+  }
+
+  .bottom-controls {
+    position: sticky;
+    bottom: 8px;
+    z-index: 20;
+    width: 100%;
+    grid-template-columns: 1fr 1fr 0.85fr;
+    gap: 8px;
+    margin-top: 12px;
+    padding: 0;
+  }
+
+  .bottom-controls .control-button {
+    min-height: 44px;
+    border-radius: 14px;
+    font-size: 0.78rem;
+  }
+
+  .technical-status,
+  .app-footer {
+    display: none;
+  }
+}
+
+@media (max-width: 560px) {
+  .whistle-app {
+    padding: 10px;
+  }
+
+  .camera-stage {
+    aspect-ratio: 9 / 14;
+  }
+
+  .coach-face {
+    display: none;
+  }
+
+  .coach-card {
+    min-height: auto;
+  }
+
+  .mini-guide {
+    display: none;
+  }
+
+  .action-stack {
+    grid-template-columns: repeat(5, minmax(78px, 1fr));
+  }
+
+  .melody-action {
+    min-height: 82px;
+    padding: 10px 8px;
+  }
+}

training/README.md

@@ -0,0 +1,56 @@
+# Nemotron Coach Policy Fine-Tuning
+
+Whistle Coach fine-tunes a small Nemotron policy model on structured practice
+states instead of raw camera or microphone data. The model learns this narrow
+mapping:
+
+```text
+practice_state history -> coach policy JSON
+```
+
+The expected output schema is:
+
+```json
+{
+  "coach_message": "one actionable sentence",
+  "diagnosis": "short blocker diagnosis",
+  "overlay_cues": [{"type": "lip_corners", "direction": "inward"}],
+  "active_step": "round_lips",
+  "agent_trace": [
+    {"step": "Observe", "action": "read_state", "detail": "..."},
+    {"step": "Diagnose", "action": "not_rounded", "detail": "..."},
+    {"step": "Plan", "action": "lip_rounding", "detail": "..."},
+    {"step": "Act", "action": "coach_message", "detail": "..."}
+  ],
+  "next_drill": "lip_rounding",
+  "difficulty_adjustment": "hold",
+  "success_trigger": false
+}
+```
+
+## Recommended model
+
+- `nvidia/NVIDIA-Nemotron-3-Nano-4B-BF16` for the tiny coach policy.
+- `nvidia/NVIDIA-Nemotron-3-Nano-30B-A3B-BF16` as an optional teacher model for
+  generating additional high-quality labels.
+
+Both are under the Build Small 32B parameter cap. The 4B model is the intended
+fine-tuned runtime policy.
+
+## Local/Modal training shape
+
+The Space itself does not install training dependencies. Run fine-tuning in a
+separate environment with:
+
+```bash
+pip install transformers datasets peft trl accelerate bitsandbytes
+python training/finetune_nemotron_policy.py
+```
+
+The script reads `data/coach_policy_sft.jsonl` and writes LoRA adapters to
+`outputs/nemotron-whistle-coach-lora/`.
+
+## Privacy
+
+The dataset stores derived numeric features and coach decisions only. It does
+not store webcam frames, face images, or microphone audio.

training/finetune_nemotron_policy.py

@@ -0,0 +1,78 @@
+"""LoRA fine-tuning scaffold for the Whistle Coach policy model.
+
+Run this outside the CPU Space, for example on a local GPU box or Modal.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from datasets import load_dataset
+from peft import LoraConfig
+from transformers import AutoModelForCausalLM, AutoTokenizer
+from trl import SFTConfig, SFTTrainer
+
+
+BASE_MODEL = os.getenv("BASE_MODEL", "nvidia/NVIDIA-Nemotron-3-Nano-4B-BF16")
+DATA_PATH = Path(os.getenv("DATA_PATH", "data/coach_policy_sft.jsonl"))
+OUTPUT_DIR = Path(os.getenv("OUTPUT_DIR", "outputs/nemotron-whistle-coach-lora"))
+
+
+def format_example(example: dict) -> str:
+    return (
+        "<|user|>\n"
+        f"{example['input']}\n"
+        "<|assistant|>\n"
+        f"{example['output']}"
+    )
+
+
+def main() -> None:
+    dataset = load_dataset("json", data_files=str(DATA_PATH), split="train")
+    dataset = dataset.map(lambda row: {"text": format_example(row)})
+
+    tokenizer = AutoTokenizer.from_pretrained(BASE_MODEL, trust_remote_code=True)
+    if tokenizer.pad_token is None:
+        tokenizer.pad_token = tokenizer.eos_token
+
+    model = AutoModelForCausalLM.from_pretrained(
+        BASE_MODEL,
+        device_map="auto",
+        trust_remote_code=True,
+    )
+
+    peft_config = LoraConfig(
+        r=16,
+        lora_alpha=32,
+        lora_dropout=0.05,
+        bias="none",
+        task_type="CAUSAL_LM",
+        target_modules=["q_proj", "k_proj", "v_proj", "o_proj"],
+    )
+
+    trainer = SFTTrainer(
+        model=model,
+        tokenizer=tokenizer,
+        train_dataset=dataset,
+        peft_config=peft_config,
+        args=SFTConfig(
+            output_dir=str(OUTPUT_DIR),
+            dataset_text_field="text",
+            max_seq_length=1536,
+            per_device_train_batch_size=1,
+            gradient_accumulation_steps=8,
+            learning_rate=2e-4,
+            num_train_epochs=3,
+            logging_steps=5,
+            save_strategy="epoch",
+            report_to="none",
+        ),
+    )
+    trainer.train()
+    trainer.save_model(str(OUTPUT_DIR))
+    tokenizer.save_pretrained(str(OUTPUT_DIR))
+
+
+if __name__ == "__main__":
+    main()