slidecap 0.1.0__py3-none-any.whl

slidecap/__init__.py

@@ -0,0 +1,5 @@
+"""slidecap package."""
+
+from .core import PipelineResult, run_pipeline
+
+__all__ = ["run_pipeline", "PipelineResult"]

slidecap/cli.py

@@ -0,0 +1,129 @@
+from __future__ import annotations
+
+import argparse
+import json
+import logging
+import sys
+
+try:
+    from .core import run_pipeline
+except ImportError:  # pragma: no cover - enables direct script invocation
+    from core import run_pipeline  # type: ignore[no-redef]
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="slidecap",
+        description="Generate slide-aligned markdown notes from a YouTube URL.",
+    )
+    parser.add_argument("--url", required=True, help="YouTube URL to process.")
+    parser.add_argument(
+        "--out-md",
+        default=None,
+        help="Output markdown file path. Defaults to ./slidecap/<video title>.md",
+    )
+    parser.add_argument(
+        "--images-dir",
+        default=None,
+        help="Directory where slide images are written. Defaults to ./slidecap/slides/",
+    )
+    parser.add_argument(
+        "--similarity-threshold",
+        type=float,
+        default=0.85,
+        help="Slide detection sensitivity threshold (default: 0.85).",
+    )
+    parser.add_argument(
+        "--sample-rate",
+        type=float,
+        default=1.0,
+        help="Frame sampling rate in seconds (default: 1.0).",
+    )
+    parser.add_argument(
+        "--whisper-model",
+        default="base",
+        help=(
+            "Whisper model name. Default: base. "
+            "Multilingual: tiny, base, small, medium, large, large-v2, large-v3, turbo. "
+            "English-only (faster): tiny.en, base.en, small.en, medium.en."
+        ),
+    )
+    parser.add_argument("--language", default=None, help="Optional transcription language code (e.g. en).")
+    parser.add_argument(
+        "--image-format",
+        default="jpg",
+        choices=["jpg", "png"],
+        help="Image format for saved slides (default: jpg).",
+    )
+    parser.add_argument(
+        "--image-quality",
+        type=int,
+        default=90,
+        help="JPEG quality 1-100 (used only for jpg output). Default: 90.",
+    )
+    parser.add_argument("--overwrite", action="store_true", help="Overwrite output markdown if it exists.")
+    parser.add_argument("--keep-temp", action="store_true", help="Keep temporary downloaded files for debugging.")
+    parser.add_argument(
+        "--allow-lower-quality",
+        action="store_true",
+        help="Fallback to sub-1080p quality if exact 1080p is not available.",
+    )
+    parser.add_argument(
+        "--log-level",
+        default="info",
+        choices=["debug", "info", "warn", "error"],
+        help="Logging verbosity (default: info).",
+    )
+    parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Print structured JSON output for agent workflows.",
+    )
+    return parser
+
+
+def _validate_args(args: argparse.Namespace) -> None:
+    if not (0.5 <= args.similarity_threshold <= 0.95):
+        raise ValueError("--similarity-threshold must be between 0.5 and 0.95.")
+    if args.sample_rate <= 0:
+        raise ValueError("--sample-rate must be > 0.")
+    if not (1 <= args.image_quality <= 100):
+        raise ValueError("--image-quality must be between 1 and 100.")
+
+
+def main() -> int:
+    parser = build_parser()
+    args = parser.parse_args()
+
+    level_map = {
+        "debug": logging.DEBUG,
+        "info": logging.INFO,
+        "warn": logging.WARNING,
+        "error": logging.ERROR,
+    }
+    logging.basicConfig(level=level_map[args.log_level], format="%(levelname)s: %(message)s")
+
+    try:
+        _validate_args(args)
+        result = run_pipeline(args)
+    except Exception as exc:  # noqa: BLE001
+        if args.json:
+            error_payload = {
+                "status": "error",
+                "error": str(exc),
+                "error_type": type(exc).__name__,
+            }
+            print(json.dumps(error_payload, ensure_ascii=True))
+        else:
+            logging.error(str(exc))
+        return 1
+
+    if args.json:
+        print(json.dumps(result.to_dict(), ensure_ascii=True))
+    else:
+        print(result.output_markdown)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

