learnx-cli 0.3.0__py3-none-any.whl

tutor/visual/subtitle_writer.py

@@ -0,0 +1,187 @@
+"""
+Convert a flat list of DialogueLines into a SRT subtitle file.
+No ffmpeg, no Pillow, no LLM calls here.
+"""
+
+from tutor.constants import SILENCE_TURN_MS, SILENCE_UNIT_MS, WPM
+from tutor.models import DialogueLine
+
+MIN_LINE_DURATION_S = 1.5
+MAX_SUBTITLE_CHARS = 60
+
+
+def build_srt(
+    all_lines: list[DialogueLine],
+    unit_durations_s: list[float],
+    timing_json: dict | None = None,
+) -> str:
+    """
+    Build a complete SRT string for the session.
+    If timing_json provided: use exact start_ms/end_ms per line.
+    If timing_json is None: use WPM estimation (existing behaviour, unchanged).
+    """
+    offsets = get_line_start_offsets(all_lines, unit_durations_s, timing_json)
+    _, durations = _compute_timing(all_lines, unit_durations_s)
+    entries: list[str] = []
+    for idx, (line, start, dur) in enumerate(
+        zip(all_lines, offsets, durations, strict=False), start=1
+    ):
+        end = start + dur
+        text = _wrap_subtitle(line.speaker, line.text)
+        entries.append(f"{idx}\n{_format_timestamp(start)} --> {_format_timestamp(end)}\n{text}\n")
+    return "\n".join(entries)
+
+
+def get_line_start_offsets(
+    all_lines: list[DialogueLine],
+    unit_durations_s: list[float],
+    timing_json: dict | None = None,
+) -> list[float]:
+    """
+    Return the start time (seconds) of each line.
+    If timing_json provided: use exact offsets.
+    If timing_json is None: use WPM estimation (existing behaviour, unchanged).
+    """
+    if timing_json is not None:
+        return _exact_line_offsets(all_lines, unit_durations_s, timing_json)
+    offsets, _ = _compute_timing(all_lines, unit_durations_s)
+    return offsets
+
+
+# ── Internals ────────────────────────────────────────────────────────────────
+
+
+def _exact_line_offsets(
+    all_lines: list[DialogueLine],
+    unit_durations_s: list[float],
+    timing_json: dict,
+) -> list[float]:
+    """
+    Compute session-global start time for each line using timing_json.
+
+    unit_start[u] accumulates unit durations + inter-unit silence so
+    subtitle timestamps align with the concatenated video.
+    Lines not in timing_json (intro/outro) fall back to WPM estimation.
+    """
+    # Build cumulative unit start offsets
+    unit_start: dict[int, float] = {}
+    cursor = 0.0
+    for u_idx, dur in enumerate(unit_durations_s, start=1):
+        unit_start[u_idx] = cursor
+        cursor += dur + SILENCE_UNIT_MS / 1000
+
+    units_timing: dict[str, list] = timing_json.get("units", {})
+    wpm_offsets, _ = _compute_timing(all_lines, unit_durations_s)
+
+    # Track within-unit line index per unit
+    unit_line_idx: dict[int, int] = {}
+    offsets: list[float] = []
+
+    for i, ln in enumerate(all_lines):
+        u = ln.unit_number
+        key = str(u)
+        unit_entries = units_timing.get(key)
+
+        if unit_entries is None:
+            offsets.append(wpm_offsets[i])
+            continue
+
+        within_idx = unit_line_idx.get(u, 0)
+        unit_line_idx[u] = within_idx + 1
+
+        if within_idx >= len(unit_entries):
+            offsets.append(wpm_offsets[i])
+            continue
+
+        entry = unit_entries[within_idx]
+        offsets.append(unit_start.get(u, 0.0) + entry["start_ms"] / 1000)
+
+    return offsets
+
+
+def _compute_timing(
+    all_lines: list[DialogueLine],
+    unit_durations_s: list[float],
+) -> tuple[list[float], list[float]]:
+    """Return (start_offsets, durations) for every line."""
+    # Group lines by unit number (preserving order)
+    unit_groups: dict[int, list[int]] = {}
+    for i, ln in enumerate(all_lines):
+        unit_groups.setdefault(ln.unit_number, []).append(i)
+
+    raw_durations: list[float] = [_line_duration(ln.text) for ln in all_lines]
+
+    # Scale per-unit durations to match actual MP3 lengths
+    for unit_num, indices in unit_groups.items():
+        if unit_num < 1:
+            continue
+        unit_idx = unit_num - 1
+        if unit_idx >= len(unit_durations_s):
+            continue
+        actual_s = unit_durations_s[unit_idx]
+        estimated_s = sum(raw_durations[i] for i in indices) + (
+            SILENCE_TURN_MS / 1000 * (len(indices) - 1)
+        )
+        if estimated_s > 0 and abs(estimated_s - actual_s) / estimated_s > 0.10:
+            scaled = _scale_unit_lines([raw_durations[i] for i in indices], actual_s)
+            for i, d in zip(indices, scaled, strict=False):
+                raw_durations[i] = d
+
+    # Build offsets with silence gaps
+    offsets: list[float] = []
+    cursor = 0.0
+    prev_unit: int | None = None
+
+    for i, ln in enumerate(all_lines):
+        if prev_unit is not None and ln.unit_number != prev_unit:
+            cursor += SILENCE_UNIT_MS / 1000
+        elif prev_unit is not None:
+            cursor += SILENCE_TURN_MS / 1000
+        offsets.append(cursor)
+        cursor += raw_durations[i]
+        prev_unit = ln.unit_number
+
+    return offsets, raw_durations
+
+
+def _line_duration(text: str) -> float:
+    words = len(text.split())
+    return max(words / WPM * 60, MIN_LINE_DURATION_S)
+
+
+def _scale_unit_lines(durations: list[float], actual_s: float) -> list[float]:
+    total = sum(durations)
+    if total == 0:
+        return durations
+    factor = actual_s / total
+    return [d * factor for d in durations]
+
+
+def _format_timestamp(seconds: float) -> str:
+    ms = int(round(seconds * 1000))
+    hh = ms // 3_600_000
+    ms -= hh * 3_600_000
+    mm = ms // 60_000
+    ms -= mm * 60_000
+    ss = ms // 1_000
+    ms -= ss * 1_000
+    return f"{hh:02d}:{mm:02d}:{ss:02d},{ms:03d}"
+
+
+def _wrap_subtitle(speaker: str, text: str, max_chars: int = MAX_SUBTITLE_CHARS) -> str:
+    prefix = f"{speaker}: "
+    full = prefix + text
+    if len(full) <= max_chars:
+        return full
+    # Wrap: keep prefix on first line, spill remainder
+    words = text.split()
+    line1_words: list[str] = []
+    for word in words:
+        candidate = prefix + " ".join(line1_words + [word])
+        if len(candidate) <= max_chars:
+            line1_words.append(word)
+        else:
+            break
+    remainder = " ".join(words[len(line1_words) :])
+    line1 = prefix + " ".join(line1_words)
+    return f"{line1}\n{remainder}" if remainder else line1

