Metadata-Version: 2.4
Name: shephouse-yt
Version: 0.1.0
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 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:
```bash
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](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`.

## 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.
