feat: mos form

README.md

@@ -1,12 +0,0 @@
----
-title: Atc Tts Mos
-emoji: 📉
-colorFrom: blue
-colorTo: red
-sdk: gradio
-sdk_version: 5.49.1
-app_file: app.py
-pinned: false
----
-
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference

app/app.py

@@ -1,347 +0,0 @@
-from __future__ import annotations
-import os, json, random, time
-from dataclasses import dataclass, asdict
-from pathlib import Path
-from typing import List, Tuple, Dict
-import gradio as gr
-
-# TODO: change later
-CLIPS: List[dict] = [
-    # --- SAMPLE DATA (replace) ---
-    {"model":"xtts","gender":"male","exercise":"Exercise 1","audio":"/audio/xtts/male/Exercise_1_1.wav","rt":"Tower controller requests clearance..."},
-    {"model":"sesame","gender":"male","exercise":"Exercise 1","audio":"/audio/sesame/male/Exercise_1_1.wav","rt":"Tower controller requests clearance..."},
-    {"model":"voxtream","gender":"male","exercise":"Exercise 1","audio":"/audio/voxtream/male/Exercise_1_1.wav","rt":"Tower controller requests clearance..."},
-    {"model":"xtts","gender":"female","exercise":"Exercise 1","audio":"/audio/xtts/female/Exercise_1_1.wav","rt":"Tower controller requests clearance..."},
-    {"model":"sesame","gender":"female","exercise":"Exercise 1","audio":"/audio/sesame/female/Exercise_1_1.wav","rt":"Tower controller requests clearance..."},
-]
-
-# Locked counts per section 
-N_MOS   = 10
-N_ABMM  = 4
-N_ABGF  = 4
-
-SUPPORTED_GENDERS = {"male", "female"}
-
-@dataclass
-class Clip:
-    model: str
-    gender: str
-    exercise: str
-    audio: str
-    rt: str
-
-    @property
-    def key(self) -> Tuple[str, str, str]:
-        return (self.exercise or "", Path(self.audio).name, self.rt or "")
-
-@dataclass
-class MosItem:
-    display_id: str
-    clip: Clip
-    alias: str  # cosmetic Model A/B/C per item
-
-@dataclass
-class ABItem:
-    display_id: str
-    clip_A: Clip
-    clip_B: Clip
-    alias_A: str
-    alias_B: str
-
-# ---------- helpers ----------
-
-def parse_clips(raw_list: List[dict]) -> List[Clip]:
-    clips: List[Clip] = []
-    for r in raw_list:
-        c = Clip(
-            model=str(r.get("model", "")).strip() or "unknown",
-            gender=str(r.get("gender", "")).strip().lower(),
-            exercise=str(r.get("exercise", "")).strip(),
-            audio=str(r.get("audio", "")).strip(),
-            rt=str(r.get("rt", "")).strip(),
-        )
-        if not c.audio:
-            continue
-        clips.append(c)
-    return clips
-
-
-def build_indices(clips: List[Clip]):
-    by_key: Dict[Tuple[str, str, str], List[Clip]] = {}
-    for c in clips:
-        by_key.setdefault(c.key, []).append(c)
-    return by_key
-
-
-def sample_mos(clips: List[Clip], n_items: int, rng: random.Random) -> List[MosItem]:
-    pool = [c for c in clips if c.audio]
-    rng.shuffle(pool)
-    sel = pool[:max(0, n_items)]
-    items: List[MosItem] = []
-    for i, c in enumerate(sel, 1):
-        alias = rng.choice(["Model A", "Model B", "Model C"])  # cosmetic
-        items.append(MosItem(display_id=f"MOS-{i}", clip=c, alias=alias))
-    return items
-
-
-def sample_ab_model_vs_model(by_key, n_pairs: int, rng: random.Random) -> List[ABItem]:
-    pairs: List[ABItem] = []
-    keys = list(by_key.keys())
-    rng.shuffle(keys)
-    for key in keys:
-        variants = by_key[key]
-        # need two distinct models for same prompt
-        uniq_by_model: Dict[str, Clip] = {}
-        for v in variants:
-            uniq_by_model.setdefault(v.model, v)
-        if len(uniq_by_model) < 2:
-            continue
-        m = list(uniq_by_model.values())
-        rng.shuffle(m)
-        A, B = m[0], m[1]
-        alias = ["Model A", "Model B"]
-        rng.shuffle(alias)
-        pairs.append(ABItem(display_id=f"ABMM-{len(pairs)+1}", clip_A=A, clip_B=B, alias_A=alias[0], alias_B=alias[1]))
-        if len(pairs) >= n_pairs:
-            break
-    return pairs
-
-
-def sample_ab_gender_flip(by_key, n_pairs: int, rng: random.Random) -> List[ABItem]:
-    pairs: List[ABItem] = []
-    keys = list(by_key.keys())
-    rng.shuffle(keys)
-    for key in keys:
-        variants = by_key[key]
-        male = next((v for v in variants if v.gender == "male"), None)
-        female = next((v for v in variants if v.gender == "female"), None)
-        if not male or not female:
-            continue
-        A, B = male, female
-        alias = ["Model A", "Model B"]
-        rng.shuffle(alias)
-        pairs.append(ABItem(display_id=f"ABGF-{len(pairs)+1}", clip_A=A, clip_B=B, alias_A=alias[0], alias_B=alias[1]))
-        if len(pairs) >= n_pairs:
-            break
-    return pairs
-
-# ---------- UI builders ----------
-
-def human_name(c: Clip) -> str:
-    rt_short = (c.rt[:120] + "…") if c.rt and len(c.rt) > 120 else (c.rt or "")
-    ex = f" | {c.exercise}" if c.exercise else ""
-    return f"{Path(c.audio).name}{ex} — {c.gender.title()}{rt_short}"
-
-def build_mos_block(items: List[MosItem]):
-    blocks = []
-    for it in items:
-        gr.Markdown(f"### {it.display_id} — {it.alias}")
-        audio = gr.Audio(label=human_name(it.clip), value=it.clip.audio, interactive=False)
-        c1 = gr.Slider(1, 5, step=1, label="Clarity", elem_classes=["big-slider"])
-        c2 = gr.Slider(1, 5, step=1, label="Pronunciation", elem_classes=["big-slider"])
-        c3 = gr.Slider(1, 5, step=1, label="Prosody", elem_classes=["big-slider"])
-        c4 = gr.Slider(1, 5, step=1, label="Naturalness", elem_classes=["big-slider"])
-        c5 = gr.Slider(1, 5, step=1, label="Overall", elem_classes=["big-slider"])
-        comment = gr.Textbox(label="Optional comment", lines=2)
-        blocks.append({"item": it, "audio": audio, "sliders": [c1, c2, c3, c4, c5], "comment": comment})
-    return blocks
-
-
-def build_ab_block(items: List[ABItem], title: str):
-    blocks = []
-    gr.Markdown(f"## {title}")
-    for it in items:
-        gr.Markdown(f"### {it.display_id}")
-        a_audio = gr.Audio(label=f"{it.alias_A} — {human_name(it.clip_A)}", value=it.clip_A.audio, interactive=False)
-        b_audio = gr.Audio(label=f"{it.alias_B} — {human_name(it.clip_B)}", value=it.clip_B.audio, interactive=False)
-        choice = gr.Radio(["Left (first)", "Right (second)", "Tie"], label="Which is better?", value=None, elem_classes=["big-radio"]) 
-        comment = gr.Textbox(label="Optional comment", lines=2)
-        blocks.append({"item": it, "a_audio": a_audio, "b_audio": b_audio, "choice": choice, "comment": comment})
-    return blocks
-
-# ---------- Wizard pages ----------
-css = """
-:root { --font-size: 20px; }
-.gradio-container { font-size: 20px; }
-h1, h2, h3 { line-height: 1.25; }
-.big-slider .wrap-inner { font-size: 18px; }
-.big-radio .wrap { font-size: 20px; }
-.gr-button { font-size: 18px; padding: 0.8rem 1.2rem; font-weight: 700; }
-"""
-
-with gr.Blocks(title="ATC TTS Evaluation (Wizard)", css=css, theme=gr.themes.Default()) as demo:
-    # States
-    session = gr.State()
-    mos_blocks_state = gr.State()
-    abmm_blocks_state = gr.State()
-    abgf_blocks_state = gr.State()
-
-    # PAGE 1 — Intro
-    page_intro = gr.Column(visible=True)
-    with page_intro:
-        gr.Markdown("""
-        # ATC TTS Evaluation
-        You will evaluate short ATC/aviation clips from three TTS systems. Within each item, models are anonymized as **Model A/B/C**.
-
-        **Please use headphones in a quiet place.**
-
-        **What you will do**
-        - Rate each clip on five MOS dimensions (1–5): *Clarity, Pronunciation, Prosody, Naturalness, Overall*.
-        - Do A/B comparisons on the same prompt: **Model vs Model**, and **Male vs Female**.
-
-        *Estimated time: 10–15 minutes. Responses are anonymous and used only to improve the models.*
-        """)
-        start_btn = gr.Button("Start", variant="primary")
-
-    # PAGE 2 — MOS
-    page_mos = gr.Column(visible=False)
-    with page_mos:
-        gr.Markdown("## Section 2 — MOS Ratings")
-        mos_container = gr.Column()
-        mos_next = gr.Button("Next ▶", variant="primary")
-
-    # PAGE 3 — AB: Model vs Model
-    page_abmm = gr.Column(visible=False)
-    with page_abmm:
-        gr.Markdown("## Section 3 — A/B: Model vs Model (same prompt)")
-        abmm_container = gr.Column()
-        abmm_next = gr.Button("Next ▶", variant="primary")
-
-    # PAGE 4 — AB: Male vs Female
-    page_abgf = gr.Column(visible=False)
-    with page_abgf:
-        gr.Markdown("## Section 4 — A/B: Male vs Female (same model & prompt)")
-        abgf_container = gr.Column()
-        abgf_next = gr.Button("Next ▶", variant="primary")
-
-    # PAGE 5 — Conclusion
-    page_done = gr.Column(visible=False)
-    with page_done:
-        gr.Markdown("## Section 5 — Conclusion")
-        pid = gr.Textbox(label="Participant ID (optional)")
-        notes = gr.Textbox(label="Additional comments (optional)", lines=3)
-        export_btn = gr.Button("Export Responses (JSON)", variant="primary")
-        export_json = gr.Code(label="Copy/save this JSON", language="json")
-
-    # ---- Handlers ----
-    def _start():
-        # Prepare randomized session using embedded CLIPS
-        clips = parse_clips(CLIPS)
-        if not clips:
-            return {"visible": True, "value": "No clips configured in app."}, None, None, None, None
-        rng = random.Random(time.time_ns())
-        by_key = build_indices(clips)
-        mos_items = sample_mos(clips, N_MOS, rng)
-        abmm_items = sample_ab_model_vs_model(by_key, N_ABMM, rng)
-        abgf_items = sample_ab_gender_flip(by_key, N_ABGF, rng)
-        ses = {
-            "seed": None,
-            "timestamp": int(time.time()),
-            "mos": [asdict(x) for x in mos_items],
-            "abmm": [asdict(x) for x in abmm_items],
-            "abgf": [asdict(x) for x in abgf_items],
-        }
-        # Build UI blocks now
-        m_items = [MosItem(**{**x, "clip": Clip(**x["clip"])}) for x in ses["mos"]]
-        a_items = [ABItem(**{**x, "clip_A": Clip(**x["clip_A"]), "clip_B": Clip(**x["clip_B"])}) for x in ses["abmm"]]
-        g_items = [ABItem(**{**x, "clip_A": Clip(**x["clip_A"]), "clip_B": Clip(**x["clip_B"])}) for x in ses["abgf"]]
-
-        # Render into containers
-        with mos_container:
-            mos_blocks = build_mos_block(m_items)
-        with abmm_container:
-            abmm_blocks = build_ab_block(a_items, title="Model vs Model")
-        with abgf_container:
-            abgf_blocks = build_ab_block(g_items, title="Male vs Female")
-        return (
-            gr.update(visible=False),  # intro off
-            gr.update(visible=True),   # show MOS
-            ses,
-            mos_blocks,
-            abmm_blocks,
-            abgf_blocks,
-        )
-
-    start_btn.click(
-        fn=_start,
-        inputs=[],
-        outputs=[page_intro, page_mos, session, mos_blocks_state, abmm_blocks_state, abgf_blocks_state],
-    )
-
-    def _to_abmm():
-        return gr.update(visible=False), gr.update(visible=True)
-
-    mos_next.click(fn=_to_abmm, inputs=[], outputs=[page_mos, page_abmm])
-
-    def _to_abgf():
-        return gr.update(visible=False), gr.update(visible=True)
-
-    abmm_next.click(fn=_to_abgf, inputs=[], outputs=[page_abmm, page_abgf])
-
-    def _to_done():
-        return gr.update(visible=False), gr.update(visible=True)
-
-    abgf_next.click(fn=_to_done, inputs=[], outputs=[page_abgf, page_done])
-
-    def _collect(ses, mos_blocks, abmm_blocks, abgf_blocks, pid, notes):
-        if not ses:
-            return json.dumps({"error": "no session"}, indent=2)
-        # MOS
-        mos_resp = []
-        for b in mos_blocks or []:
-            sliders = [s.value for s in b["sliders"]]
-            mos_resp.append({
-                "display_id": b["item"].display_id,
-                "model": b["item"].clip.model,
-                "gender": b["item"].clip.gender,
-                "exercise": b["item"].clip.exercise,
-                "audio": b["item"].clip.audio,
-                "rt": b["item"].clip.rt,
-                "clarity": sliders[0],
-                "pronunciation": sliders[1],
-                "prosody": sliders[2],
-                "naturalness": sliders[3],
-                "overall": sliders[4],
-                "comment": b["comment"].value,
-            })
-        # AB: model vs model
-        abmm_resp = []
-        for b in abmm_blocks or []:
-            abmm_resp.append({
-                "display_id": b["item"].display_id,
-                "A": {"model": b["item"].clip_A.model, "gender": b["item"].clip_A.gender, "audio": b["item"].clip_A.audio},
-                "B": {"model": b["item"].clip_B.model, "gender": b["item"].clip_B.gender, "audio": b["item"].clip_B.audio},
-                "choice": b["choice"].value,
-                "comment": b["comment"].value,
-            })
-        # AB: gender flip
-        abgf_resp = []
-        for b in abgf_blocks or []:
-            abgf_resp.append({
-                "display_id": b["item"].display_id,
-                "male": {"model": b["item"].clip_A.model if b["item"].clip_A.gender=="male" else b["item"].clip_B.model,
-                          "audio": b["item"].clip_A.audio if b["item"].clip_A.gender=="male" else b["item"].clip_B.audio},
-                "female": {"model": b["item"].clip_A.model if b["item"].clip_A.gender=="female" else b["item"].clip_B.model,
-                            "audio": b["item"].clip_A.audio if b["item"].clip_A.gender=="female" else b["item"].clip_B.audio},
-                "choice": b["choice"].value,
-                "comment": b["comment"].value,
-            })
-        out = {
-            "pid": pid or "anon",
-            "notes": notes or "",
-            "timestamp": ses.get("timestamp"),
-            "mos": mos_resp,
-            "ab_model_vs_model": abmm_resp,
-            "ab_gender_flip": abgf_resp,
-        }
-        return json.dumps(out, indent=2)
-
-    export_btn.click(
-        fn=_collect,
-        inputs=[session, mos_blocks_state, abmm_blocks_state, abgf_blocks_state, pid, notes],
-        outputs=[export_json],
-    )
-
-if __name__ == "__main__":
-    os.environ.setdefault("GRADIO_THEME", "default")
-    demo.launch()

