Add user video↔slide matching with auto-detect fallback

- semantic_alignment: new --mapping option accepts a JSON file mapping
  caption stems to slide file paths. User-mapped pairs are used first;
  unmapped captions fall back to auto name/content matching.
- gui.py Align page: new "Video ↔ Slide Matching" card that:
  - Scans course folder for all captions and slide files
  - Shows each video with a dropdown to select its slide file
  - "(none)" = auto-detect fallback
  - Saves mapping JSON and passes it to the align script
- Priority order: user mapping → lecture number match → filename
  similarity → content embedding fallback

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: nodeeeeee

gui.py

@@ -1201,6 +1201,106 @@ def build_align(page: ft.Page, console: OutputConsole) -> ft.Column:
     manual_out_f = _text_field("Output directory",
                                 hint="blank = auto-inferred")
 
+    # ── Video ↔ Slide Matching state ─────────────────────────────────────────
+    match_rows_col = ft.Column(controls=[], spacing=6)
+    match_course_dd = _course_dropdown(
+        value=course_val["v"],
+        on_select=lambda e: course_val.update({"v": e.data}),
+    )
+    # Each row: {caption_stem, dropdown_value}
+    _match_state: dict = {"rows": [], "captions": [], "slide_options": []}
+
+    def _scan_matching(_) -> None:
+        """Scan course folder for captions and slide files, build matching UI."""
+        cid = course_val["v"]
+        base = _get_output_dir() / cid
+        cap_dir = base / "captions"
+        mat_dir = base / "materials"
+
+        captions = sorted(cap_dir.glob("*.json")) if cap_dir.exists() else []
+        exts = {".pdf", ".pptx", ".ppt", ".docx", ".doc"}
+        slides = sorted([
+            p for p in mat_dir.rglob("*")
+            if p.is_file() and p.suffix.lower() in exts
+            and "image_cache" not in p.name
+        ]) if mat_dir.exists() else []
+
+        if not captions:
+            console.write("No captions found. Transcribe videos first.", color=C_WARN)
+            return
+
+        # Build dropdown options: "(none)" + all slide files
+        slide_opts = [ft.dropdown.Option("(none)", "(none — auto-detect)")]
+        for sp in slides:
+            rel = str(sp.relative_to(base))
+            slide_opts.append(ft.dropdown.Option(rel, sp.name))
+
+        _match_state["captions"] = captions
+        _match_state["slide_options"] = slides
+        _match_state["rows"] = []
+        match_rows_col.controls.clear()
+
+        for cap in captions:
+            dd = ft.Dropdown(
+                options=list(slide_opts),  # copy
+                value="(none)",
+                dense=True,
+                bgcolor=C_OUTPUT_BG,
+                border_color=C_PRIMARY,
+                text_size=11,
+                expand=True,
+            )
+            _match_state["rows"].append({"stem": cap.stem, "dropdown": dd})
+            match_rows_col.controls.append(
+                ft.Row(controls=[
+                    ft.Text(cap.stem, size=11, width=250,
+                            color=ft.Colors.WHITE, overflow=ft.TextOverflow.ELLIPSIS),
+                    ft.Icon(ft.Icons.ARROW_FORWARD, size=14, color=C_PRIMARY),
+                    dd,
+                ], spacing=8, vertical_alignment=ft.CrossAxisAlignment.CENTER)
+            )
+
+        page.update()
+        console.write(f"Found {len(captions)} caption(s), {len(slides)} slide file(s). "
+                      "Select matching slides for each video, then click 'Align with mapping'.",
+                      color=C_SUCCESS)
+
+    def _run_with_mapping(_) -> None:
+        """Save the mapping and run alignment with it."""
+        cid = course_val["v"]
+        base = _get_output_dir() / cid
+
+        mapping: dict[str, list[str]] = {}
+        for row in _match_state["rows"]:
+            val = row["dropdown"].value
+            if val and val != "(none)":
+                mapping[row["stem"]] = [val]
+
+        if not mapping and not _match_state["rows"]:
+            console.write("Scan for videos first.", color=C_WARN)
+            return
+
+        # Save mapping JSON
+        mapping_file = base / "alignment" / "video_slide_mapping.json"
+        mapping_file.parent.mkdir(parents=True, exist_ok=True)
+        with open(mapping_file, "w") as f:
+            json.dump(mapping, f, indent=2)
+
+        n_mapped = len(mapping)
+        n_total = len(_match_state["rows"])
+        console.write(
+            f"Mapping saved: {n_mapped}/{n_total} video(s) matched to slides. "
+            f"Remaining {n_total - n_mapped} will use auto-detect.",
+            color=C_PRIMARY,
+        )
+
+        cmd = [PYTHON, str(SCRIPTS["align"]),
+               "--course", cid,
+               "--mapping", str(mapping_file)]
+        if out_dir_f.value.strip():
+            cmd += ["--out", out_dir_f.value.strip()]
+        console.run(cmd)
+
     def _run_course(_) -> None:
         cmd = [PYTHON, str(SCRIPTS["align"]), "--course", course_val["v"]]
         if out_dir_f.value.strip():
