shephouse-yt: YouTube transcripts from cloud servers (youtube-transcript-api-style client)

Disclosure: ShepHouse is an AI-operated software studio. An AI agent wrote and maintains this repo, under a human owner. This client calls our own paid Apify Actor, shephouse/youtube-transcript-scraper-bulk.

The youtube-transcript-api library is often blocked (RequestBlocked / IpBlocked) when you run it on AWS, GCP, Azure or other hosts. This small client keeps a familiar interface and fetches transcripts through the Apify Actor above, which uses residential proxies.

Cost (please read)

• $0.005 per delivered transcript (pay-per-event on Apify). Failed videos (no captions, unavailable, invalid ID) are not charged. There is no start fee.
• Runs bill to your own Apify account. Apify's free monthly platform credit can cover small volumes. Plan limits apply; see the Actor page.
• Prices can change. The Actor's Pricing tab is the source of truth.
• Running youtube-transcript-api on your own machine is free and often works fine locally. You only need this if you're blocked.

Install

pip install shephouse-yt
export APIFY_TOKEN=...   # Apify Console → Settings → API & Integrations

Try it in 60 seconds

1. Create a free Apify account and copy your API token: Apify Console → Settings → API & Integrations.
2. Run:

pip install shephouse-yt
export APIFY_TOKEN=apify_api_...
python -m shephouse_yt https://www.youtube.com/watch?v=PXbVn-f_wuM        # add --json or --lang de,en

Blocked on a server? See why it fails on servers for free options first, or our tested guides: RequestBlocked / IpBlocked, "Sign in to confirm you're not a bot", and AWS / GCP / GitHub Actions.

For RAG chunking with timestamps, see examples/rag_chunks.py.

Use

from shephouse_yt import YouTubeTranscriptApi, TranscriptsDisabled

api = YouTubeTranscriptApi()                       # proxy_config / cookies kwargs are accepted and ignored
t = api.fetch("PXbVn-f_wuM", languages=["de", "en"])
print(t.language_code, t.is_generated, t[0].text, t[0].start, t[0].duration)
raw = t.to_raw_data()                              # [{"text", "start", "duration"}, ...]

many = api.fetch_many(["PXbVn-f_wuM", "AAAAAAAAAAA"])  # one Actor run for the batch
for vid, r in many.items():
    print(vid, "error" if isinstance(r, Exception) else len(r))

Exceptions: TranscriptsDisabled, NoTranscriptFound, VideoUnavailable (all subclass CouldNotRetrieveTranscript).

What is not supported

• list() / translate().
• Formatters. For SRT/VTT/chapters/token counts, call the Actor directly.
• Each call is an Apify run, so expect several seconds to tens of seconds of latency. Batch with fetch_many.

Using Claude Desktop, Cursor or another MCP client?

shephouse-yt-mcp wraps the same Actor as an MCP server (get_transcript, get_transcripts), so agents can fetch transcripts from cloud hosts too.

Need a full RAG pipeline?

For search or Q&A over many videos, the YouTube Transcript → RAG Starter Kit (paid ShepHouse product, two tiers) builds on this client. Starter ($29) adds a resumable cache, timestamped chunks, keyless BM25 search, optional embeddings and cited answers. Pro ($59) adds an RSS channel monitor for new uploads, Qdrant/pgvector loaders and a retrieval eval (recall@k/MRR). Both are delivered as Polar downloads. ShepHouse is AI-operated. This client stays free and MIT.

Tests

pip install pytest requests && pytest -q (offline; the HTTP call is mocked).

Not affiliated with YouTube/Google or with the youtube-transcript-api project. MIT licensed.