audios/female.wav

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:59ada1cd9b9940a91544ed4068547dc56efe85d047aa1e174c5486183e57dfa1
+size 442662

audios/male.wav

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:f5349f8fc82f18d9841a48b34cabca71872f0363218c0e5a46359c89ae653808
+size 664600

backend/__init__.py

@@ -0,0 +1,26 @@
+# backend/__init__.py
+
+from .config import RATINGS_DATASET_ID, AUDIO_DATASET_ID
+from .models import (
+    Clip,
+    MOSResponse,
+    ABResponse,
+    get_display_model_name,
+    audio_to_base64_url,
+)
+from .data_manager import DataManager
+from .session_manager import SessionManager
+from .hf_logging import push_session_to_hub
+
+__all__ = [
+    "RATINGS_DATASET_ID",
+    "AUDIO_DATASET_ID",
+    "Clip",
+    "MOSResponse",
+    "ABResponse",
+    "get_display_model_name",
+    "audio_to_base64_url",
+    "DataManager",
+    "SessionManager",
+    "push_session_to_hub",
+]

backend/config.py

@@ -0,0 +1,5 @@
+# backend/config.py
+
+# Dataset IDs
+RATINGS_DATASET_ID = "aether-raid/atc-tts-mos-ratings"
+AUDIO_DATASET_ID = "aether-raid/axite-tts"

backend/data_manager.py

@@ -0,0 +1,119 @@
+# backend/data_manager.py
+
+import os
+import base64
+import io
+from typing import List, Optional, Any, Dict
+
+import numpy as np
+from datasets import load_dataset
+
+from .config import AUDIO_DATASET_ID
+from .models import Clip
+
+try:
+    import soundfile as sf
+except ImportError:
+    sf = None
+
+
+class DataManager:
+    """Handles loading and processing data from Hugging Face."""
+
+    def __init__(self, dataset_id: str = AUDIO_DATASET_ID):
+        self.dataset_id = dataset_id
+        self._clips: Optional[List[Clip]] = None
+        self._loading = False
+
+    def _audio_to_data_url(self, audio_val) -> Optional[str]:
+        """
+        Accepts:
+        - torchcodec AudioDecoder
+        - dict-like with 'path' / 'array' / 'sampling_rate'
+        Returns data:audio/wav;base64,... or None.
+        """
+        # 1) Try to get a real file path and read it
+        try:
+            path = None
+            if isinstance(audio_val, dict) and "path" in audio_val:
+                path = audio_val["path"]
+            else:
+                # mapping-like: try __getitem__ then attribute
+                try:
+                    path = audio_val["path"]  # works on some decoders
+                except Exception:
+                    path = getattr(audio_val, "path", None)
+
+            if isinstance(path, str) and os.path.exists(path):
+                with open(path, "rb") as f:
+                    audio_bytes = f.read()
+                b64 = base64.b64encode(audio_bytes).decode("ascii")
+                return f"data:audio/wav;base64,{b64}"
+        except Exception as e:
+            print(f"[WARN] Failed to build data URL from path: {e}")
+
+        # 2) Fallback: use array + sampling_rate and render WAV in-memory
+        try:
+            array = None
+            sr = None
+
+            if isinstance(audio_val, dict):
+                array = audio_val.get("array")
+                sr = audio_val.get("sampling_rate")
+            if array is None or sr is None:
+                # try mapping-style then attributes
+                try:
+                    array = audio_val["array"]
+                    sr = audio_val["sampling_rate"]
+                except Exception:
+                    array = getattr(audio_val, "array", None)
+                    sr = getattr(audio_val, "sampling_rate", None)
+
+            if array is not None and sr is not None and sf is not None:
+                buf = io.BytesIO()
+                sf.write(buf, np.array(array), int(sr), format="WAV")
+                b64 = base64.b64encode(buf.getvalue()).decode("ascii")
+                return f"data:audio/wav;base64,{b64}"
+        except Exception as e:
+            print(f"[WARN] Failed to build data URL from array/sr: {e}")
+
+        print("[WARN] Could not build audio data URL for this example")
+        return None
+
+    def load_clips(self) -> List[Clip]:
+        if self._clips is not None:
+            return self._clips
+
+        if self._loading:
+            print("Dataset loading already in progress...")
+            return []
+
+        self._loading = True
+
+        print(f"Loading dataset {self.dataset_id}...")
+        dataset = load_dataset(self.dataset_id, split="train")
+
+        clips: List[Clip] = []
+        for row in dataset:
+            audio_val = row.get("audio")
+
+            audio_url = self._audio_to_data_url(audio_val)
+            if audio_url is None:
+                print(f"[WARN] Skipping clip {row.get('exercise_id')} – could not build audio URL")
+                continue
+
+            clip = Clip(
+                id=f"{row['model']}_{row['speaker']}_{row['exercise_id']}",
+                model=row["model"],
+                speaker=row["speaker"],
+                exercise=row["exercise"],
+                exercise_id=row["exercise_id"],
+                transcript=row["rt"],
+                audio_url=audio_url,  # string usable in <audio src="...">
+            )
+            clips.append(clip)
+
+        self._clips = clips
+        self._loading = False
+        print(f"Loaded {len(clips)} clips")
+        return clips

backend/hf_logging.py

@@ -0,0 +1,68 @@
+# backend/hf_logging.py
+
+import json
+import io
+from datetime import datetime
+from typing import Dict, Any
+
+from huggingface_hub import HfApi, CommitOperationAdd
+
+from .config import RATINGS_DATASET_ID
+
+# Hugging Face API for logging
+hf_api = HfApi()
+
+
+def push_session_to_hub(session_id: str, export_data: Dict[str, Any]):
+    """
+    Save one session's ratings to the HF dataset as sessions/<session_id>.json
+    """
+    # Add human-readable timestamps and summary to session metadata
+    if "session_metadata" in export_data:
+        metadata = export_data["session_metadata"]
+        if "created_at" in metadata and metadata["created_at"]:
+            metadata["created_at_readable"] = datetime.fromtimestamp(metadata["created_at"]).isoformat()
+        if "exported_at" in metadata and metadata["exported_at"]:
+            metadata["exported_at_readable"] = datetime.fromtimestamp(metadata["exported_at"]).isoformat()
+    
+    # Add a summary section for easy viewing
+    export_data["summary"] = {
+        "session_id": session_id,
+        "evaluation_completed": export_data.get("session_metadata", {}).get("completed", False),
+        "total_mos_ratings": len(export_data.get("mos_ratings", [])),
+        "total_ab_comparisons": len(export_data.get("ab_comparisons", [])),
+        "models_evaluated": list(set(
+            [r.get("model") for r in export_data.get("mos_ratings", [])] +
+            [r.get("clip_a_model") for r in export_data.get("ab_comparisons", [])] +
+            [r.get("clip_b_model") for r in export_data.get("ab_comparisons", [])]
+        )),
+        "evaluation_date": export_data.get("session_metadata", {}).get("created_at_readable", ""),
+    }
+    
+    # Add readable timestamps to individual responses
+    for response_list in [export_data.get("mos_ratings", []), export_data.get("ab_comparisons", [])]:
+        for response in response_list:
+            if "response_timestamp" in response and response["response_timestamp"]:
+                response["response_timestamp_readable"] = datetime.fromtimestamp(response["response_timestamp"]).isoformat()
+    
+    # Serialize to bytes with nice formatting
+    json_bytes = json.dumps(export_data, indent=2, default=str, ensure_ascii=False).encode("utf-8")
+    fileobj = io.BytesIO(json_bytes)
+
+    # Path inside the dataset repo
+    path_in_repo = f"sessions/{session_id}.json"
+
+    # Create a git commit adding/updating that file
+    hf_api.create_commit(
+        repo_id=RATINGS_DATASET_ID,
+        repo_type="dataset",
+        operations=[
+            CommitOperationAdd(
+                path_in_repo=path_in_repo,
+                path_or_fileobj=fileobj,
+            )
+        ],
+        commit_message=f"Add MOS ratings for session {session_id}",
+    )
+
+    print(f"[LOG] Pushed session {session_id} to {RATINGS_DATASET_ID}/{path_in_repo}")

backend/models.py

@@ -0,0 +1,60 @@
+# backend/models.py
+
+from dataclasses import dataclass
+from typing import Any, Optional
+
+# Model name mapping for anonymization
+# Maps internal model names to display labels
+MODEL_NAME_MAP = {
+    "xtts": "Model A",     # Coqui XTTS -> Model A
+    "csm": "Model B",      # Sesame CSM -> Model B
+    "orpheus": "Model C",  # Orpheus -> Model C
+}
+
+
+def get_display_model_name(internal_name: str) -> str:
+    """Convert internal model name to display label."""
+    return MODEL_NAME_MAP.get(internal_name, internal_name.upper())
+
+
+def audio_to_base64_url(audio_data):
+    """Return the audio data URL string as-is (no-op since audio_url is already a base64 data URL)."""
+    return audio_data if isinstance(audio_data, str) else None
+
+
+# Data models
+@dataclass
+class Clip:
+    id: str
+    model: str
+    speaker: str  # male/female
+    exercise: str
+    exercise_id: str
+    transcript: str
+    audio_url: Any  # Can be string URL or tuple (array, sample_rate)
+    duration_s: Optional[float] = None
+
+
+@dataclass
+class MOSResponse:
+    session_id: str
+    clip_id: str
+    clarity: int
+    pronunciation: int
+    prosody: int
+    naturalness: int
+    overall: int
+    comment: str = ""
+    gender_mismatch: bool = False  # Flag for wrong gender voice
+
+
+@dataclass
+class ABResponse:
+    session_id: str
+    clip_a_id: str
+    clip_b_id: str
+    comparison_type: str  # "model_vs_model" or "gender_vs_gender"
+    choice: str  # "A", "B", "tie"
+    comment: str = ""
+    gender_mismatch_a: bool = False  # Flag for wrong gender voice in clip A
+    gender_mismatch_b: bool = False  # Flag for wrong gender voice in clip B

backend/session_manager.py

