Fetch a YouTube video's existing captions as text so you can answer questions about it.

Returns existing captions/subtitles only; it does not transcribe audio. Videos without captions have nothing to return.

Args: video: A YouTube URL (watch, youtu.be, shorts, embed, live) or an 11-character video ID. languages: Preferred language codes in priority order. Defaults to ["en"]. include_timestamps: If true, group the transcript into ~15s blocks, each prefixed with [mm:ss] (or [h:mm:ss] past an hour). Use this to find where a topic is discussed and pass that [mm:ss] to build_video_link. translate_to: Optional ISO language code to translate the transcript into.

Returns: The transcript as plain text.

Build a YouTube link that opens a video at a specific moment.

Returns a watch URL like https://www.youtube.com/watch?v=&t= so a user can click straight to the moment something is discussed. Pair it with get_transcript(include_timestamps= True) -- read off the [mm:ss] of the relevant block and pass it as start -- to turn "where is X mentioned?" into a clickable link.

Args: video: A YouTube URL (watch, youtu.be, shorts, embed, live) or an 11-character video ID. start: The moment to jump to -- seconds (e.g. 90) or a "mm:ss" / "h:mm:ss" string.

Returns: The watch URL as a string.

List the transcripts available for a YouTube video.

Use this when get_transcript can't find your requested language. It reports each available transcript (language, code, whether it's auto-generated, whether it's translatable) plus the set of languages you can pass to get_transcript's translate_to.

Args: video: A YouTube URL or an 11-character video ID.

Get a YouTube video's metadata: title, channel, upload date, duration, view/like counts, chapters and tags.

Use this to answer questions about a video (its name, who made it, how long it is, when it came out) without fetching its transcript.

Args: video: A YouTube URL (watch, youtu.be, shorts, embed, live) or an 11-character video ID. include_description: If true, also return the (often long) description; otherwise it's omitted to keep the response small.

Get a YouTube video's "most replayed" moments -- the peaks of its viewer-interest heatmap (the curve shown above the timeline marking where people rewatch most).

Use this for "what are the best / most-rewatched parts?", "jump me to the good part", or to weight a summary toward what viewers actually care about. Each peak is a high-interest region (region_start_seconds..region_end_seconds) with the hottest instant at peak_start_seconds, a ready-to-share url that opens the video at the start of the stretch, and the chapter it falls in. relative_intensity is 0..1 within this video (1.0 = its single most-rewatched moment) -- it is NOT a view count and is not comparable across videos.

A peak with is_opening=True sits at the very start (t~=0): that spot is almost always inflated by playback starting there, not a genuine rewatch, so discount it as a "best part". It is returned in addition to (not counted against) top_n, so the opening can't crowd out content.

To say what is actually happening at a peak, read its peak_label (mm:ss) and look it up with get_transcript(include_timestamps=True); profile is a coarse 0..1 curve for the overall shape (front-loaded vs steady vs spikes near the end).

has_data may be False -- then peaks is empty and note explains why (many newer, low-traffic, or Shorts videos have no heatmap).

Args: video: A YouTube URL (watch, youtu.be, shorts, embed, live) or an 11-character video ID. top_n: Max number of content peak regions (clamped to 1..20; default 8). The flagged opening (t~=0) peak, when present, is returned in addition to these.