learnx-cli 0.3.0__py3-none-any.whl

tutor/tests/visual/test_beat_timer.py

@@ -0,0 +1,321 @@
+from pathlib import Path
+
+import pytest
+
+from tutor.models import DialogueLine, SlideSegment, VisualSpec
+from tutor.visual.beat_timer import (
+    MIN_SLIDE_DURATION,
+    OUTRO_CARD_DURATION,
+    TITLE_CARD_DURATION,
+    _compute_slide_timings_v2,
+    compute_slide_timings,
+    compute_slide_timings_v3,
+)
+
+
+def _line(speaker: str, unit: int) -> DialogueLine:
+    return DialogueLine(speaker=speaker, text="Some text here", unit_number=unit)
+
+
+def _unit_spec(idx: int) -> VisualSpec:
+    return VisualSpec(
+        unit_index=idx,
+        slide_type="unit",
+        concept=f"Concept {idx}",
+        memory_hook="remember this",
+    )
+
+
+def _slides(n_units: int) -> list[Path]:
+    paths = [Path("slides/00_title.png")]
+    for i in range(1, n_units + 1):
+        paths += [
+            Path(f"slides/{i:02d}_hook.png"),
+            Path(f"slides/{i:02d}_concept.png"),
+            Path(f"slides/{i:02d}_memory.png"),
+        ]
+    paths.append(Path("slides/99_outro.png"))
+    return paths
+
+
+def test_title_card_fixed_4_seconds():
+    script = [_line("ALEX", 1), _line("MAYA", 1)]
+    offsets = [0.0, 5.0]
+    visuals = [
+        VisualSpec(unit_index=0, slide_type="title_card"),
+        _unit_spec(1),
+        VisualSpec(unit_index=2, slide_type="outro"),
+    ]
+    slides = _slides(1)
+    timings = compute_slide_timings(slides, script, offsets, visuals, [30.0])
+
+    title_timing = next((d for p, d in timings if "_title" in p.stem), None)
+    assert title_timing == TITLE_CARD_DURATION
+
+
+def test_outro_card_fixed_6_seconds():
+    script = [_line("ALEX", 1), _line("MAYA", 1)]
+    offsets = [0.0, 5.0]
+    visuals = [
+        VisualSpec(unit_index=0, slide_type="title_card"),
+        _unit_spec(1),
+        VisualSpec(unit_index=2, slide_type="outro"),
+    ]
+    slides = _slides(1)
+    timings = compute_slide_timings(slides, script, offsets, visuals, [30.0])
+
+    outro_timing = next((d for p, d in timings if "_outro" in p.stem), None)
+    assert outro_timing == OUTRO_CARD_DURATION
+
+
+def test_hook_slide_assigned_to_first_alex_line():
+    script = [_line("ALEX", 1), _line("MAYA", 1), _line("ALEX", 1)]
+    offsets = [2.0, 10.0, 20.0]
+    visuals = [
+        VisualSpec(unit_index=0, slide_type="title_card"),
+        _unit_spec(1),
+        VisualSpec(unit_index=2, slide_type="outro"),
+    ]
+    slides = _slides(1)
+    timings = compute_slide_timings(slides, script, offsets, visuals, [30.0])
+
+    hook_dur = next((d for p, d in timings if "_hook" in p.stem), None)
+    # Hook starts at 2.0 (first ALEX), concept at 10.0 → duration = 8.0
+    assert hook_dur == pytest.approx(8.0, abs=0.01)
+
+
+def test_concept_slide_assigned_to_first_maya_line():
+    script = [_line("ALEX", 1), _line("MAYA", 1), _line("ALEX", 1)]
+    offsets = [2.0, 10.0, 20.0]
+    visuals = [
+        VisualSpec(unit_index=0, slide_type="title_card"),
+        _unit_spec(1),
+        VisualSpec(unit_index=2, slide_type="outro"),
+    ]
+    slides = _slides(1)
+    timings = compute_slide_timings(slides, script, offsets, visuals, [30.0])
+
+    # concept starts at 10.0, memory starts at 20.0 (last ALEX) → dur = 10.0
+    concept_dur = next((d for p, d in timings if "_concept" in p.stem), None)
+    assert concept_dur == pytest.approx(10.0, abs=0.01)
+
+
+def test_minimum_slide_duration_enforced():
+    # All lines packed into 1 second — every slide should be clamped to MIN
+    script = [_line("ALEX", 1), _line("MAYA", 1), _line("ALEX", 1)]
+    offsets = [0.0, 0.1, 0.2]
+    visuals = [
+        VisualSpec(unit_index=0, slide_type="title_card"),
+        _unit_spec(1),
+        VisualSpec(unit_index=2, slide_type="outro"),
+    ]
+    slides = _slides(1)
+    timings = compute_slide_timings(slides, script, offsets, visuals, [0.3])
+
+    for path, dur in timings:
+        if "_title" in path.stem or "_outro" in path.stem:
+            continue
+        assert dur >= MIN_SLIDE_DURATION
+
+
+# ── v3 beat timer tests ───────────────────────────────────────────────────────
+
+
+def _make_seg(
+    unit_index: int = 1,
+    segment_index: int = 0,
+    lines_start: int = 0,
+    lines_end: int = 1,
+    visual_type: str = "key_insight",
+    png_path: str = "slides/01_00_key_insight.png",
+) -> SlideSegment:
+    return SlideSegment(
+        unit_index=unit_index,
+        segment_index=segment_index,
+        lines_start=lines_start,
+        lines_end=lines_end,
+        visual_type=visual_type,
+        title="Test",
+        body=None,
+        code=None,
+        language=None,
+        mermaid=None,
+        left=None,
+        right=None,
+        rows=None,
+        png_path=png_path,
+    )
+
+
+def _timing_json(unit_timings: dict) -> dict:
+    return {"version": 1, "units": unit_timings}
+
+
+def test_exact_duration_from_timing_json() -> None:
+    seg = _make_seg(lines_start=0, lines_end=0)
+    unit_timing = [{"line_index": 0, "start_ms": 0, "end_ms": 3240}]
+    tj = _timing_json({"1": unit_timing})
+    timings = compute_slide_timings_v3(
+        Path("slides/00_title.png"),
+        Path("slides/99_outro.png"),
+        {1: [seg]},
+        tj,
+        [30.0],
+    )
+    # title, seg, outro
+    # raw = 3240ms, +1 line * SILENCE_TURN_MS(500ms) = 3740ms = 3.74 s
+    seg_dur = timings[1][1]
+    assert seg_dur == pytest.approx(3.74, abs=0.01)
+
+
+def test_exact_duration_uses_lines_start_and_end() -> None:
+    seg = _make_seg(lines_start=2, lines_end=4)
+    unit_timing = [
+        {"line_index": 0, "start_ms": 0, "end_ms": 1000},
+        {"line_index": 1, "start_ms": 1000, "end_ms": 2000},
+        {"line_index": 2, "start_ms": 2000, "end_ms": 3000},
+        {"line_index": 3, "start_ms": 3000, "end_ms": 4000},
+        {"line_index": 4, "start_ms": 4000, "end_ms": 9000},
+    ]
+    tj = _timing_json({"1": unit_timing})
+    timings = compute_slide_timings_v3(
+        Path("slides/00_title.png"),
+        Path("slides/99_outro.png"),
+        {1: [seg]},
+        tj,
+        [30.0],
+    )
+    # raw = 9000-2000 = 7000ms, +1 trailing SILENCE_TURN_MS(500ms) = 7500ms = 7.5 s
+    assert timings[1][1] == pytest.approx(7.5, abs=0.01)
+
+
+def test_proportional_fallback_when_timing_absent() -> None:
+    seg = _make_seg(lines_start=0, lines_end=4)
+    timings = compute_slide_timings_v3(
+        Path("slides/00_title.png"),
+        Path("slides/99_outro.png"),
+        {1: [seg]},
+        None,
+        [30.0],
+    )
+    # proportional: 5/5 lines of 30 s = 30.0 s
+    assert timings[1][1] == pytest.approx(30.0, abs=0.01)
+
+
+def test_min_slide_duration_enforced() -> None:
+    # Very short segment (0.5 s) should be clamped to MIN_SLIDE_DURATION
+    seg = _make_seg(lines_start=0, lines_end=0)
+    unit_timing = [{"line_index": 0, "start_ms": 0, "end_ms": 500}]
+    tj = _timing_json({"1": unit_timing})
+    timings = compute_slide_timings_v3(
+        Path("slides/00_title.png"),
+        Path("slides/99_outro.png"),
+        {1: [seg]},
+        tj,
+        [30.0],
+    )
+    assert timings[1][1] >= MIN_SLIDE_DURATION
+
+
+def test_title_duration_is_4_seconds() -> None:
+    title_path = Path("slides/00_title.png")
+    seg = _make_seg()
+    timings = compute_slide_timings_v3(
+        title_path, Path("slides/99_outro.png"), {1: [seg]}, None, [30.0]
+    )
+    assert timings[0] == (title_path, TITLE_CARD_DURATION)
+
+
+def test_outro_duration_is_6_seconds() -> None:
+    outro_path = Path("slides/99_outro.png")
+    seg = _make_seg()
+    timings = compute_slide_timings_v3(
+        Path("slides/00_title.png"), outro_path, {1: [seg]}, None, [30.0]
+    )
+    assert timings[-1] == (outro_path, OUTRO_CARD_DURATION)
+
+
+def test_all_segments_present_in_output() -> None:
+    segs_u1 = [_make_seg(unit_index=1, segment_index=i) for i in range(3)]
+    segs_u2 = [_make_seg(unit_index=2, segment_index=i) for i in range(2)]
+    timings = compute_slide_timings_v3(
+        Path("slides/00_title.png"),
+        Path("slides/99_outro.png"),
+        {1: segs_u1, 2: segs_u2},
+        None,
+        [30.0, 30.0],
+    )
+    # title + 3 + 2 + outro = 7
+    assert len(timings) == 7
+
+
+def test_timing_gap_accounted_in_exact_duration() -> None:
+    from tutor.constants import SILENCE_TURN_MS
+    from tutor.visual.beat_timer import _exact_duration
+
+    seg = _make_seg(lines_start=0, lines_end=2)  # 3 lines
+    unit_timing = [
+        {"line_index": 0, "start_ms": 0, "end_ms": 1000},
+        {"line_index": 1, "start_ms": 1500, "end_ms": 2500},
+        {"line_index": 2, "start_ms": 3000, "end_ms": 4000},
+    ]
+    raw_ms = 4000 - 0  # end_ms of last - start_ms of first
+    expected_s = (raw_ms + SILENCE_TURN_MS) / 1000.0
+    assert _exact_duration(seg, unit_timing) == pytest.approx(expected_s, abs=0.01)
+
+
+def test_single_line_segment_includes_one_gap() -> None:
+    from tutor.constants import SILENCE_TURN_MS
+    from tutor.visual.beat_timer import MIN_SLIDE_DURATION, _exact_duration
+
+    seg = _make_seg(lines_start=1, lines_end=1)  # 1 line
+    unit_timing = [
+        {"line_index": 0, "start_ms": 0, "end_ms": 800},
+        {"line_index": 1, "start_ms": 1300, "end_ms": 5500},  # long enough to exceed MIN
+    ]
+    raw_ms = 5500 - 1300
+    expected_s = max((raw_ms + 1 * SILENCE_TURN_MS) / 1000.0, MIN_SLIDE_DURATION)
+    assert _exact_duration(seg, unit_timing) == pytest.approx(expected_s, abs=0.01)
+
+
+def test_exact_duration_single_line_adds_one_turn_silence() -> None:
+    """Single line: duration = (end - start) + 1 × SILENCE_TURN_MS."""
+    from tutor.constants import SILENCE_TURN_MS
+    from tutor.visual.beat_timer import _exact_duration
+
+    seg = _make_seg(lines_start=0, lines_end=0)
+    unit_timing = [{"start_ms": 0, "end_ms": 2000}]
+    dur = _exact_duration(seg, unit_timing)
+    expected_ms = (2000 - 0) + SILENCE_TURN_MS
+    assert abs(dur - expected_ms / 1000.0) < 0.001
+
+
+def test_exact_duration_multi_line_still_adds_one_turn_silence() -> None:
+    """5-line segment: only 1 trailing silence added, not 5."""
+    from tutor.constants import SILENCE_TURN_MS
+    from tutor.visual.beat_timer import _exact_duration
+
+    seg = _make_seg(lines_start=0, lines_end=4)
+    unit_timing = [
+        {"start_ms": 0, "end_ms": 1000},
+        {"start_ms": 1500, "end_ms": 2500},
+        {"start_ms": 3000, "end_ms": 4000},
+        {"start_ms": 4500, "end_ms": 5500},
+        {"start_ms": 6000, "end_ms": 7000},
+    ]
+    dur = _exact_duration(seg, unit_timing)
+    expected_ms = (7000 - 0) + SILENCE_TURN_MS  # raw span + 1 trailing silence
+    assert abs(dur - expected_ms / 1000.0) < 0.001
+
+
+def test_v2_function_still_callable() -> None:
+    script = [_line("ALEX", 1), _line("MAYA", 1)]
+    offsets = [0.0, 5.0]
+    visuals = [
+        VisualSpec(unit_index=0, slide_type="title_card"),
+        _unit_spec(1),
+        VisualSpec(unit_index=2, slide_type="outro"),
+    ]
+    slides = _slides(1)
+    result = _compute_slide_timings_v2(slides, script, offsets, visuals, [30.0])
+    assert isinstance(result, list)