@@ -0,0 +1,456 @@
+# backend/session_manager.py
+
+import json
+import random
+import time
+import uuid
+from typing import List, Dict, Any, Optional
+
+from .models import Clip, get_display_model_name
+
+
+class SessionManager:
+    """Manages evaluation sessions, responses, and export logic."""
+
+    def __init__(self, data_manager):
+        self.data_manager = data_manager
+        self.sessions: Dict[str, Dict[str, Any]] = {}
+        self.responses: Dict[str, List[Dict[str, Any]]] = {
+            "mos": [],
+            "ab": [],
+            "feedback": [],
+        }
+
+    # --------------------------
+    # Session creation
+    # --------------------------
+    def create_session(self) -> Dict[str, Any]:
+        session_id = str(uuid.uuid4())
+        clips = self.data_manager.load_clips()
+
+        rng = random.Random(time.time())
+
+        mos_clips: List[Clip] = []
+        models = {clip.model for clip in clips}
+
+        # Build MOS clip set
+        for model in models:
+            model_clips = [clip for clip in clips if clip.model == model]
+
+            exercise_groups: Dict[str, Dict[str, List[Clip]]] = {}
+            for clip in model_clips:
+                if clip.exercise_id not in exercise_groups:
+                    exercise_groups[clip.exercise_id] = {"male": [], "female": []}
+                exercise_groups[clip.exercise_id][clip.speaker].append(clip)
+
+            paired_exercises = []
+            for _, speakers in exercise_groups.items():
+                if speakers["male"] and speakers["female"]:
+                    male_clip = rng.choice(speakers["male"])
+                    female_clip = rng.choice(speakers["female"])
+                    paired_exercises.append((male_clip, female_clip))
+
+            if len(paired_exercises) >= 3:
+                selected_pairs = rng.sample(paired_exercises, 3)
+                for male_clip, female_clip in selected_pairs:
+                    mos_clips.extend([male_clip, female_clip])
+            else:
+                for male_clip, female_clip in paired_exercises:
+                    mos_clips.extend([male_clip, female_clip])
+
+                used_clip_ids = {clip.id for clip in mos_clips if clip.model == model}
+                remaining_clips = [
+                    clip for clip in model_clips if clip.id not in used_clip_ids
+                ]
+                slots_needed = 6 - len([c for c in mos_clips if c.model == model])
+
+                if remaining_clips and slots_needed > 0:
+                    additional_clips = rng.sample(
+                        remaining_clips, min(slots_needed, len(remaining_clips))
+                    )
+                    mos_clips.extend(additional_clips)
+
+        # Group by content (exercise + transcript) for comparisons
+        content_groups: Dict[Any, List[Clip]] = {}
+        for clip in clips:
+            key = (clip.exercise, clip.exercise_id, clip.transcript)
+            content_groups.setdefault(key, []).append(clip)
+
+        # Model vs model pairs (ensure same gender)
+        ab_model_pairs = []
+        for _, group in content_groups.items():
+            # Group clips by model and speaker (gender)
+            model_speaker_map: Dict[str, Dict[str, List[Clip]]] = {}
+            for clip in group:
+                model_speaker_map.setdefault(clip.model, {}).setdefault(clip.speaker, []).append(clip)
+
+            model_names = list(model_speaker_map.keys())
+            if len(model_names) >= 2:
+                # Try each possible gender to find matching clips
+                for speaker in ["male", "female"]:
+                    # Find models that have clips for this speaker
+                    available_models = [
+                        model for model in model_names 
+                        if speaker in model_speaker_map[model] and model_speaker_map[model][speaker]
+                    ]
+                    
+                    if len(available_models) >= 2:
+                        model_a, model_b = rng.sample(available_models, 2)
+                        clip_a = rng.choice(model_speaker_map[model_a][speaker])
+                        clip_b = rng.choice(model_speaker_map[model_b][speaker])
+                        ab_model_pairs.append((clip_a, clip_b))
+                        break  # Found a valid pair for this content group
+
+                if len(ab_model_pairs) >= 6:
+                    break
+
+        # Gender vs gender pairs
+        ab_gender_pairs = []
+        for _, group in content_groups.items():
+            model_gender_groups: Dict[str, Dict[str, List[Clip]]] = {}
+            for clip in group:
+                model_gender_groups.setdefault(clip.model, {}).setdefault(
+                    clip.speaker, []
+                ).append(clip)
+
+            for model, gender_groups in model_gender_groups.items():
+                if "male" in gender_groups and "female" in gender_groups:
+                    clip_male = rng.choice(gender_groups["male"])
+                    clip_female = rng.choice(gender_groups["female"])
+                    ab_gender_pairs.append((clip_male, clip_female))
+                    if len(ab_gender_pairs) >= 6:
+                        break
+            if len(ab_gender_pairs) >= 6:
+                break
+
+        # Sample clips (for the reference/sample section)
+        remaining_clips = [c for c in clips if c not in mos_clips]
+        sample_clips = rng.sample(remaining_clips, min(3, len(remaining_clips)))
+
+        session_data: Dict[str, Any] = {
+            "session_id": session_id,
+            "created_at": time.time(),
+            "mos_clips": mos_clips,
+            "ab_model_pairs": ab_model_pairs,
+            "ab_gender_pairs": ab_gender_pairs,
+            "sample_clips": sample_clips,
+            "completed": False,
+        }
+
+        self.sessions[session_id] = session_data
+        return session_data
+
+    # --------------------------
+    # Response storage helpers
+    # --------------------------
+    def save_response(self, response_type: str, response: Dict[str, Any]):
+        """Generic low-level append with auto-timestamp."""
+        if "timestamp" not in response:
+            response["timestamp"] = time.time()
+        self.responses.setdefault(response_type, []).append(response)
+
+    def save_mos_rating(
+        self,
+        session: Dict[str, Any],
+        clip_id: str,
+        model: str,
+        clarity: Optional[int],
+        pronunciation: Optional[int],
+        prosody: Optional[int],
+        naturalness: Optional[int],
+        overall: Optional[int],
+        comment: str,
+        gender_mismatch: bool,
+    ) -> None:
+        """Optional helper for saving a single MOS rating."""
+        if not session:
+            return
+
+        mos_response = {
+            "session_id": session["session_id"],
+            "clip_id": clip_id,
+            "clarity": int(clarity) if clarity is not None else None,
+            "pronunciation": int(pronunciation) if pronunciation is not None else None,
+            "prosody": int(prosody) if prosody is not None else None,
+            "naturalness": int(naturalness) if naturalness is not None else None,
+            "overall": int(overall) if overall is not None else None,
+            "comment": comment or "",
+            "gender_mismatch": bool(gender_mismatch),
+            "timestamp": time.time(),
+        }
+        self.save_response("mos", mos_response)
+
+    def save_ab_rating(
+        self,
+        session: Dict[str, Any],
+        clip_a_id: str,
+        clip_b_id: str,
+        comparison_type: str,
+        choice: str,
+        comment: str,
+        gender_mismatch_a: bool,
+        gender_mismatch_b: bool,
+    ) -> None:
+        """Optional helper for saving a single A/B comparison."""
+        if not session:
+            return
+
+        ab_response = {
+            "session_id": session["session_id"],
+            "clip_a_id": clip_a_id,
+            "clip_b_id": clip_b_id,
+            "comparison_type": comparison_type,
+            "choice": choice,
+            "comment": comment or "",
+            "gender_mismatch_a": bool(gender_mismatch_a),
+            "gender_mismatch_b": bool(gender_mismatch_b),
+            "timestamp": time.time(),
+        }
+        self.save_response("ab", ab_response)
+
+    # --------------------------
+    # Bulk processing from JS JSON
+    # --------------------------
+    def process_mos_data(
+        self,
+        session: Dict[str, Any],
+        mos_data_json: str,
+    ) -> None:
+        """
+        Take the JSON string from the hidden MOS textbox and turn it into
+        individual MOS responses in self.responses["mos"].
+        """
+        print(f"[DEBUG] process_mos_data called with JSON: '{mos_data_json}'")
+        print(f"[DEBUG] Session ID: {session.get('session_id') if session else 'None'}")
+        if not session or not mos_data_json:
+            print(f"[DEBUG] Skipping MOS processing - session: {session is not None}, data length: {len(mos_data_json) if mos_data_json else 0}")
+            return
+
+        try:
+            ratings_data = json.loads(mos_data_json) if mos_data_json else {}
+        except json.JSONDecodeError as e:
+            print(f"[WARN] Failed to parse MOS data JSON: {e}")
+            return
+
+        try:
+            for clip_id, ratings in ratings_data.items():
+                # Only process if we have at least one dimension filled
+                if not any(
+                    ratings.get(dim)
+                    for dim in ["clarity", "pronunciation", "prosody", "naturalness", "overall"]
+                ):
+                    continue
+
+                mos_response = {
+                    "session_id": session["session_id"],
+                    "clip_id": clip_id,
+                    "clarity": int(ratings.get("clarity"))
+                    if ratings.get("clarity")
+                    else None,
+                    "pronunciation": int(ratings.get("pronunciation"))
+                    if ratings.get("pronunciation")
+                    else None,
+                    "prosody": int(ratings.get("prosody"))
+                    if ratings.get("prosody")
+                    else None,
+                    "naturalness": int(ratings.get("naturalness"))
+                    if ratings.get("naturalness")
+                    else None,
+                    "overall": int(ratings.get("overall"))
+                    if ratings.get("overall")
+                    else None,
+                    "comment": ratings.get("comment", ""),
+                    "gender_mismatch": ratings.get("gender_mismatch", False),
+                    "timestamp": time.time(),
+                }
+
+                self.save_response("mos", mos_response)
+                print(f"[INFO] Processed MOS rating for clip {clip_id}")
+
+        except Exception as e:
+            print(f"[WARN] Error processing MOS data: {e}")
+
+    def process_ab_data(
+        self,
+        session: Dict[str, Any],
+        ab_data_json: str,
+    ) -> None:
+        """
+        Take the JSON string from the hidden AB textbox and turn it into
+        individual A/B responses in self.responses["ab"].
+        """
+        print(f"[DEBUG] process_ab_data called with JSON: '{ab_data_json}'")
+        print(f"[DEBUG] Session ID: {session.get('session_id') if session else 'None'}")
+        if not session or not ab_data_json:
+            print(f"[DEBUG] Skipping AB processing - session: {session is not None}, data length: {len(ab_data_json) if ab_data_json else 0}")
+            return
+
+        try:
+            comparisons_data = json.loads(ab_data_json) if ab_data_json else {}
+        except json.JSONDecodeError as e:
+            print(f"[WARN] Failed to parse A/B data JSON: {e}")
+            return
+
+        try:
+            for comp_id, comparison in comparisons_data.items():
+                if not comparison.get("choice"):
+                    continue
+
+                ab_response = {
+                    "session_id": session["session_id"],
+                    "clip_a_id": comparison.get("clip_a_id"),
+                    "clip_b_id": comparison.get("clip_b_id"),
+                    "comparison_type": comparison.get("comparison_type"),
+                    "choice": comparison.get("choice"),
+                    "comment": comparison.get("comment", ""),
+                    # Support both model_vs_model (gender_mismatch_a/b)
+                    # and gender_vs_gender (gender_mismatch_male/female)
+                    "gender_mismatch_a": comparison.get("gender_mismatch_a", False)
+                    or comparison.get("gender_mismatch_male", False),
+                    "gender_mismatch_b": comparison.get("gender_mismatch_b", False)
+                    or comparison.get("gender_mismatch_female", False),
+                    "timestamp": time.time(),
+                }
+
+                self.save_response("ab", ab_response)
+                print(
+                    f"[INFO] Processed A/B rating for clips "
+                    f"{comparison.get('clip_a_id')} vs {comparison.get('clip_b_id')}"
+                )
+
+        except Exception as e:
+            print(f"[WARN] Error processing A/B data: {e}")
+
+    # --------------------------
+    # Export
+    # --------------------------
+    def export_session(self, session_id: str) -> Dict[str, Any]:
+        """Build a fully annotated export dict for a given session."""
+        session = self.sessions.get(session_id, {})
+
+        # Create detailed MOS responses with full clip metadata
+        detailed_mos_responses = []
+        session_mos_clips = {clip.id: clip for clip in session.get("mos_clips", [])}
+
+        for r in self.responses.get("mos", []):
+            if r.get("session_id") != session_id:
+                continue
+
+            clip_id = r.get("clip_id")
+            clip = session_mos_clips.get(clip_id)
+            if not clip:
+                continue
+
+            detailed_response = {
+                # Session metadata
+                "session_id": session_id,
+                "response_timestamp": r.get("timestamp", time.time()),
+                # Full clip metadata
+                "clip_id": clip_id,
+                "exercise": clip.exercise,
+                "exercise_id": clip.exercise_id,
+                "transcript": clip.transcript,
+                "model": clip.model,  # Original model name
+                "display_model": get_display_model_name(
+                    clip.model
+                ),  # Anonymized name
+                "speaker": clip.speaker,
+                # MOS ratings
+                "clarity": r.get("clarity"),
+                "pronunciation": r.get("pronunciation"),
+                "prosody": r.get("prosody"),
+                "naturalness": r.get("naturalness"),
+                "overall": r.get("overall"),
+                "comment": r.get("comment", ""),
+                # Quality control flags
+                "gender_mismatch": r.get(
+                    "gender_mismatch", False
+                ),  # True if user flagged wrong gender
+                # Response type
+                "evaluation_type": "mos_rating",
+            }
+            detailed_mos_responses.append(detailed_response)
+
+        # Create detailed A/B responses with full clip metadata
+        detailed_ab_responses = []
+        session_ab_model_pairs = session.get("ab_model_pairs", [])
+        session_ab_gender_pairs = session.get("ab_gender_pairs", [])
+
+        for r in self.responses.get("ab", []):
+            if r.get("session_id") != session_id:
+                continue
+
+            clip_a_id = r.get("clip_a_id")
+            clip_b_id = r.get("clip_b_id")
+            comparison_type = r.get("comparison_type")
+
+            # Find the clips from session pairs
+            clip_a, clip_b = None, None
+
+            if comparison_type == "model_vs_model":
+                for pair_a, pair_b in session_ab_model_pairs:
+                    if pair_a.id == clip_a_id and pair_b.id == clip_b_id:
+                        clip_a, clip_b = pair_a, pair_b
+                        break
+            elif comparison_type == "gender_vs_gender":
+                for pair_a, pair_b in session_ab_gender_pairs:
+                    if pair_a.id == clip_a_id and pair_b.id == clip_b_id:
+                        clip_a, clip_b = pair_a, pair_b
+                        break
+
+            if not (clip_a and clip_b):
+                continue
+
+            detailed_response = {
+                # Session metadata
+                "session_id": session_id,
+                "response_timestamp": r.get("timestamp", time.time()),
+                # Comparison metadata
+                "comparison_type": comparison_type,
+                "choice": r.get("choice"),
+                "comment": r.get("comment", ""),
+                # Clip A metadata
+                "clip_a_id": clip_a.id,
+                "clip_a_exercise": clip_a.exercise,
+                "clip_a_exercise_id": clip_a.exercise_id,
+                "clip_a_transcript": clip_a.transcript,
+                "clip_a_model": clip_a.model,
+                "clip_a_display_model": get_display_model_name(clip_a.model),
+                "clip_a_speaker": clip_a.speaker,
+                # Clip B metadata
+                "clip_b_id": clip_b.id,
+                "clip_b_exercise": clip_b.exercise,
+                "clip_b_exercise_id": clip_b.exercise_id,
+                "clip_b_transcript": clip_b.transcript,
+                "clip_b_model": clip_b.model,
+                "clip_b_display_model": get_display_model_name(clip_b.model),
+                "clip_b_speaker": clip_b.speaker,
+                # Quality control flags
+                "gender_mismatch_a": r.get(
+                    "gender_mismatch_a", False
+                ),  # True if clip A has wrong gender
+                "gender_mismatch_b": r.get(
+                    "gender_mismatch_b", False
+                ),  # True if clip B has wrong gender
+                # Response type
+                "evaluation_type": "ab_comparison",
+            }
+            detailed_ab_responses.append(detailed_response)
+
+        return {
+            "session_metadata": {
+                "session_id": session_id,
+                "created_at": session.get("created_at"),
+                "completed": session.get("completed", False),
+                "exported_at": time.time(),
+                "total_mos_ratings": len(detailed_mos_responses),
+                "total_ab_comparisons": len(detailed_ab_responses),
+            },
+            "mos_ratings": detailed_mos_responses,
+            "ab_comparisons": detailed_ab_responses,
+            "overall_feedback": [
+                r
+                for r in self.responses.get("feedback", [])
+                if r.get("session_id") == session_id
+            ],
+        }

backend/utils/hf_utils.py

