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 git+https://github.com/shephouse-actors/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 git+https://github.com/shephouse-actors/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

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.

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.