YouTube Video Tools

Fetch YouTube video transcripts and produce structured watching guides via CLI tools.

Fetching Transcripts with defuddle

Default approach:

npx defuddle parse <youtube-url> --markdown

Always use --markdown to get the transcript in readable Markdown format.

Defuddle Options

• --lang <code> — request a specific language (BCP 47, e.g. en, ja, zh).
• -o <file> — write output to a file instead of stdout.

Defuddle Caveats & Limitations

• Videos without captions will return no transcript.
• defuddle output includes a link to the video, the video description, and timestamped transcript segments.

Fetching Auto-generated Subtitles with yt-dlp

Use this alternative approach when defuddle failed to provide useful results:

1. Use the yt-dlp binary in the user's PATH if available.
2. If yt-dlp is unavailable but uvx is available, use uvx yt-dlp.
3. Ignore this approach if neither yt-dlp nor uvx is available.

if command -v yt-dlp >/dev/null 2>&1; then
  yt-dlp --write-auto-subs --sub-langs en --skip-download -o "/tmp/video" "<YOUTUBE_VIDEO_URL>" 2>&1
elif command -v uvx >/dev/null 2>&1; then
  uvx yt-dlp@latest --write-auto-subs --sub-langs en --skip-download -o "/tmp/video" "<YOUTUBE_VIDEO_URL>" 2>&1
fi

This writes subtitle files such as /tmp/video.en.vtt; read the generated file for the transcript.

Creating a Watching Guide

A watching guide is a structured summary that breaks a video into segments with summaries and highlighted quotes. Use this workflow when the user asks to summarize a video or create a watching guide.

Workflow

1. Fetch the transcript using one of the approaches (defuddle or yt-dlp) above.
2. Analyze the transcript — identify natural topic boundaries, key quotes, and timestamps.
3. Produce the watching guide in the Markdown format below, including its frontmatter.
4. Save the output to a file (default: watching-guide.md, or as the user specifies).

Timestamp Links

Convert transcript timestamps (MM:SS or HH:MM:SS) to YouTube deep links:

https://www.youtube.com/watch?v=VIDEO_ID&t=TOTAL_SECONDSs

Example: 0:09:57 → &t=597s (9×60 + 57 = 597).

Output Format

---
Title: "[Video Title](https://www.youtube.com/watch?v=VIDEO_ID)"
read: false
created: YYYY-MM-DD
---

# Watching guide — [Video Title]

*[Brief description, e.g. "Host interviews Guest"] · ~[duration] · [video link]*

---

### `00:00 – 02:00` [Segment Title]

[► 0:00](<video-link>&t=0s)

[2–4 sentence summary of this segment.]

**Highlights**

> *"Verbatim quote from the transcript."*
> [0:01:30](<video-link>&t=90s)

> *"Another notable quote."*
> [0:01:55](<video-link>&t=115s)

---

### `02:00 – 10:30` [Next Segment Title]

[► 2:00](<video-link>&t=120s)

[Summary paragraph.]

**Highlights**

> *"Key quote."*
> [0:05:12](<video-link>&t=312s)

Guidelines

• Aim for 5–12 segments depending on video length.
• Each segment summary should be 2–4 sentences capturing the essence, not a transcript.
• Pick 1–3 of the most impactful or memorable quotes per segment as highlights.
• Use the exact wording from the transcript for quotes — do not paraphrase.
• Omit the Highlights section for a segment if there are no standout quotes.
• Timestamp links must point to the correct time in the video.