@@ -1,224 +0,0 @@
-from __future__ import annotations
-
-import os
-from pathlib import Path
-from typing import Any, Dict, Optional
-
-import numpy as np
-import pandas as pd
-
-import json
-from urllib.parse import urlparse
-
-from datasets import load_dataset, Audio, Dataset
-
-DATASET_ID = "aether-raid/axite-tts"
-DEFAULT_SPLIT = "train"
-DEFAULT_OUTDIR = "/home/raid/atc-c3-comms/assets/tts/src/evaluation/mos/outputs"
-
-
-def _hf_raw_file_url(dataset_id: str, path: str) -> str:
-    """Construct a raw file URL for a file stored in a Hugging Face dataset repo.
-
-    This assumes the file is stored in the dataset repo under `main` branch. If the
-    dataset audio files are stored elsewhere or use a different branch, this URL may be wrong.
-    """
-    # If path already looks like a URL, return it
-    if path is None:
-        return None
-    parsed = urlparse(path)
-    if parsed.scheme in ("http", "https"):
-        return path
-    # Otherwise assume relative path inside the dataset repo
-    return f"https://huggingface.co/datasets/{dataset_id}/resolve/main/{path}"
-
-def compute_duration_from_audio_obj(a: Any) -> Optional[float]:
-    """Return duration in seconds for a datasets audio object (decoded) or None.
-
-    The audio object can be:
-      - dict with 'array' and 'sampling_rate'
-      - dict with 'path' (string)
-      - a bytes or other lazy decoder after decoding (we rely on datasets Audio to decode)
-    """
-    if a is None:
-        return None
-    # Case: decoded dict from datasets Audio feature
-    if isinstance(a, dict):
-        # If decoded array present, compute from array length and sampling_rate
-        if "array" in a and "sampling_rate" in a and a["array"] is not None:
-            arr = a["array"]
-            sr = a["sampling_rate"]
-            try:
-                return float(len(arr)) / float(sr) if sr and len(arr) else None
-            except Exception:
-                return None
-        # If a duration field already present use it (some datasets include it)
-        if "duration" in a and a["duration"] is not None:
-            try:
-                return float(a["duration"])
-            except Exception:
-                pass
-        # fallback: path available — we DO NOT download files here; return None
-        # (downstream code can decide whether to fetch/inspect remote files)
-        return None
-    # If it's a tuple/list like (array, sr)
-    if isinstance(a, (tuple, list)) and len(a) >= 2:
-        arr, sr = a[0], a[1]
-        try:
-            return float(len(arr)) / float(sr) if sr and len(arr) else None
-        except Exception:
-            return None
-    return None
-
-
-def summarize_dataset(
-    dataset_id: str, split: str = "train", out_dir: Optional[str] = None, decode_audio: bool = True
-) -> pd.DataFrame:
-    """Load HF dataset and build a summary DataFrame with requested fields.
-
-    Expected columns in dataset: exercise, exercise_id, rt, model, speaker, audio
-    """
-    ds = load_dataset(dataset_id, split=split)
-
-    # If audio column exists and decode_audio is True, cast to Audio to standardise decoding
-    if "audio" in ds.column_names and decode_audio:
-        try:
-            ds = ds.cast_column("audio", Audio(sampling_rate=16000))
-        except Exception:
-            # casting may fail for some dataset types; we'll handle per-row
-            pass
-
-    records = []
-    for i, row in enumerate(ds):
-        rec: Dict[str, Any] = {}
-        rec["exercise"] = row.get("exercise")
-        rec["exercise_id"] = row.get("exercise_id")
-        rec["rt"] = row.get("rt")
-        rec["model"] = row.get("model")
-        rec["speaker"] = row.get("speaker")
-
-        audio_obj = row.get("audio")
-        duration = None
-        audio_path = None
-        try:
-            # If decoded to dict with array & sampling_rate, compute duration
-            if isinstance(audio_obj, dict) and ("array" in audio_obj or "sampling_rate" in audio_obj):
-                duration = compute_duration_from_audio_obj(audio_obj)
-                audio_path = audio_obj.get("path") if isinstance(audio_obj, dict) else None
-            else:
-                # datasets Audio feature may return dict with 'path' before decoding
-                # Try common locations for an audio path without forcing decoding
-                if isinstance(audio_obj, dict) and audio_obj.get("path"):
-                    audio_path = audio_obj.get("path")
-                    # try to get duration from file header
-                    if decode_audio:
-                        duration = compute_duration_from_audio_obj(audio_obj)
-                else:
-                    # final fallback: try to decode using the dataset's audio decoder by calling ds[i]['audio']
-                    # but avoid reloading if already decoded
-                    if decode_audio:
-                        try:
-                            a2 = ds[i]["audio"]
-                            duration = compute_duration_from_audio_obj(a2)
-                            if isinstance(a2, dict) and a2.get("path"):
-                                audio_path = a2.get("path")
-                        except Exception:
-                            duration = None
-        except Exception:
-            duration = None
-
-        rec["audio_duration_s"] = float(duration) if duration is not None else None
-        # If no explicit audio_path found, try to extract attribute 'path' from lazy object
-        if audio_path is None and audio_obj is not None:
-            audio_path = getattr(audio_obj, "path", None)
-        # If still none and path looks local (no scheme), construct HF raw URL
-        if audio_path and not urlparse(str(audio_path)).scheme:
-            audio_path = _hf_raw_file_url(dataset_id, str(audio_path))
-        rec["audio_path"] = audio_path
-
-        records.append(rec)
-
-    df = pd.DataFrame.from_records(records)
-
-    # Basic summaries printed
-    def safe_uniques(col: str):
-        if col in df.columns:
-            vals = df[col].dropna().unique()
-            return len(vals), list(vals[:10])
-        return 0, []
-
-    for c in ["exercise", "model", "speaker"]:
-        nuniq, sample = safe_uniques(c)
-        print(f"{c}: {nuniq} unique (sample {sample})")
-
-    # String length stats for exercise_id and rt
-    for c in ["exercise_id", "rt"]:
-        if c in df.columns:
-            lens = df[c].dropna().astype(str).map(len)
-            if len(lens):
-                print(f"{c} lengths -> min={int(lens.min())} max={int(lens.max())} mean={float(lens.mean()):.1f}")
-
-    # Audio duration stats
-    if "audio_duration_s" in df.columns:
-        dur = df["audio_duration_s"].dropna().astype(float)
-        if len(dur):
-            print(f"audio_duration_s -> min={dur.min():.2f}s max={dur.max():.2f}s mean={dur.mean():.2f}s")
-
-    # write outputs
-    if out_dir is not None:
-        out = Path(out_dir)
-        out.mkdir(parents=True, exist_ok=True)
-        csv_path = out / f"{dataset_id.replace('/', '_')}_{split}_summary.csv"
-        parquet_path = out / f"{dataset_id.replace('/', '_')}_{split}_summary.parquet"
-        df.to_csv(csv_path, index=False)
-        try:
-            df.to_parquet(parquet_path, index=False)
-        except Exception:
-            # parquet optional
-            pass
-        print(f"Wrote summary to: {csv_path}  (parquet: {parquet_path if parquet_path.exists() else 'skipped'})")
-
-    return df
-
-
-def summarize_from_config(config_path: str = "/home/raid/atc-c3-comms/assets/tts/src/evaluation/mos/config/config.json") -> pd.DataFrame:
-    """Read the MOS config.json and summarize all hf_utils entries into a single DataFrame.
-
-    The config is expected to contain an `hf_utils` list with objects like:
-      {"dataset_id": "user/dataset", "split": "train"}
-
-    Returns a combined DataFrame with an additional `source_dataset` and `source_split` columns.
-    """
-    cfg_path = Path(config_path)
-    if not cfg_path.exists():
-        raise FileNotFoundError(f"Config not found: {config_path}")
-    with open(cfg_path, "r") as f:
-        cfg = json.load(f)
-
-    entries = cfg.get("hf_utils", [])
-    all_dfs = []
-    for e in entries:
-        dsid = e.get("dataset_id") or e.get("dataset")
-        split = e.get("split", "train")
-        name = e.get("name", f"{dsid.replace('/', '_')}_{split}")
-        out_dir = e.get("out_dir") or cfg.get("base_dir") or DEFAULT_OUTDIR
-        decode_audio = bool(e.get("decode_audio", False))
-
-        df = summarize_dataset(dsid, split=split, out_dir=out_dir, decode_audio=decode_audio)
-        df["source_dataset"] = dsid
-        df["source_split"] = split
-        df["source_name"] = name
-        all_dfs.append(df)
-
-    if all_dfs:
-        return pd.concat(all_dfs, ignore_index=True)
-    else:
-        return pd.DataFrame()
-
-
-def get_mos_dataset_summary(split: str = DEFAULT_SPLIT, out_dir: Optional[str] = DEFAULT_OUTDIR, decode_audio: bool = True) -> pd.DataFrame:
-    """Convenience wrapper that summarizes the MOS dataset configured for this repo.
-
-    Returns a pandas DataFrame with the summary and writes CSV/Parquet to `out_dir`.
-    """
-    return summarize_dataset(DATASET_ID, split=split, out_dir=out_dir, decode_audio=decode_audio)

config/config.json

@@ -1,13 +0,0 @@
-{
-  "base_dir": "assets/tts/src/evaluation/outputs",
-  "axite_script": "assets/tts/src/evaluation/axite.json",
-  "n_mos": 10,
-  "n_abmm": 4,
-  "n_abgf": 4,
-  "hf_utils": [
-    {
-      "dataset_id": "aether-raid/axite-tts",
-      "split": "train"
-    }
-  ]
-}

frontend/app.py

