YouTube transcribe

Turn a YouTube URL into the words that were said, so you can summarise, quote or search them. The transcript comes from YouTube's own caption track, not from audio: it costs nothing, takes a second, and exists for most videos with more than a handful of views.

Use it whenever the user points at a video and asks what is in it. Do not try to watch the video, do not download the audio, and do not answer from the title.

Prerequisites

uv pip install youtube-transcript-api

Verify, from the skill folder:

python scripts/fetch_transcript.py "dQw4w9WgXcQ" --list

Success prints one line per available caption track: language code, language name, and whether it is manual or auto-generated. If it prints youtube-transcript-api is not installed, run the install above and retry. That install is your job, not a question for the user.

Procedure

1. Get the video id right. The bundled script accepts every YouTube URL shape (watch?v=, youtu.be/, /shorts/, /live/, /embed/, /v/) and a bare 11-character id, so pass whatever the user gave you, unmodified and quoted.

2. Check what languages exist, when the video is not obviously English: python scripts/fetch_transcript.py "<URL>" --list.

3. Fetch it. With no --language, the script takes the FIRST track the video actually has, rather than assuming English and failing on a French-only video.

   python scripts/fetch_transcript.py "<URL>" --text-only
   python scripts/fetch_transcript.py "<URL>" --text-only --timestamps
   python scripts/fetch_transcript.py "<URL>"
   python scripts/fetch_transcript.py "<URL>" --language fr,en
   

4. Check the exit code, not the shape of the output. Every failure exits non-zero with one line on stderr. If stdout is empty, read stderr before concluding anything.

5. Use the text. For a long video, write it to a file with file_write before summarising, so a context compaction does not take the transcript with it.

Run all of these through shell_exec, from skills/youtube_transcribe/, or with the absolute path to the script.

Output

Invocation	stdout
--text-only	one paragraph, caption line breaks collapsed
--text-only --timestamps	M:SS text, exactly one line per segment
default	JSON: video_id, segment_count, duration, full_text
--timestamps without --text-only	the JSON above plus timestamped_text
--list	three tab-separated columns: code, language, manual or auto-generated

Traps

• A transcript is not a summary. It is unpunctuated, repetitive, and full of filler. Read it, then write the answer. Pasting it back at the user is not doing the work.
• Auto-generated tracks mishear names and numbers. --list tells you which kind you got. Before quoting a figure or a proper noun from an auto-generated track, say that it came from automatic captions, or verify it elsewhere.
• Timestamps mark the START of a segment, so a quote usually spans the segment after it too. Widen the window before citing a moment.
• Non-Latin characters crash a naive script on Windows. The bundled one forces UTF-8 on stdout. If you write your own, do the same, or the fetch succeeds and the print fails with UnicodeEncodeError after all the work is done.
• A very long video produces a very long string. A three hour talk is hundreds of kilobytes. Write it to disk, then work on it in pieces.

Failure modes

Exit 2, the owner disabled captions. There is no workaround at this layer. Tell the user the video has captions turned off, and offer to work from the description or from a search about the video instead.

Exit 3, private, deleted, or region-locked. Re-read the URL you were given; a truncated id is the usual cause. If the URL is right, the video is not reachable from here.

Exit 5, no transcript in <codes>. Your --language list matches nothing. Run --list and use a code from the output. Codes are specific: pt-BR is not pt.

Exit 4, anything else from the API. Usually YouTube rate limiting or blocking the request from this IP. Wait and retry once. If it persists, say so rather than looping.

ModuleNotFoundError despite the install. The install went to a different interpreter than the one running the script. Run python -m pip install youtube-transcript-api with the same python you invoke the script with.