tutor/visual/templates/_base.html.j2

@@ -0,0 +1,40 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=1920, height=1080">
+<link rel="stylesheet" href="{{ asset_dir }}/slide_base.css">
+<link rel="stylesheet" href="{{ asset_dir }}/theme-learnx-dark.css">
+<style>{% block extra_style %}{% endblock %}</style>
+<script src="{{ asset_dir }}/highlight.min.js"></script>
+<script src="{{ asset_dir }}/highlight-java.min.js"></script>
+<script src="{{ asset_dir }}/highlight-python.min.js"></script>
+<script src="{{ asset_dir }}/highlight-javascript.min.js"></script>
+<script src="{{ asset_dir }}/mermaid.min.js"></script>
+<script>
+  document.addEventListener('DOMContentLoaded', function() {
+    if (typeof hljs !== 'undefined') { hljs.highlightAll(); }
+    if (typeof mermaid !== 'undefined') { mermaid.initialize({startOnLoad: true, theme: 'dark'}); }
+  });
+</script>
+</head>
+<body>
+<div class="top-bar">
+  {% block top_bar %}
+  {% if seg is defined %}Unit {{ seg.unit_index }} &middot; {{ seg.title | e }}{% endif %}
+  {% endblock %}
+</div>
+<div class="content">
+  {% block content %}{% endblock %}
+</div>
+<div class="footer-bar">
+  {% block footer %}
+  {% if total_dots is defined %}
+    {% for i in range(total_dots) %}
+      <span class="dot {% if i < current_dot %}dot--filled{% else %}dot--hollow{% endif %}"></span>
+    {% endfor %}
+  {% endif %}
+  {% endblock %}
+</div>
+</body>
+</html>

tutor/visual/templates/analogy.html.j2

@@ -0,0 +1,21 @@
+{% extends "_base.html.j2" %}
+{% block extra_style %}:root { --type-accent: var(--purple); }{% endblock %}
+{% block content %}
+<div class="analogy-slide">
+  {% if seg.rows %}
+  <div class="analogy-panel">
+    <div class="analogy-label">{{ seg.left | default('Real world') | e }}</div>
+    <div class="analogy-body">{{ seg.rows[0][0] | e }}</div>
+  </div>
+  <div class="analogy-sep">&#8776;</div>
+  <div class="analogy-panel">
+    <div class="analogy-label">{{ seg.right | default('In code') | e }}</div>
+    <div class="analogy-body">{{ seg.rows[0][1] | e }}</div>
+  </div>
+  {% else %}
+  <div class="analogy-panel" style="grid-column:1/4;">
+    <div class="analogy-body">{{ seg.body | e if seg.body else seg.title | e }}</div>
+  </div>
+  {% endif %}
+</div>
+{% endblock %}