@@ -0,0 +1,511 @@
+"""
+ATC TTS MOS Evaluation App
+Main entrypoint wiring backend + frontend pages.
+"""
+
+import time
+import gradio as gr
+
+import os
+import sys
+
+# Add parent directory (mos) to path so we can import backend
+mos_dir = os.path.dirname(os.path.dirname(__file__))
+sys.path.insert(0, mos_dir)
+
+# Backend pieces
+from backend.data_manager import DataManager
+from backend.session_manager import SessionManager
+from backend.hf_logging import push_session_to_hub
+from backend.models import get_display_model_name, audio_to_base64_url
+
+# Frontend styling + pages
+from frontend.css import CSS
+from frontend.pages.intro import build_intro_page
+from frontend.pages.samples import build_sample_page
+from frontend.pages.mos import build_mos_page, render_mos_html
+from frontend.pages.ab_model import build_ab_model_page, render_ab_model_html
+from frontend.pages.ab_gender import build_ab_gender_page, render_ab_gender_html
+from frontend.pages.conclusion import build_conclusion_page
+from frontend.pages.thank_you import build_thank_you_page
+
+
+def create_app(data_manager, session_manager):
+    with gr.Blocks(title="ATC TTS Evaluation", css=CSS) as app:
+        # Global state
+        session_state = gr.State()
+
+        # Hidden textboxes used by the JS collectors on MOS / AB pages
+        mos_data_textbox = gr.Textbox(
+            value="", visible=False, elem_id="mos_data_store"
+        )
+        ab_data_textbox = gr.Textbox(
+            value="", visible=False, elem_id="ab_data_store"
+        )
+
+        # Build all pages
+        intro_page, start_btn = build_intro_page()
+
+        (
+            sample_page,
+            back_to_intro_btn,
+            continue_samples_btn,
+            sample_audio_container,
+        ) = build_sample_page()
+
+        (
+            mos_page,
+            back_to_samples_btn,
+            continue_mos_btn,
+            mos_dynamic_content
+        ) = build_mos_page()
+
+        (
+            ab_model_page,
+            back_to_mos_btn,
+            continue_ab_model_btn,
+            ab_model_dynamic_content,
+        ) = build_ab_model_page()
+
+        (
+            ab_gender_page,
+            back_to_ab_model_btn,
+            continue_ab_gender_btn,
+            ab_gender_dynamic_content,
+        ) = build_ab_gender_page()
+
+        (
+            conclusion_page,
+            back_to_ab_gender_btn,
+            export_btn,
+            overall_feedback,
+            final_comments,
+        ) = build_conclusion_page()
+
+        thank_you_page = build_thank_you_page()
+
+        # =========================
+        # Event handlers
+        # =========================
+
+        def start_evaluation():
+            """Create a new session and populate sample page with sample clips."""
+            try:
+                session = session_manager.create_session()
+                print(f"[INFO] Session created: {session['session_id']}")
+                print(f"[INFO] Sample clips: {len(session.get('sample_clips', []))}")
+            except Exception as e:
+                print(f"[ERROR] Error creating session: {e}")
+                session = {
+                    "session_id": "fallback",
+                    "sample_clips": [],
+                    "mos_clips": [],
+                    "ab_model_pairs": [],
+                    "ab_gender_pairs": [],
+                    "created_at": time.time(),
+                    "completed": False,
+                }
+
+            # Dynamically render the sample clips into the sample_audio_container
+            with sample_audio_container:
+                sample_clips = session.get("sample_clips", [])
+                if len(sample_clips) == 0:
+                    with gr.Group(elem_classes=["clip-container"]):
+                        gr.Markdown("### No sample clips available")
+                        gr.Markdown(
+                            "The dataset appears to be empty or not loading correctly. "
+                            "You can still navigate through the interface."
+                        )
+                else:
+                    for i, clip in enumerate(sample_clips, 1):
+                        with gr.Group(elem_classes=["clip-container"]):
+                            gr.Markdown(f"### Sample {i}: TTS Generated Audio")
+
+                            with gr.Group(elem_classes=["audio-info"]):
+                                gr.HTML(
+                                    f"""
+                                    <div>
+                                        <span class="info-label">Model:</span>
+                                        <span class="info-value">{get_display_model_name(clip.model)}</span><br>
+                                        <span class="info-label">Speaker:</span>
+                                        <span class="info-value">{clip.speaker.title()} Voice</span><br>
+                                    </div>
+                                    """
+                                )
+
+                            audio_src = audio_to_base64_url(clip.audio_url) or ""
+                            gr.HTML(
+                                f"""
+                                <div style="background: #1f2937; padding: 15px; border-radius: 8px; margin-bottom: 15px;">
+                                    <audio controls style="width: 100%; height: 54px;">
+                                        <source src="{audio_src}" type="audio/wav">
+                                        Audio not available
+                                    </audio>
+                                </div>
+                                """
+                            )
+
+                            with gr.Group(elem_classes=["transcript-box"]):
+                                gr.Markdown(f"**Transcript:** *{clip.transcript}*")
+
+            return (
+                gr.update(visible=False),  # hide intro
+                gr.update(visible=True),   # show sample page
+                session,                   # update session_state
+            )
+
+        def show_mos_page(session):
+            """Navigate from sample page to MOS page and render MOS HTML."""
+            if not session:
+                return gr.update(), gr.update(), ""
+
+            mos_html = render_mos_html(session)
+            return (
+                gr.update(visible=False),   # hide sample page
+                gr.update(visible=True),    # show MOS page
+                mos_html,                   # set MOS HTML content
+            )
+
+        def continue_from_mos_to_ab_model(session, mos_data_json):
+            """
+            Process MOS data (collected via JavaScript) and move to Model-vs-Model page.
+            """
+            print(f"[DEBUG] continue_from_mos_to_ab_model called")
+            print(f"[DEBUG] MOS data JSON received: '{mos_data_json}'")
+            session_manager.process_mos_data(session, mos_data_json)
+            ab_model_html = render_ab_model_html(session)
+            return (
+                gr.update(visible=False),   # hide MOS page
+                gr.update(visible=True),    # show AB model page
+                ab_model_html,              # set AB model HTML content
+            )
+
+        def continue_from_ab_model_to_ab_gender(session, ab_data_json):
+            """
+            Process A/B model comparison data (collected via JavaScript) and move to Gender A/B page.
+            """
+            print(f"[DEBUG] continue_from_ab_model_to_ab_gender called")
+            print(f"[DEBUG] AB data JSON received: '{ab_data_json}'")
+            session_manager.process_ab_data(session, ab_data_json)
+            ab_gender_html = render_ab_gender_html(session)
+            return (
+                gr.update(visible=False),   # hide AB model page
+                gr.update(visible=True),    # show AB gender page
+                ab_gender_html,             # set AB gender HTML content
+            )
+
+        def complete_evaluation_with_ab_gender_data(session, ab_data_json):
+            """
+            Process A/B gender comparison data (collected via JavaScript) and move to conclusion page.
+            """
+            session_manager.process_ab_data(session, ab_data_json)
+            if session:
+                session["completed"] = True
+            return (
+                gr.update(visible=False),   # hide AB gender page
+                gr.update(visible=True),    # show conclusion page
+            )
+
+        def export_results_with_data_processing(
+            session,
+            overall_preference,
+            comments,
+            mos_data_json,
+            ab_data_json,
+        ):
+            """
+            Final submit: process any remaining MOS/AB data (collected via JavaScript), 
+            save overall feedback, export the session, and push to HF.
+            """
+            if not session:
+                return gr.update(), gr.update()
+
+            # Ensure all MOS / AB ratings are processed
+            session_manager.process_mos_data(session, mos_data_json)
+            session_manager.process_ab_data(session, ab_data_json)
+
+            # Save overall feedback
+            if overall_preference or comments:
+                feedback_response = {
+                    "session_id": session["session_id"],
+                    "overall_preference": overall_preference,
+                    "final_comments": comments,
+                    "timestamp": time.time(),
+                }
+                session_manager.save_response("feedback", feedback_response)
+
+            # Export and push to Hub
+            export_data = session_manager.export_session(session["session_id"])
+            try:
+                push_session_to_hub(session["session_id"], export_data)
+                print(
+                    f"[INFO] Successfully submitted session {session['session_id']} to Hub"
+                )
+            except Exception as e:
+                print(
+                    f"[WARN] Failed to push session {session['session_id']} to Hub: {e}"
+                )
+
+            return (
+                gr.update(visible=False),  # hide conclusion page
+                gr.update(visible=True),   # show thank you page
+            )
+
+        # =========================
+        # Wire buttons to handlers
+        # =========================
+
+        # Intro → Samples
+        start_btn.click(
+            start_evaluation,
+            inputs=[],
+            outputs=[intro_page, sample_page, session_state],
+        )
+
+        # Samples → MOS
+        continue_samples_btn.click(
+            show_mos_page,
+            inputs=[session_state],
+            outputs=[sample_page, mos_page, mos_dynamic_content],
+        )
+
+        # MOS → AB Model (process MOS first)
+        continue_mos_btn.click(
+            fn=continue_from_mos_to_ab_model,
+            inputs=[session_state, mos_data_textbox],
+            outputs=[mos_page, ab_model_page, ab_model_dynamic_content],
+            js="""
+            (session_data, current_mos_data) => {
+                // Collect MOS data from the current page
+                const ratings = {};
+                
+                const selects = document.querySelectorAll('select[data-clip-id]');
+                const checkboxes = document.querySelectorAll('input[type="checkbox"][data-clip-id]');
+                const textareas = document.querySelectorAll('textarea[data-clip-id]');
+                
+                console.log('[DEBUG] Found selects:', selects.length);
+                console.log('[DEBUG] Found checkboxes:', checkboxes.length);
+                console.log('[DEBUG] Found textareas:', textareas.length);
+                
+                selects.forEach(select => {
+                    const clipId = select.getAttribute('data-clip-id');
+                    const dimension = select.getAttribute('data-dimension');
+                    if (!ratings[clipId]) ratings[clipId] = {};
+                    ratings[clipId][dimension] = select.value;
+                    console.log('[DEBUG] Select:', clipId, dimension, select.value);
+                });
+                
+                checkboxes.forEach(checkbox => {
+                    const clipId = checkbox.getAttribute('data-clip-id');
+                    const dimension = checkbox.getAttribute('data-dimension');
+                    if (!ratings[clipId]) ratings[clipId] = {};
+                    ratings[clipId][dimension] = checkbox.checked;
+                    console.log('[DEBUG] Checkbox:', clipId, dimension, checkbox.checked);
+                });
+                
+                textareas.forEach(textarea => {
+                    const clipId = textarea.getAttribute('data-clip-id');
+                    const dimension = textarea.getAttribute('data-dimension');
+                    if (!ratings[clipId]) ratings[clipId] = {};
+                    ratings[clipId][dimension] = textarea.value;
+                    console.log('[DEBUG] Textarea:', clipId, dimension, textarea.value);
+                });
+                
+                console.log('[DEBUG] Final ratings object:', ratings);
+                const ratingsJson = JSON.stringify(ratings);
+                console.log('[DEBUG] Ratings JSON:', ratingsJson);
+                
+                return [session_data, ratingsJson];
+            }
+            """
+        )
+
+        # AB Model → AB Gender (process AB model first)
+        continue_ab_model_btn.click(
+            continue_from_ab_model_to_ab_gender,
+            inputs=[session_state, ab_data_textbox],
+            outputs=[ab_model_page, ab_gender_page, ab_gender_dynamic_content],
+            js="""
+            (session_data, current_ab_data) => {
+                // Collect A/B data from the current page
+                const ratings = {};
+                
+                const radios = document.querySelectorAll('input[type="radio"]:checked');
+                const checkboxes = document.querySelectorAll('input[type="checkbox"][data-comparison-id]');
+                const textareas = document.querySelectorAll('textarea[data-comparison-id]');
+                
+                console.log('[DEBUG] Found radios:', radios.length);
+                console.log('[DEBUG] Found checkboxes:', checkboxes.length);
+                console.log('[DEBUG] Found textareas:', textareas.length);
+                
+                radios.forEach(radio => {
+                    const compId = radio.getAttribute('data-comparison-id');
+                    const clipAId = radio.getAttribute('data-clip-a-id');
+                    const clipBId = radio.getAttribute('data-clip-b-id');
+                    const compType = radio.getAttribute('data-type');
+                    
+                    if (!ratings[compId]) ratings[compId] = {};
+                    ratings[compId].clip_a_id = clipAId;
+                    ratings[compId].clip_b_id = clipBId;
+                    ratings[compId].comparison_type = compType;
+                    ratings[compId].choice = radio.value;
+                    console.log('[DEBUG] Radio:', compId, radio.value);
+                });
+                
+                checkboxes.forEach(checkbox => {
+                    const compId = checkbox.getAttribute('data-comparison-id');
+                    const dimension = checkbox.getAttribute('data-dimension');
+                    if (!ratings[compId]) ratings[compId] = {};
+                    ratings[compId][dimension] = checkbox.checked;
+                    console.log('[DEBUG] Checkbox:', compId, dimension, checkbox.checked);
+                });
+                
+                textareas.forEach(textarea => {
+                    const compId = textarea.getAttribute('data-comparison-id');
+                    const dimension = textarea.getAttribute('data-dimension');
+                    if (!ratings[compId]) ratings[compId] = {};
+                    ratings[compId][dimension] = textarea.value;
+                    console.log('[DEBUG] Textarea:', compId, dimension, textarea.value);
+                });
+                
+                console.log('[DEBUG] Final A/B ratings object:', ratings);
+                const ratingsJson = JSON.stringify(ratings);
+                console.log('[DEBUG] A/B Ratings JSON:', ratingsJson);
+                
+                return [session_data, ratingsJson];
+            }
+            """
+        )
+
+        # AB Gender → Conclusion (process AB gender data)
+        continue_ab_gender_btn.click(
+            complete_evaluation_with_ab_gender_data,
+            inputs=[session_state, ab_data_textbox],
+            outputs=[ab_gender_page, conclusion_page],
+            js="""
+            (session_data, current_ab_data) => {
+                // Collect A/B gender data from the current page
+                const ratings = {};
+                
+                const radios = document.querySelectorAll('input[type="radio"]:checked');
+                const checkboxes = document.querySelectorAll('input[type="checkbox"][data-comparison-id]');
+                const textareas = document.querySelectorAll('textarea[data-comparison-id]');
+                
+                console.log('[DEBUG] Found radios:', radios.length);
+                console.log('[DEBUG] Found checkboxes:', checkboxes.length);
+                console.log('[DEBUG] Found textareas:', textareas.length);
+                
+                radios.forEach(radio => {
+                    const compId = radio.getAttribute('data-comparison-id');
+                    const clipAId = radio.getAttribute('data-clip-a-id');
+                    const clipBId = radio.getAttribute('data-clip-b-id');
+                    const compType = radio.getAttribute('data-type');
+                    
+                    if (!ratings[compId]) ratings[compId] = {};
+                    ratings[compId].clip_a_id = clipAId;
+                    ratings[compId].clip_b_id = clipBId;
+                    ratings[compId].comparison_type = compType;
+                    ratings[compId].choice = radio.value;
+                    console.log('[DEBUG] Radio:', compId, radio.value);
+                });
+                
+                checkboxes.forEach(checkbox => {
+                    const compId = checkbox.getAttribute('data-comparison-id');
+                    const dimension = checkbox.getAttribute('data-dimension');
+                    if (!ratings[compId]) ratings[compId] = {};
+                    ratings[compId][dimension] = checkbox.checked;
+                    console.log('[DEBUG] Checkbox:', compId, dimension, checkbox.checked);
+                });
+                
+                textareas.forEach(textarea => {
+                    const compId = textarea.getAttribute('data-comparison-id');
+                    const dimension = textarea.getAttribute('data-dimension');
+                    if (!ratings[compId]) ratings[compId] = {};
+                    ratings[compId][dimension] = textarea.value;
+                    console.log('[DEBUG] Textarea:', compId, dimension, textarea.value);
+                });
+                
+                console.log('[DEBUG] Final A/B gender ratings object:', ratings);
+                const ratingsJson = JSON.stringify(ratings);
+                console.log('[DEBUG] A/B Gender Ratings JSON:', ratingsJson);
+                
+                return [session_data, ratingsJson];
+            }
+            """
+        )
+
+        # Conclusion → Thank You (process any remaining data + export)
+        export_btn.click(
+            export_results_with_data_processing,
+            inputs=[
+                session_state,
+                overall_feedback,
+                final_comments,
+                mos_data_textbox,
+                ab_data_textbox,
+            ],
+            outputs=[conclusion_page, thank_you_page],
+        )
+
+        # Back navigation
+        back_to_intro_btn.click(
+            lambda: (gr.update(visible=True), gr.update(visible=False)),
+            inputs=[],
+            outputs=[intro_page, sample_page],
+        )
+
+        back_to_samples_btn.click(
+            lambda: (gr.update(visible=False), gr.update(visible=True)),
+            inputs=[],
+            outputs=[mos_page, sample_page],
+        )
+
+        back_to_mos_btn.click(
+            lambda: (gr.update(visible=False), gr.update(visible=True)),
+            inputs=[],
+            outputs=[ab_model_page, mos_page],
+        )
+
+        back_to_ab_model_btn.click(
+            lambda: (gr.update(visible=False), gr.update(visible=True)),
+            inputs=[],
+            outputs=[ab_gender_page, ab_model_page],
+        )
+
+        back_to_ab_gender_btn.click(
+            lambda: (gr.update(visible=False), gr.update(visible=True)),
+            inputs=[],
+            outputs=[conclusion_page, ab_gender_page],
+        )
+
+    return app
+
+
+if __name__ == "__main__":
+    print("Starting ATC TTS MOS Evaluation...")
+
+    try:
+        data_manager = DataManager()
+        session_manager = SessionManager(data_manager)
+        clips = data_manager.load_clips()
+        print(f"Dataset ready with {len(clips)} clips")
+
+        models = {clip.model for clip in clips}
+        speakers = {clip.speaker for clip in clips}
+        exercises = {clip.exercise for clip in clips}
+
+        print(f"Models: {', '.join(models)}")
+        print(f"Speakers: {', '.join(speakers)}")
+        print(f"Exercises: {len(exercises)} unique exercises")
+    except Exception as e:
+        print(f"[ERROR] Error loading data: {e}")
+        print("Please check your dataset access and try again.")
+        raise SystemExit(1)
+
+    app = create_app(data_manager, session_manager)
+    app.launch(
+        server_name="0.0.0.0",
+        server_port=7860,
+        share=False,
+        show_error=True,
+    )

frontend/css.py

