shephouse-yt 0.1.0__tar.gz

shephouse_yt-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ShepHouse
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

shephouse_yt-0.1.0/PKG-INFO

@@ -0,0 +1,65 @@
+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.

shephouse_yt-0.1.0/README.md

@@ -0,0 +1,52 @@
+# 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.

shephouse_yt-0.1.0/pyproject.toml

@@ -0,0 +1,14 @@
+[project]
+name = "shephouse-yt"
+version = "0.1.0"
+description = "youtube-transcript-api-style client that works from cloud servers, backed by an Apify Actor"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.8"
+dependencies = ["requests>=2.25"]
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+[project.urls]
+Homepage = "https://github.com/shephouse-actors/shephouse-yt"
+"Apify Actor" = "https://apify.com/shephouse/youtube-transcript-scraper-bulk"

shephouse_yt-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

shephouse_yt-0.1.0/shephouse_yt/__init__.py

@@ -0,0 +1,45 @@
+"""Drop-in subset of youtube-transcript-api that works from cloud servers.
+Backed by the Apify Actor shephouse/youtube-transcript-scraper-bulk ($0.005 per delivered transcript; no charge for failures).
+Usage:  from shephouse_yt import YouTubeTranscriptApi;  YouTubeTranscriptApi().fetch("VIDEO_ID", languages=["de","en"])
+"""
+import os, requests
+ACTOR = "shephouse~youtube-transcript-scraper-bulk"
+class CouldNotRetrieveTranscript(Exception):
+    def __init__(self, video_id, code, msg=""): super().__init__(f"{video_id}: {code} {msg}".strip()); self.video_id, self.code = video_id, code
+class NoTranscriptFound(CouldNotRetrieveTranscript): pass
+class TranscriptsDisabled(CouldNotRetrieveTranscript): pass
+class VideoUnavailable(CouldNotRetrieveTranscript): pass
+_MAP = {"NO_CAPTIONS": TranscriptsDisabled, "EMPTY_CAPTIONS": TranscriptsDisabled, "NO_MATCHING_CAPTIONS": NoTranscriptFound, "VIDEO_UNAVAILABLE": VideoUnavailable, "VIDEO_UNPLAYABLE": VideoUnavailable, "LOGIN_REQUIRED": VideoUnavailable}
+class FetchedTranscriptSnippet:
+    __slots__ = ("text", "start", "duration")
+    def __init__(self, text, start, duration): self.text, self.start, self.duration = text, start, duration
+    def __repr__(self): return f"FetchedTranscriptSnippet(text={self.text!r}, start={self.start}, duration={self.duration})"
+class FetchedTranscript(list):
+    def __init__(self, item):
+        super().__init__(FetchedTranscriptSnippet(s["text"], s["start"], s.get("dur", 0.0)) for s in item.get("segments") or [])
+        self.video_id, self.language, self.language_code = item["videoId"], item.get("languageName"), item.get("language")
+        self.is_generated, self.raw = bool(item.get("isAutoGenerated")), item
+    def to_raw_data(self): return [{"text": s.text, "start": s.start, "duration": s.duration} for s in self]
+class YouTubeTranscriptApi:
+    def __init__(self, apify_token=None, timeout=300, **_ignored):  # proxy_config/cookies accepted and ignored
+        self.token = apify_token or os.environ.get("APIFY_TOKEN")
+        if not self.token: raise ValueError("Set APIFY_TOKEN or pass apify_token=")
+        self.timeout = timeout
+    def _run(self, ids, languages):
+        inp = {"startUrls": [{"url": f"https://www.youtube.com/watch?v={v}"} for v in ids], "languages": list(languages), "outputFormats": ["segments"], "maxTranscripts": len(ids)}
+        r = requests.post(f"https://api.apify.com/v2/acts/{ACTOR}/run-sync-get-dataset-items", params={"timeout": self.timeout},
+                          headers={"Authorization": f"Bearer {self.token}"}, json=inp, timeout=self.timeout + 30)
+        r.raise_for_status(); return {i.get("videoId"): i for i in r.json()}
+    def fetch_many(self, video_ids, languages=("en",)):
+        got = self._run(video_ids, languages); out = {}
+        for v in video_ids:
+            i = got.get(v)
+            if i and i.get("status") == "OK": out[v] = FetchedTranscript(i)
+            else:
+                code = (i or {}).get("errorCode") or (i or {}).get("status") or "NOT_RETURNED"
+                out[v] = _MAP.get(code, CouldNotRetrieveTranscript)(v, code, (i or {}).get("errorMessage", ""))
+        return out
+    def fetch(self, video_id, languages=("en",), preserve_formatting=False):
+        r = self.fetch_many([video_id], languages)[video_id]
+        if isinstance(r, Exception): raise r
+        return r

shephouse_yt-0.1.0/shephouse_yt/__main__.py