tutor/visual/templates/callout.html.j2

@@ -0,0 +1,10 @@
+{% extends "_base.html.j2" %}
+{% block extra_style %}:root { --type-accent: var(--amber); }{% endblock %}
+{% block content %}
+<div class="callout-slide">
+  <div class="callout-box">
+    <div class="callout-label">{{ seg.title | e }}</div>
+    <div class="callout-text">{{ seg.body | e }}</div>
+  </div>
+</div>
+{% endblock %}

tutor/visual/templates/code_example.html.j2

@@ -0,0 +1,12 @@
+{% extends "_base.html.j2" %}
+{% block extra_style %}:root { --type-accent: var(--green); }{% endblock %}
+{% block content %}
+<div class="code-slide">
+  {% if seg.body %}
+  <div class="code-desc">{{ seg.body | e }}</div>
+  {% endif %}
+  {% if seg.code %}
+  <pre><code class="language-{{ seg.language or 'text' }}">{{ seg.code | e }}</code></pre>
+  {% endif %}
+</div>
+{% endblock %}

tutor/visual/templates/comparison.html.j2

@@ -0,0 +1,28 @@
+{% extends "_base.html.j2" %}
+{% block extra_style %}:root { --type-accent: var(--teal); }{% endblock %}
+{% block content %}
+<div class="comparison-slide">
+  <table class="comparison-table">
+    <thead>
+      <tr>
+        <th class="th-left">{{ seg.left | default('') | e }}</th>
+        <th class="th-right">{{ seg.right | default('') | e }}</th>
+      </tr>
+    </thead>
+    <tbody>
+      {% set rows = seg.rows or [] %}
+      {% for row in rows[:6] %}
+      <tr>
+        <td>{{ row[0] | e }}</td>
+        <td>{{ row[1] | e }}</td>
+      </tr>
+      {% endfor %}
+      {% if rows | length > 6 %}
+      <tr>
+        <td colspan="2" class="td-ellipsis">…</td>
+      </tr>
+      {% endif %}
+    </tbody>
+  </table>
+</div>
+{% endblock %}

tutor/visual/templates/decision_guide.html.j2

@@ -0,0 +1,37 @@
+{% extends "_base.html.j2" %}
+{% block extra_style %}:root { --type-accent: var(--orange); }{% endblock %}
+{% block content %}
+{% if seg.rows %}
+<div class="comparison-slide">
+  <table class="comparison-table">
+    <thead>
+      <tr>
+        <th class="th-left">{{ seg.left | default('Use when') | e }}</th>
+        <th class="th-right">{{ seg.right | default('Avoid when') | e }}</th>
+      </tr>
+    </thead>
+    <tbody>
+      {% set rows = seg.rows or [] %}
+      {% for row in rows[:6] %}
+      <tr>
+        <td>{{ row[0] | e }}</td>
+        <td>{{ row[1] | e }}</td>
+      </tr>
+      {% endfor %}
+      {% if rows | length > 6 %}
+      <tr>
+        <td colspan="2" class="td-ellipsis">…</td>
+      </tr>
+      {% endif %}
+    </tbody>
+  </table>
+</div>
+{% else %}
+<div class="definition-slide">
+  <div class="definition-term">{{ seg.title | e }}</div>
+  {% if seg.body %}
+  <div class="definition-text">{{ seg.body | e }}</div>
+  {% endif %}
+</div>
+{% endif %}
+{% endblock %}

tutor/visual/templates/definition.html.j2

@@ -0,0 +1,13 @@
+{% extends "_base.html.j2" %}
+{% block extra_style %}:root { --type-accent: var(--blue); }{% endblock %}
+{% block content %}
+<div class="definition-slide">
+  <div class="definition-term">{{ seg.title | e }}</div>
+  {% if seg.body %}
+  <div class="definition-text">{{ seg.body | e }}</div>
+  {% endif %}
+  {% if seg.code %}
+  <pre><code class="language-{{ seg.language or 'text' }}">{{ seg.code | e }}</code></pre>
+  {% endif %}
+</div>
+{% endblock %}

tutor/visual/templates/diagram.html.j2