@@ -0,0 +1,160 @@
+# frontend/css.py
+
+CSS = """
+.gradio-container {
+    max-width: 1200px !important;
+    margin: auto;
+    background-color: #1a1a1a !important;
+    color: #e5e5e5 !important;
+}
+
+.dark .gradio-container {
+    background-color: #1a1a1a !important;
+}
+
+.section-header {
+    background: linear-gradient(135deg, #2563eb, #1d4ed8) !important;
+    padding: 25px;
+    border-radius: 12px;
+    border-left: 6px solid #60a5fa;
+    margin: 25px 0;
+    color: #ffffff !important;
+    box-shadow: 0 4px 12px rgba(37, 99, 235, 0.3);
+}
+
+.section-header h2, .section-header h3 {
+    color: #ffffff !important;
+    margin-bottom: 10px;
+}
+
+.section-header p {
+    color: #e0e7ff !important;
+    opacity: 0.95;
+}
+
+.clip-container {
+    background: #2d2d2d !important;
+    padding: 20px;
+    border-radius: 12px;
+    border: 2px solid #3f3f46;
+    margin: 15px 0;
+    box-shadow: 0 4px 8px rgba(0, 0, 0, 0.3);
+}
+
+.clip-container:hover {
+    border-color: #60a5fa;
+    box-shadow: 0 6px 16px rgba(96, 165, 250, 0.2);
+}
+
+.comparison-container {
+    background: #2a2a2a !important;
+    padding: 25px;
+    border-radius: 12px;
+    border: 2px solid #4f46e5;
+    margin: 20px 0;
+    box-shadow: 0 4px 12px rgba(79, 70, 229, 0.2);
+}
+
+.reference-container {
+    background: linear-gradient(135deg, #059669, #047857) !important;
+    padding: 20px;
+    border-radius: 12px;
+    border: 2px solid #10b981;
+    margin: 15px 0;
+    box-shadow: 0 4px 12px rgba(16, 185, 129, 0.3);
+}
+
+.reference-container h4, .reference-container p {
+    color: #ffffff !important;
+}
+
+.audio-info {
+    background: #374151 !important;
+    padding: 15px;
+    border-radius: 8px;
+    border-left: 4px solid #60a5fa;
+    margin: 10px 0;
+    font-family: 'Courier New', monospace;
+}
+
+.audio-info .info-label {
+    color: #60a5fa !important;
+    font-weight: bold;
+    font-size: 0.9em;
+}
+
+.audio-info .info-value {
+    color: #e5e5e5 !important;
+    margin-left: 10px;
+}
+
+.transcript-box {
+    background: #1f2937 !important;
+    padding: 15px;
+    border-radius: 8px;
+    border: 1px solid #4b5563;
+    font-style: italic;
+    color: #d1d5db !important;
+    line-height: 1.6;
+}
+
+.progress-text {
+    background: linear-gradient(135deg, #1e40af, #1d4ed8) !important;
+    border-left: 4px solid #60a5fa !important;
+    padding: 12px 16px;
+    border-radius: 8px;
+    font-weight: 600;
+    color: #ffffff !important;
+    box-shadow: 0 2px 8px rgba(30, 64, 175, 0.3);
+}
+
+.gr-button {
+    background: linear-gradient(135deg, #2563eb, #1d4ed8) !important;
+    border: none !important;
+    color: #ffffff !important;
+    padding: 12px 24px !important;
+    border-radius: 8px !important;
+    font-weight: 600 !important;
+    transition: all 0.3s ease !important;
+}
+
+.gr-button:hover {
+    background: linear-gradient(135deg, #1d4ed8, #1e40af) !important;
+    transform: translateY(-2px);
+    box-shadow: 0 6px 16px rgba(37, 99, 235, 0.4) !important;
+}
+
+.gr-button.secondary {
+    background: linear-gradient(135deg, #6b7280, #4b5563) !important;
+    color: #ffffff !important;
+}
+
+.gr-button.secondary:hover {
+    background: linear-gradient(135deg, #4b5563, #374151) !important;
+    box-shadow: 0 6px 16px rgba(107, 114, 128, 0.3) !important;
+}
+
+.gr-textbox, .gr-slider, .gr-radio, .gr-accordion {
+    background-color: #2d2d2d !important;
+    border-color: #4b5563 !important;
+    color: #e5e5e5 !important;
+}
+
+h1, h2, h3, h4, h5, h6, p, span, div {
+    color: #e5e5e5 !important;
+}
+
+a {
+    color: #60a5fa !important;
+}
+
+a:hover {
+    color: #93c5fd !important;
+}
+
+.gr-accordion .label-wrap {
+    background-color: #374151 !important;
+    color: #e5e5e5 !important;
+    border-color: #4b5563 !important;
+}
+"""

frontend/pages/__init__.py

@@ -0,0 +1,48 @@
+# frontend/pages/intro.py
+
+import gradio as gr
+
+
+def build_intro_page():
+    """Builds the intro page and returns (container, start_button)."""
+    with gr.Column(visible=True) as intro_page:
+        gr.Markdown(
+            """
+        # ATC TTS Evaluation Study
+
+        You will evaluate short ATC/aviation clips from three TTS systems: Model A, Model B, and Model C.
+
+        <div class="section-header">
+        <h3>Evaluation Process (5 Sections):</h3>
+        <ol>
+        <li><strong>Reference Audio</strong> - Listen to sample clips to calibrate expectations</li>
+        <li><strong>MOS Block</strong> - Rate clips across several quality dimensions (9-12 sections; mix models and genders)</li>
+        <li><strong>AB Model Comparisons</strong> - Model vs Model comparisons (same gender)</li>
+        <li><strong>AB Gender Comparisons</strong> - Male vs Female voice comparisons (same model)</li>
+        <li><strong>Conclusion</strong> - Best overall model and additional comments</li>
+        </ol>
+        </div>
+
+        Please use headphones in a quiet place, rate what you hear.
+
+        ### What you will do
+
+        - Rate each clip on five MOS dimensions (1–5).
+        - Do a few A/B comparisons (two clips of the same prompt).
+        - Some clips are Male voice, others Female; you may also compare Male vs Female for the same model.
+
+        ### What to listen for (quick checklist)
+
+        - **Clarity**: Can you understand every word, number, call-sign, waypoint, runway, and altitude?
+        - **Pronunciation**: Are aviation terms spoken correctly (e.g., "flight level three zero zero")?
+        - **Prosody (Intonation/Rhythm)**: Is pacing appropriate for ATC (brisk, not rushed; natural stress/pauses)?
+        - **Naturalness**: Does it sound human-like (no robotic artifacts, buzz, hiss, warble)?
+        - **Overall**: Your total impression for ATC use.
+
+        **Estimated time**: ~10–15 minutes. Responses are anonymous and used only to improve the models.
+        """
+        )
+
+        start_btn = gr.Button("Start Evaluation", variant="primary")
+
+    return intro_page, start_btn

frontend/pages/ab_gender.py

@@ -0,0 +1,238 @@
+# frontend/pages/ab_gender.py
+
+import gradio as gr
+from typing import Any, Dict
+
+from backend.models import get_display_model_name, audio_to_base64_url
+
+
+def build_ab_gender_page():
+    """
+    Build the Gender A/B comparison page.
+
+    Returns:
+        ab_gender_page: Column container
+        back_btn: button to go back to model comparisons
+        continue_btn: button to go to conclusion
+        ab_gender_dynamic_content: HTML component where dynamic comparison blocks are rendered
+    """
+    with gr.Column(visible=False) as ab_gender_page:
+        with gr.Group(elem_classes=["progress-text"]):
+            gr.Markdown("### Section 4 of 5: Male vs Female Voice Comparisons")
+
+        gr.Markdown(
+            """
+        <div class="section-header">
+        <h2>Gender Voice Comparison</h2>
+        <p>Compare male vs female voices for the same model and content.</p>
+        <p>Consider which voice is more suitable for ATC communication.</p>
+        </div>
+        """
+        )
+
+        ab_gender_dynamic_content = gr.HTML(
+            value="<p>Loading gender comparisons...</p>", visible=True
+        )
+
+        with gr.Row():
+            back_btn = gr.Button(
+                "Back to Model Comparisons", variant="secondary"
+            )
+            continue_btn = gr.Button(
+                "Complete Evaluation", variant="primary"
+            )
+
+    return ab_gender_page, back_btn, continue_btn, ab_gender_dynamic_content
+
+
+def render_ab_gender_html(session: Dict[str, Any]) -> str:
+    """
+    Render the HTML for Gender A/B comparisons based on session data.
+
+    Uses session['ab_gender_pairs'], which should be a list of (male_clip, female_clip) tuples.
+    """
+    if not session:
+        return ""
+
+    gender_pairs = session.get("ab_gender_pairs", [])
+
+    if len(gender_pairs) == 0:
+        return """
+        <div style="text-align: center; padding: 40px; background: #1f2937; border-radius: 12px; border: 2px solid #374151; margin: 20px 0;">
+            <h3 style="color: #9ca3af; margin-bottom: 10px;">No Gender Comparisons Available</h3>
+            <p style="color: #6b7280;">There are no male/female voice pairs to compare in your session.</p>
+            <p style="color: #6b7280;">Click "Complete Evaluation" to proceed to the final step.</p>
+        </div>
+        """
+
+    # Initialize html_content and add JavaScript collector (same as AB model page)
+    html_content = """
+    <script>
+    function collectABData() {
+        const ratings = {};
+        
+        const radios = document.querySelectorAll('input[type="radio"]:checked');
+        const checkboxes = document.querySelectorAll('input[type="checkbox"][data-comparison-id]');
+        const textareas = document.querySelectorAll('textarea[data-comparison-id]');
+        
+        radios.forEach(radio => {
+            const compId = radio.getAttribute('data-comparison-id');
+            const clipAId = radio.getAttribute('data-clip-a-id');
+            const clipBId = radio.getAttribute('data-clip-b-id');
+            const compType = radio.getAttribute('data-type');
+            
+            if (!ratings[compId]) ratings[compId] = {};
+            ratings[compId].clip_a_id = clipAId;
+            ratings[compId].clip_b_id = clipBId;
+            ratings[compId].comparison_type = compType;
+            ratings[compId].choice = radio.value;
+        });
+        
+        checkboxes.forEach(checkbox => {
+            const compId = checkbox.getAttribute('data-comparison-id');
+            const dimension = checkbox.getAttribute('data-dimension');
+            if (!ratings[compId]) ratings[compId] = {};
+            ratings[compId][dimension] = checkbox.checked;
+        });
+        
+        textareas.forEach(textarea => {
+            const compId = textarea.getAttribute('data-comparison-id');
+            const dimension = textarea.getAttribute('data-dimension');
+            if (!ratings[compId]) ratings[compId] = {};
+            ratings[compId][dimension] = textarea.value;
+        });
+        
+        // Find the hidden textbox and update it - try both possible selectors
+        let abDataElement = document.querySelector('#ab_data_store textarea');
+        if (!abDataElement) {
+            abDataElement = document.querySelector('#ab_data_store input');
+        }
+        
+        console.log('[DEBUG] collectABData called (Gender comparison)');
+        console.log('[DEBUG] Found', Object.keys(ratings).length, 'comparisons');
+        console.log('[DEBUG] Ratings object:', ratings);
+        console.log('[DEBUG] AB data element found:', abDataElement);
+        
+        if (abDataElement) {
+            abDataElement.value = JSON.stringify(ratings);
+            console.log('[DEBUG] Updated hidden textbox with:', abDataElement.value);
+            abDataElement.dispatchEvent(new Event('input', { bubbles: true }));
+        } else {
+            console.error('[ERROR] Could not find AB data textbox element');
+        }
+    }
+    </script>
+    """
+
+    for i, (male_clip, female_clip) in enumerate(gender_pairs, 1):
+        male_audio_url = audio_to_base64_url(male_clip.audio_url) or ""
+        female_audio_url = audio_to_base64_url(female_clip.audio_url) or ""
+
+        html_content += f"""
+<div class="comparison-container" style="background: #2a2a2a; padding: 25px; border-radius: 12px; border: 2px solid #059669; margin: 20px 0;">
+    <h3>Gender Comparison {i}: {get_display_model_name(male_clip.model)} Male vs Female</h3>
+    
+    <div style="background: #1e293b; padding: 15px; border-radius: 8px; margin: 15px 0;">
+        <p style="margin: 0; color: #cbd5e1; font-style: italic;">
+            <strong>Transcript:</strong> "{male_clip.transcript}"
+        </p>
+    </div>
+
+    <div style="display: grid; grid-template-columns: 1fr 1fr; gap: 20px; margin: 20px 0;">
+        <div style="padding: 20px; background: #1e3a8a; border-radius: 8px; border: 2px solid #3b82f6;">
+            <h4>Male Voice</h4>
+            <audio controls style="width: 100%; margin-bottom: 15px;">
+                <source src="{male_audio_url}" type="audio/wav">
+                Audio not available
+            </audio>
+        </div>
+
+        <div style="padding: 20px; background: #7c2d92; border-radius: 8px; border: 2px solid #ec4899;">
+            <h4>Female Voice</h4>
+            <audio controls style="width: 100%; margin-bottom: 15px;">
+                <source src="{female_audio_url}" type="audio/wav">
+                Audio not available
+            </audio>
+        </div>
+    </div>
+
+    <div style="background: #2d3748; padding: 20px; border-radius: 8px; border: 1px solid #059669; margin-top: 20px;">
+        <h4 style="color: #e5e5e5; margin: 0 0 15px 0;">Which voice sounds better for ATC use?</h4>
+        <div style="display: flex; flex-direction: column; gap: 10px;">
+            <label style="color: #cbd5e1; cursor: pointer;">
+                <input type="radio" name="ab_gender_{i}" value="male"
+                       data-comparison-id="{i}"
+                       data-clip-a-id="{male_clip.id}"
+                       data-clip-b-id="{female_clip.id}"
+                       data-type="gender_vs_gender"
+                       onchange="collectABData()"
+                       style="margin-right: 10px;">
+                Male voice sounds better
+            </label>
+            <label style="color: #cbd5e1; cursor: pointer;">
+                <input type="radio" name="ab_gender_{i}" value="female"
+                       data-comparison-id="{i}"
+                       data-clip-a-id="{male_clip.id}"
+                       data-clip-b-id="{female_clip.id}"
+                       data-type="gender_vs_gender"
+                       onchange="collectABData()"
+                       style="margin-right: 10px;">
+                Female voice sounds better
+            </label>
+            <label style="color: #cbd5e1; cursor: pointer;">
+                <input type="radio" name="ab_gender_{i}" value="tie"
+                       data-comparison-id="{i}"
+                       data-clip-a-id="{male_clip.id}"
+                       data-clip-b-id="{female_clip.id}"
+                       data-type="gender_vs_gender"
+                       onchange="collectABData()"
+                       style="margin-right: 10px;">
+                Both voices sound equally good (tie)
+            </label>
+            
+            <div style="margin-top: 15px; padding: 15px; background: #451a03; border-radius: 8px; border: 2px solid #92400e;">
+                <h5 style="color: #fbbf24; margin: 0 0 10px 0; font-weight: bold;">Gender Mismatch Check:</h5>
+                <label style="color: #fbbf24; cursor: pointer; display: flex; align-items: center; margin-bottom: 8px;">
+                    <input type="checkbox"
+                           data-comparison-id="{i}"
+                           data-clip-a-id="{male_clip.id}"
+                           data-clip-b-id="{female_clip.id}"
+                           data-type="gender_vs_gender"
+                           data-dimension="gender_mismatch_male"
+                           onchange="collectABData()"
+                           style="margin-right: 10px; transform: scale(1.2);">
+                    ⚠️ {get_display_model_name(male_clip.model)} (male voice) sounds wrong
+                </label>
+                <label style="color: #fbbf24; cursor: pointer; display: flex; align-items: center;">
+                    <input type="checkbox"
+                           data-comparison-id="{i}"
+                           data-clip-a-id="{male_clip.id}"
+                           data-clip-b-id="{female_clip.id}"
+                           data-type="gender_vs_gender"
+                           data-dimension="gender_mismatch_female"
+                           onchange="collectABData()"
+                           style="margin-right: 10px; transform: scale(1.2);">
+                    ⚠️ {get_display_model_name(female_clip.model)} (female voice) sounds wrong
+                </label>
+            </div>
+            
+            <div style="margin-top: 15px; padding-top: 10px; border-top: 1px solid #059669;">
+                <label style="color: #cbd5e1; display: block; margin-bottom: 5px;">
+                    <strong>Comments (optional):</strong>
+                </label>
+                <textarea data-comparison-id="{i}"
+                          data-clip-a-id="{male_clip.id}"
+                          data-clip-b-id="{female_clip.id}"
+                          data-type="gender_vs_gender"
+                          data-dimension="comment"
+                          onchange="collectABData()"
+                          placeholder="Why did you choose this option? Any specific observations?"
+                          style="width: 100%; padding: 8px; background: #1f2937; color: #e5e5e5; border: 1px solid #059669; border-radius: 4px; resize: vertical; min-height: 60px; font-size: 13px;"
+                          rows="3"></textarea>
+            </div>
+        </div>
+    </div>
+</div>
+"""
+
+    return html_content

