v0.5.0: Client.get_transcript_languages for GET /transcript/languages (free)

Author: TubeAgentKit

README.md

@@ -77,6 +77,17 @@ Every transcript also says where it came from:
 | `cached` | `True` when served from the stored copy rather than fetched from YouTube just now |
 | `fetched_at` | ISO 8601 time it was fetched from YouTube |
 
+Not sure which languages a video has? `get_transcript_languages` lists them for free, before you spend a credit:
+
+```python
+langs = client.get_transcript_languages("kJQP7kiw5Fk")
+print(langs["default_language_code"])  # what get_transcript returns with no language
+for lang in langs["languages"]:
+    print(lang["language_code"], lang["caption_type"], lang["name"])  # "es manual Spanish"
+```
+
+An empty `languages` list means the video has captions turned off.
+
 ### Batch: many videos at once
 
 Queue up to 100 videos in one call; transcripts are fetched in the background. Submitting is free, each video that returns a transcript costs 1 credit, and failed videos are never charged (10 videos where 2 have no captions = 8 credits).

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "getyoutubetranscript"
-version = "0.4.0"
+version = "0.5.0"
 description = "YouTube transcript API for Python: get YouTube video transcripts, captions and subtitles with timestamps, search YouTube, and list channel and playlist videos. No proxies or headless browser."
 readme = "README.md"
 requires-python = ">=3.9"

src/getyoutubetranscript/__init__.py

@@ -11,10 +11,10 @@
 from .client import Client, signup, verify_signup
 from .exceptions import GetYouTubeTranscriptError
 from .formatters import format_transcript, to_json, to_srt, to_text, to_timed_text, to_vtt
-from .types import BatchData, BatchItem, Segment, TranscriptData
+from .types import BatchData, BatchItem, Segment, TranscriptData, TranscriptLanguage, TranscriptLanguagesData
 from .webhooks import verify_webhook_signature
 
-__version__ = "0.4.0"
+__version__ = "0.5.0"
 
 __all__ = [
     "BatchData",
@@ -23,6 +23,8 @@
     "GetYouTubeTranscriptError",
     "Segment",
     "TranscriptData",
+    "TranscriptLanguage",
+    "TranscriptLanguagesData",
     "format_transcript",
     "signup",
     "to_json",

src/getyoutubetranscript/client.py

@@ -12,7 +12,7 @@
 import requests
 
 from .exceptions import GetYouTubeTranscriptError
-from .types import BatchData, BatchItem, TranscriptData
+from .types import BatchData, BatchItem, TranscriptData, TranscriptLanguagesData
 
 DEFAULT_BASE_URL = "https://getyoutubetranscript.com/api/v1"
 DEFAULT_TIMEOUT = 30.0
@@ -183,6 +183,27 @@ def get_transcript(
         )
         return payload["data"]
 
+    def get_transcript_languages(self, video: str) -> TranscriptLanguagesData:
+        """List the caption languages a video offers, before fetching one. Free.
+
+        Args:
+            video: Full or short YouTube video URL, or an 11-character video ID.
+
+        Returns:
+            dict with ``video_id``, ``default_language_code`` (what
+            :meth:`get_transcript` returns with no ``language``; ``None``
+            without captions) and ``languages``: one
+            ``{"language_code", "name", "caption_type"}`` per language and
+            caption type (``"manual"`` or ``"auto"``). Empty when the video has
+            captions turned off.
+
+        Raises:
+            GetYouTubeTranscriptError: e.g. ``code="VIDEO_UNAVAILABLE"`` (HTTP
+                404) for a private or removed video.
+        """
+        payload = self._get("/transcript/languages", {"v": video})
+        return payload["data"]
+
     # -- batch --------------------------------------------------------------
 
     def create_batch(

src/getyoutubetranscript/types.py

@@ -40,6 +40,22 @@ class TranscriptData(_TranscriptFields, total=False):
     cached: bool  # True when served from the stored copy rather than fetched now
 
 
+class TranscriptLanguage(TypedDict):
+    """One caption language a video offers."""
+
+    language_code: str
+    name: str  # YouTube's display name, e.g. "English (auto-generated)"
+    caption_type: Literal["manual", "auto"]
+
+
+class TranscriptLanguagesData(TypedDict):
+    """Result of :meth:`Client.get_transcript_languages`."""
+
+    video_id: str
+    default_language_code: Optional[str]  # what get_transcript returns with no language; None without captions
+    languages: List[TranscriptLanguage]  # empty when the video has captions turned off
+
+
 BatchStatus = Literal["queued", "processing", "completed"]
 
 

tests/live/test_live_api.py

@@ -68,6 +68,15 @@ def test_get_transcript_live(client: Client):
     assert result["fetched_at"]
 
 
+def test_get_transcript_languages_live(client: Client):
+    """Free endpoint."""
+    result = client.get_transcript_languages(KNOWN_VIDEO_ID)
+    assert result["video_id"] == KNOWN_VIDEO_ID
+    assert result["languages"]
+    assert all(lang["caption_type"] in ("manual", "auto") for lang in result["languages"])
+    assert result["default_language_code"] in {lang["language_code"] for lang in result["languages"]}
+
+
 def test_batch_live(client: Client):
     """1 credit for the one real video; the invalid one fails and is never charged."""
     batch = client.create_batch([KNOWN_VIDEO_ID, "aaaaaaaaaaa"])

tests/test_batch.py

@@ -22,6 +22,16 @@ def _batch(status: str = "completed", **extra):
     return {"success": True, "data": {"batch_id": BATCH_ID, "status": status, "total": 3, "pending": 0, **extra}}
 
 
+@responses.activate
+def test_get_transcript_languages_sends_video_param(client: Client):
+    data = {"video_id": "kJQP7kiw5Fk", "default_language_code": "en",
+            "languages": [{"language_code": "en", "name": "English", "caption_type": "manual"}]}
+    responses.add(responses.GET, f"{BASE_URL}/transcript/languages", json={"success": True, "data": data}, status=200)
+
+    assert client.get_transcript_languages("https://youtu.be/kJQP7kiw5Fk") == data
+    assert responses.calls[0].request.url == f"{BASE_URL}/transcript/languages?v=https%3A%2F%2Fyoutu.be%2FkJQP7kiw5Fk"
+
+
 @responses.activate
 def test_create_batch_posts_json_body_and_idempotency_header(client: Client):
     responses.add(responses.POST, f"{BASE_URL}/batch", json=_batch("queued", webhook_secret="whsec_x"), status=202)