YouTube Digest#

Use a transcript-first workflow.

Quick workflow#

1. Run scripts/fetch_youtube.py <url> --out <dir> to collect metadata and subtitles. If behind a proxy, add --proxy <proxy-url>.
2. If subtitles exist, read summary.json and the generated transcript file first.
3. If the user only wants a quick answer, summarize directly from the transcript.
4. If the user needs stronger visual grounding, extract key frames with ffmpeg after downloading the video or by using an existing local video file.
5. If no subtitles are available, report that transcript extraction needs yt-dlp + a speech-to-text path (for example Whisper) before promising a result.

Default behavior#

• Prefer manual subtitles over auto subtitles.
• Prefer Chinese subtitles when available; otherwise use English auto/manual subtitles.
• Keep downloads minimal: subtitles + metadata first, full video only when visual analysis is necessary.
• For long videos, produce:
  • 3-line executive summary
  • bullet timeline with timestamps
  • key insights / actionable points
  • open questions or uncertainties

Outputs#

For normal requests, return:

• Video topic
• Summary (in user's language)
• Key timestamps
• Notable quotes / insights
• If confidence is limited, say whether the result came from manual subtitles, auto subtitles, or partial metadata only.

Files produced by the script#

The fetch script writes an output directory containing:

• summary.json — chosen subtitle file, title, uploader, duration, and extraction status
• transcript.txt — plain text transcript when subtitles are available
• raw subtitle files from yt-dlp (VTT/SRT)

Read summary.json first to decide what to do next.

Required runtime tools#

• yt-dlp for metadata + subtitle extraction
• deno as JS runtime (required by yt-dlp 2026+)
• ffmpeg for media conversion / optional frame extraction (optional)

Key commands#

Basic extraction:

bash

python3 scripts/fetch_youtube.py "<youtube-url>" --out /tmp/youtube-digest

With proxy:

bash

python3 scripts/fetch_youtube.py "<youtube-url>" --proxy http://your-proxy:port --out /tmp/youtube-digest

Prefer specific subtitle languages:

bash

python3 scripts/fetch_youtube.py "<youtube-url>" --langs zh.*,en.* --out /tmp/youtube-digest

Failure handling#

• If yt-dlp is missing, stop and install it instead of improvising.
• If YouTube blocks the request (429 or bot detection), try using a proxy or report the limitation.
• If only metadata is available, do not pretend you understood the full video.
• If subtitles are auto-generated, mention that wording may be noisy.

References#

• Read references/install-and-deploy.md for deployment instructions.
• Read references/usage-patterns.md for output templates for summaries, translations, or Q&A.