YouTube Video Transcriber

An Apify actor that extracts full transcripts from YouTube videos of any length.

Features

• Supports any video length — no limits
• Dual transcription strategy:
  1. YouTube captions (primary) — instant, free, no API key needed
  2. OpenAI Whisper (fallback) — works even when captions are disabled or unavailable
• Accepts URLs in any format: youtube.com/watch?v=, youtu.be/, /shorts/, /live/, bare video IDs
• Multiple output formats: plain text, JSON segments, SRT, WebVTT
• Optional timestamp injection in plain-text output
• Optional chunking of very long transcripts into smaller dataset items
• Batch processing: pass multiple URLs in one run

---

Input

Field	Type	Default	Description
videoUrls	string[]	required	YouTube video URLs or bare video IDs
preferredLanguage	string	"en"	BCP-47 language code (e.g. "es", "fr")
transcriptMethod	string	"auto"	"auto" | "captions" | "whisper"
openaiApiKey	string	—	OpenAI API key (required for Whisper)
whisperModel	string	"whisper-1"	Whisper model ID
outputFormat	string	"text"	"text" | "json" | "srt" | "vtt"
includeTimestamps	boolean	false	Prepend [HH:MM:SS] to each line in text output
chunkLongTranscripts	boolean	false	Split output into multiple dataset items
chunkSizeTokens	integer	2000	Target words per chunk
proxyConfiguration	object	—	Apify proxy or custom proxy settings

Example input (JSON)

{
  "videoUrls": [
    "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "https://youtu.be/9bZkp7q19f0"
  ],
  "preferredLanguage": "en",
  "transcriptMethod": "auto",
  "openaiApiKey": "sk-...",
  "outputFormat": "text",
  "includeTimestamps": false
}

---

Output

Each video produces one dataset item (or multiple if chunking is enabled):

{
  "videoUrl": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "videoId": "dQw4w9WgXcQ",
  "status": "success",
  "transcriptSource": "captions",
  "language": "en",
  "segmentCount": 312,
  "durationSec": 3842,
  "outputFormat": "text",
  "transcript": "We're no strangers to love..."
}

On error:

{
  "videoUrl": "https://www.youtube.com/watch?v=INVALID",
  "videoId": "INVALID",
  "status": "error",
  "error": "Could not fetch captions for video INVALID: ..."
}

---

Transcript Methods Explained

auto (recommended)

Tries YouTube captions first. If none are available (disabled, private, etc.), automatically falls back to downloading the audio and running it through OpenAI Whisper. Requires openaiApiKey only if the fallback is triggered.

captions

Only uses YouTube's built-in caption/subtitle track. Fastest and free — but fails on videos without captions.

whisper

Always downloads the audio and transcribes via Whisper. Works on any video but consumes OpenAI API credits. Large videos are automatically split into ≤24 MB chunks, transcribed in order, and the results are merged seamlessly.

---

Long Video Support

Method	How long videos are handled
Captions	YouTube delivers the entire caption track in one request — no size limit
Whisper	Audio is downloaded once, then split into ≤24 MB mp3 chunks. Each chunk is transcribed with proper time offsets so the final transcript is seamless

---

Local Development

npm install
# Set environment variables
export APIFY_TOKEN=your_token   # optional for local runs
# Create input.json (see example above)
node src/main.js

The actor uses the Apify SDK and reads input from ./storage/key_value_stores/default/INPUT.json when run locally without the apify-cli.

Using the Apify CLI:

npm install -g apify-cli
apify login
apify run          # uses .actor/input_schema.json prefill values

---

Dependencies

Package	Purpose
apify	Actor SDK (dataset, KV store, proxy, logging)
youtube-transcript	Fetch YouTube caption tracks
ytdl-core	Download YouTube audio stream
fluent-ffmpeg + @ffmpeg-installer/ffmpeg	Convert/split audio for Whisper
openai	OpenAI Whisper API client

---

License

MIT