frontend/pages/ab_model.py

@@ -0,0 +1,240 @@
+# frontend/pages/ab_model.py
+
+import gradio as gr
+from typing import Any, Dict
+
+from backend.models import get_display_model_name, audio_to_base64_url
+
+
+def build_ab_model_page():
+    """
+    Build the Model vs Model A/B comparison page.
+
+    Returns:
+        ab_model_page: Column container
+        back_btn: button to go back to MOS page
+        continue_btn: button to go to gender comparison page
+        ab_model_dynamic_content: HTML component where dynamic comparison blocks are rendered
+    """
+    with gr.Column(visible=False) as ab_model_page:
+        with gr.Group(elem_classes=["progress-text"]):
+            gr.Markdown("### Section 3 of 5: Model vs Model Comparisons")
+
+        gr.Markdown(
+            """
+        <div class="section-header">
+        <h2>Model vs Model Comparisons</h2>
+        <p>Compare pairs of clips with the same content but different TTS models.</p>
+        <p>Listen to both clips and decide which sounds better for ATC use.</p>
+        </div>
+        """
+        )
+
+        ab_model_dynamic_content = gr.HTML(
+            value="<p>Loading model comparisons...</p>", visible=True
+        )
+
+        with gr.Row():
+            back_btn = gr.Button(
+                "Back to Model Ratings", variant="secondary"
+            )
+            continue_btn = gr.Button(
+                "Continue to Gender Comparisons", variant="primary"
+            )
+
+    return ab_model_page, back_btn, continue_btn, ab_model_dynamic_content
+
+
+def render_ab_model_html(session: Dict[str, Any]) -> str:
+    """
+    Render the HTML for Model vs Model A/B comparisons based on session data.
+
+    Uses session['ab_model_pairs'], which should be a list of (clip_a, clip_b) tuples.
+    """
+    if not session:
+        return ""
+
+    ab_model_pairs = session.get("ab_model_pairs", [])
+
+    if len(ab_model_pairs) == 0:
+        return """
+        <div class="comparison-container" style="padding: 20px; border-radius: 12px; border: 2px solid #f59e0b; margin: 15px 0;">
+            <h3>No model comparison pairs available</h3>
+            <p>No matching content found across different models for comparison.</p>
+        </div>
+        """
+
+    html_content = ""
+
+    for i, (clip_a, clip_b) in enumerate(ab_model_pairs, 1):
+        audio_a_url = audio_to_base64_url(clip_a.audio_url) or ""
+        audio_b_url = audio_to_base64_url(clip_b.audio_url) or ""
+
+        html_content += f"""
+        <div class="comparison-container" style="background: #2a2a2a; padding: 25px; border-radius: 12px; border: 2px solid #4f46e5; margin: 20px 0;">
+            <h3>Model Comparison {i}: {get_display_model_name(clip_a.model)} vs {get_display_model_name(clip_b.model)}</h3>
+            <p><strong>Speaker:</strong> {clip_a.speaker.title()} Voice</p>
+            
+            <div style="background: #1e293b; padding: 15px; border-radius: 8px; margin: 15px 0;">
+                <p style="margin: 0; color: #cbd5e1; font-style: italic;">
+                    <strong>Transcript:</strong> "{clip_a.transcript}"
+                </p>
+            </div>
+
+            <div style="display: grid; grid-template-columns: 1fr 1fr; gap: 20px; margin: 20px 0;">
+                <div style="padding: 20px; background: #1e3a8a; border-radius: 8px; border: 2px solid #3b82f6;">
+                    <h4>Model A</h4>
+                    <audio controls style="width: 100%; margin-bottom: 15px;">
+                        <source src="{audio_a_url}" type="audio/wav">
+                        Audio not available
+                    </audio>
+                </div>
+
+                <div style="padding: 20px; background: #7c2d92; border-radius: 8px; border: 2px solid #ec4899;">
+                    <h4>Model B</h4>
+                    <audio controls style="width: 100%; margin-bottom: 15px;">
+                        <source src="{audio_b_url}" type="audio/wav">
+                        Audio not available
+                    </audio>
+                </div>
+            </div>
+
+            <div style="background: #2d3748; padding: 20px; border-radius: 8px; border: 1px solid #4f46e5; margin-top: 20px;">
+                <h4 style="color: #e5e5e5; margin: 0 0 15px 0;">Which model sounds better for ATC use?</h4>
+                <div style="display: flex; flex-direction: column; gap: 10px;">
+                    <label style="color: #cbd5e1; cursor: pointer;">
+                        <input type="radio" name="ab_model_{i}" value="A"
+                               data-comparison-id="{i}"
+                               data-clip-a-id="{clip_a.id}"
+                               data-clip-b-id="{clip_b.id}"
+                               data-type="model_vs_model"
+                               onchange="collectABData()"
+                               style="margin-right: 10px;">
+                        {get_display_model_name(clip_a.model)} sounds better
+                    </label>
+                    <label style="color: #cbd5e1; cursor: pointer;">
+                        <input type="radio" name="ab_model_{i}" value="B"
+                               data-comparison-id="{i}"
+                               data-clip-a-id="{clip_a.id}"
+                               data-clip-b-id="{clip_b.id}"
+                               data-type="model_vs_model"
+                               onchange="collectABData()"
+                               style="margin-right: 10px;">
+                        {get_display_model_name(clip_b.model)} sounds better
+                    </label>
+                    <label style="color: #cbd5e1; cursor: pointer;">
+                        <input type="radio" name="ab_model_{i}" value="tie"
+                               data-comparison-id="{i}"
+                               data-clip-a-id="{clip_a.id}"
+                               data-clip-b-id="{clip_b.id}"
+                               data-type="model_vs_model"
+                               onchange="collectABData()"
+                               style="margin-right: 10px;">
+                        Both models sound equally good (tie)
+                    </label>
+                    
+                    <div style="margin-top: 15px; padding: 15px; background: #451a03; border-radius: 8px; border: 2px solid #92400e;">
+                        <h5 style="color: #fbbf24; margin: 0 0 10px 0; font-weight: bold;">Gender Mismatch Check:</h5>
+                        <label style="color: #fbbf24; cursor: pointer; display: flex; align-items: center; margin-bottom: 8px;">
+                            <input type="checkbox"
+                                   data-comparison-id="{i}"
+                                   data-clip-a-id="{clip_a.id}"
+                                   data-clip-b-id="{clip_b.id}"
+                                   data-type="model_vs_model"
+                                   data-dimension="gender_mismatch_a"
+                                   onchange="collectABData()"
+                                   style="margin-right: 10px; transform: scale(1.2);">
+                            ⚠️ {get_display_model_name(clip_a.model)} ({clip_a.speaker} voice) is the wrong gender
+                        </label>
+                        <label style="color: #fbbf24; cursor: pointer; display: flex; align-items: center;">
+                            <input type="checkbox"
+                                   data-comparison-id="{i}"
+                                   data-clip-a-id="{clip_a.id}"
+                                   data-clip-b-id="{clip_b.id}"
+                                   data-type="model_vs_model"
+                                   data-dimension="gender_mismatch_b"
+                                   onchange="collectABData()"
+                                   style="margin-right: 10px; transform: scale(1.2);">
+                            ⚠️ {get_display_model_name(clip_b.model)} ({clip_b.speaker} voice) is the wrong gender
+                        </label>
+                    </div>
+                    
+                    <div style="margin-top: 15px; padding-top: 10px; border-top: 1px solid #4f46e5;">
+                        <label style="color: #cbd5e1; display: block; margin-bottom: 5px;">
+                            <strong>Comments (optional):</strong>
+                        </label>
+                        <textarea data-comparison-id="{i}"
+                                  data-clip-a-id="{clip_a.id}"
+                                  data-clip-b-id="{clip_b.id}"
+                                  data-type="model_vs_model"
+                                  data-dimension="comment"
+                                  onchange="collectABData()"
+                                  placeholder="Why did you choose this option? Any specific observations?"
+                                  style="width: 100%; padding: 8px; background: #1f2937; color: #e5e5e5; border: 1px solid #4f46e5; border-radius: 4px; resize: vertical; min-height: 60px; font-size: 13px;"
+                                  rows="3"></textarea>
+                    </div>
+                </div>
+            </div>
+        </div>
+        """
+
+    # Add JavaScript collector
+    html_content += """
+    <script>
+    function collectABData() {
+        const ratings = {};
+        
+        const radios = document.querySelectorAll('input[type="radio"]:checked');
+        const checkboxes = document.querySelectorAll('input[type="checkbox"][data-comparison-id]');
+        const textareas = document.querySelectorAll('textarea[data-comparison-id]');
+        
+        radios.forEach(radio => {
+            const compId = radio.getAttribute('data-comparison-id');
+            const clipAId = radio.getAttribute('data-clip-a-id');
+            const clipBId = radio.getAttribute('data-clip-b-id');
+            const compType = radio.getAttribute('data-type');
+            
+            if (!ratings[compId]) ratings[compId] = {};
+            ratings[compId].clip_a_id = clipAId;
+            ratings[compId].clip_b_id = clipBId;
+            ratings[compId].comparison_type = compType;
+            ratings[compId].choice = radio.value;
+        });
+        
+        checkboxes.forEach(checkbox => {
+            const compId = checkbox.getAttribute('data-comparison-id');
+            const dimension = checkbox.getAttribute('data-dimension');
+            if (!ratings[compId]) ratings[compId] = {};
+            ratings[compId][dimension] = checkbox.checked;
+        });
+        
+        textareas.forEach(textarea => {
+            const compId = textarea.getAttribute('data-comparison-id');
+            const dimension = textarea.getAttribute('data-dimension');
+            if (!ratings[compId]) ratings[compId] = {};
+            ratings[compId][dimension] = textarea.value;
+        });
+        
+        // Find the hidden textbox and update it - try both possible selectors
+        let abDataElement = document.querySelector('#ab_data_store textarea');
+        if (!abDataElement) {
+            abDataElement = document.querySelector('#ab_data_store input');
+        }
+        
+        console.log('[DEBUG] collectABData called (Model comparison)');
+        console.log('[DEBUG] Found', Object.keys(ratings).length, 'comparisons');
+        console.log('[DEBUG] Ratings object:', ratings);
+        console.log('[DEBUG] AB data element found:', abDataElement);
+        
+        if (abDataElement) {
+            abDataElement.value = JSON.stringify(ratings);
+            console.log('[DEBUG] Updated hidden textbox with:', abDataElement.value);
+            abDataElement.dispatchEvent(new Event('input', { bubbles: true }));
+        } else {
+            console.error('[ERROR] Could not find AB data textbox element');
+        }
+    }
+    </script>
+    """
+
+    return html_content

frontend/pages/conclusion.py

@@ -0,0 +1,45 @@
+# frontend/pages/conclusion.py
+
+import gradio as gr
+
+
+def build_conclusion_page():
+    """
+    Build the conclusion page (overall preference + comments).
+
+    Returns:
+        conclusion_page: Column container
+        back_btn: button to go back to gender comparisons
+        export_btn: button to submit results
+        overall_feedback: Radio input
+        final_comments: Textbox input
+    """
+    with gr.Column(visible=False) as conclusion_page:
+        with gr.Group(elem_classes=["progress-text"]):
+            gr.Markdown("### Section 5 of 5: Evaluation Complete")
+
+        overall_feedback = gr.Radio(
+            choices=[
+                "Model A was consistently best",
+                "Model B was consistently best",
+                "Model C was consistently best",
+                "Quality varied significantly",
+                "All models were similar quality",
+            ],
+            label="Overall, which TTS system performed best?",
+            value=None,
+        )
+
+        final_comments = gr.Textbox(
+            label="Additional Comments",
+            placeholder="Any other observations...",
+            lines=4,
+        )
+
+        with gr.Row():
+            back_btn = gr.Button(
+                "Back to Gender Comparisons", variant="secondary"
+            )
+            export_btn = gr.Button("Submit Results", variant="primary")
+
+    return conclusion_page, back_btn, export_btn, overall_feedback, final_comments

frontend/pages/intro.py

@@ -0,0 +1,48 @@
+# frontend/pages/intro.py
+
+import gradio as gr
+
+
+def build_intro_page():
+    """Builds the intro page and returns (container, start_button)."""
+    with gr.Column(visible=True) as intro_page:
+        gr.Markdown(
+            """
+        # ATC TTS Evaluation Study
+
+        You will evaluate short ATC/aviation clips from three TTS systems: Model A, Model B, and Model C.
+
+        <div class="section-header">
+        <h3>Evaluation Process (5 Sections):</h3>
+        <ol>
+        <li><strong>Reference Audio</strong> - Listen to sample clips to calibrate expectations</li>
+        <li><strong>MOS Block</strong> - Rate clips across several quality dimensions (9-12 sections; mix models and genders)</li>
+        <li><strong>AB Model Comparisons</strong> - Model vs Model comparisons (same gender)</li>
+        <li><strong>AB Gender Comparisons</strong> - Male vs Female voice comparisons (same model)</li>
+        <li><strong>Conclusion</strong> - Best overall model and additional comments</li>
+        </ol>
+        </div>
+
+        Please use headphones in a quiet place, rate what you hear.
+
+        ### What you will do
+
+        - Rate each clip on five MOS dimensions (1–5).
+        - Do a few A/B comparisons (two clips of the same prompt).
+        - Some clips are Male voice, others Female; you may also compare Male vs Female for the same model.
+
+        ### What to listen for (quick checklist)
+
+        - **Clarity**: Can you understand every word, number, call-sign, waypoint, runway, and altitude?
+        - **Pronunciation**: Are aviation terms spoken correctly (e.g., "flight level three zero zero")?
+        - **Prosody (Intonation/Rhythm)**: Is pacing appropriate for ATC (brisk, not rushed; natural stress/pauses)?
+        - **Naturalness**: Does it sound human-like (no robotic artifacts, buzz, hiss, warble)?
+        - **Overall**: Your total impression for ATC use.
+
+        **Estimated time**: ~10–15 minutes. Responses are anonymous and used only to improve the models.
+        """
+        )
+
+        start_btn = gr.Button("Start Evaluation", variant="primary")
+
+    return intro_page, start_btn

frontend/pages/mos.py

