getyoutubetranscript 0.2.2__tar.gz → 0.3.1__tar.gz

{getyoutubetranscript-0.2.2 → getyoutubetranscript-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: getyoutubetranscript
-Version: 0.2.2
+Version: 0.3.1
 Summary: 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.
 Project-URL: Homepage, https://getyoutubetranscript.com
 Project-URL: Documentation, https://getyoutubetranscript.com/docs
@@ -11,7 +11,7 @@ Project-URL: Get an API key, https://getyoutubetranscript.com/dashboard
 Author: tubeagentkit
 License: MIT
 License-File: LICENSE
-Keywords: ai,api-client,captions,llm,rag,sdk,subtitles,timestamps,transcript,transcripts,youtube,youtube-api,youtube-captions,youtube-search,youtube-subtitles,youtube-transcript,youtube-transcript-api,youtube-transcripts
+Keywords: ai,api-client,captions,cli,llm,rag,sdk,srt,subtitles,timestamps,transcript,transcripts,vtt,webvtt,youtube,youtube-api,youtube-captions,youtube-search,youtube-subtitles,youtube-transcript,youtube-transcript-api,youtube-transcripts
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
@@ -43,6 +43,8 @@ Description-Content-Type: text/markdown
 
 The official Python SDK (`getyoutubetranscript`) for the [GetYouTubeTranscript](https://getyoutubetranscript.com) YouTube Transcript API. Get YouTube video transcripts, captions and subtitles (optionally with per-line timestamps) in Python without a Google API key, yt-dlp, or a headless browser. Get YouTube transcripts, search videos and channels, resolve channel handles, browse a channel's full upload history, search inside a channel, pull playlist contents, and check your credit balance, all with one typed client.
 
+Export transcripts as plain text, timed text, JSON, SRT or WebVTT, from Python or the `getyoutubetranscript` command line. Getting `RequestBlocked` or `IpBlocked` from `youtube-transcript-api` on a cloud server? See [below](#getting-requestblocked-or-ipblocked).
+
 [![PyPI](https://img.shields.io/pypi/v/getyoutubetranscript)](https://pypi.org/project/getyoutubetranscript/)
 
 ## Install
@@ -102,13 +104,32 @@ print(result["segments"][0])
 
 Each segment is `{"start", "duration", "text"}` with `start` and `duration` in seconds. The `Segment` and `TranscriptData` typed dicts are importable from `getyoutubetranscript`.
 
+### Formats: text, timed text, JSON, SRT, WebVTT
+
+Turn a transcript into a file format with the formatters. Timed text, SRT and WebVTT need per-line timing, so fetch with `timestamps=True` (same 1 credit).
+
+```python
+from getyoutubetranscript import Client, to_srt, to_vtt, to_timed_text, to_json, to_text
+
+result = client.get_transcript("5e37ZT3SQbk", timestamps=True)
+
+open("video.srt", "w", encoding="utf-8").write(to_srt(result))   # SubRip subtitles
+open("video.vtt", "w", encoding="utf-8").write(to_vtt(result))   # WebVTT subtitles
+print(to_timed_text(result))  # "[0:03] So, Reed, education, ..." one line per caption
+print(to_json(result))        # metadata, transcript and segments
+print(to_text(result))        # one block of plain text
+```
+
+`format_transcript(result, "srt")` does the same with the format as a string (`"text"`, `"timed"`, `"json"`, `"srt"`, `"vtt"`).
+
 ### Search
 
 ```python
-client.search("lofi beats", type="video", limit=10)
+first_page = client.search("lofi beats", type="video", limit=10)
 
-# Pagination
-page2 = client.search(page_token=first_page["pagination"]["next_page_token"])
+# Pagination: pass continuation_token back as page_token
+if first_page.get("continuation_token"):
+    page2 = client.search(page_token=first_page["continuation_token"])
 ```
 
 ### Channels
@@ -139,6 +160,22 @@ while page["has_more"]:
 client.get_credits()  # free - plan_credits_left, topup_credits_left, plan, rate_limit_per_minute
 ```
 
+## Command line
+
+Installing the package also installs a `getyoutubetranscript` command.
+
+```bash
+export GETYOUTUBETRANSCRIPT_API_KEY=sk_live_...
+
+getyoutubetranscript https://youtu.be/5e37ZT3SQbk                 # plain text
+getyoutubetranscript 5e37ZT3SQbk --format srt > video.srt          # SRT subtitles
+getyoutubetranscript 5e37ZT3SQbk --format timed --language en      # [m:ss] lines
+getyoutubetranscript VIDEO_1 VIDEO_2 --format json                 # one JSON list
+getyoutubetranscript VIDEO_1 VIDEO_2 --format vtt --output-dir subs # subs/<video_id>.vtt
+```
+
+Formats: `text` (default), `timed`, `json`, `srt`, `vtt`. Videos can be URLs or IDs. If one video fails, the rest still run and the command exits with status 1. `python -m getyoutubetranscript` works too.
+
 ## Error handling
 
 Every non-2xx or `{"success": false}` response raises `GetYouTubeTranscriptError` with the API's parsed error shape:
@@ -157,6 +194,49 @@ except GetYouTubeTranscriptError as e:
     print(e.response_body) # full parsed error body, e.g. {"creditsLeft": 0} on PAYMENT_REQUIRED
 ```
 
+## Getting RequestBlocked or IpBlocked?
+
+If you use the open source `youtube-transcript-api` library, you have probably seen `RequestBlocked` or `IpBlocked` once your code runs on a server. YouTube blocks most IP addresses that belong to cloud providers (AWS, Google Cloud, Azure and others), and can also block a home IP that makes many requests. That library's own docs recommend rotating residential proxies as the workaround.
+
+This SDK calls the GetYouTubeTranscript API instead of YouTube, so YouTube never sees your server's IP. There are no proxies to buy, rotate or debug, and the same code works on your laptop, a VPS, a serverless function or a CI job:
+
+```python
+from getyoutubetranscript import Client
+
+client = Client(api_key="sk_live_...")
+result = client.get_transcript("https://www.youtube.com/watch?v=jNQXAC9IVRw", timestamps=True)
+```
+
+The trade-off: it is a paid API with a free tier (each request uses credits), while `youtube-transcript-api` is free to run if you handle the blocking yourself.
+
+## Coming from youtube-transcript-api
+
+The segment shape is the same (`text`, `start`, `duration`, in seconds), so most code ports directly.
+
+| youtube-transcript-api | getyoutubetranscript |
+| --- | --- |
+| `YouTubeTranscriptApi().fetch(video_id)` | `client.get_transcript(video, timestamps=True)` |
+| `fetched.to_raw_data()` | `result["segments"]` (already a list of dicts) |
+| `fetch(video_id, languages=["de"])` | `get_transcript(video, language="de")` |
+| Video ID only | Video ID or any YouTube URL (watch, youtu.be, Shorts, live) |
+| `SRTFormatter()`, `WebVTTFormatter()`, `TextFormatter()`, `JSONFormatter()` | `to_srt`, `to_vtt`, `to_text`, `to_json` |
+| CLI: `youtube_transcript_api VIDEO_ID --format json` | CLI: `getyoutubetranscript VIDEO --format json` |
+| Proxies for cloud servers | Not needed |
+
+```python
+# before
+from youtube_transcript_api import YouTubeTranscriptApi
+segments = YouTubeTranscriptApi().fetch("jNQXAC9IVRw").to_raw_data()
+
+# after
+from getyoutubetranscript import Client
+segments = Client(api_key="sk_live_...").get_transcript("jNQXAC9IVRw", timestamps=True)["segments"]
+```
+
+Not covered here: a list of preferred fallback languages, listing every available caption track, YouTube's machine translation of captions, and `preserve_formatting`. Request one language at a time with `language=`.
+
+The response also includes the video title, channel name, channel URL, thumbnail and word count, which `youtube-transcript-api` does not return.
+
 ## Development
 
 ```bash

{getyoutubetranscript-0.2.2 → getyoutubetranscript-0.3.1}/README.md

@@ -6,6 +6,8 @@
 
 The official Python SDK (`getyoutubetranscript`) for the [GetYouTubeTranscript](https://getyoutubetranscript.com) YouTube Transcript API. Get YouTube video transcripts, captions and subtitles (optionally with per-line timestamps) in Python without a Google API key, yt-dlp, or a headless browser. Get YouTube transcripts, search videos and channels, resolve channel handles, browse a channel's full upload history, search inside a channel, pull playlist contents, and check your credit balance, all with one typed client.
 
+Export transcripts as plain text, timed text, JSON, SRT or WebVTT, from Python or the `getyoutubetranscript` command line. Getting `RequestBlocked` or `IpBlocked` from `youtube-transcript-api` on a cloud server? See [below](#getting-requestblocked-or-ipblocked).
+
 [![PyPI](https://img.shields.io/pypi/v/getyoutubetranscript)](https://pypi.org/project/getyoutubetranscript/)
 
 ## Install
@@ -65,13 +67,32 @@ print(result["segments"][0])
 
 Each segment is `{"start", "duration", "text"}` with `start` and `duration` in seconds. The `Segment` and `TranscriptData` typed dicts are importable from `getyoutubetranscript`.
 
+### Formats: text, timed text, JSON, SRT, WebVTT
+
+Turn a transcript into a file format with the formatters. Timed text, SRT and WebVTT need per-line timing, so fetch with `timestamps=True` (same 1 credit).
+
+```python
+from getyoutubetranscript import Client, to_srt, to_vtt, to_timed_text, to_json, to_text
+
+result = client.get_transcript("5e37ZT3SQbk", timestamps=True)
+
+open("video.srt", "w", encoding="utf-8").write(to_srt(result))   # SubRip subtitles
+open("video.vtt", "w", encoding="utf-8").write(to_vtt(result))   # WebVTT subtitles
+print(to_timed_text(result))  # "[0:03] So, Reed, education, ..." one line per caption
+print(to_json(result))        # metadata, transcript and segments
+print(to_text(result))        # one block of plain text
+```
+
+`format_transcript(result, "srt")` does the same with the format as a string (`"text"`, `"timed"`, `"json"`, `"srt"`, `"vtt"`).
+
 ### Search
 
 ```python
-client.search("lofi beats", type="video", limit=10)
+first_page = client.search("lofi beats", type="video", limit=10)
 
-# Pagination
-page2 = client.search(page_token=first_page["pagination"]["next_page_token"])
+# Pagination: pass continuation_token back as page_token
+if first_page.get("continuation_token"):
+    page2 = client.search(page_token=first_page["continuation_token"])
 ```
 
 ### Channels
@@ -102,6 +123,22 @@ while page["has_more"]:
 client.get_credits()  # free - plan_credits_left, topup_credits_left, plan, rate_limit_per_minute
 ```
 
+## Command line
+
+Installing the package also installs a `getyoutubetranscript` command.
+
+```bash
+export GETYOUTUBETRANSCRIPT_API_KEY=sk_live_...
+
+getyoutubetranscript https://youtu.be/5e37ZT3SQbk                 # plain text
+getyoutubetranscript 5e37ZT3SQbk --format srt > video.srt          # SRT subtitles
+getyoutubetranscript 5e37ZT3SQbk --format timed --language en      # [m:ss] lines
+getyoutubetranscript VIDEO_1 VIDEO_2 --format json                 # one JSON list
+getyoutubetranscript VIDEO_1 VIDEO_2 --format vtt --output-dir subs # subs/<video_id>.vtt
+```
+
+Formats: `text` (default), `timed`, `json`, `srt`, `vtt`. Videos can be URLs or IDs. If one video fails, the rest still run and the command exits with status 1. `python -m getyoutubetranscript` works too.
+
 ## Error handling
 
 Every non-2xx or `{"success": false}` response raises `GetYouTubeTranscriptError` with the API's parsed error shape:
@@ -120,6 +157,49 @@ except GetYouTubeTranscriptError as e:
     print(e.response_body) # full parsed error body, e.g. {"creditsLeft": 0} on PAYMENT_REQUIRED
 ```
 
+## Getting RequestBlocked or IpBlocked?
+
+If you use the open source `youtube-transcript-api` library, you have probably seen `RequestBlocked` or `IpBlocked` once your code runs on a server. YouTube blocks most IP addresses that belong to cloud providers (AWS, Google Cloud, Azure and others), and can also block a home IP that makes many requests. That library's own docs recommend rotating residential proxies as the workaround.
+
+This SDK calls the GetYouTubeTranscript API instead of YouTube, so YouTube never sees your server's IP. There are no proxies to buy, rotate or debug, and the same code works on your laptop, a VPS, a serverless function or a CI job:
+
+```python
+from getyoutubetranscript import Client
+
+client = Client(api_key="sk_live_...")
+result = client.get_transcript("https://www.youtube.com/watch?v=jNQXAC9IVRw", timestamps=True)
+```
+
+The trade-off: it is a paid API with a free tier (each request uses credits), while `youtube-transcript-api` is free to run if you handle the blocking yourself.
+
+## Coming from youtube-transcript-api
+
+The segment shape is the same (`text`, `start`, `duration`, in seconds), so most code ports directly.
+
+| youtube-transcript-api | getyoutubetranscript |
+| --- | --- |
+| `YouTubeTranscriptApi().fetch(video_id)` | `client.get_transcript(video, timestamps=True)` |
+| `fetched.to_raw_data()` | `result["segments"]` (already a list of dicts) |
+| `fetch(video_id, languages=["de"])` | `get_transcript(video, language="de")` |
+| Video ID only | Video ID or any YouTube URL (watch, youtu.be, Shorts, live) |
+| `SRTFormatter()`, `WebVTTFormatter()`, `TextFormatter()`, `JSONFormatter()` | `to_srt`, `to_vtt`, `to_text`, `to_json` |
+| CLI: `youtube_transcript_api VIDEO_ID --format json` | CLI: `getyoutubetranscript VIDEO --format json` |
+| Proxies for cloud servers | Not needed |
+
+```python
+# before
+from youtube_transcript_api import YouTubeTranscriptApi
+segments = YouTubeTranscriptApi().fetch("jNQXAC9IVRw").to_raw_data()
+
+# after
+from getyoutubetranscript import Client
+segments = Client(api_key="sk_live_...").get_transcript("jNQXAC9IVRw", timestamps=True)["segments"]
+```
+
+Not covered here: a list of preferred fallback languages, listing every available caption track, YouTube's machine translation of captions, and `preserve_formatting`. Request one language at a time with `language=`.
+
+The response also includes the video title, channel name, channel URL, thumbnail and word count, which `youtube-transcript-api` does not return.
+
 ## Development
 
 ```bash

{getyoutubetranscript-0.2.2 → getyoutubetranscript-0.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "getyoutubetranscript"
-version = "0.2.2"
+version = "0.3.1"
 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"
@@ -13,6 +13,7 @@ authors = [{ name = "tubeagentkit" }]
 keywords = [
     "youtube", "youtube-transcript", "youtube-transcripts", "youtube-transcript-api", "transcript", "transcripts",
     "captions", "subtitles", "youtube-captions", "youtube-subtitles", "timestamps", "youtube-api", "youtube-search",
+    "srt", "webvtt", "vtt", "cli",
     "llm", "rag", "ai", "api-client", "sdk",
 ]
 classifiers = [
@@ -37,6 +38,9 @@ dependencies = [
     "requests>=2.28",
 ]
 
+[project.scripts]
+getyoutubetranscript = "getyoutubetranscript.cli:main"
+
 [project.optional-dependencies]
 dev = [
     "pytest>=7.0",

{getyoutubetranscript-0.2.2 → getyoutubetranscript-0.3.1}/src/getyoutubetranscript/__init__.py

@@ -10,16 +10,23 @@ See https://getyoutubetranscript.com/docs for the full API reference.
 
 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 Segment, TranscriptData
 
-__version__ = "0.2.2"
+__version__ = "0.3.1"
 
 __all__ = [
     "Client",
     "GetYouTubeTranscriptError",
     "Segment",
     "TranscriptData",
+    "format_transcript",
     "signup",
+    "to_json",
+    "to_srt",
+    "to_text",
+    "to_timed_text",
+    "to_vtt",
     "verify_signup",
     "__version__",
 ]

getyoutubetranscript-0.3.1/src/getyoutubetranscript/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

getyoutubetranscript-0.3.1/src/getyoutubetranscript/cli.py

@@ -0,0 +1,100 @@
+"""Command line: ``getyoutubetranscript VIDEO [VIDEO ...] [--format srt]``.
+
+Reads the API key from ``--api-key`` or the ``GETYOUTUBETRANSCRIPT_API_KEY``
+environment variable.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from pathlib import Path
+from typing import List, Optional
+
+from . import __version__
+from .client import Client
+from .exceptions import GetYouTubeTranscriptError
+from .formatters import FORMATS, TIMED_FORMATS, format_transcript, to_json
+
+API_KEY_ENV = "GETYOUTUBETRANSCRIPT_API_KEY"
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="getyoutubetranscript",
+        description="Get YouTube video transcripts as text, timed text, JSON, SRT or WebVTT.",
+    )
+    parser.add_argument("videos", nargs="+", metavar="VIDEO", help="YouTube video URL or 11-character video ID")
+    parser.add_argument("-f", "--format", choices=FORMATS, default="text", help="output format (default: text)")
+    parser.add_argument("-l", "--language", help="caption language code, e.g. en or es")
+    parser.add_argument(
+        "-o",
+        "--output-dir",
+        type=Path,
+        help="write one <video_id>.<format> file per video instead of printing (needed for several videos in a timed, SRT or VTT format)",
+    )
+    parser.add_argument("--api-key", help=f"API key (default: ${API_KEY_ENV})")
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    return parser
+
+
+def _extension(fmt: str) -> str:
+    return "txt" if fmt in ("text", "timed") else fmt
+
+
+def main(argv: Optional[List[str]] = None, client: Optional[Client] = None) -> int:
+    try:
+        return _run(argv, client)
+    except BrokenPipeError:
+        # Output piped into a command that stopped reading (e.g. `| head`): exit quietly.
+        devnull = os.open(os.devnull, os.O_WRONLY)
+        os.dup2(devnull, sys.stdout.fileno())
+        return 0
+
+
+def _run(argv: Optional[List[str]], client: Optional[Client]) -> int:
+    parser = _parser()
+    args = parser.parse_args(argv)
+
+    if args.format in TIMED_FORMATS and len(args.videos) > 1 and not args.output_dir:
+        parser.error(f"--output-dir is required to save {args.format} for more than one video")
+
+    if client is None:
+        api_key = args.api_key or os.environ.get(API_KEY_ENV)
+        if not api_key:
+            parser.error(f"no API key: pass --api-key or set {API_KEY_ENV} (get one at https://getyoutubetranscript.com)")
+        client = Client(api_key=api_key)
+
+    if args.output_dir:
+        args.output_dir.mkdir(parents=True, exist_ok=True)
+
+    failures = 0
+    json_results = []
+    for video in args.videos:
+        try:
+            data = client.get_transcript(
+                video, language=args.language, timestamps=args.format in TIMED_FORMATS or args.format == "json"
+            )
+        except GetYouTubeTranscriptError as e:
+            failures += 1
+            print(f"{video}: {e.message} ({e.code})", file=sys.stderr)
+            continue
+
+        if args.output_dir:
+            path = args.output_dir / f"{data['video_id']}.{_extension(args.format)}"
+            path.write_text(format_transcript(data, args.format), encoding="utf-8")
+            print(path, file=sys.stderr)
+        elif args.format == "json":
+            json_results.append(data)
+        else:
+            print(format_transcript(data, args.format))
+
+    if json_results:
+        print(to_json(json_results[0] if len(args.videos) == 1 else json_results))
+
+    return 1 if failures else 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

{getyoutubetranscript-0.2.2 → getyoutubetranscript-0.3.1}/src/getyoutubetranscript/client.py

@@ -184,9 +184,9 @@ class Client:
         Args:
             query: Search query. Required for a first page unless
                 ``page_token`` is given.
-            page_token: Continuation token from a previous response's
-                ``pagination.next_page_token``, to fetch the next page. Treat
-                as opaque - don't construct it yourself.
+            page_token: The ``continuation_token`` from a previous response,
+                to fetch the next page. Treat as opaque - don't construct it
+                yourself. Expires after 24 hours.
             type: Restrict results to ``"video"`` (default) or ``"channel"``.
                 Never mixes both kinds in one response.
             country: Two-letter region code, e.g. ``"us"``.
@@ -196,7 +196,8 @@ class Client:
         Returns:
             dict with ``query``, and either ``video_results`` or
             ``channel_results`` depending on ``type``, plus
-            ``pagination.next_page_token`` when more results are available.
+            ``continuation_token`` for the next page (missing or ``None`` when
+            there are no more pages, so read it with ``.get()``).
 
         Raises:
             ValueError: if neither ``query`` nor ``page_token`` is given.

getyoutubetranscript-0.3.1/src/getyoutubetranscript/formatters.py

@@ -0,0 +1,110 @@
+"""Turn a transcript from :meth:`Client.get_transcript` into text, timed text, JSON, SRT or WebVTT.
+
+    from getyoutubetranscript import Client
+    from getyoutubetranscript.formatters import to_srt
+
+    result = client.get_transcript("jNQXAC9IVRw", timestamps=True)
+    open("video.srt", "w", encoding="utf-8").write(to_srt(result))
+
+Timed text, SRT and WebVTT need per-line timing, so fetch with ``timestamps=True``.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Callable, Dict, List, Mapping
+
+from .types import Segment
+
+FORMATS = ("text", "timed", "json", "srt", "vtt")
+TIMED_FORMATS = ("timed", "srt", "vtt")
+
+
+def _segments(data: Mapping[str, Any]) -> List[Segment]:
+    segments = data.get("segments")
+    if not segments:
+        raise ValueError(
+            "This format needs per-line timing. Fetch the transcript with timestamps=True."
+        )
+    return segments
+
+
+def _clock(seconds: float, decimal_mark: str) -> str:
+    millis = max(0, int(round(seconds * 1000)))
+    hours, millis = divmod(millis, 3_600_000)
+    minutes, millis = divmod(millis, 60_000)
+    secs, millis = divmod(millis, 1000)
+    return f"{hours:02d}:{minutes:02d}:{secs:02d}{decimal_mark}{millis:03d}"
+
+
+def _cues(data: Mapping[str, Any], decimal_mark: str) -> List[str]:
+    cues = []
+    for segment in _segments(data):
+        start = float(segment["start"])
+        end = start + float(segment["duration"])
+        timing = f"{_clock(start, decimal_mark)} --> {_clock(end, decimal_mark)}"
+        cues.append(f"{timing}\n{segment['text'].strip()}")
+    return cues
+
+
+def to_text(data: Mapping[str, Any]) -> str:
+    """The transcript as one block of plain text."""
+    return data.get("transcript", "")
+
+
+def _player_time(seconds: float) -> str:
+    total = max(0, int(seconds))
+    hours, rest = divmod(total, 3600)
+    minutes, secs = divmod(rest, 60)
+    return f"{hours}:{minutes:02d}:{secs:02d}" if hours else f"{minutes}:{secs:02d}"
+
+
+def to_timed_text(data: Mapping[str, Any]) -> str:
+    """One ``[m:ss] text`` line per caption (``[h:mm:ss]`` past an hour). Needs ``segments``.
+
+    Easy for people and AI models to read and cite.
+    """
+    return "\n".join(f"[{_player_time(float(s['start']))}] {s['text'].strip()}" for s in _segments(data))
+
+
+def to_json(data: Mapping[str, Any], **json_kwargs: Any) -> str:
+    """The full result (metadata, transcript and any segments) as a JSON string."""
+    json_kwargs.setdefault("ensure_ascii", False)
+    json_kwargs.setdefault("indent", 2)
+    return json.dumps(data, **json_kwargs)
+
+
+def to_srt(data: Mapping[str, Any]) -> str:
+    """SubRip (.srt) subtitles. Needs ``segments`` (``timestamps=True``)."""
+    cues = _cues(data, ",")
+    return "\n\n".join(f"{index}\n{cue}" for index, cue in enumerate(cues, start=1)) + "\n"
+
+
+def to_vtt(data: Mapping[str, Any]) -> str:
+    """WebVTT (.vtt) subtitles. Needs ``segments`` (``timestamps=True``)."""
+    cues = [_escape_vtt_text(cue) for cue in _cues(data, ".")]
+    return "WEBVTT\n\n" + "\n\n".join(cues) + "\n"
+
+
+def _escape_vtt_text(cue: str) -> str:
+    # "-->" inside cue text would be read as a timing line, so escape it.
+    timing, _, text = cue.partition("\n")
+    return f"{timing}\n{text.replace('-->', '-->')}"
+
+
+_FORMATTERS: Dict[str, Callable[[Mapping[str, Any]], str]] = {
+    "text": to_text,
+    "timed": to_timed_text,
+    "json": to_json,
+    "srt": to_srt,
+    "vtt": to_vtt,
+}
+
+
+def format_transcript(data: Mapping[str, Any], fmt: str) -> str:
+    """Format a transcript as ``"text"``, ``"timed"``, ``"json"``, ``"srt"`` or ``"vtt"``."""
+    try:
+        formatter = _FORMATTERS[fmt]
+    except KeyError:
+        raise ValueError(f"Unknown format {fmt!r}. Choose one of: {', '.join(FORMATS)}.") from None
+    return formatter(data)

{getyoutubetranscript-0.2.2 → getyoutubetranscript-0.3.1}/tests/live/test_live_api.py

@@ -71,6 +71,18 @@ def test_search_live(client: Client):
     assert len(result["video_results"]) > 0
 
 
+def test_search_pagination_live(client: Client):
+    """The README pagination example: continuation_token goes back in as page_token."""
+    first_page = client.search("lofi beats", type="video", limit=10)
+    assert "pagination" not in first_page
+    token = first_page.get("continuation_token")
+    assert token, "first page should offer a next page"
+    page2 = client.search(page_token=token)
+    assert page2["video_results"]
+    first_titles = {v.get("title") for v in first_page["video_results"]}
+    assert not first_titles & {v.get("title") for v in page2["video_results"]}
+
+
 def test_get_credits_live(client: Client):
     """Free endpoint - safe to run often."""
     result = client.get_credits()

getyoutubetranscript-0.3.1/tests/test_cli.py

@@ -0,0 +1,93 @@
+"""Unit tests for the command line (client is faked, no network)."""
+
+from __future__ import annotations
+
+import json
+
+import pytest
+
+from getyoutubetranscript import GetYouTubeTranscriptError
+from getyoutubetranscript.cli import API_KEY_ENV, main
+
+SEGMENTS = [{"start": 0.0, "duration": 1.0, "text": "hi"}]
+
+
+class FakeClient:
+    def __init__(self, fail=()):
+        self.calls = []
+        self.fail = set(fail)
+
+    def get_transcript(self, video, *, language=None, timestamps=False):
+        self.calls.append({"video": video, "language": language, "timestamps": timestamps})
+        if video in self.fail:
+            raise GetYouTubeTranscriptError("NOT_FOUND", "No transcript for this video.", 404)
+        data = {"video_id": video, "language_code": language or "en", "transcript": f"text of {video}"}
+        if timestamps:
+            data["segments"] = SEGMENTS
+        return data
+
+
+def test_text_to_stdout_without_timestamps(capsys):
+    client = FakeClient()
+    assert main(["vid1"], client=client) == 0
+    assert capsys.readouterr().out == "text of vid1\n"
+    assert client.calls == [{"video": "vid1", "language": None, "timestamps": False}]
+
+
+def test_srt_requests_timestamps_and_passes_language(capsys):
+    client = FakeClient()
+    assert main(["vid1", "-f", "srt", "-l", "es"], client=client) == 0
+    assert capsys.readouterr().out == "1\n00:00:00,000 --> 00:00:01,000\nhi\n\n"
+    assert client.calls[0] == {"video": "vid1", "language": "es", "timestamps": True}
+
+
+def test_json_for_several_videos_is_one_list(capsys):
+    assert main(["a", "b", "-f", "json"], client=FakeClient()) == 0
+    out = json.loads(capsys.readouterr().out)
+    assert [item["video_id"] for item in out] == ["a", "b"]
+    assert out[0]["segments"] == SEGMENTS
+
+
+def test_output_dir_writes_one_file_per_video(tmp_path):
+    assert main(["a", "b", "-f", "vtt", "-o", str(tmp_path)], client=FakeClient()) == 0
+    assert sorted(p.name for p in tmp_path.iterdir()) == ["a.vtt", "b.vtt"]
+    assert (tmp_path / "a.vtt").read_text(encoding="utf-8").startswith("WEBVTT\n\n00:00:00.000")
+
+
+def test_timed_files_use_txt_extension(tmp_path):
+    assert main(["a", "-f", "timed", "-o", str(tmp_path)], client=FakeClient()) == 0
+    assert (tmp_path / "a.txt").read_text(encoding="utf-8") == "[0:00] hi"
+
+
+def test_several_srt_videos_need_output_dir(capsys):
+    with pytest.raises(SystemExit) as exit_info:
+        main(["a", "b", "-f", "srt"], client=FakeClient())
+    assert exit_info.value.code == 2
+    assert "--output-dir" in capsys.readouterr().err
+
+
+def test_keeps_going_after_a_failure_and_exits_1(capsys):
+    assert main(["bad", "good"], client=FakeClient(fail={"bad"})) == 1
+    captured = capsys.readouterr()
+    assert captured.out == "text of good\n"
+    assert "bad: No transcript for this video. (NOT_FOUND)" in captured.err
+
+
+def test_missing_api_key_is_a_usage_error(monkeypatch, capsys):
+    monkeypatch.delenv(API_KEY_ENV, raising=False)
+    with pytest.raises(SystemExit) as exit_info:
+        main(["vid1"])
+    assert exit_info.value.code == 2
+    assert API_KEY_ENV in capsys.readouterr().err
+
+
+def test_pipe_closed_early_exits_quietly(monkeypatch, tmp_path):
+    import getyoutubetranscript.cli as cli
+
+    def broken_pipe(*args, **kwargs):
+        raise BrokenPipeError
+
+    monkeypatch.setattr(cli, "_run", broken_pipe)
+    out = (tmp_path / "out").open("w")
+    monkeypatch.setattr("sys.stdout", out)
+    assert cli.main(["vid1"]) == 0

getyoutubetranscript-0.3.1/tests/test_formatters.py

@@ -0,0 +1,73 @@
+"""Unit tests for the transcript formatters (no network)."""
+
+from __future__ import annotations
+
+import json
+
+import pytest
+
+from getyoutubetranscript import format_transcript, to_json, to_srt, to_text, to_timed_text, to_vtt
+
+DATA = {
+    "video_id": "abc12345678",
+    "language_code": "en",
+    "title": "A video",
+    "author_name": "A channel",
+    "transcript": "hello world. café --> next",
+    "word_count": 5,
+    "segments": [
+        {"start": 0.0, "duration": 2.5, "text": "hello world."},
+        {"start": 1.9996, "duration": 1.0, "text": "café --> next"},
+        {"start": 3725.25, "duration": 4.0, "text": " an hour in "},
+    ],
+}
+NO_SEGMENTS = {k: v for k, v in DATA.items() if k != "segments"}
+
+
+def test_text_is_the_plain_transcript():
+    assert to_text(DATA) == "hello world. café --> next"
+    assert to_text(NO_SEGMENTS) == "hello world. café --> next"
+
+
+def test_timed_text_uses_player_clock():
+    assert to_timed_text(DATA).splitlines() == [
+        "[0:00] hello world.",
+        "[0:01] café --> next",
+        "[1:02:05] an hour in",
+    ]
+
+
+def test_srt_cues_numbering_and_rounding():
+    assert to_srt(DATA) == (
+        "1\n00:00:00,000 --> 00:00:02,500\nhello world.\n\n"
+        # 1.9996s rounds to 2.000s, never "00:00:01,1000"
+        "2\n00:00:02,000 --> 00:00:03,000\ncafé --> next\n\n"
+        "3\n01:02:05,250 --> 01:02:09,250\nan hour in\n"
+    )
+
+
+def test_vtt_header_dot_millis_and_escaped_arrow():
+    assert to_vtt(DATA) == (
+        "WEBVTT\n\n"
+        "00:00:00.000 --> 00:00:02.500\nhello world.\n\n"
+        "00:00:02.000 --> 00:00:03.000\ncafé --> next\n\n"
+        "01:02:05.250 --> 01:02:09.250\nan hour in\n"
+    )
+
+
+def test_json_round_trips_and_keeps_unicode():
+    out = to_json(DATA)
+    assert json.loads(out) == DATA
+    assert "café" in out
+
+
+@pytest.mark.parametrize("fn", [to_srt, to_vtt, to_timed_text])
+def test_timed_formats_explain_missing_segments(fn):
+    with pytest.raises(ValueError, match="timestamps=True"):
+        fn(NO_SEGMENTS)
+
+
+def test_format_transcript_dispatches_and_rejects_unknown():
+    assert format_transcript(DATA, "srt") == to_srt(DATA)
+    with pytest.raises(ValueError, match="Unknown format"):
+        format_transcript(DATA, "docx")