transcript.py

"""
YouTube Transcript - Chocodata YouTube Transcript Scraper API

Runnable example. It calls the LIVE API and prints the real JSON response.

    pip install requests
    export CHOCODATA_API_KEY="your_key"      # free: 1,000 requests, one-time
    python youtube_transcript_scraper_api_codes/transcript.py

Docs: https://chocodata.com/docs
"""
import json
import os
import sys

import requests

API = "https://api.chocodata.com/api/v1/youtube/transcript"
KEY = os.environ.get("CHOCODATA_API_KEY")

if not KEY:
    sys.exit("Set CHOCODATA_API_KEY first. Free key (1,000 requests, one-time): https://chocodata.com")


def _check(r) -> None:
    """Map the API's documented statuses onto actionable messages instead of a traceback."""
    if r.status_code == 400:
        sys.exit(f"400 invalid_params: {r.text[:200]}")
    if r.status_code == 401:
        sys.exit("401 INVALID_API_KEY: key missing or not recognised. Get one: https://chocodata.com")
    if r.status_code == 402:
        sys.exit("402 INSUFFICIENT_CREDITS: balance exhausted. Top up or upgrade: https://chocodata.com/pricing")
    if r.status_code == 429:
        sys.exit("429 RATE_LIMITED: over 120 requests/60s or your plan's concurrency. Back off and retry.")
    if r.status_code == 502:
        sys.exit("502: YouTube did not return the caption data for this request. "
                 "Retryable, and you were not charged.")
    r.raise_for_status()


def transcript(video, lang="en", fmt="both", units="seconds") -> dict:
    """One video's transcript: segments with timestamps, plain text, and metadata."""
    params = {"api_key": KEY, "lang": lang, "format": fmt, "units": units}
    # Accept an 11-char id or any URL form; send whichever the caller passed.
    params["url" if "/" in video or "?" in video else "video_id"] = video
    r = requests.get(API, params=params, timeout=90)
    _check(r)
    return r.json()


if __name__ == "__main__":
    # "But what is a neural network?" by 3Blue1Brown: a human (not auto-generated)
    # English transcript with 30+ available languages.
    data = transcript("aircAruvnKk")

    if not data.get("transcript_available"):
        print(json.dumps(data, indent=2, ensure_ascii=False))
        sys.exit(f"No transcript: reason = {data.get('reason')}")

    # segments[] is long; print the metadata and the first few rows only. The
    # committed sample trims segments too and says so.
    head = {k: v for k, v in data.items() if k not in ("segments", "text")}
    print(json.dumps(head, indent=2, ensure_ascii=False))
    print()
    for seg in data.get("segments", [])[:6]:
        stamp = f'{seg["start"]:>8.3f}s' if seg["start"] is not None else "     ?  "
        print(f'  {stamp}  {seg["text"]}')
    print("  ...")
    print()
    print(f'{data["language_name"]} '
          f'({"auto-generated" if data["is_generated"] else "human"}), '
          f'{data["segment_count"]} segments, {data["word_count"]} words.')