Upload folder using huggingface_hub

.gitattributes

@@ -33,3 +33,4 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+static/voice/belinda.wav filter=lfs diff=lfs merge=lfs -text

engine.py

@@ -336,6 +336,80 @@ def parse_lesson_json(text):
     return None
 
 
+# ---- board layout hygiene: the model's spatial reasoning is approximate, ----
+# ---- so clamp out-of-bounds coordinates and nudge overlapping text.       ----
+
+_TEXT_H = {"s": 4.0, "m": 5.5, "l": 7.0, "xl": 9.0}
+
+
+def _clamp_pt(pt, lo_x=2, hi_x=98, lo_y=3, hi_y=72):
+    try:
+        return [min(max(float(pt[0]), lo_x), hi_x), min(max(float(pt[1]), lo_y), hi_y)]
+    except Exception:
+        return [50, 38]
+
+
+def _op_bbox(op):
+    """Rough bounding box (x1, y1, x2, y2) for collision checks; None = skip."""
+    kind = op.get("op")
+    if kind == "title":
+        return (22, 2, 78, 14)
+    if kind in ("text", "note"):
+        x, y = op.get("at", [10, 20])
+        size = op.get("size", "m" if kind == "text" else "s")
+        w = min(len(str(op.get("text", ""))) * {"s": 1.5, "m": 2.0, "l": 2.7, "xl": 3.6}.get(size, 2.0), 52)
+        lines = max(1, int(w // 52) + 1)
+        h = _TEXT_H.get(size, 5.5) * lines
+        if op.get("align") == "center":
+            x -= w / 2
+        return (x, y - h / 2, x + w, y + h / 2)
+    if kind in ("box", "ellipse"):
+        x, y = op.get("at", [10, 20])
+        return (x, y, x + float(op.get("w", 20) or 20), y + float(op.get("h", 10) or 10))
+    return None
+
+
+def _overlaps(a, b):
+    return a[0] < b[2] - 1 and a[2] > b[0] + 1 and a[1] < b[3] - 1 and a[3] > b[1] + 1
+
+
+def layout_pass(board, placed):
+    """Clamp coordinates into the visible board; move colliding text down/over."""
+    out = []
+    for op in board:
+        op = dict(op)
+        kind = op.get("op")
+        try:
+            if "at" in op:
+                op["at"] = _clamp_pt(op["at"])
+            if "from" in op:
+                op["from"] = _clamp_pt(op["from"])
+            if "to" in op:
+                op["to"] = _clamp_pt(op["to"])
+            if "points" in op and isinstance(op["points"], list):
+                op["points"] = [_clamp_pt(p) for p in op["points"][:12]]
+            if kind in ("box", "ellipse", "axes"):
+                x, y = op.get("at", [10, 20])
+                op["w"] = min(float(op.get("w", 20) or 20), 96 - x)
+                op["h"] = min(float(op.get("h", 10) or 10), 71 - y)
+            if kind in ("text", "note"):  # nudge colliding labels into free space
+                bbox = _op_bbox(op)
+                for _ in range(8):
+                    if bbox is None or not any(_overlaps(bbox, p) for p in placed):
+                        break
+                    op["at"] = [op["at"][0], op["at"][1] + 5]
+                    if op["at"][1] > 71:
+                        op["at"] = [min(op["at"][0] + 18, 96), 8]
+                    bbox = _op_bbox(op)
+            bbox = _op_bbox(op)
+            if bbox:
+                placed.append(bbox)
+        except Exception:
+            pass
+        out.append(op)
+    return out
+
+
 def sanitize_step(step, step_index=0):
     if not isinstance(step, dict):
         return None
@@ -384,13 +458,21 @@ def transcribe(audio_path):
 _SPOKEN_CLEAN = re.compile(r"[*_#`<>\[\]{}|\\~^]")
 
 
+# Zero-shot voice cloning: a fixed reference clip + exact transcript pins
+# Tutori's voice — without it, Higgs samples a fresh "smart voice" per step
+# and the voice drifts mid-lesson. Swap the wav+txt pair to change the voice.
+_VOICE_DIR = os.path.join(os.path.dirname(os.path.abspath(__file__)), "static", "voice")
+_VOICE_REF_WAV = os.path.join(_VOICE_DIR, "belinda.wav")
+with open(os.path.join(_VOICE_DIR, "belinda.txt")) as _f:
+    _VOICE_REF_TEXT = _f.read().strip()
+
 _TTS_SYSTEM = [
     {"role": "system",
      "content": [{"type": "text", "text": "Generate audio following instruction."}]},
     {"role": "scene",
-     "content": [{"type": "text", "text":
-                  "Audio is recorded from a quiet room. SPEAKER0 is a warm, friendly "
-                  "tutor in her thirties with a clear, gently enthusiastic voice."}]},
+     "content": [{"type": "text", "text": "Audio is recorded from a quiet room."}]},
+    {"role": "user", "content": [{"type": "text", "text": _VOICE_REF_TEXT}]},
+    {"role": "assistant", "content": [{"type": "audio", "path": _VOICE_REF_WAV}]},
 ]
 
 
@@ -608,12 +690,14 @@ def run_turn(audio_path, typed_text, board_snapshot, history, profile,
         parser = LessonStreamParser()
         n_steps = 0
         full_text = ""
+        placed = []  # bboxes drawn so far this turn, for collision nudging
         for chunk in streamer:
             full_text += chunk
             for raw_step in parser.feed(chunk):
                 step = sanitize_step(raw_step, n_steps)
                 if not step:
                     continue
+                step["board"] = layout_pass(step["board"], placed)
                 audio_b64, dur = (None, None)
                 if voice_on and step["say"]:
                     audio_b64, dur = synthesize(step["say"])
@@ -635,6 +719,7 @@ def run_turn(audio_path, typed_text, board_snapshot, history, profile,
                 step = sanitize_step(raw_step, n_steps)
                 if not step:
                     continue
+                step["board"] = layout_pass(step["board"], placed)
                 audio_b64, dur = (None, None)
                 if voice_on and step["say"]:
                     audio_b64, dur = synthesize(step["say"])

static/board.js

@@ -355,6 +355,7 @@
     const ops = (step.board || []).map(o => ({ op: o, seed: (S.opSeedCounter++ * 2654435761) >>> 0 }));
     let dur = step.dur || Math.max(2.2, String(step.say || "").split(/\s+/).length * 0.36);
     let src = null;
+    let audioEnded = true;   // true while there is no source; set false when one starts
 
     if (step.audio && S.voiceOn) {
       try {
@@ -366,6 +367,8 @@
           src = actx().createBufferSource();
           src.buffer = buf;
           src.connect(actx().destination);
+          audioEnded = false;
+          src.onended = () => { audioEnded = true; };  // the ONLY reliable end signal
         }
       } catch (e) { src = null; }
     }
@@ -402,10 +405,13 @@
             renderOp(live, it, (el - it.start) / (it.end - it.start));
           }
         }
-        const audioDone = !src || el >= dur;
-        if (bakedIdx >= sched.length && audioDone && el >= dur) {
+        // wait for the audio's real `ended` event — clock estimates start the
+        // next clip while this one's tail is still audible (voices overlap).
+        // el > dur + 2 is only a safety net if `ended` never fires.
+        const audioDone = audioEnded || el > dur + 2.0;
+        if (bakedIdx >= sched.length && audioDone) {
           live.clearRect(0, 0, S.liveCv.width, S.liveCv.height);
-          resolve();
+          setTimeout(resolve, 140);   // natural breath between steps
         } else if (S.stopFlag) {
           try { src && src.stop(); } catch (e) {}
           // bake the remainder instantly so the board ends complete

static/voice/belinda.txt

@@ -0,0 +1 @@
+Twas the night before my birthday. Hooray! It's almost here! It may not be a holiday, but it's the best day of the year.

static/voice/belinda.wav

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