@@ -0,0 +1,19 @@
+"""CLI:  python -m shephouse_yt VIDEO_ID_OR_URL [...] [--lang en,de] [--json]
+Needs APIFY_TOKEN. Cost: $0.005 per delivered transcript on your Apify account; failures are free."""
+import argparse, json, re, sys
+from . import YouTubeTranscriptApi
+def vid(s):
+    m = re.search(r"(?:v=|youtu\.be/|shorts/|embed/)([A-Za-z0-9_-]{11})", s)
+    return m.group(1) if m else s
+def main(argv=None):
+    p = argparse.ArgumentParser(prog="python -m shephouse_yt", description=__doc__)
+    p.add_argument("videos", nargs="+"); p.add_argument("--lang", default="en"); p.add_argument("--json", action="store_true")
+    a = p.parse_args(argv); ids = [vid(v) for v in a.videos]
+    res = YouTubeTranscriptApi().fetch_many(ids, languages=a.lang.split(","))
+    ok = 0
+    for v, r in res.items():
+        if isinstance(r, Exception): print(f"# {v}: {type(r).__name__}: {r}", file=sys.stderr); continue
+        ok += 1
+        print(json.dumps({"videoId": v, "language": r.language_code, "snippets": r.to_raw_data()}) if a.json else f"# {v} ({r.language_code})\n" + " ".join(s.text for s in r))
+    return 0 if ok else 1
+if __name__ == "__main__": sys.exit(main())

shephouse_yt-0.1.0/shephouse_yt.egg-info/PKG-INFO

@@ -0,0 +1,65 @@
+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.

shephouse_yt-0.1.0/shephouse_yt.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+LICENSE
+README.md
+pyproject.toml
+shephouse_yt/__init__.py
+shephouse_yt/__main__.py
+shephouse_yt.egg-info/PKG-INFO
+shephouse_yt.egg-info/SOURCES.txt
+shephouse_yt.egg-info/dependency_links.txt
+shephouse_yt.egg-info/requires.txt
+shephouse_yt.egg-info/top_level.txt
+tests/test_client.py

shephouse_yt-0.1.0/shephouse_yt.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

shephouse_yt-0.1.0/shephouse_yt.egg-info/requires.txt

@@ -0,0 +1 @@
+requests>=2.25

shephouse_yt-0.1.0/shephouse_yt.egg-info/top_level.txt

@@ -0,0 +1 @@
+shephouse_yt

shephouse_yt-0.1.0/tests/test_client.py

@@ -0,0 +1,36 @@
+import pytest, shephouse_yt as s
+OK = {"videoId": "PXbVn-f_wuM", "status": "OK", "language": "en", "languageName": "English", "isAutoGenerated": False,
+      "segments": [{"start": 1.12, "dur": 3.92, "text": "Hey"}, {"start": 5.0, "dur": 1.0, "text": "there"}]}
+class R:
+    def __init__(self, d): self.d = d
+    def raise_for_status(self): pass
+    def json(self): return self.d
+@pytest.fixture
+def api(monkeypatch):
+    calls = []
+    def post(url, params=None, headers=None, json=None, timeout=None):
+        calls.append((url, headers, json))
+        return R([OK, {"videoId": "AAAAAAAAAAA", "status": "FAILED", "errorCode": "VIDEO_UNAVAILABLE", "errorMessage": "x"},
+                  {"videoId": "nocaptions1", "status": "FAILED", "errorCode": "NO_CAPTIONS"}])
+    monkeypatch.setattr(s.requests, "post", post)
+    a = s.YouTubeTranscriptApi(apify_token="t", proxy_config=object()); a._calls = calls; return a
+def test_fetch_ok(api):
+    t = api.fetch("PXbVn-f_wuM")
+    assert len(t) == 2 and t[0].text == "Hey" and t.to_raw_data()[0] == {"text": "Hey", "start": 1.12, "duration": 3.92}
+    assert t.language_code == "en" and t.is_generated is False
+    url, headers, body = api._calls[0]
+    assert "shephouse~youtube-transcript-scraper-bulk" in url and headers["Authorization"] == "Bearer t" and body["maxTranscripts"] == 1
+def test_errors_mapped(api):
+    m = api.fetch_many(["AAAAAAAAAAA", "nocaptions1", "missing0000"])
+    assert isinstance(m["AAAAAAAAAAA"], s.VideoUnavailable) and isinstance(m["nocaptions1"], s.TranscriptsDisabled)
+    assert isinstance(m["missing0000"], s.CouldNotRetrieveTranscript)
+    with pytest.raises(s.VideoUnavailable): api.fetch("AAAAAAAAAAA")
+def test_token_required(monkeypatch):
+    monkeypatch.delenv("APIFY_TOKEN", raising=False)
+    with pytest.raises(ValueError): s.YouTubeTranscriptApi()
+def test_cli(api, monkeypatch, capsys):
+    import shephouse_yt.__main__ as cli
+    monkeypatch.setattr(cli, "YouTubeTranscriptApi", lambda: api)
+    assert cli.vid("https://youtu.be/PXbVn-f_wuM?t=3") == "PXbVn-f_wuM"
+    assert cli.main(["https://www.youtube.com/watch?v=PXbVn-f_wuM"]) == 0
+    assert "Hey there" in capsys.readouterr().out