tutor/tests/visual/test_pipeline_integration.py

@@ -0,0 +1,178 @@
+"""
+Integration tests for tutor/visual/__init__.py — run_visual_pipeline and helpers.
+Heavy operations (LLM, Playwright, ffmpeg) are mocked.
+"""
+
+import json
+from pathlib import Path
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from tutor.visual import _load_timing_json
+
+# ── _load_timing_json tests ───────────────────────────────────────────────────
+
+
+def test_load_timing_json_returns_none_for_absent_file(tmp_path: Path) -> None:
+    assert _load_timing_json(tmp_path) is None
+
+
+def test_load_timing_json_returns_none_for_wrong_version(tmp_path: Path) -> None:
+    (tmp_path / "tutorial.timing.json").write_text(
+        json.dumps({"version": 2, "units": {}}), encoding="utf-8"
+    )
+    assert _load_timing_json(tmp_path) is None
+
+
+def test_load_timing_json_returns_none_for_corrupt_json(tmp_path: Path) -> None:
+    (tmp_path / "tutorial.timing.json").write_text("not json {{{{", encoding="utf-8")
+    assert _load_timing_json(tmp_path) is None
+
+
+# ── run_visual_pipeline tests ─────────────────────────────────────────────────
+
+
+def _write_units_json(audio_dir: Path, n_units: int = 1) -> None:
+    units = []
+    for i in range(1, n_units + 1):
+        units.append(
+            {
+                "unit": i,
+                "concept": f"Concept {i}",
+                "lines": [
+                    {"speaker": "ALEX", "text": "Hello", "unit_number": i},
+                    {"speaker": "MAYA", "text": "Great", "unit_number": i},
+                ],
+            }
+        )
+    (audio_dir / "tutorial.units.json").write_text(json.dumps(units), encoding="utf-8")
+
+
+def _make_mock_pipeline(tmp_path: Path, video_dir: Path) -> tuple:
+    """Return (mock_plan_visuals, mock_plan_segments, mock_render_all, mock_build_srt,
+    mock_compute_v3, mock_assemble) all configured with sensible return values."""
+    from tutor.models import SlideSegment, VisualSpec
+
+    title_spec = VisualSpec(unit_index=0, slide_type="title_card", title="Test")
+    outro_spec = VisualSpec(unit_index=99, slide_type="outro", title="Outro")
+
+    title_path = video_dir / "slides" / "00_title.png"
+    outro_path = video_dir / "slides" / "99_outro.png"
+    title_path.parent.mkdir(parents=True, exist_ok=True)
+    title_path.write_bytes(b"PNG")
+    outro_path.write_bytes(b"PNG")
+
+    seg = SlideSegment(
+        unit_index=1,
+        segment_index=0,
+        lines_start=0,
+        lines_end=1,
+        visual_type="key_insight",
+        title="T",
+        body=None,
+        code=None,
+        language=None,
+        mermaid=None,
+        left=None,
+        right=None,
+        rows=None,
+        png_path=str(video_dir / "slides" / "01_00_key_insight.png"),
+    )
+
+    mock_visuals = MagicMock(return_value=[title_spec, outro_spec])
+    mock_segments = MagicMock(return_value={1: [seg]})
+    mock_render = MagicMock(
+        return_value=[title_path, video_dir / "slides" / "01_00_key_insight.png", outro_path]
+    )
+    mock_srt = MagicMock(return_value="1\n00:00:00,000 --> 00:00:01,000\nALEX: Hello\n")
+    mock_compute = MagicMock(return_value=[(title_path, 4.0), (outro_path, 6.0)])
+    result_mp4 = video_dir / "full_session.mp4"
+    result_mp4.write_bytes(b"fake")
+    mock_assemble = MagicMock(return_value=result_mp4)
+
+    return mock_visuals, mock_segments, mock_render, mock_srt, mock_compute, mock_assemble
+
+
+def test_run_visual_pipeline_six_steps_printed(
+    tmp_path: Path, capsys: pytest.CaptureFixture
+) -> None:
+    audio_dir = tmp_path / "audio" / "s1"
+    video_dir = tmp_path / "video" / "s1"
+    audio_dir.mkdir(parents=True)
+    video_dir.mkdir(parents=True)
+    (audio_dir / "tutorial_units").mkdir()
+    _write_units_json(audio_dir)
+
+    mv, ms, mr, msrt, mc, ma = _make_mock_pipeline(tmp_path, video_dir)
+
+    with (
+        patch("tutor.generation.visual_planner.plan_visuals", mv),
+        patch("tutor.generation.segment_planner.plan_segments", ms),
+        patch("tutor.visual.slide_renderer.render_all_slides", mr),
+        patch("tutor.visual.subtitle_writer.build_srt", msrt),
+        patch("tutor.visual.beat_timer.compute_slide_timings_v3", mc),
+        patch("tutor.visual.video_assembler.assemble_session", ma),
+        patch("tutor.visual._mp3_duration", return_value=30.0),
+    ):
+        from tutor.visual import run_visual_pipeline
+
+        run_visual_pipeline("s1", audio_dir, video_dir, MagicMock())
+
+    captured = capsys.readouterr()
+    for i in range(1, 7):
+        assert f"[{i}/6]" in captured.out
+
+
+def test_run_visual_pipeline_no_timing_json(tmp_path: Path) -> None:
+    audio_dir = tmp_path / "audio" / "s1"
+    video_dir = tmp_path / "video" / "s1"
+    audio_dir.mkdir(parents=True)
+    video_dir.mkdir(parents=True)
+    (audio_dir / "tutorial_units").mkdir()
+    _write_units_json(audio_dir)
+    # Deliberately no tutorial.timing.json
+
+    mv, ms, mr, msrt, mc, ma = _make_mock_pipeline(tmp_path, video_dir)
+
+    with (
+        patch("tutor.generation.visual_planner.plan_visuals", mv),
+        patch("tutor.generation.segment_planner.plan_segments", ms),
+        patch("tutor.visual.slide_renderer.render_all_slides", mr),
+        patch("tutor.visual.subtitle_writer.build_srt", msrt),
+        patch("tutor.visual.beat_timer.compute_slide_timings_v3", mc),
+        patch("tutor.visual.video_assembler.assemble_session", ma),
+        patch("tutor.visual._mp3_duration", return_value=30.0),
+    ):
+        from tutor.visual import run_visual_pipeline
+
+        result = run_visual_pipeline("s1", audio_dir, video_dir, MagicMock())
+
+    assert result is not None
+
+
+@pytest.mark.slow
+def test_output_path_is_under_video_dir(tmp_path: Path) -> None:
+    audio_dir = tmp_path / "audio" / "s1"
+    video_dir = tmp_path / "video" / "s1"
+    audio_dir.mkdir(parents=True)
+    video_dir.mkdir(parents=True)
+    (audio_dir / "tutorial_units").mkdir()
+    _write_units_json(audio_dir)
+
+    mv, ms, mr, msrt, mc, ma = _make_mock_pipeline(tmp_path, video_dir)
+
+    with (
+        patch("tutor.generation.visual_planner.plan_visuals", mv),
+        patch("tutor.generation.segment_planner.plan_segments", ms),
+        patch("tutor.visual.slide_renderer.render_all_slides", mr),
+        patch("tutor.visual.subtitle_writer.build_srt", msrt),
+        patch("tutor.visual.beat_timer.compute_slide_timings_v3", mc),
+        patch("tutor.visual.video_assembler.assemble_session", ma),
+        patch("tutor.visual._mp3_duration", return_value=30.0),
+    ):
+        from tutor.visual import run_visual_pipeline
+
+        result = run_visual_pipeline("s1", audio_dir, video_dir, MagicMock())
+
+    assert str(result).startswith(str(video_dir))