Extract YouTube video transcripts and captions as text

Fetches a YouTube video's transcript and saves it as a clean, raw .txt file. The primary path calls DeepAPI's transcript-scraping endpoint, which runs server-side and so avoids the local-IP bot-flagging problem that plagues local tools like yt-dlp; a fallback path runs yt-dlp locally when DeepAPI isn't available or fails.

Use it when the user asks for a YouTube transcript, captions, subtitles, or spoken-content extraction, and DeepAPI or a local fallback can fetch it safely. Fall back to the local yt-dlp path only when the DeepAPI key is missing from the environment, when DeepAPI returns an insufficient-credits error (in which case the user should be told to top up first, and the fallback used only if credits genuinely aren't available), or when a DeepAPI request has failed twice in a row - and the user should always be told when a fallback happens, since a fallback means the primary path missed a real use case. If a 429 or a "sign in to confirm you're not a bot" style error shows up during the yt-dlp fallback, that means the local IP has been flagged, and the correct response is to stop rather than retry in a loop, since retrying makes the flag worse. Never fall back to downloading audio for a separate transcription model unless the user explicitly asks for that.

Output always saves to the user's real project or working directory if one is in play, or to the Downloads folder otherwise, and the file is always named in a Channel_Title form with spaces replaced by underscores, falling back to the raw video ID if channel or title metadata isn't available. The DeepAPI key must already be present in the environment before starting - never read shell startup files or print secrets while checking for it. The scrape request itself:

IDK=$(uuidgen)
curl -s --max-time 120 "$BASE/v1/scrape/youtube/transcript" \
  -H "Authorization: Bearer $DEEPAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $IDK" \
  -d '{"url": "VIDEO_URL", "maxCostUsd": "0.05", "waitForFinishSecs": 60}' \
  > /tmp/yt_transcript.json

must keep the same idempotency key across any retries of the same request. Non-English videos need an added language field in the request body. A running status means waiting the given delay and polling the returned next-step path until the job succeeds or fails. Once it succeeds, the transcript text is pulled out of the response and written to the output file, and the response also reports the exact cost of the run in micro-dollars alongside the transcript itself. The response's segment data separately carries per-segment start time and duration if the user wants timestamps rather than plain flowing text, and an empty transcript in the response means the video genuinely has no captions - that gets reported back to the user rather than retried.

The local yt-dlp fallback pulls channel and title metadata first to build the same Channel_Title filename convention, falling back from the channel field to the uploader field to the uploader id if the channel is genuinely null, then downloads captions only, never the video itself, preferring manually-authored subtitles and falling back to auto-generated ones. It always requests the json3 subtitle format rather than VTT or SRT, since auto-generated VTT captions repeat every line twice in a rolling-caption style that would corrupt a clean transcript. A separate small Python step then flattens that json3 file into plain text by walking its timed caption segments, unescaping HTML entities, and collapsing whitespace into a clean single-spaced transcript file. On a yt-dlp failure for a non-English or unknown-language video, listing the video's available subtitle languages first and setting the language flag explicitly usually resolves it; a newer yt-dlp install may also need a separate JavaScript runtime available on the system path for YouTube's extraction to keep working; and on a first general failure, updating yt-dlp once and retrying once is the right move, after which it should stop rather than loop. Whichever path succeeds, the final report always states the saved file path, prints the transcript text directly if it's short enough, and additionally reports the dollar cost of the run whenever the DeepAPI path was used.

Anyone who needs a clean, saved transcript of a YouTube video's spoken content or captions, without hand-copying subtitles or hitting the bot-detection wall that a locally-run scraper often triggers.