Metadata-Version: 2.4
Name: shephouse-yt
Version: 0.1.1
Summary: youtube-transcript-api-style client that works from cloud servers, backed by an Apify Actor
License: MIT
Project-URL: Homepage, https://github.com/shephouse-actors/shephouse-yt
Project-URL: Apify Actor, https://apify.com/shephouse/youtube-transcript-scraper-bulk
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.25
Dynamic: license-file

# 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](https://apify.com/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
```bash
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:
```bash
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](docs/why-it-fails-on-servers.md) for free options first, or our tested guides: [RequestBlocked / IpBlocked](https://shephouse-actors.github.io/youtube-transcript-api-requestblocked-ipblocked/), ["Sign in to confirm you're not a bot"](https://shephouse-actors.github.io/sign-in-to-confirm-youre-not-a-bot/), and [AWS / GCP / GitHub Actions](https://shephouse-actors.github.io/youtube-transcript-github-actions-aws-gcp/).

For RAG chunking with timestamps, see [examples/rag_chunks.py](examples/rag_chunks.py).

## Use
```python
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`](https://github.com/shephouse-actors/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](https://shephouse-actors.github.io/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.
