YouTube Transcript Scraper

Retrieve captions from public YouTube videos without customer authentication or browser automation. Results are saved to the default dataset; videos without available captions are reported as item errors and do not create transcript charges.

The Actor supports watch, shorts, live, embed, and youtu.be URLs. It can return plain text, timestamped segments, SRT, or VTT and can optionally include the title, channel, and publication date returned by YouTube.

Input

Provide urls (one or more YouTube video URLs). Optional settings are languages (priority-ordered language codes, default en), output_format (text, segments, srt, or vtt), include_metadata, concurrency from 1 to 20, max_run_seconds from 1 to 3600, and an HTTP proxy_url.

Example:

{
  "urls": ["https://www.youtube.com/watch?v=dQw4w9WgXcQ"],
  "languages": ["en"],
  "output_format": "segments",
  "include_metadata": true
}

Output and pricing

Each successful dataset item contains the video ID, selected language, output format, transcript, and one transcript billing event. The Actor also records a memory-scaled apify-actor-start event for each run. Invalid, unavailable, captionless, blocked, and failed videos are returned as error items and carry no transcript event. Duplicate video IDs are processed once per run.

YouTube's public caption and player endpoints are undocumented and may change. Some videos may require a proxy, may be blocked for datacenter traffic, or may not expose captions. Age-restricted and private videos are not authenticated.

Functional input contract

Call scrape_transcripts(ScrapeInput(...)) with:

• urls: one or more YouTube watch, short, live, embed, or youtu.be URLs;
• languages: language codes in priority order (default en);
• output_format: text, segments, srt, or vtt;
• include_metadata: include title, channel, and publication date when available;
• concurrency: 1–20 (default 5);
• max_run_seconds: 1–3600 (default 900);
• proxy_url: optional HTTP proxy URL supplied by the platform adapter.

Duplicate video IDs are processed once so a successful video cannot produce duplicate output or duplicate transcript charges within a batch.

Functional output and billing contract

The returned object has results and errors arrays. Every successful result contains the video identity, selected language, requested transcript format, and exactly one {event: "transcript", quantity: 1} billing signal. Invalid, unavailable, captionless, blocked, and failed videos appear only in errors and never carry that signal. One video's failure does not stop the batch.

start_billable_events(memory_mb) emits the separate apify-actor-start signal: one event per configured GiB, rounded up, with a minimum of one. Deploy owns the mapping of these neutral signals to Apify charging and dataset operations.

Development verification

PYTHONPATH=src python3 -m unittest discover -s tests -v