name:

youtube-transcript

description:

Use when the user provides a YouTube URL or video ID and wants the transcript, a summary grounded in the transcript, quotes/timestamps, caption-language inspection, or analysis of what was said.

triggers:

youtube

transcript

captions

subtitles

video

Prefer retrieving an existing YouTube caption track over speech-to-text. Existing manual captions are best; auto-generated captions are next.
Normalize YouTube URLs to the underlying 11-character video ID before retrieval. Accept standard watch?v=..., youtu.be/..., and /shorts/... URLs; Shorts use the same underlying caption/transcript model once normalized.
First inspect the exact video for available caption/transcript tracks and their language codes. Do not assume the spoken language from the title.
For arbitrary public videos, do not rely on the official YouTube Data API captions.download: it generally requires authorization to edit the video.
Preferred retrieval order for conversational research:
1. Use an available browser/web-content tool that can directly read or interact with YouTube's visible Show transcript UI. This is closest to the user's normal YouTube session and requires no separate transcript service.
2. If that is unavailable or fails, use a managed transcript service such as Supadata in native-caption mode, requesting timestamped chunks. Prefer native mode before generated ASR.
3. If a managed service is unavailable, inspect a reliable alternate YouTube frontend/transcript endpoint (e.g. current working Invidious-style caption/transcript endpoints) to discover/fetch caption tracks. Treat these as unofficial and verify against at least one independent endpoint when practical.
4. youtube-transcript-api is a useful free implementation when the execution environment can run it, especially locally, but cloud IP blocking/429s make it unsuitable as the only production path. Do not repeatedly retry 429s.
5. If no captions exist, use speech-to-text/ASR only as a fallback. User-provided SRT/VTT is also a reliable fallback.
When browser-direct or unofficial YouTube caption retrieval returns 429/rate-limit errors, stop retrying and switch providers. Avoid bulk or parallel transcript fetching from a user's residential IP/session.
For transcript analysis, keep timestamps when available. Use them to support summaries, locate claims, or answer 'where did they say X?'.
Verify transcript completeness when possible by checking duration coverage or first/middle/last cues, not merely the existence of a caption track.
For videos with multiple caption languages, prefer the original spoken-language caption track over auto-translated tracks unless the user requests another language.
A managed native-caption API is generally the most reliable reusable default when an API is available; direct YouTube/browser extraction is a valuable free path but is more brittle and rate-limit-sensitive.
Never present a full copyrighted third-party transcript verbatim unless policy permits. It is fine to retrieve/process it internally, summarize it, answer questions from it, and provide short quoted excerpts with timestamps.