@@ -0,0 +1,252 @@
+# frontend/pages/mos.py
+
+import random
+import time
+from typing import Any, Dict, List
+
+import gradio as gr
+
+from backend.models import get_display_model_name, audio_to_base64_url
+
+
+def build_mos_page():
+    """
+    Build the MOS page (Section 2).
+
+    Returns:
+        mos_page, back_btn, continue_btn, mos_dynamic_content, mos_data_textbox
+    """
+    with gr.Column(visible=False) as mos_page:
+        with gr.Group(elem_classes=["progress-text"]):
+            gr.Markdown("### Section 2 of 5: Model Rating Evaluation")
+
+        gr.Markdown(
+            """
+        <div class="section-header">
+        <h2>Mixed Model Evaluation</h2>
+        <p>Listen to TTS clips and rate each one. Model identities are hidden to reduce bias.</p>
+
+        <h3>Instructions:</h3>
+        <ul>
+            <li>Listen to each clip carefully.</li>
+            <li>Rate each clip individually using the dropdown menus (1–5 scale).</li>
+            <li>Leave comments if you notice specific issues or strengths.</li>
+            <li>Rating dimensions:
+                <ul>
+                    <li>Clarity</li>
+                    <li>Pronunciation</li>
+                    <li>Prosody (Intonation/Rhythm)</li>
+                    <li>Naturalness</li>
+                    <li>Overall quality</li>
+                </ul>
+            </li>
+        </ul>
+        </div>
+        """
+        )
+
+        mos_dynamic_content = gr.HTML(value="<p>Loading clips...</p>", visible=True)
+
+        with gr.Row():
+            back_btn = gr.Button("Back to Reference Audio", variant="secondary")
+            continue_btn = gr.Button(
+                "Continue to Model Comparisons", variant="primary"
+            )
+
+    return mos_page, back_btn, continue_btn, mos_dynamic_content
+
+
+def render_mos_html(session) -> str:
+    """
+    Given a session (from SessionManager), return the big HTML string
+    used in your original show_mos_page().
+    """
+    if not session:
+        return ""
+
+    clips = session.get("mos_clips", [])
+    if len(clips) == 0:
+        return """
+        <div class="clip-container" style="padding: 20px; border-radius: 12px; border: 2px solid #f59e0b; margin: 15px 0;">
+            <h3>No MOS clips available</h3>
+            <p>The dataset appears to be empty or not loading correctly.</p>
+            <p>This is a demo of the interface structure.</p>
+        </div>
+        """
+
+    rng = random.Random(session.get("session_id", time.time()))
+    shuffled_clips = clips.copy()
+    rng.shuffle(shuffled_clips)
+
+    html_content = ""
+    for i, clip in enumerate(shuffled_clips, 1):
+        gender_color = "#3B82F6" if clip.speaker == "male" else "#EC4899"
+        audio_url = audio_to_base64_url(clip.audio_url) or ""
+
+        # --- this is exactly your original MOS HTML per clip ---
+        html_content += f"""
+        <div class="clip-container" style="background: linear-gradient(135deg, {gender_color}15, {gender_color}08);
+                    padding: 20px; border-radius: 12px; border-left: 4px solid {gender_color}; margin: 15px 0;">
+            <h3>Clip {i}: {clip.speaker.title()} Voice - {get_display_model_name(clip.model)}</h3>
+
+            <div style="background: #1e293b; padding: 15px; border-radius: 8px; margin-bottom: 20px;">
+                <p style="margin: 0; color: #cbd5e1; font-style: italic;">
+                    <strong>Text:</strong> "{clip.transcript}"
+                </p>
+            </div>
+
+            <div style="background: #1f2937; padding: 15px; border-radius: 8px; margin-bottom: 15px;">
+                <audio controls style="width: 100%; height: 54px;">
+                    <source src="{audio_url}" type="audio/wav">
+                    Audio not available
+                </audio>
+            </div>
+
+            <div style="background: #2d3748; padding: 15px; border-radius: 8px; border: 1px solid {gender_color};">
+                <h5 style="color: #e5e5e5; margin: 0 0 10px 0;">Rate this clip:</h5>
+                <div style="display: flex; flex-direction: column; gap: 8px; font-size: 14px;">
+                    <label style="color: #cbd5e1;">
+                        <strong>Clarity (1–5):</strong>
+                        <select data-clip-id="{clip.id}" data-model="{clip.model}" data-dimension="clarity"
+                                style="margin-left: 10px; padding: 5px; background: #4a5568; color: white; border: 1px solid {gender_color}; border-radius: 4px;">
+                            <option value="">Select...</option>
+                            <option value="1">1 - Poor</option>
+                            <option value="2">2 - Fair</option>
+                            <option value="3">3 - Good</option>
+                            <option value="4">4 - Very Good</option>
+                            <option value="5">5 - Excellent</option>
+                        </select>
+                    </label>
+
+                    <label style="color: #cbd5e1;">
+                        <strong>Pronunciation (1–5):</strong>
+                        <select data-clip-id="{clip.id}" data-model="{clip.model}" data-dimension="pronunciation"
+                                style="margin-left: 10px; padding: 5px; background: #4a5568; color: white; border: 1px solid {gender_color}; border-radius: 4px;">
+                            <option value="">Select...</option>
+                            <option value="1">1 - Poor</option>
+                            <option value="2">2 - Fair</option>
+                            <option value="3">3 - Good</option>
+                            <option value="4">4 - Very Good</option>
+                            <option value="5">5 - Excellent</option>
+                        </select>
+                    </label>
+
+                    <label style="color: #cbd5e1;">
+                        <strong>Prosody (1–5):</strong>
+                        <select data-clip-id="{clip.id}" data-model="{clip.model}" data-dimension="prosody"
+                                style="margin-left: 10px; padding: 5px; background: #4a5568; color: white; border: 1px solid {gender_color}; border-radius: 4px;">
+                            <option value="">Select...</option>
+                            <option value="1">1 - Very poor pacing</option>
+                            <option value="2">2 - Poor pacing</option>
+                            <option value="3">3 - Acceptable pacing</option>
+                            <option value="4">4 - Good pacing</option>
+                            <option value="5">5 - Excellent pacing</option>
+                        </select>
+                    </label>
+
+                    <label style="color: #cbd5e1;">
+                        <strong>Naturalness (1–5):</strong>
+                        <select data-clip-id="{clip.id}" data-model="{clip.model}" data-dimension="naturalness"
+                                style="margin-left: 10px; padding: 5px; background: #4a5568; color: white; border: 1px solid {gender_color}; border-radius: 4px;">
+                            <option value="">Select...</option>
+                            <option value="1">1 - Very robotic</option>
+                            <option value="2">2 - Robotic</option>
+                            <option value="3">3 - Neutral</option>
+                            <option value="4">4 - Natural</option>
+                            <option value="5">5 - Very natural</option>
+                        </select>
+                    </label>
+
+                    <label style="color: #cbd5e1;">
+                        <strong>Overall (1–5):</strong>
+                        <select data-clip-id="{clip.id}" data-model="{clip.model}" data-dimension="overall"
+                                style="margin-left: 10px; padding: 5px; background: #4a5568; color: white; border: 1px solid {gender_color}; border-radius: 4px;">
+                            <option value="">Select...</option>
+                            <option value="1">1 - Unacceptable</option>
+                            <option value="2">2 - Poor</option>
+                            <option value="3">3 - Acceptable</option>
+                            <option value="4">4 - Good</option>
+                            <option value="5">5 - Excellent</option>
+                        </select>
+                    </label>
+
+                    <div style="margin-top: 15px; padding: 15px; background: #451a03; border-radius: 8px; border: 2px solid #92400e;">
+                        <label style="color: #fbbf24; cursor: pointer; display: flex; align-items: center; font-weight: bold;">
+                            <input type="checkbox" data-clip-id="{clip.id}" data-model="{clip.model}" data-dimension="gender_mismatch" onchange="collectMOSData()"
+                                   style="margin-right: 10px; transform: scale(1.2);">
+                            ⚠️ {get_display_model_name(clip.model)} ({clip.speaker} voice) sounds wrong
+                        </label>
+                        <p style="margin: 8px 0 0 0; font-size: 12px; color: #fbbf24;">
+                            Check this box if you hear the wrong gender voice for this clip.
+                        </p>
+                    </div>
+
+                    <div style="margin-top: 15px; padding-top: 10px; border-top: 1px solid {gender_color};">
+                        <label style="color: #cbd5e1; display: block; margin-bottom: 5px;">
+                            <strong>Comments (optional):</strong>
+                        </label>
+                            <textarea data-clip-id="{clip.id}" data-model="{clip.model}" data-dimension="comment" onchange="collectMOSData()"
+                            placeholder="Any specific observations about this clip?"
+                            style="width: 100%; padding: 8px; background: #1f2937; color: #e5e5e5; border: 1px solid {gender_color}; border-radius: 4px; resize: vertical; min-height: 60px; font-size: 13px;"
+                            rows="3"></textarea>
+                    </div>
+                </div>
+            </div>
+        </div>
+        """
+
+    # Add JavaScript collector that updates the hidden textbox
+    html_content += """
+    <script>
+    function collectMOSData() {
+        const ratings = {};
+        
+        const selects = document.querySelectorAll('select[data-clip-id]');
+        const checkboxes = document.querySelectorAll('input[type="checkbox"][data-clip-id]');
+        const textareas = document.querySelectorAll('textarea[data-clip-id]');
+        
+        selects.forEach(select => {
+            const clipId = select.getAttribute('data-clip-id');
+            const dimension = select.getAttribute('data-dimension');
+            if (!ratings[clipId]) ratings[clipId] = {};
+            ratings[clipId][dimension] = select.value;
+        });
+        
+        checkboxes.forEach(checkbox => {
+            const clipId = checkbox.getAttribute('data-clip-id');
+            const dimension = checkbox.getAttribute('data-dimension');
+            if (!ratings[clipId]) ratings[clipId] = {};
+            ratings[clipId][dimension] = checkbox.checked;
+        });
+        
+        textareas.forEach(textarea => {
+            const clipId = textarea.getAttribute('data-clip-id');
+            const dimension = textarea.getAttribute('data-dimension');
+            if (!ratings[clipId]) ratings[clipId] = {};
+            ratings[clipId][dimension] = textarea.value;
+        });
+        
+        // Find the hidden textbox and update it - try both possible selectors
+        let mosDataElement = document.querySelector('#mos_data_store textarea');
+        if (!mosDataElement) {
+            mosDataElement = document.querySelector('#mos_data_store input');
+        }
+        
+        console.log('[DEBUG] collectMOSData called');
+        console.log('[DEBUG] Found', Object.keys(ratings).length, 'rated clips');
+        console.log('[DEBUG] Ratings object:', ratings);
+        console.log('[DEBUG] MOS data element found:', mosDataElement);
+        
+        if (mosDataElement) {
+            mosDataElement.value = JSON.stringify(ratings);
+            console.log('[DEBUG] Updated hidden textbox with:', mosDataElement.value);
+            mosDataElement.dispatchEvent(new Event('input', { bubbles: true }));
+        } else {
+            console.error('[ERROR] Could not find MOS data textbox element');
+        }
+    }
+    
+    </script>
+    """
+
+    return html_content

frontend/pages/samples.py

@@ -0,0 +1,64 @@
+# frontend/pages/samples.py
+
+import gradio as gr
+
+
+def build_sample_page():
+    """
+    Builds the reference / sample audio page.
+
+    Returns:
+        sample_page: Column container
+        back_btn: button to go back to intro
+        continue_btn: button to go to MOS
+        sample_audio_container: Column where dynamic sample clips will be injected
+    """
+    with gr.Column(visible=False) as sample_page:
+        with gr.Group(elem_classes=["progress-text"]):
+            gr.Markdown("### Section 1 of 5: Reference Audio Samples")
+
+        gr.Markdown(
+            """
+        <div class="section-header">
+        <h2>Reference Audio Samples</h2>
+        <p>Listen to these reference clips to understand the expected ATC communication style and quality.</p>
+        <p>These clips help calibrate your internal scale before rating synthetic audio.</p>
+        </div>
+        """
+        )
+
+        with gr.Group(elem_classes=["reference-container"]):
+            gr.Markdown("### Reference Voices")
+            gr.Markdown("These are human reference recordings.")
+
+            with gr.Row():
+                with gr.Column():
+                    gr.Markdown("#### Male Reference Voice")
+                    gr.Audio(
+                        "/home/raid/atc-c3-comms/assets/tts/src/evaluation/mos/audios/male.wav",
+                        label="Male Reference - Professional ATC",
+                    )
+                    with gr.Group(elem_classes=["transcript-box"]):
+                        gr.Markdown(
+                            "**Text:** *TENGAH Approach to CAMEL, CAMEL identified on squawk, QNH 29.80, Delta 4 hot, report abeam Tuas.*"
+                        )
+
+                with gr.Column():
+                    gr.Markdown("#### Female Reference Voice")
+                    gr.Audio(
+                        "/home/raid/atc-c3-comms/assets/tts/src/evaluation/mos/audios/female.wav",
+                        label="Female Reference - Professional ATC",
+                    )
+                    with gr.Group(elem_classes=["transcript-box"]):
+                        gr.Markdown(
+                            "**Text:** *JOHOR climbing to flight level 300, contact Approach on 123.45.*"
+                        )
+
+        # container where we will render session.sample_clips dynamically
+        sample_audio_container = gr.Column()
+
+        with gr.Row():
+            back_btn = gr.Button("Back to Introduction", variant="secondary")
+            continue_btn = gr.Button("Continue to Model Ratings", variant="primary")
+
+    return sample_page, back_btn, continue_btn, sample_audio_container

frontend/pages/thank_you.py

@@ -0,0 +1,27 @@
+# frontend/pages/thank_you.py
+
+import gradio as gr
+
+
+def build_thank_you_page():
+    """
+    Build the final thank-you page.
+
+    Returns:
+        thank_you_page: Column container
+    """
+    with gr.Column(visible=False) as thank_you_page:
+        gr.Markdown(
+            """
+        <div class="section-header">
+        <h2>Thank You!</h2>
+        <p>Your evaluation has been successfully submitted.</p>
+        </div>
+        
+        <div style="text-align: center; margin: 50px 0;">
+            <h3 style="color: #10b981;">✓ Evaluation Complete</h3>
+        </div>
+        """
+        )
+
+    return thank_you_page

requirements.txt

@@ -0,0 +1,8 @@
+# Core dependencies
+gradio>=4.0.0
+datasets>=2.14.0
+pandas>=1.5.0
+huggingface_hub>=0.17.0
+soundfile>=0.12.1
+torchcodec>=0.1.0
+torch>=1.12.0