from __future__ import annotations import argparse import hashlib from collections.abc import Callable, Iterable from pathlib import Path from PIL import Image from .captioner import ( OllamaCaptioner, ensure_caption_prompt_file, ensure_specialist_prompt_file, ) from .caption_windows import ( build_contact_sheet, caption_window_policy, caption_window_route_counts, iter_caption_windows, save_caption_window, ) from .config import settings from .database import connect, init_db, pack_vector, unpack_vector from .embedder import SiglipEmbedder from .frame_source import FrameSource from .frames import extract_frames, media_id_for, sha256_file from .jellyfin import ( caption_context_from_tags, route_override_from_tags, tags_from_json, ) from .jellyfin_index import ( cmd_jellyfin_index, cmd_jellyfin_items, cmd_jellyfin_libraries, cmd_jellyfin_test, ) from .maintenance import ( list_legacy_jellyfin_thumbs, list_media_by_source, remove_legacy_jellyfin_thumbs, remove_media_by_source, ) from .meili import Meili from .overviews import preview as preview_visual_overview from .overviews import publish as publish_visual_overview from .overviews import restore as restore_visual_overview from .routing import ExplicitContentRouter, apply_context_routing from .search_service import SearchService from .sync import ( CaptionMeiliSync, count_caption_repair_documents, rebuild_meili, repair_caption_documents, ) def format_ts(ms: int) -> str: total = ms // 1000 h, rem = divmod(total, 3600) m, s = divmod(rem, 60) return f"{h:02d}:{m:02d}:{s:02d}" def build_embedder() -> SiglipEmbedder: print(f"Loading {settings.model_id} on {settings.device}...") return SiglipEmbedder(settings.model_id, settings.device) def cmd_init(_: argparse.Namespace) -> None: init_db(settings.db_path) ensure_caption_prompt_file(settings.caption_prompt_file) ensure_specialist_prompt_file(settings.caption_specialist_prompt_file) print(f"SQLite ready: {settings.db_path}") print(f"General caption prompt: {settings.caption_prompt_file}") print(f"Specialist caption prompt: {settings.caption_specialist_prompt_file}") def cmd_index_file(args: argparse.Namespace) -> None: init_db(settings.db_path) path = Path(args.path).expanduser().resolve() if not path.is_file(): raise SystemExit(f"Not a file: {path}") interval_ms = int(round(args.interval * 1000)) stat = path.stat() digest = sha256_file(path) media_id = media_id_for(path, digest) title = args.title or path.stem with connect(settings.db_path) as con: row = con.execute("SELECT * FROM media WHERE id = ?", (media_id,)).fetchone() if ( row and row["content_sha256"] == digest and row["interval_ms"] == interval_ms and row["model_id"] == settings.model_id and not args.force ): count = con.execute("SELECT COUNT(*) FROM frames WHERE media_id = ?", (media_id,)).fetchone()[0] print(f"Already indexed: {title} ({count} frames). Use --force to rebuild.") return out_dir = settings.thumbs_dir / media_id print(f"Extracting one frame every {args.interval:g}s from {title!r}...") frame_paths = extract_frames(path, out_dir, args.interval) if not frame_paths: raise SystemExit("ffmpeg produced no frames") embedder = build_embedder() rows: list[tuple] = [] dim = None for start in range(0, len(frame_paths), settings.batch_size): batch_paths = frame_paths[start:start + settings.batch_size] images = [] try: for frame_path in batch_paths: images.append(Image.open(frame_path).convert("RGB")) vectors = embedder.embed_images(images) finally: for image in images: image.close() dim = int(vectors.shape[1]) for offset, (frame_path, vector) in enumerate(zip(batch_paths, vectors, strict=True)): frame_number = start + offset timestamp_ms = frame_number * interval_ms frame_id = hashlib.sha256(f"{media_id}:{timestamp_ms}:{settings.model_id}".encode()).hexdigest()[:40] rows.append(( frame_id, media_id, frame_number, timestamp_ms, str(frame_path), pack_vector(vector), )) print(f"Embedded {min(start + len(batch_paths), len(frame_paths))}/{len(frame_paths)} frames") assert dim is not None with connect(settings.db_path) as con: con.execute("DELETE FROM media WHERE id = ?", (media_id,)) con.execute( """ INSERT INTO media (id, source_path, title, content_sha256, size_bytes, mtime_ns, interval_ms, model_id, embedding_dim) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?) """, (media_id, str(path), title, digest, stat.st_size, stat.st_mtime_ns, interval_ms, settings.model_id, dim), ) con.executemany( """ INSERT INTO frames (id, media_id, frame_number, timestamp_ms, thumb_path, embedding_f16) VALUES (?, ?, ?, ?, ?, ?) """, rows, ) print(f"Stored {len(rows)} canonical frame embeddings in {settings.db_path}") print("Next: python -m scene_search.cli sync-meili") def cmd_sync_meili(_: argparse.Namespace) -> None: def report(update: dict) -> None: if update.get("stage") == "sync": print( f"Queued {int(update.get('documents_processed') or 0)} " "documents into Meilisearch" ) total = rebuild_meili(progress=report) if total: print("Meilisearch rebuild complete (tasks may continue briefly inside Meili).") else: print("Meilisearch cleared; no canonical media remain.") def cmd_repair_caption_index(args: argparse.Namespace) -> None: """Restore only the Meilisearch documents touched by caption sync.""" candidate_count = count_caption_repair_documents() print(f"Caption-affected canonical frame documents: {candidate_count:,}") if not candidate_count: print("Nothing to repair.") return if not args.apply: print( "Dry run: no changes made. Stop captioning/indexing first, then " "rerun with --apply to restore these documents from SQLite." ) return def progress(update: dict) -> None: count = int(update.get("documents_processed") or 0) print(f"Restored and indexed {count:,}/{candidate_count:,} documents") repaired = repair_caption_documents( batch_size=args.batch_size, progress=progress, resume_task_uid=args.resume_task, ) print( f"Repair invocation complete: {repaired:,} full documents confirmed " "during this invocation (progress is saved in SQLite). " "No visual embeddings or captions were regenerated." ) def _route_policy() -> str: if settings.caption_force_specialist: return ( "forced-specialist|" f"specialist={settings.caption_specialist_model}" ) tag_policy = ( f"force-specialist={settings.jellyfin_force_specialist_tag}|" f"force-general={settings.jellyfin_force_general_tag}|" f"specialist-tags={','.join(settings.jellyfin_specialist_tags)}" ) if not settings.caption_router_enabled: return ( f"disabled|general={settings.caption_general_model}|{tag_policy}" ) return ( f"model={settings.caption_router_model}|" f"threshold={settings.caption_router_threshold:.6f}|" f"context={settings.caption_router_context_seconds:.3f}|" f"{tag_policy}" ) def _caption_window_policy() -> str: return caption_window_policy( settings.caption_window_seconds, settings.caption_window_max_frames, ) def _route_model_name() -> str: if settings.caption_force_specialist: return "forced-specialist" if settings.caption_router_enabled: return settings.caption_router_model return "disabled" CaptionProgress = Callable[[dict], None] def _select_caption_rows( args: argparse.Namespace, *, only_needing_caption: bool, ) -> list: conditions = [] params: list[object] = [] if only_needing_caption and not getattr(args, "force", False): route_policy = _route_policy() window_policy = _caption_window_policy() conditions.append( "(" "f.caption_route IS NULL " "OR f.caption_route NOT IN ('general', 'specialist') " "OR f.route_policy IS NULL OR f.route_policy != ? " "OR NOT EXISTS (" " SELECT 1 " " FROM caption_window_frames cwf " " JOIN caption_windows cw ON cw.id = cwf.window_id " " WHERE cwf.frame_id = f.id " " AND cw.caption IS NOT NULL " " AND cw.window_policy = ? " " AND cw.route_policy = ? " " AND (" " (cw.caption_route = 'general' AND cw.caption_model = ?) " " OR (cw.caption_route = 'specialist' AND cw.caption_model = ?)" " )" ")" ")" ) params.extend( [ route_policy, window_policy, route_policy, settings.caption_general_model, settings.caption_specialist_model, ] ) if getattr(args, "media_id", None): conditions.append("f.media_id = ?") params.append(args.media_id) if getattr(args, "title", None): conditions.append("m.title = ?") params.append(args.title) library_ids = getattr(args, "library_ids", None) if library_ids: placeholders = ",".join("?" for _ in library_ids) conditions.append(f"m.jellyfin_library_id IN ({placeholders})") params.extend(library_ids) where = f"WHERE {' AND '.join(conditions)}" if conditions else "" limit = "" if getattr(args, "limit", None) is not None: limit = " LIMIT ?" params.append(args.limit) with connect(settings.db_path) as con: return con.execute( f""" SELECT f.id, f.media_id, f.frame_number, f.timestamp_ms, f.thumb_path, f.caption, f.caption_model, f.caption_route, f.caption_route_reason, f.route_score, f.route_model, f.route_policy, m.title, m.interval_ms, m.source_kind, m.jellyfin_item_id, m.jellyfin_media_source_id, m.jellyfin_tags, m.trickplay_width FROM frames f JOIN media m ON m.id = f.media_id {where} ORDER BY m.title, f.media_id, f.timestamp_ms {limit} """, params, ).fetchall() def _route_rows( rows: list, *, verbose: bool = False, progress: CaptionProgress | None = None, frame_source: FrameSource | None = None, before_batch: Callable[[], None] | None = None, ) -> tuple[list[tuple], int]: own_source = frame_source is None source = frame_source or FrameSource() missing = 0 try: policy = _route_policy() reusable = [ ( row, str(row["caption_route"]), float(row["route_score"] or 0.0), str(row["caption_route_reason"] or "saved"), ) for row in rows if str(row["route_policy"] or "") == policy and str(row["caption_route"] or "") in {"general", "specialist"} ] reusable_ids = {str(item[0]["id"]) for item in reusable} pending_rows = [ row for row in rows if str(row["id"]) not in reusable_ids ] if reusable: print( f"Reusing {len(reusable)} saved routing decision(s); " f"{len(pending_rows)} frame(s) need routing." ) if not pending_rows: if progress is not None: progress( { "stage": "routed", "frames_total": len(reusable), "frames_completed": 0, "failed": 0, } ) return reusable, 0 if settings.caption_force_specialist: print( f"Forcing {len(pending_rows)} frame(s) to specialist captioner " f"{settings.caption_specialist_model}; router skipped." ) valid_rows = list(pending_rows) scores = {str(row["id"]): 0.0 for row in valid_rows} decisions = { str(row["id"]): ("specialist", "global-specialist") for row in valid_rows } route_model = "forced-specialist" elif settings.caption_router_enabled: print( f"Routing {len(pending_rows)} frame(s) with " f"{settings.caption_router_model} on {settings.caption_router_device}..." ) router = ExplicitContentRouter( settings.caption_router_model, settings.caption_router_device, settings.caption_router_batch_size, ) valid_rows = [] score_values: list[float] = [] for start in range(0, len(pending_rows), settings.caption_router_batch_size): if before_batch is not None: before_batch() batch_rows = pending_rows[start:start + settings.caption_router_batch_size] images: list[Image.Image] = [] image_rows = [] try: for row in batch_rows: try: images.append(source.image(row)) image_rows.append(row) except Exception as exc: missing += 1 print( f"SKIP {row['title']} @ " f"{format_ts(int(row['timestamp_ms']))}: {exc}" ) if images: batch_scores = router.score_images(images) valid_rows.extend(image_rows) score_values.extend(batch_scores) finally: for image in images: image.close() if progress is not None: progress( { "stage": "routing", "frames_total": len(pending_rows), "frames_completed": min( start + len(batch_rows), len(pending_rows), ), "failed": missing, } ) if not valid_rows: return reusable, missing scores = { str(row["id"]): score for row, score in zip(valid_rows, score_values, strict=True) } route_input = [ { "id": str(row["id"]), "media_id": str(row["media_id"]), "timestamp_ms": int(row["timestamp_ms"]), } for row in valid_rows ] decisions = apply_context_routing( route_input, scores, settings.caption_router_threshold, int(round(settings.caption_router_context_seconds * 1000)), ) route_model = settings.caption_router_model else: valid_rows = list(pending_rows) scores = {str(row["id"]): 0.0 for row in valid_rows} decisions = { str(row["id"]): ("general", "disabled") for row in valid_rows } route_model = "disabled" if not settings.caption_force_specialist: for row in valid_rows: tags = tags_from_json(row["jellyfin_tags"]) override = route_override_from_tags( tags, force_specialist_tag=settings.jellyfin_force_specialist_tag, force_general_tag=settings.jellyfin_force_general_tag, specialist_tags=settings.jellyfin_specialist_tags, ) if override is not None: decisions[str(row["id"])] = override routed_by_id = { str(row["id"]): (row, route, score, reason) for row, route, score, reason in reusable } with connect(settings.db_path) as con: for row in valid_rows: frame_id = str(row["id"]) route, reason = decisions[frame_id] score = scores[frame_id] con.execute( """ UPDATE frames SET caption_route = ?, caption_route_reason = ?, route_score = ?, route_model = ?, route_policy = ?, routed_at = CURRENT_TIMESTAMP, meili_synced_at = NULL WHERE id = ? """, (route, reason, score, route_model, policy, frame_id), ) routed_by_id[frame_id] = (row, route, score, reason) if verbose: print( f"{row['title']} @ {format_ts(int(row['timestamp_ms']))}: " f"score={score:.4f} -> {route} ({reason})" ) routed = [ routed_by_id[str(row["id"])] for row in rows if str(row["id"]) in routed_by_id ] if progress is not None: progress( { "stage": "routed", "frames_total": len(routed), "frames_completed": 0, "failed": missing, } ) general_count = sum( 1 for _, route, _, _ in routed if route == "general" ) specialist_count = len(routed) - general_count if settings.caption_force_specialist: print( f"Routing complete: {specialist_count} specialist " "(global specialist override)" ) elif settings.caption_router_enabled: print( f"Routing complete: {general_count} general, " f"{specialist_count} specialist " f"(threshold {settings.caption_router_threshold:.2f}, " f"context ±{settings.caption_router_context_seconds:g}s)" ) else: print( f"Routing disabled: {general_count} frame(s) -> general model" ) return routed, missing finally: if own_source: source.close() def _unload_ollama_model(model: str) -> None: captioner = OllamaCaptioner( settings.ollama_url, model, settings.caption_timeout_seconds, max_tokens=settings.caption_max_tokens, ) try: captioner.unload() except Exception as exc: print(f"WARN could not unload {model}: {exc}") def _caption_window_queue( label: str, windows: Iterable, model: str, prompt: str, *, progress: CaptionProgress | None = None, completed_offset: int = 0, queue_total: int, total_windows: int | None = None, frame_source: FrameSource | None = None, before_window: Callable[[], None] | None = None, after_saved: Callable[[str], None] | None = None, ) -> tuple[int, int]: if queue_total <= 0: return 0, 0 print(f"\n{label}: {queue_total} window(s) with {model}") captioner = OllamaCaptioner( settings.ollama_url, model, settings.caption_timeout_seconds, prompt, settings.caption_max_tokens, ) own_source = frame_source is None source = frame_source or FrameSource() completed = 0 failed = 0 try: for window in windows: if before_window is not None: before_window() row = window.representative_row if progress is not None: progress( { "stage": "captioning", "title": window.title, "timestamp_ms": window.start_ms, "window_start_ms": window.start_ms, "window_end_ms": window.end_ms, "model": model, "route": window.route, "frames_total": total_windows or queue_total, "frames_completed": completed_offset + completed, "failed": failed, "work_unit": "windows", } ) try: context_hint = None if settings.jellyfin_tag_context: context_hint = caption_context_from_tags( tags_from_json(row["jellyfin_tags"]), control_tags=( settings.jellyfin_force_specialist_tag, settings.jellyfin_force_general_tag, settings.jellyfin_skip_tag, ), ) sheet = build_contact_sheet(source, window) try: caption = captioner.caption_image( sheet, context_hint=context_hint, chronological_sequence=True, ) finally: sheet.close() except Exception as exc: failed += 1 if progress is not None: progress( { "stage": "captioning", "title": window.title, "timestamp_ms": window.start_ms, "window_start_ms": window.start_ms, "window_end_ms": window.end_ms, "model": model, "route": window.route, "frames_total": total_windows or queue_total, "frames_completed": completed_offset + completed, "failed": failed, "work_unit": "windows", } ) print( f"FAIL {window.title} @ " f"{format_ts(window.start_ms)}-{format_ts(window.end_ms)}: {exc}" ) continue frame_ids = save_caption_window( settings.db_path, window, caption=caption, model=model, ) completed += 1 if after_saved is not None: for frame_id in frame_ids: after_saved(frame_id) if progress is not None: progress( { "stage": "captioning", "title": window.title, "timestamp_ms": window.start_ms, "window_start_ms": window.start_ms, "window_end_ms": window.end_ms, "model": model, "route": window.route, "frames_total": total_windows or queue_total, "frames_completed": completed_offset + completed, "failed": failed, "work_unit": "windows", } ) print( f"{completed:4d}/{queue_total} {window.title} @ " f"{format_ts(window.start_ms)}-{format_ts(window.end_ms)} " f"[{window.route} {window.score:.3f}/{window.reason}; " f"{len(window.sample_rows)} sampled/{len(window.members)} frames]: " f"{caption}" ) finally: if own_source: source.close() try: captioner.unload() print(f"Unloaded {model} from Ollama.") except Exception as exc: print(f"WARN could not unload {model}: {exc}") return completed, failed def cmd_route(args: argparse.Namespace) -> None: init_db(settings.db_path) rows = _select_caption_rows(args, only_needing_caption=False) if not rows: print("No matching frames.") return _, missing = _route_rows(rows, verbose=True) if missing: print(f"Routing skipped {missing} frame(s) with missing thumbnails.") def cmd_caption(args: argparse.Namespace) -> None: init_db(settings.db_path) rows = _select_caption_rows(args, only_needing_caption=True) if not rows: print("No caption windows need processing.") return routed, missing = _route_rows(rows) del rows if not routed: print(f"No captionable frames ({missing} missing thumbnails).") return route_model = _route_model_name() route_policy = _route_policy() total_windows, general_total, specialist_total = caption_window_route_counts( routed, window_seconds=settings.caption_window_seconds, max_frames=settings.caption_window_max_frames, route_model=route_model, route_policy=route_policy, ) def windows_for(route: str): return ( window for window in iter_caption_windows( routed, window_seconds=settings.caption_window_seconds, max_frames=settings.caption_window_max_frames, route_model=route_model, route_policy=route_policy, ) if window.route == route ) print( f"Grouped {len(routed)} routed frame(s) into {total_windows} " f"~{settings.caption_window_seconds:g}s caption window(s), sampling up to " f"{settings.caption_window_max_frames} frame(s) per window." ) general_prompt = ensure_caption_prompt_file(settings.caption_prompt_file) specialist_prompt = ensure_specialist_prompt_file( settings.caption_specialist_prompt_file ) print(f"General prompt: {settings.caption_prompt_file}") print(f"Specialist prompt: {settings.caption_specialist_prompt_file}") print(f"Ollama: {settings.ollama_url}") caption_sync = None if args.sync: caption_sync = CaptionMeiliSync( [], meili=Meili( settings.meili_url, settings.meili_master_key, settings.meili_index, ), batch_size=settings.caption_meili_batch_size, ) if general_total: _unload_ollama_model(settings.caption_specialist_model) general_done, general_failed = _caption_window_queue( "General queue", windows_for("general"), settings.caption_general_model, general_prompt, queue_total=general_total, total_windows=total_windows, after_saved=caption_sync.add if caption_sync is not None else None, ) if specialist_total: _unload_ollama_model(settings.caption_general_model) specialist_done, specialist_failed = _caption_window_queue( "Specialist queue", windows_for("specialist"), settings.caption_specialist_model, specialist_prompt, queue_total=specialist_total, completed_offset=general_done, total_windows=total_windows, after_saved=caption_sync.add if caption_sync is not None else None, ) completed = general_done + specialist_done failed = general_failed + specialist_failed + missing print( f"\nCaptioning complete: {completed} window(s) saved, " f"{failed} failed/skipped." ) if args.sync and caption_sync is not None: caption_sync.flush() print( f"Incremental Meilisearch caption updates complete: " f"{caption_sync.updated_total} document(s) updated." ) elif completed: print("Next: python -m scene_search.cli sync-meili") def cmd_remove(args: argparse.Namespace) -> None: source_kind = args.source.strip().lower() matches = list_media_by_source(settings.db_path, source_kind) if not matches: print(f"No media found with source_kind={source_kind!r}.") return print(f"Media matching source_kind={source_kind!r}:") for item in matches: print(f"- {item.title} ({item.media_id})") if not args.yes: answer = input( f"Remove {len(matches)} media item(s), their frames/captions/vectors, " "and cached thumbnails? [y/N] " ).strip().lower() if answer not in {"y", "yes"}: print("Cancelled.") return removed = remove_media_by_source( settings.db_path, settings.thumbs_dir, source_kind, ) print(f"Removed {len(removed)} media item(s) from the canonical index.") with connect(settings.db_path) as con: remaining = int(con.execute("SELECT COUNT(*) FROM media").fetchone()[0]) if remaining: print("Rebuilding Meilisearch from remaining canonical media...") cmd_sync_meili(args) else: print("No canonical media remain; clearing Meilisearch.") meili = Meili( settings.meili_url, settings.meili_master_key, settings.meili_index, ) meili.clear_documents() print("Meilisearch cleared.") def _human_bytes(value: int) -> str: units = ["B", "KiB", "MiB", "GiB", "TiB"] amount = float(value) for unit in units: if amount < 1024 or unit == units[-1]: return f"{amount:.1f} {unit}" amount /= 1024 return f"{value} B" def cmd_cleanup_jellyfin_thumbs(args: argparse.Namespace) -> None: matches = list_legacy_jellyfin_thumbs( settings.db_path, settings.thumbs_dir, ) if not matches: print("No duplicated Jellyfin Trickplay thumbnails found.") return files = sum(item.files for item in matches) size = sum(item.bytes for item in matches) print( f"Found {files} duplicated JPEG(s) across {len(matches)} " f"Jellyfin item(s), using {_human_bytes(size)}." ) print( "Canonical SQLite embeddings/captions and Meilisearch documents " "will not be changed." ) if not args.yes: print( "Dry run only. After verifying on-demand Jellyfin thumbnails work, " "rerun with --yes to remove these duplicate files." ) return removed = remove_legacy_jellyfin_thumbs( settings.db_path, settings.thumbs_dir, ) print( f"Removed duplicate local thumbnails for {len(removed)} " f"Jellyfin item(s), freeing about {_human_bytes(size)}." ) def cmd_status(_: argparse.Namespace) -> None: init_db(settings.db_path) print("Canonical SQLite") print("----------------") with connect(settings.db_path) as con: media_rows = con.execute( """ SELECT m.id, m.title, m.interval_ms, m.model_id, COUNT(f.id) AS frames, SUM(CASE WHEN f.caption IS NOT NULL THEN 1 ELSE 0 END) AS captioned, SUM(CASE WHEN f.caption_route = 'specialist' THEN 1 ELSE 0 END) AS specialist_routed FROM media m LEFT JOIN frames f ON f.media_id = m.id GROUP BY m.id, m.title, m.interval_ms, m.model_id ORDER BY m.title, m.id """ ).fetchall() total_frames = sum(int(row["frames"]) for row in media_rows) print(f"Media items: {len(media_rows)}") print(f"Frames: {total_frames}") if media_rows: print() for row in media_rows: print( f"- {row['title']}: {row['frames']} frames, " f"{row['captioned']} captioned, " f"{row['specialist_routed']} specialist-routed " f"({row['interval_ms'] / 1000:g}s interval)" ) print() print("Meilisearch") print("-----------") meili = Meili(settings.meili_url, settings.meili_master_key, settings.meili_index) try: stats = meili.stats() except Exception as exc: print(f"Status: unavailable ({exc})") return print(f"Index: {settings.meili_index}") print(f"Documents: {stats.get('numberOfDocuments', 'unknown')}") print(f"Indexing: {stats.get('isIndexing', 'unknown')}") def cmd_jellyfin_overview(args: argparse.Namespace) -> None: """Preview first; publish and restore are explicit, separate actions.""" target = { "db_path": settings.db_path, "media_id": args.media_id, "title": args.title, } if args.restore: result = restore_visual_overview(**target) print(f"Restored original Jellyfin Overview for {result['title']!r}.") return if args.apply: result = publish_visual_overview(**target) print( f"Jellyfin Overview for {result['title']!r}: " f"{result['status']}. Original synopsis retained." ) return result = preview_visual_overview( **target, model=args.model, max_captions=args.max_captions, regenerate=args.regenerate, style=args.style, ) print(f"Title: {result['title']}") print(f"Media ID: {result['media_id']}") print(f"Jellyfin: {result['jellyfin_item_id']}") print(f"LLM model: {result['model']}") print(f"Style: {result['style']}") counts = result["route_counts"] print( f"Routes: {counts['general']} general, " f"{counts['specialist']} specialist, {counts['unknown']} unknown" ) print( f"Evidence: {result['sampled_captions']}/" f"{result['total_captions']} caption segments" ) print("\nDRAFT ONLY — no Jellyfin metadata has been changed:\n") print(result["overview"]) print( "\nTo append this to the existing Jellyfin synopsis, run this " "command again with --apply. To undo later, use --restore. " "This is a visual summary, not a verified film synopsis." ) def cmd_search(args: argparse.Namespace) -> None: service = SearchService( db_path=settings.db_path, meili_url=settings.meili_url, meili_master_key=settings.meili_master_key, meili_index=settings.meili_index, model_id=settings.model_id, device=settings.device, semantic_ratio=settings.hybrid_semantic_ratio, ) result = service.search( args.query, scene_limit=args.limit, item_limit=args.limit, jellyfin_only=False, ) scenes = result["scenes"] if not scenes: print("No hits") return print(f"\nQuery: {args.query!r}\n") for i, scene in enumerate(scenes, 1): meili_score = scene.get("ranking_score") siglip_score = scene.get("siglip_score") meili_text = f" meili={meili_score:.4f}" if meili_score is not None else "" siglip_text = f" siglip={siglip_score:.4f}" if siglip_score is not None else "" print( f"{i:2d}. {scene.get('title')} @ " f"{format_ts(int(scene.get('timestamp_ms') or 0))}" f"{meili_text}{siglip_text}" ) if scene.get("caption"): print(f" {scene['caption']}") if scene.get("caption_route"): route_score = scene.get("route_score") score_text = f" score={float(route_score):.3f}" if route_score is not None else "" print(f" route={scene['caption_route']}{score_text}") if scene.get("jellyfin_item_id"): tags = scene.get("tags") or [] tags_text = f" tags={', '.join(tags)}" if tags else "" print(f" jellyfin={scene['jellyfin_item_id']}{tags_text}") def cmd_serve(_: argparse.Namespace) -> None: from .api import main as api_main api_main() def make_parser() -> argparse.ArgumentParser: p = argparse.ArgumentParser(prog="jellyfin-scene-search") sub = p.add_subparsers(dest="command", required=True) init = sub.add_parser("init", help="Create the persistent SQLite database") init.set_defaults(func=cmd_init) idx = sub.add_parser("index-file", help="Index a local test video") idx.add_argument("path") idx.add_argument("--title") idx.add_argument("--interval", type=float, default=2.0, help="Seconds between test frames (default: 2)") idx.add_argument("--force", action="store_true") idx.set_defaults(func=cmd_index_file) sync = sub.add_parser("sync-meili", help="Rebuild/feed Meilisearch from canonical SQLite vectors") sync.set_defaults(func=cmd_sync_meili) repair = sub.add_parser( "repair-caption-index", help="Restore caption-affected Meilisearch documents without a full rebuild", ) repair.add_argument( "--apply", action="store_true", help="Actually restore documents; default is a read-only count", ) repair.add_argument( "--batch-size", type=int, default=250, help="Documents per Meilisearch repair task (default: 250)", ) repair.add_argument( "--resume-task", type=int, help=( "Adopt a known existing first-batch Meilisearch task from the old " "repair implementation, rather than enqueueing it again" ), ) repair.set_defaults(func=cmd_repair_caption_index) overview = sub.add_parser( "jellyfin-overview", help="Preview an AI visual overview, then explicitly publish/restore Jellyfin metadata", ) overview_target = overview.add_mutually_exclusive_group(required=True) overview_target.add_argument("--title", help="Exact indexed title (must be unique)") overview_target.add_argument("--media-id", help="Canonical scene-search media ID") action = overview.add_mutually_exclusive_group() action.add_argument( "--apply", action="store_true", help="Publish the previously previewed draft (append; preserve original)", ) action.add_argument( "--restore", action="store_true", help="Restore the original Jellyfin synopsis if no later edits were made", ) action.add_argument( "--regenerate", action="store_true", help="Regenerate the draft with current captions and model (no Jellyfin write)", ) overview.add_argument( "--model", help="Override OVERVIEW_MODEL when generating drafts" ) overview.add_argument( "--style", choices=["auto", "general", "specialist"], default="auto", help="Auto-detect from saved caption routes, or force a style", ) overview.add_argument( "--max-captions", type=int, default=64, help="Max evenly spaced caption segments sent to Ollama (1-64)", ) overview.set_defaults(func=cmd_jellyfin_overview) jf_test = sub.add_parser("jellyfin-test", help="Verify Jellyfin API connectivity") jf_test.set_defaults(func=cmd_jellyfin_test) jf_libs = sub.add_parser("jellyfin-libraries", help="List Jellyfin media libraries") jf_libs.set_defaults(func=cmd_jellyfin_libraries) jf_items = sub.add_parser("jellyfin-items", help="Inspect video items, tags and Trickplay") jf_items.add_argument( "--library", action="append", help="Jellyfin library name; repeat to inspect multiple libraries", ) jf_items.add_argument( "--all-libraries", action="store_true", help="Inspect every Jellyfin library visible to the API key", ) jf_items.add_argument( "--exclude-library", action="append", help="Library name to exclude; repeat as needed", ) jf_items.add_argument( "--limit", type=int, help="Maximum number of items to inspect per selected library", ) jf_items.set_defaults(func=cmd_jellyfin_items) jf_index = sub.add_parser("jellyfin-index", help="Index one or more Jellyfin libraries via Trickplay") jf_index.add_argument( "--library", action="append", help="Jellyfin library name; repeat to index multiple libraries", ) jf_index.add_argument( "--all-libraries", action="store_true", help="Index every Jellyfin library visible to the API key", ) jf_index.add_argument( "--exclude-library", action="append", help="Library name to exclude; repeat as needed", ) jf_index.add_argument( "--limit", type=int, help="Maximum number of items to index per selected library; disables pruning", ) jf_index.add_argument("--force", action="store_true", help="Rebuild matching Jellyfin items") jf_index.set_defaults(func=cmd_jellyfin_index) route = sub.add_parser("route", help="Classify frames and show which caption model they will use") route.add_argument("--media-id", help="Only route frames from one media ID") route.add_argument("--title", help="Only route frames from one exact media title") route.add_argument("--limit", type=int, help="Maximum number of frames to route") route.set_defaults(func=cmd_route) caption = sub.add_parser("caption", help="Route frames and generate persistent captions with Ollama") caption.add_argument("--media-id", help="Only caption frames from one media ID") caption.add_argument("--title", help="Only caption frames from one exact media title") caption.add_argument("--limit", type=int, help="Maximum number of frames to caption") caption.add_argument("--force", action="store_true", help="Regenerate captions even if already present") caption.add_argument( "--sync", action="store_true", help="Incrementally sync caption changes to Meilisearch while captioning", ) caption.set_defaults(func=cmd_caption) remove = sub.add_parser("remove", help="Remove indexed media by source kind") remove.add_argument( "--source", required=True, choices=["file", "jellyfin"], help="Source kind to remove", ) remove.add_argument( "--yes", action="store_true", help="Skip the interactive confirmation prompt", ) remove.set_defaults(func=cmd_remove) cleanup_thumbs = sub.add_parser( "cleanup-jellyfin-thumbs", help="Remove duplicated local Jellyfin Trickplay JPEGs without touching vectors", ) cleanup_thumbs.add_argument( "--yes", action="store_true", help="Actually delete files; without this flag the command is a dry run", ) cleanup_thumbs.set_defaults(func=cmd_cleanup_jellyfin_thumbs) status = sub.add_parser("status", help="Show canonical SQLite and Meilisearch index status") status.set_defaults(func=cmd_status) serve = sub.add_parser("serve", help="Run the local HTTP search API") serve.set_defaults(func=cmd_serve) search = sub.add_parser("search", help="Hybrid caption + visual scene search") search.add_argument("query") search.add_argument("--limit", type=int, default=10) search.set_defaults(func=cmd_search) return p def main() -> None: args = make_parser().parse_args() args.func(args) if __name__ == "__main__": main()