slidecap/core.py

@@ -0,0 +1,530 @@
+from __future__ import annotations
+
+import argparse
+import json
+import logging
+import os
+import re
+import shutil
+import subprocess
+import tempfile
+import time
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Iterable
+from urllib.parse import parse_qs, urlparse
+
+import cv2
+import whisper
+from PIL import Image
+from skimage.metrics import structural_similarity as ssim
+
+LOGGER = logging.getLogger(__name__)
+
+
+@dataclass
+class Slide:
+    slide_num: int
+    timestamp: float
+    image_path: str
+    transcript: str
+    youtube_link: str
+
+
+@dataclass
+class PipelineResult:
+    status: str
+    url: str
+    video_id: str
+    output_markdown: str
+    images_dir: str
+    slide_count: int
+    image_files: list[str]
+    downloaded_resolution: str
+    downloaded_fps: str
+    format_note: str
+    download_format: str
+    similarity_threshold: float
+    sample_rate: float
+    whisper_model: str
+    language: str | None
+    started_at: str
+    completed_at: str
+    duration_seconds: float
+    warnings: list[str]
+
+    def to_dict(self) -> dict:
+        return {
+            "status": self.status,
+            "url": self.url,
+            "video_id": self.video_id,
+            "output_markdown": self.output_markdown,
+            "images_dir": self.images_dir,
+            "slide_count": self.slide_count,
+            "image_files": self.image_files,
+            "downloaded_resolution": self.downloaded_resolution,
+            "downloaded_fps": self.downloaded_fps,
+            "format_note": self.format_note,
+            "download_format": self.download_format,
+            "similarity_threshold": self.similarity_threshold,
+            "sample_rate": self.sample_rate,
+            "whisper_model": self.whisper_model,
+            "language": self.language,
+            "started_at": self.started_at,
+            "completed_at": self.completed_at,
+            "duration_seconds": self.duration_seconds,
+            "warnings": self.warnings,
+        }
+
+
+def _check_runtime_dependencies() -> None:
+    missing = [cmd for cmd in ("yt-dlp", "ffmpeg") if shutil.which(cmd) is None]
+    if missing:
+        missing_list = ", ".join(missing)
+        raise RuntimeError(f"Missing required system binaries: {missing_list}")
+
+
+def _extract_video_id(youtube_url: str) -> str:
+    parsed = urlparse(youtube_url)
+    host = parsed.netloc.lower()
+
+    if "youtu.be" in host:
+        candidate = parsed.path.strip("/").split("/")[0]
+        if candidate:
+            return candidate
+
+    if "youtube.com" in host:
+        params = parse_qs(parsed.query)
+        video_ids = params.get("v", [])
+        if video_ids:
+            return video_ids[0]
+
+        parts = parsed.path.strip("/").split("/")
+        if len(parts) >= 2 and parts[0] in {"shorts", "embed", "live"}:
+            return parts[1]
+
+    return "unknown_video"
+
+
+def _canonical_watch_url(youtube_url: str, video_id: str) -> str:
+    if video_id != "unknown_video":
+        return f"https://www.youtube.com/watch?v={video_id}"
+    parsed = urlparse(youtube_url)
+    path = parsed.path
+    if not path:
+        return youtube_url
+    return f"{parsed.scheme}://{parsed.netloc}{path}"
+
+
+def generate_youtube_timestamp_url(youtube_url: str, timestamp_seconds: float) -> str:
+    video_id = _extract_video_id(youtube_url)
+    base = _canonical_watch_url(youtube_url, video_id)
+    return f"{base}&t={int(timestamp_seconds)}s" if "?" in base else f"{base}?t={int(timestamp_seconds)}s"
+
+
+def build_1080p_format_string(allow_lower_quality: bool) -> str:
+    strict_1080 = "bestvideo[height=1080]+bestaudio/best[height=1080]"
+    if not allow_lower_quality:
+        return strict_1080
+
+    fallback = (
+        "bestvideo[height<=720]+bestaudio/best[height<=720]/"
+        "bestvideo[height<=480]+bestaudio/best[height<=480]/"
+        "bestvideo[height<=360]+bestaudio/best[height<=360]/best"
+    )
+    return f"{strict_1080}/{fallback}"
+
+
+def _run_command(cmd: Iterable[str]) -> subprocess.CompletedProcess[str]:
+    LOGGER.debug("Running command: %s", " ".join(cmd))
+    return subprocess.run(list(cmd), capture_output=True, text=True)
+
+
+def _download_video(youtube_url: str, video_path: Path, allow_lower_quality: bool) -> tuple[Path, str]:
+    format_string = build_1080p_format_string(allow_lower_quality)
+    cmd = [
+        "yt-dlp",
+        "-f",
+        format_string,
+        "--merge-output-format",
+        "mp4",
+        "--write-info-json",
+        "--no-playlist",
+        "-o",
+        str(video_path),
+        youtube_url,
+    ]
+    result = _run_command(cmd)
+    if result.returncode != 0:
+        raise RuntimeError(f"yt-dlp download failed:\n{result.stderr.strip()}")
+    LOGGER.info("Video downloaded: %s", video_path)
+    return video_path, format_string
+
+
+def _extract_audio(video_path: Path, audio_path: Path) -> None:
+    cmd = ["ffmpeg", "-i", str(video_path), "-q:a", "0", "-map", "a", str(audio_path), "-y"]
+    result = _run_command(cmd)
+    if result.returncode != 0:
+        raise RuntimeError(f"ffmpeg audio extraction failed:\n{result.stderr.strip()}")
+    LOGGER.info("Audio extracted: %s", audio_path)
+
+
+def detect_slides(video_path: Path, similarity_threshold: float = 0.85, sample_rate: float = 1.0) -> list[tuple[float, Image.Image]]:
+    """
+    Reuses the slide detection behavior from the existing app:
+    - SSIM frame comparison on sampled grayscale frames.
+    - Dynamic threshold adjustment based on video height.
+    - Extra blur for 1080p+ input.
+    """
+    cap = cv2.VideoCapture(str(video_path))
+    cap.set(cv2.CAP_PROP_FOURCC, cv2.VideoWriter_fourcc(*"mp4v"))
+    cap.set(cv2.CAP_PROP_BUFFERSIZE, 1)
+
+    fps = cap.get(cv2.CAP_PROP_FPS) or 0.0
+    total_frames = int(cap.get(cv2.CAP_PROP_FRAME_COUNT) or 0)
+    width = int(cap.get(cv2.CAP_PROP_FRAME_WIDTH) or 0)
+    height = int(cap.get(cv2.CAP_PROP_FRAME_HEIGHT) or 0)
+
+    if fps <= 0:
+        cap.release()
+        raise RuntimeError("Failed to read video FPS; cannot perform slide detection.")
+
+    LOGGER.info("Video info: %sx%s, %.1f FPS, %s frames", width, height, fps, total_frames)
+
+    if height >= 1080:
+        adjusted_threshold = similarity_threshold * 1.05
+        LOGGER.info("High quality video detected. Adjusted threshold: %.3f", adjusted_threshold)
+    elif height >= 720:
+        adjusted_threshold = similarity_threshold * 1.02
+        LOGGER.info("Medium quality video detected. Adjusted threshold: %.3f", adjusted_threshold)
+    else:
+        adjusted_threshold = similarity_threshold
+        LOGGER.info("Standard quality video detected. Threshold: %.3f", adjusted_threshold)
+
+    slides: list[tuple[float, Image.Image]] = []
+    prev_frame = None
+    frame_count = 0
+
+    sample_interval = int(fps * sample_rate)
+    sample_interval = max(sample_interval, 1)
+
+    if height >= 1080:
+        sample_interval = max(sample_interval, int(fps * 0.5))
+
+    while True:
+        ret, frame = cap.read()
+        if not ret:
+            break
+
+        frame_count += 1
+        if frame_count % sample_interval != 0:
+            continue
+
+        gray = cv2.cvtColor(frame, cv2.COLOR_BGR2GRAY)
+        if height >= 1080:
+            gray = cv2.GaussianBlur(gray, (3, 3), 0)
+
+        if prev_frame is not None:
+            similarity = ssim(prev_frame, gray)
+            if similarity < adjusted_threshold:
+                timestamp = frame_count / fps
+                img_rgb = cv2.cvtColor(frame, cv2.COLOR_BGR2RGB)
+                pil_img = Image.fromarray(img_rgb)
+                slides.append((timestamp, pil_img))
+                LOGGER.info(
+                    "Slide detected at %.1fs (similarity %.3f < threshold %.3f)",
+                    timestamp,
+                    similarity,
+                    adjusted_threshold,
+                )
+
+        prev_frame = gray
+
+    cap.release()
+
+    if not slides:
+        fallback_cap = cv2.VideoCapture(str(video_path))
+        fallback_cap.set(cv2.CAP_PROP_FOURCC, cv2.VideoWriter_fourcc(*"mp4v"))
+        fallback_cap.set(cv2.CAP_PROP_BUFFERSIZE, 1)
+        ret, frame = fallback_cap.read()
+        if ret:
+            img_rgb = cv2.cvtColor(frame, cv2.COLOR_BGR2RGB)
+            pil_img = Image.fromarray(img_rgb)
+            slides.insert(0, (0.0, pil_img))
+        fallback_cap.release()
+
+    return slides
+
+
+def _transcribe_audio(audio_path: Path, whisper_model: str, language: str | None) -> tuple[str, list[dict]]:
+    LOGGER.info("Loading Whisper model: %s", whisper_model)
+    model = whisper.load_model(whisper_model)
+    kwargs = {"language": language} if language else {}
+    LOGGER.info("Transcribing audio...")
+    result = model.transcribe(str(audio_path), **kwargs)
+    return result.get("text", "").strip(), result.get("segments", [])
+
+
+def _align_transcript_to_slides(segments: list[dict], slide_timestamps: list[float]) -> list[str]:
+    """Assign Whisper segments to slides based on actual segment start times."""
+    if not slide_timestamps:
+        return []
+
+    chunks: list[str] = []
+    for i, timestamp in enumerate(slide_timestamps):
+        next_timestamp = slide_timestamps[i + 1] if i + 1 < len(slide_timestamps) else float("inf")
+
+        if i == 0:
+            # First slide gets all segments that start before the second slide
+            slide_segs = [seg for seg in segments if seg["start"] < next_timestamp]
+        else:
+            slide_segs = [seg for seg in segments if timestamp <= seg["start"] < next_timestamp]
+
+        chunks.append(" ".join(seg["text"].strip() for seg in slide_segs))
+
+    return chunks
+
+
+def _write_slide_images(
+    slides: list[tuple[float, Image.Image]],
+    images_dir: Path,
+    video_id: str,
+    image_format: str,
+    image_quality: int,
+) -> list[Path]:
+    images_dir.mkdir(parents=True, exist_ok=True)
+    output_paths: list[Path] = []
+
+    pil_format = "JPEG" if image_format == "jpg" else "PNG"
+    extension = "jpg" if image_format == "jpg" else "png"
+
+    for idx, (timestamp, image) in enumerate(slides, start=1):
+        file_name = f"yt_{video_id}_slide_{idx:03d}_t{int(timestamp):06d}.{extension}"
+        out_path = images_dir / file_name
+        if image_format == "jpg":
+            if image.mode in ("RGBA", "LA", "P"):
+                rgb_image = Image.new("RGB", image.size, (255, 255, 255))
+                rgb_image.paste(image, mask=image.split()[-1] if image.mode == "RGBA" else None)
+                image = rgb_image
+            image.save(out_path, format=pil_format, quality=image_quality, optimize=True)
+        else:
+            image.save(out_path, format=pil_format, optimize=True)
+        output_paths.append(out_path)
+
+    return output_paths
+
+
+def _anchor_for_slide(slide_num: int, timestamp: float) -> str:
+    ts = f"{timestamp:.1f}".replace(".", "")
+    return f"slide-{slide_num}-{ts}s"
+
+
+def _build_markdown(
+    youtube_url: str,
+    video_id: str,
+    slide_records: list[Slide],
+    format_string: str,
+) -> str:
+    generated = datetime.now(timezone.utc).isoformat()
+    lines = [
+        "# YouTube Slide Transcript",
+        "",
+        f"- Source: {youtube_url}",
+        f"- Video ID: {video_id}",
+        f"- Generated: {generated}",
+        f"- Slide Count: {len(slide_records)}",
+        f"- Download Format: `{format_string}`",
+        "",
+        "## Table of Contents",
+    ]
+
+    for slide in slide_records:
+        anchor = _anchor_for_slide(slide.slide_num, slide.timestamp)
+        lines.append(f"- [Slide {slide.slide_num} ({slide.timestamp:.1f}s)](#{anchor})")
+
+    lines.extend(["", "---", ""])
+
+    for slide in slide_records:
+        anchor = _anchor_for_slide(slide.slide_num, slide.timestamp)
+        lines.extend(
+            [
+                f"## Slide {slide.slide_num} ({slide.timestamp:.1f}s)",
+                f'<a id="{anchor}"></a>',
+                "",
+                f"YouTube Link: {slide.youtube_link}",
+                "",
+                f"![Slide {slide.slide_num}]({slide.image_path})",
+                "",
+                "Transcript:",
+                slide.transcript or "_No transcript text for this segment._",
+                "",
+                "---",
+                "",
+            ]
+        )
+
+    return "\n".join(lines).rstrip() + "\n"
+
+
+def _read_download_info(video_path: Path) -> dict:
+    info_path = video_path.with_suffix(".info.json")
+    if not info_path.exists():
+        return {}
+    try:
+        with info_path.open("r", encoding="utf-8") as f:
+            return json.load(f)
+    except (json.JSONDecodeError, OSError):
+        return {}
+
+
+def _fetch_video_title(url: str) -> str | None:
+    """Fetch video title via yt-dlp without downloading the video."""
+    result = _run_command(["yt-dlp", "--print", "title", "--no-playlist", url])
+    if result.returncode == 0:
+        title = result.stdout.strip()
+        if title:
+            return title
+    return None
+
+
+def _sanitize_filename(name: str, max_length: int = 100) -> str:
+    """Remove filesystem-invalid characters and truncate."""
+    sanitized = re.sub(r'[\\/:*?"<>|]', "", name)
+    sanitized = re.sub(r"\s+", " ", sanitized).strip().strip(".")
+    return (sanitized[:max_length].rstrip() if len(sanitized) > max_length else sanitized) or "untitled"
+
+
+def resolve_output_paths(url: str, out_md: str | None, images_dir: str | None) -> tuple[Path, Path]:
+    """Return resolved (out_md, images_dir) paths, filling in defaults when not provided."""
+    base_dir = Path.cwd() / "slidecap"
+
+    if out_md is None:
+        title = _fetch_video_title(url)
+        filename = (_sanitize_filename(title) if title else _extract_video_id(url)) + ".md"
+        resolved_out_md = base_dir / filename
+    else:
+        resolved_out_md = Path(out_md).expanduser().resolve()
+
+    if images_dir is None:
+        resolved_images_dir = base_dir / "slides"
+    else:
+        resolved_images_dir = Path(images_dir).expanduser().resolve()
+
+    return resolved_out_md, resolved_images_dir
+
+
+def run_pipeline(args: argparse.Namespace) -> PipelineResult:
+    _check_runtime_dependencies()
+    started_at_dt = datetime.now(timezone.utc)
+    started_at = started_at_dt.isoformat()
+    start_time = time.time()
+
+    out_md, images_dir = resolve_output_paths(args.url, args.out_md, args.images_dir)
+
+    if out_md.exists() and not args.overwrite:
+        raise FileExistsError(f"Output markdown already exists: {out_md}. Use --overwrite.")
+
+    out_md.parent.mkdir(parents=True, exist_ok=True)
+    images_dir.mkdir(parents=True, exist_ok=True)
+
+    if args.keep_temp:
+        temp_dir = Path(tempfile.mkdtemp(prefix="slidecap_"))
+        LOGGER.info("Keeping temp directory: %s", temp_dir)
+        should_cleanup = False
+    else:
+        temp_dir = Path(tempfile.mkdtemp(prefix="slidecap_"))
+        should_cleanup = True
+
+    try:
+        video_path = temp_dir / "video.mp4"
+        audio_path = temp_dir / "audio.mp3"
+
+        downloaded_video, format_string = _download_video(args.url, video_path, args.allow_lower_quality)
+        info = _read_download_info(downloaded_video)
+        if info:
+            LOGGER.info(
+                "Downloaded resolution: %sx%s, fps: %s, format: %s",
+                info.get("width", "unknown"),
+                info.get("height", "unknown"),
+                info.get("fps", "unknown"),
+                info.get("format_note", "unknown"),
+            )
+
+        _extract_audio(video_path, audio_path)
+        slides = detect_slides(video_path, similarity_threshold=args.similarity_threshold, sample_rate=args.sample_rate)
+        if not slides:
+            raise RuntimeError("No slides detected.")
+
+        _transcript, segments = _transcribe_audio(audio_path, args.whisper_model, args.language)
+        slide_timestamps = [s[0] for s in slides]
+        transcript_chunks = _align_transcript_to_slides(segments, slide_timestamps)
+        video_id = _extract_video_id(args.url)
+        image_paths = _write_slide_images(
+            slides,
+            images_dir,
+            video_id=video_id,
+            image_format=args.image_format,
+            image_quality=args.image_quality,
+        )
+
+        slide_records: list[Slide] = []
+        for idx, ((timestamp, _image), transcript_chunk, image_path) in enumerate(
+            zip(slides, transcript_chunks, image_paths), start=1
+        ):
+            relative_img_path = os.path.relpath(image_path, start=out_md.parent).replace(os.sep, "/")
+            slide_records.append(
+                Slide(
+                    slide_num=idx,
+                    timestamp=timestamp,
+                    image_path=relative_img_path,
+                    transcript=transcript_chunk,
+                    youtube_link=generate_youtube_timestamp_url(args.url, timestamp),
+                )
+            )
+
+        markdown = _build_markdown(
+            youtube_url=args.url,
+            video_id=video_id,
+            slide_records=slide_records,
+            format_string=format_string,
+        )
+        out_md.write_text(markdown, encoding="utf-8")
+        LOGGER.info("Markdown written: %s", out_md)
+        LOGGER.info("Slides written to: %s", images_dir)
+
+        width = info.get("width")
+        height = info.get("height")
+        downloaded_resolution = (
+            f"{width}x{height}" if isinstance(width, int) and isinstance(height, int) else "unknown"
+        )
+        downloaded_fps = str(info.get("fps", "unknown"))
+        format_note = str(info.get("format_note", "unknown"))
+
+        completed_at = datetime.now(timezone.utc).isoformat()
+        duration_seconds = round(time.time() - start_time, 3)
+
+        return PipelineResult(
+            status="ok",
+            url=args.url,
+            video_id=video_id,
+            output_markdown=str(out_md),
+            images_dir=str(images_dir),
+            slide_count=len(slide_records),
+            image_files=[str(path) for path in image_paths],
+            downloaded_resolution=downloaded_resolution,
+            downloaded_fps=downloaded_fps,
+            format_note=format_note,
+            download_format=format_string,
+            similarity_threshold=args.similarity_threshold,
+            sample_rate=args.sample_rate,
+            whisper_model=args.whisper_model,
+            language=args.language,
+            started_at=started_at,
+            completed_at=completed_at,
+            duration_seconds=duration_seconds,
+            warnings=[],
+        )
+    finally:
+        if should_cleanup:
+            shutil.rmtree(temp_dir, ignore_errors=True)

