fetchworks-youtube-transcript

YouTube transcripts for Node.js and TypeScript — timestamped segments, plain text, SRT, and VTT from videos, Shorts, channels, playlists, and search results.

This is a thin, zero-dependency client for the Fetchworks YouTube Transcript Scraper on Apify. The extraction runs on Apify's infrastructure; you bring your own Apify token. Pricing is $2 per 1,000 transcripts — only delivered transcripts are billed. Failed videos (no captions, blocked, unavailable) cost nothing.

Install

npm install fetchworks-youtube-transcript

Quickstart

import { FetchworksClient } from "fetchworks-youtube-transcript";

const client = new FetchworksClient({ apifyToken: process.env.APIFY_TOKEN! });
const item = await client.getTranscript("https://www.youtube.com/watch?v=jNQXAC9IVRw");
console.log(item.status); // "ok"
console.log(item.text);   // "All right, so here we are…"

Get a token by signing up at apify.com (free tier included), then copy it from console.apify.com/settings/integrations.

API

All methods return dataset items in the exact shape the actor emits — including an honest per-video status (ok, no_captions, blocked, live_stream, age_restricted, unavailable, translation_unavailable, po_token_required, error). A video without captions comes back as an item with status: "no_captions", never a silent empty transcript.

// One video (URL, Shorts/youtu.be/embed URL, or bare 11-char ID)
const item = await client.getTranscript("jNQXAC9IVRw", { languages: ["en", "de"] });

// A batch of videos
const items = await client.getTranscripts(["url1", "url2"], { outputFormats: ["text", "srt"] });

// A channel's uploads, newest first
const uploads = await client.getChannelTranscripts("@3blue1brown", { maxVideosPerChannel: 25 });

// A playlist
const playlist = await client.getPlaylistTranscripts("PLZHQObOWTQDMsr9K-rj53DwVRMYO3t5Yr");

// Top results for a YouTube search
const results = await client.search("neural networks explained", { maxSearchResults: 10 });

Jobs expected to cover fewer than 60 videos run on Apify's synchronous endpoint and return in seconds. Larger jobs (big batches, whole channels, playlists) start an actor run and poll until it finishes — no code change needed on your side.

Options

Every method accepts an options object mirroring the actor input:

| Option | Type | Default | Description | | --- | --- | --- | --- | | languages | string[] | ["en"] | Language priority list (ISO codes). First available caption track wins; the item reports the actual language used. | | preferAutoGenerated | boolean | false | Prefer auto-generated (ASR) tracks when a manual track also exists. | | translateTo | string | — | Target language for YouTube caption auto-translation. Best-effort; failures come back as translation_unavailable and are not billed. | | outputFormats | ("segments" \| "text" \| "srt" \| "vtt")[] | ["segments", "text"] | Transcript representations to include on each item. | | includeMetadata | boolean | true | Include title, channel, duration, views, publish date, etc. Free. | | includeChapters | boolean | false | Include video chapters (one extra request per video). | | maxVideosPerChannel | number | 100 | Channel method only: upper bound on videos taken, newest first. | | maxSearchResults | number | 50 | Search method only: upper bound on videos taken per query. |

Client-level options: baseUrl, pollIntervalMs (default 3000), maxWaitMs (default 30 min).

Result shape

{
  videoId: "jNQXAC9IVRw",
  url: "https://www.youtube.com/watch?v=jNQXAC9IVRw",
  status: "ok",
  language: "en",
  isAutoGenerated: false,
  availableLanguages: [{ languageCode: "en", kind: "manual", name: "English" }],
  segments: [{ start: 1.3, dur: 3.4, text: "All right, so here we are" }],
  text: "All right, so here we are…",
  srt: "…",   // when requested
  vtt: "…",   // when requested
  metadata: { title: "Me at the zoo", author: "jawed", lengthSeconds: 19, /* … */ }
}

Links

• Actor page and pricing: https://apify.com/fetchworks/youtube-transcript-scraper
• Apify API tokens: https://console.apify.com/settings/integrations

License

MIT