@@ -0,0 +1,11 @@
+{% extends "_base.html.j2" %}
+{% block extra_style %}:root { --type-accent: var(--indigo); }{% endblock %}
+{% block content %}
+<div class="diagram-slide">
+  {% if seg.mermaid %}
+  <div class="mermaid">{{ seg.mermaid | e }}</div>
+  {% else %}
+  <p style="color:var(--text-sec);font-size:36px;">{{ seg.title | e }}</p>
+  {% endif %}
+</div>
+{% endblock %}

tutor/visual/templates/hook_question.html.j2

@@ -0,0 +1,17 @@
+{% extends "_base.html.j2" %}
+{% block extra_style %}:root { --type-accent: var(--cyan); }{% endblock %}
+{% block content %}
+<div class="hook-slide">
+  <div class="hook-question">{{ seg.title | e }}</div>
+  {% if seg.body %}
+  <div>
+    <div class="learn-label">What you'll learn</div>
+    <ul class="learn-list">
+      {% for item in seg.body.split('\n') if item.strip() %}
+      <li>{{ item.strip() | e }}</li>
+      {% endfor %}
+    </ul>
+  </div>
+  {% endif %}
+</div>
+{% endblock %}

tutor/visual/templates/key_insight.html.j2

@@ -0,0 +1,9 @@
+{% extends "_base.html.j2" %}
+{% block extra_style %}:root { --type-accent: var(--pink); }{% endblock %}
+{% block content %}
+<div class="key-insight-slide">
+  <div class="key-insight-rule"></div>
+  <div class="key-insight-text">{{ seg.body | e if seg.body else seg.title | e }}</div>
+  <div class="key-insight-rule"></div>
+</div>
+{% endblock %}

tutor/visual/templates/memory_hook.html.j2

@@ -0,0 +1,7 @@
+{% extends "_base.html.j2" %}
+{% block extra_style %}:root { --type-accent: var(--rose); }{% endblock %}
+{% block content %}
+<div class="memory-hook-slide">
+  <p class="memory-hook-text">{{ seg.body | e if seg.body else seg.title | e }}</p>
+</div>
+{% endblock %}

tutor/visual/templates/outro.html.j2

@@ -0,0 +1,16 @@
+{% extends "_base.html.j2" %}
+{% block top_bar %}LearnX{% endblock %}
+{% block footer %}{% endblock %}
+{% block content %}
+<div class="outro-slide">
+  <div class="outro-text">That's a wrap.</div>
+  {% if spec is defined and spec.memory_hooks %}
+  <div class="outro-sub">
+    {% for hook in spec.memory_hooks[:3] %}{{ hook | e }}{% if not loop.last %} &nbsp;·&nbsp; {% endif %}{% endfor %}
+  </div>
+  {% endif %}
+  {% if spec is defined and spec.session_stats %}
+  <div class="outro-sub">{{ spec.session_stats | e }}</div>
+  {% endif %}
+</div>
+{% endblock %}

tutor/visual/templates/question_prompt.html.j2

@@ -0,0 +1,13 @@
+{% extends "_base.html.j2" %}
+{% block extra_style %}:root { --type-accent: var(--amber); }{% endblock %}
+{% block top_bar %}{% endblock %}
+{% block footer %}{% endblock %}
+{% block content %}
+<div class="question-slide">
+  {% set speaker = seg.title.split(':')[0].strip().upper() if seg.title and ':' in seg.title else 'MAYA' %}
+  <span class="speaker-badge {% if speaker == 'SAM' %}badge-sam{% else %}badge-maya{% endif %}">
+    {{ speaker }}
+  </span>
+  <p class="question-text">{{ seg.body | e if seg.body else seg.title | e }}</p>
+</div>
+{% endblock %}

tutor/visual/templates/step_sequence.html.j2

@@ -0,0 +1,14 @@
+{% extends "_base.html.j2" %}
+{% block extra_style %}:root { --type-accent: var(--sky); }{% endblock %}
+{% block content %}
+<div class="step-slide">
+  {% if seg.body %}
+    {% for step in seg.body.split('\n') if step.strip() %}
+    <div class="step-item">
+      <div class="step-num">{{ loop.index }}</div>
+      <div class="step-text">{{ step.strip() | e }}</div>
+    </div>
+    {% endfor %}
+  {% endif %}
+</div>
+{% endblock %}

tutor/visual/templates/title_card.html.j2

@@ -0,0 +1,12 @@
+{% extends "_base.html.j2" %}
+{% block top_bar %}LearnX{% endblock %}
+{% block footer %}{% endblock %}
+{% block content %}
+<div class="title-card-slide">
+  <div class="title-card-accent"></div>
+  <div class="title-card-title">{{ spec.title | e if spec is defined and spec.title else 'LearnX Tutorial' }}</div>
+  {% if spec is defined and spec.subtitle %}
+  <div class="title-card-sub">{{ spec.subtitle | e }}</div>
+  {% endif %}
+</div>
+{% endblock %}