slidecap-0.1.0.dist-info/METADATA

@@ -0,0 +1,154 @@
+Metadata-Version: 2.4
+Name: slidecap
+Version: 0.1.0
+Summary: CLI tool to generate slide-aligned markdown notes from YouTube videos.
+License-Expression: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: opencv-python
+Requires-Dist: openai-whisper
+Requires-Dist: Pillow
+Requires-Dist: scikit-image
+Requires-Dist: yt-dlp
+Dynamic: license-file
+
+# slidecap
+
+CLI tool that turns a YouTube video into slide-aligned markdown notes for agent/LLM workflows.
+
+## What It Does
+
+1. Downloads a YouTube video at 1080p (strict by default).
+2. Detects slide changes using SSIM-based frame comparison (same behavior as your existing app).
+3. Transcribes audio with Whisper.
+4. Aligns transcript chunks to detected slide timestamps.
+5. Writes:
+   - A markdown file with slide sections + transcript text.
+   - Slide images to one shared images folder.
+
+## Install
+
+```bash
+pip install slidecap
+```
+
+System dependencies:
+- `ffmpeg` in PATH
+- `yt-dlp` in PATH
+
+## Usage
+
+Minimal — just pass a URL:
+
+```bash
+slidecap --url "https://www.youtube.com/watch?v=abc123"
+```
+
+This creates:
+```
+./slidecap/
+  My Video Title.md
+  slides/
+    yt_abc123_slide_001_t000005.jpg
+    ...
+```
+
+Custom output paths:
+
+```bash
+slidecap \
+  --url "https://www.youtube.com/watch?v=abc123" \
+  --out-md "/path/to/vault/notes/abc123.md" \
+  --images-dir "/path/to/vault/assets/youtube-slides"
+```
+
+JSON output (for agents):
+
+```bash
+slidecap --url "https://www.youtube.com/watch?v=abc123" --json
+```
+
+## Flags
+
+- `--url` (required): YouTube URL.
+- `--out-md` (optional): Output markdown path. Defaults to `./slidecap/<video title>.md`.
+- `--images-dir` (optional): Slide images folder. Defaults to `./slidecap/slides/`.
+- `--similarity-threshold` (default `0.85`): Slide detection threshold.
+- `--sample-rate` (default `1.0`): Frame sampling interval in seconds.
+- `--whisper-model` (default `base`): Whisper model name. See [Whisper Models](#whisper-models) below.
+- `--language`: Optional transcription language code (e.g. `en`, `de`, `ja`).
+- `--image-format` (default `jpg`): `jpg` or `png`.
+- `--image-quality` (default `90`): JPEG quality.
+- `--allow-lower-quality`: Fallback below 1080p if exact 1080p is unavailable.
+- `--overwrite`: Overwrite existing markdown output.
+- `--keep-temp`: Keep temp downloads for debugging.
+- `--log-level` (default `info`): `debug|info|warn|error`.
+- `--json`: Print structured JSON result (success or error) for agent workflows.
+
+## Whisper Models
+
+| Model | Speed | Accuracy | Notes |
+|---|---|---|---|
+| `tiny` | Fastest | Lowest | Quick drafts |
+| `base` | Fast | Good | **Default** |
+| `small` | Moderate | Better | Good general choice |
+| `medium` | Slow | Strong | |
+| `large` | Slowest | Best | |
+| `large-v2` | Slowest | Best | Improved large |
+| `large-v3` | Slowest | Best | Latest multilingual |
+| `turbo` | Fast | Very good | Efficient alternative to large |
+
+English-only variants (`tiny.en`, `base.en`, `small.en`, `medium.en`) are faster than their multilingual counterparts when transcribing English content.
+
+## Output Format
+
+The markdown file includes:
+- source metadata
+- table of contents
+- per-slide sections with:
+  - timestamped YouTube link
+  - relative markdown image link
+  - transcript chunk aligned to that slide
+
+Images are named to avoid collisions:
+- `yt_<video-id>_slide_<nnn>_t<seconds>.<ext>`
+
+## JSON Response Shape
+
+Success:
+
+```json
+{
+  "status": "ok",
+  "url": "https://www.youtube.com/watch?v=abc123",
+  "video_id": "abc123",
+  "output_markdown": "/path/to/vault/notes/abc123.md",
+  "images_dir": "/path/to/vault/assets/youtube-slides",
+  "slide_count": 12,
+  "image_files": [],
+  "downloaded_resolution": "1920x1080",
+  "downloaded_fps": "30",
+  "format_note": "1080p",
+  "download_format": "bestvideo[height=1080]+bestaudio/best[height=1080]",
+  "similarity_threshold": 0.85,
+  "sample_rate": 1.0,
+  "whisper_model": "base",
+  "language": "en",
+  "started_at": "2026-02-23T00:00:00+00:00",
+  "completed_at": "2026-02-23T00:03:00+00:00",
+  "duration_seconds": 180.123,
+  "warnings": []
+}
+```
+
+Error:
+
+```json
+{
+  "status": "error",
+  "error": "message",
+  "error_type": "RuntimeError"
+}
+```

slidecap-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+slidecap/__init__.py,sha256=lTJYDmoHO7U-ssMprVoySTwM7DZTl-Mo_OUzemBgnnw,118
+slidecap/cli.py,sha256=6kz0fCH5NvLTtO9uqNfeaife6MT8ul7OeRYW_ve3TWM,4070
+slidecap/core.py,sha256=k-cADRg6iKdN5QqZzCdjuq-hqZBcF2E_Zw5nzaTHZLw,18421
+slidecap-0.1.0.dist-info/licenses/LICENSE,sha256=i3dxjfqY5jUHFWG0wcttwDSBMGM6Amty7c4JheB1GUA,1073
+slidecap-0.1.0.dist-info/METADATA,sha256=UQmhxmttu76wE-As_v0mETTMGuSii1oXDZg3jqkIkmQ,4205
+slidecap-0.1.0.dist-info/WHEEL,sha256=YCfwYGOYMi5Jhw2fU4yNgwErybb2IX5PEwBKV4ZbdBo,91
+slidecap-0.1.0.dist-info/entry_points.txt,sha256=bEUTtoW1EF6UpJBy4rMGptMx9grKWZ2FVy2wVuuSLBI,47
+slidecap-0.1.0.dist-info/top_level.txt,sha256=-BSzqHMmzqatHCzbKR8SRP3mLDFKAhk3UmlBaADdGTg,9
+slidecap-0.1.0.dist-info/RECORD,,

slidecap-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

slidecap-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+slidecap = slidecap.cli:main

slidecap-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aadhil A. Majeed
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

slidecap-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+slidecap