yt_transcript_extractor.py

import re
import sys
from pathlib import Path
from typing import List, Dict, Optional, Any

import yt_dlp
from youtube_transcript_api import (
    YouTubeTranscriptApi,
    TranscriptsDisabled,
    NoTranscriptFound,
    VideoUnavailable,
)

# Regex for YouTube video ID (watch?v=ID or youtu.be/ID)
VIDEO_ID_RE = re.compile(r"(?:v=|\/)([a-zA-Z0-9_-]{11})(?:\?|&|$)")

# Regex for timestamp in URL: t=123 or t=1m30s or t=2m or t=45s
TIMESTAMP_RE = re.compile(r"[?&]t=([^&]+)", re.I)


def parse_start_seconds(url: str) -> Optional[int]:
    """
    Parse start time from YouTube URL. Returns seconds or None if no timestamp.
    Supports: t=123, t=1m30s, t=2m, t=45s
    """
    m = TIMESTAMP_RE.search(url)
    if not m:
        return None
    raw = m.group(1).strip()
    if not raw:
        return None
    # Plain integer = seconds
    if raw.isdigit():
        return int(raw)
    total = 0
    # Parse patterns like 1m30s, 2m, 45s
    for part in re.finditer(r"(\d+)([ms])", raw, re.I):
        n = int(part.group(1))
        unit = part.group(2).lower()
        total += n * 60 if unit == "m" else n
    return total if total > 0 else None


def extract_video_id(url: str) -> Optional[str]:
    """Extract YouTube video ID from watch URL or youtu.be URL."""
    m = VIDEO_ID_RE.search(url)
    return m.group(1) if m else None


def fetch_transcript_api(
    video_id: str, start_seconds: Optional[int] = None
) -> List[Dict[str, Any]]:
    """
    Fetch transcript via YouTube's timedtext API (no browser).
    If start_seconds is set, only returns segments at or after that time.
    Returns list of dicts: seconds (int), text (str).
    """
    try:
        api = YouTubeTranscriptApi()
        fetched = api.fetch(video_id)
    except (TranscriptsDisabled, NoTranscriptFound, VideoUnavailable) as e:
        print(f"Transcript API: {type(e).__name__} - {e}")
        return []

    segments = []
    for snippet in fetched.snippets:
        start = int(snippet.start)
        if start_seconds is not None and start < start_seconds:
            continue
        text = (snippet.text or "").strip()
        if not text:
            continue
        segments.append({"seconds": start, "text": text})

    return segments


def fetch_metadata_ytdlp(url: str) -> Dict[str, Any]:
    """
    Fetch video title, full description, and chapters via yt-dlp (no browser).
    Returns dict with 'title', 'description', 'chapters' (list of {seconds, title}).
    """
    opts = {"quiet": True, "no_warnings": True, "extract_flat": False}
    try:
        with yt_dlp.YoutubeDL(opts) as ydl:
            info = ydl.extract_info(url, download=False)
    except Exception as e:
        print(f"yt-dlp: {e}")
        return {"title": "video", "description": "", "chapters": []}

    title = (info.get("title") or "video").strip()
    # Full description (intro, bullet points, links, etc.)
    description = (info.get("description") or "").strip()

    chapters: List[Dict[str, Any]] = []
    for ch in info.get("chapters") or []:
        start = int(ch.get("start_time") or 0)
        ch_title = (ch.get("title") or "").strip()
        chapters.append({"seconds": start, "title": ch_title})

    return {"title": title, "description": description, "chapters": chapters}


def slugify_filename(title: str) -> str:
    """Turn video title into a safe filename."""
    title = title.strip()
    title = re.sub(r'[\\/*?:"<>|]', "_", title)
    if len(title) > 180:
        title = title[:180].rstrip()
    return title or "video"


def escape_md(text: str) -> str:
    """Escape Markdown special characters in table cells."""
    if text is None:
        return ""
    text = text.replace("|", "\\|")
    text = text.replace("\r\n", " ").replace("\n", " ").strip()
    return text


def _source_link(url: str, start_seconds: Optional[int] = None) -> str:
    """Link with optional start time: use URL's t= if present, else t=0."""
    base = re.sub(r"[?&]t=[^&]*", "", url).rstrip("/").rstrip("?&")
    sep = "&" if "?" in base else "?"
    t = start_seconds if start_seconds is not None else 0
    return f"{base}{sep}t={t}"


def process_video(url: str) -> None:
    """Fetch title, description, chapters, and transcript via APIs (no browser)."""
    meta = fetch_metadata_ytdlp(url)
    title = meta["title"]
    description = meta.get("description", "")
    chapters = meta["chapters"]

    print(f"Title: {title!r}")
    print(f"Chapters found: {len(chapters)}")

    video_id = extract_video_id(url)
    start_seconds = parse_start_seconds(url)
    if start_seconds is not None:
        print(f"Transcript from {start_seconds}s to end")
    if not video_id:
        print("Could not extract video ID from URL")
        transcript = []
    else:
        transcript = fetch_transcript_api(video_id, start_seconds)
    print(f"Transcript segments found: {len(transcript)}")

    filename = slugify_filename(title) + ".md"
    source = _source_link(url, start_seconds)

    lines = [
        f"# {title}",
        "",
        f"Source: {source}",
        "",
    ]

    if description:
        lines.append("## Description")
        lines.append("")
        lines.append(description)
        lines.append("")

    lines.append("## Chapters")
    lines.append("")
    if chapters:
        lines.append("| Time | Title |")
        lines.append("| --- | --- |")
        for ch in chapters:
            lines.append(
                f"| {ch.get('seconds', 0)} | {escape_md(ch.get('title', ''))} |"
            )
        lines.append("")
    else:
        lines.append("_No chapters found._")
        lines.append("")

    lines.append("## Transcript")
    lines.append("")
    if transcript:
        lines.append("| Time | Text |")
        lines.append("| --- | --- |")
        for seg in transcript:
            lines.append(
                f"| {seg.get('seconds', 0)} | {escape_md(seg.get('text', ''))} |"
            )
    else:
        lines.append("_Transcript is not available or could not be extracted._")

    Path(filename).write_text("\n".join(lines), encoding="utf-8")
    print(f"Saved to {filename}")


def main() -> None:
    if len(sys.argv) != 2:
        print("Usage: python yt_trans.py <youtube_url>")
        raise SystemExit(1)
    url = sys.argv[1]
    process_video(url)


if __name__ == "__main__":
    main()