@@ -1227,16 +1327,39 @@ def _run_manual(_) -> None:
             ft.Icon(ft.Icons.INFO_OUTLINE, color=C_PRIMARY, size=15),
             ft.Text(
                 f"Embed: {embed_model}   Context: ±{ctx_sec}s   "
-                "Content-based fallback if names don't match.",
+                "Match videos to slides, or let auto-detect find them.",
                 size=12,
                 color=ft.Colors.with_opacity(0.7, ft.Colors.WHITE),
             ),
         ], spacing=8)),
 
+        # ── Video ↔ Slide Matching card ──────────────────────────────────────
+        _card(ft.Column(controls=[
+            ft.Text("Video ↔ Slide Matching", size=13,
+                    weight=ft.FontWeight.BOLD, color=ft.Colors.WHITE),
+            ft.Text("Match each video to its lecture slides. "
+                    "Unmatched videos fall back to auto-detect.",
+                    size=12, color=ft.Colors.with_opacity(0.6, ft.Colors.WHITE)),
+            ft.Container(height=6),
+            ft.Row(controls=[
+                ft.Column(controls=[_label("Course"), match_course_dd],
+                          spacing=6, expand=True),
+                _run_btn("Scan", ft.Icons.SEARCH, _scan_matching),
+            ], spacing=12, vertical_alignment=ft.CrossAxisAlignment.END),
+            ft.Container(height=4),
+            match_rows_col,
+            ft.Container(height=4),
+            ft.Row(controls=[
+                _run_btn("Align with mapping", ft.Icons.LINK, _run_with_mapping),
+            ]),
+        ], spacing=8)),
+
+        # ── Auto-discover card ───────────────────────────────────────────────
         _card(ft.Column(controls=[
             ft.Text("Auto-discover (whole course)", size=13,
                     weight=ft.FontWeight.BOLD, color=ft.Colors.WHITE),
-            ft.Text("Pairs all unaligned captions with matching slide files.",
+            ft.Text("Auto-pairs all captions with slides by name/content. "
+                    "No user matching needed.",
                     size=12, color=ft.Colors.with_opacity(0.6, ft.Colors.WHITE)),
             ft.Container(height=6),
             ft.Row(controls=[

semantic_alignment.py

@@ -1380,7 +1380,33 @@ def _content_match_slide_group(
     return [best]
 
 
-def process_course(course_id: int | str, use_jina: bool = False) -> None:
+def _load_mapping(mapping_path: Path, course_dir: Path) -> dict[str, list[Path]]:
+    """Load a user-supplied video↔slide mapping JSON.
+
+    Format: {"caption_stem": ["path/to/slide.pdf", ...], ...}
+    Paths are relative to course_dir or absolute.
+    Returns {caption_stem: [resolved_Path, ...]}.
+    """
+    with open(mapping_path, encoding="utf-8") as f:
+        raw = json.load(f)
+    mapping: dict[str, list[Path]] = {}
+    for cap_stem, slide_list in raw.items():
+        resolved = []
+        for sp in slide_list:
+            p = Path(sp)
+            if not p.is_absolute():
+                p = course_dir / p
+            if p.exists():
+                resolved.append(p)
+            else:
+                print(f"  [warn] Mapped slide not found: {sp}")
+        if resolved:
+            mapping[cap_stem] = resolved
+    return mapping
+
+
+def process_course(course_id: int | str, use_jina: bool = False,
+                   mapping_path: Path | None = None) -> None:
     course_dir  = COURSE_DATA_DIR / str(course_id)
     captions_dir = course_dir / "captions"
     print(f"Course dir : {course_dir}", flush=True)
@@ -1401,6 +1427,14 @@ def process_course(course_id: int | str, use_jina: bool = False) -> None:
 
     print(f"Found {len(captions)} caption(s), {len(all_slides)} slide file(s).", flush=True)
 
+    # ── Load user-supplied mapping if provided ────────────────────────────────
+    user_mapping: dict[str, list[Path]] = {}
+    if mapping_path and mapping_path.exists():
+        user_mapping = _load_mapping(mapping_path, course_dir)
+        print(f"  User mapping: {len(user_mapping)} video→slide pair(s) loaded")
+        for cap_stem, slides in user_mapping.items():
+            print(f"    {cap_stem} → {[s.name for s in slides]}")
+
     # Check Jina API availability if requested
     if use_jina:
         jina_key = _get_jina_key()
@@ -1417,7 +1451,7 @@ def process_course(course_id: int | str, use_jina: bool = False) -> None:
         if num is not None:
             slides_by_num[num].append(sp)
 
-    embedder = None if use_jina else get_embedder()
+    embedder = None if use_jina else None  # lazy-load only when needed
 
     for cap in captions:
         # Skip captions flagged as low-quality (wrong/empty recordings)
@@ -1430,20 +1464,24 @@ def process_course(course_id: int | str, use_jina: bool = False) -> None:
         except Exception:
             pass   # can't read → proceed and let align() handle it
 
-        # Find matching slides
-        if embedder is None and not use_jina:
-            embedder = get_embedder()
-
-        slide_group = _find_best_slide_group(cap, slides_by_num, all_slides)
-        if not slide_group:
-            if embedder is None:
-                embedder = get_embedder()
-            slide_group = _content_match_slide_group(
-                cap, slides_by_num, all_slides, embedder
-            )
-        if not slide_group:
-            print(f"  [warn] No matching slides for {cap.name} — skipping")
-            continue
+        # ── Priority 1: user-supplied mapping ────────────────────────────────
+        slide_group: list[Path] = []
+        if cap.stem in user_mapping:
+            slide_group = user_mapping[cap.stem]
+            print(f"  [mapping] {cap.name} → {[s.name for s in slide_group]}")
+        else:
+            # ── Priority 2: automatic name/number matching ───────────────────
+            slide_group = _find_best_slide_group(cap, slides_by_num, all_slides)
+            if not slide_group:
+                # ── Priority 3: content embedding fallback ───────────────────
+                if embedder is None:
+                    embedder = get_embedder()
+                slide_group = _content_match_slide_group(
+                    cap, slides_by_num, all_slides, embedder
+                )
+            if not slide_group:
+                print(f"  [warn] No matching slides for {cap.name} — skipping")
+                continue
 
         # Check if all output files for this group already exist
         if len(slide_group) == 1:
@@ -1463,8 +1501,6 @@ def process_course(course_id: int | str, use_jina: bool = False) -> None:
                 continue
             # Fall back to text-based on failure
             print("  [jina] Falling back to text-based alignment")
-            if embedder is None:
-                embedder = get_embedder()
 
         if embedder is None:
             embedder = get_embedder()
@@ -1486,10 +1522,15 @@ def main() -> None:
                         help="Output directory (default: [course]/alignment)")
     parser.add_argument("--jina",    action="store_true",
                         help="Use Jina Embeddings v4 for multimodal (image+text) alignment")
+    parser.add_argument("--mapping", metavar="JSON",
+                        help="User-supplied video↔slide mapping JSON file. "
+                             "Format: {\"caption_stem\": [\"slide_path\", ...]}. "
+                             "Unmapped captions fall back to auto-discovery.")
     args = parser.parse_args()
 
     if args.course:
-        process_course(args.course, use_jina=args.jina)
+        mapping = Path(args.mapping) if args.mapping else None
+        process_course(args.course, use_jina=args.jina, mapping_path=mapping)
         return
 
     if not args.caption or not args.slides: