# YouTube Transcript Master \[EASY] (WebVTT & more) (`zerohour/yt-transcript`) Actor
YouTube Transcripts in BULK! Easily query via channel, playlist, or video URLs. Built with simplicity & reliability in mind, with expert support. Perfect data to feed your AI or LLM. Output multiple formats: TEXT, JSON, SRV, TTML, VTT (WebVTT). Automatic YouTube captions are available as backup.
- **URL**: https://apify.com/zerohour/yt-transcript.md
- **Developed by:** [Zerohour](https://apify.com/zerohour) (community)
- **Categories:** SEO tools, Videos, AI
- **Stats:** 119 total users, 4 monthly users, 100.0% runs succeeded, 4 bookmarks
- **User rating**: No ratings yet
## Pricing
$37.50/month + usage
To use this Actor, you pay a monthly rental fee to the developer. The rent is subtracted from your prepaid usage every month after the free trial period.You also pay for the Apify platform usage, which gets cheaper the higher Apify subscription plan you have.
Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#rental-actors
## What's an Apify Actor?
Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".
## How to integrate an Actor?
If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.
In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md):
```bash
npm install apify-client
```
In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md):
```bash
pip install apify-client
```
In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md):
````bash
# MacOS / Linux
curl -fsSL https://apify.com/install-cli.sh | bash
# Windows
irm https://apify.com/install-cli.ps1 | iex
```bash
In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md).
If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md).
For usage examples, see the [API](#api) section below.
For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).
# README
## 📜 YouTube Transcript Master
This Actor extracts transcripts from YouTube videos a mix of sources like: channel URLs, or playlist URLs, and video URLs. It fetches video metadata (title, duration, upload date) and transcripts in specified formats and languages.
⭐ **Paying users will enjoy recieve quick responses messages, expert support for issues, as well as feature or Actor requests**
*Why the high price?*
*This a robust Actor built for high volume and bulk dataset for long term use cases. This way I can support the long term users of this Actor more effectively rather than on a "per result" basis. If you would like you may try the lite version of this Actor here: [YouTube Transcript Master [Lite]](https://apify.com/zerohour/yt-transcript-lite)*
---
🌟 Features
* Retrieve **transcripts in bulk** with a mix of inputs like: YouTube channels, playlists, or individual video links.
* Extracts video title, duration, and upload date.
* Fetches transcripts in **multiple formats** (Plain Text, JSON, VTT, TTML, etc.).
* Supports specifying the desired transcript **language**.
* Uses **efficient** HTML scraping minimizing CPU usage.
* Includes enhanced retry logic for network requests to improve **reliability**.
* Optionally uses Apify's residential proxies for **consistent results**.
---
📊 Usage & Estimated Costs
Understanding the potential costs associated with running this Actor is important. Below is an example based on a **test run processing `500` videos** to retrieve **`plainText` transcripts**. Please note that actual costs can vary based on several factors.
**Test Run Statistics:**
* Videos Processed: **500**
* Transcript Format Requested: **`plainText`**
* Total Combined Video Length: **~380 hours**
* Average Video Length: **~45 minutes**
* Success Rate: **100%** (0 missed results or errors)
##### Estimated Cost Breakdown (according to test run):
| Cost Category | Estimated Cost | Notes |
| :-------------------- | :------------- | :-------------------------------------------------------------------- |
| Actor Compute Units | $1.358 | Cost for the server resources used to run the Actor's code. |
| Proxy (Residential) | $1.194 | Cost for using Apify's residential proxies to avoid blocks by YouTube. |
| Other (Platform Fees) | $0.004 | Minimal platform usage fees. |
| **Total Estimated Cost** | **$2.56** | |
**Factors Influencing Costs:**
* **Number of Videos:** The primary driver of cost. More videos mean longer compute time and potentially more proxy usage.
* **Transcript Formats:** Requesting multiple formats per video *might* slightly increase compute time and proxy usage if different underlying fetches are needed.
* **Proxy Usage:** Disabling the proxy (`useApifyProxy: false`) eliminates proxy costs but significantly increases the risk of being blocked by YouTube, leading to failed runs and potentially higher compute costs due to retries or incomplete runs. **Using the proxy is highly recommended.**
**Important Considerations:**
* The costs shown are **estimates** based on a specific run and current Apify pricing. Your actual costs may differ.
* While the Actor includes robust error handling and retries, occasional failures for specific videos (due to missing transcripts, YouTube errors, private videos, or persistent proxy issues) can still occur. Check the output dataset's `error` field and Actor logs for details on any failed items.
---
The actor takes a JSON object as input with the following properties:
| Field | Type | Description | Required | Default |
| :------------------- | :-------- | :------------------------------------------------------------------------------------------------------------------------------------------ | :------- | :------------------------------------------------------------------------------------------------------ |
| `sources` | `Array` | A list of YouTube URLs. Can include video URLs (`watch?v=`), playlist URLs (`playlist?list=`), or channel URLs (`@handle`, `/c/`, `/user/`). | Yes | `[]` |
| `formats` | `Object` | Specifies which transcript formats to retrieve. Set the desired format key(s) to `true`. | No | `{ "plainText": true, "json": false, "json3": false, "srv1": false, "srv2": false, "srv3": false, "ttml": false, "vtt": false }` |
| `language` | `String` | The two-letter language code for the desired transcript (e.g., `en`, `es`, `de`). | No | `"en"` |
| `useApifyProxy` | `Boolean` | If `true`, uses Apify's residential proxies for fetching. Highly recommended to avoid blocks. If `false`, uses the container's direct IP. | No | `true` |
| `delayBetweenVideos` | `Integer` | An optional delay in milliseconds to wait between processing each video. Useful for mitigating rate limits on very large lists. | No | `0` |
#### Input Example
```json
{
"sources": [
"https://www.youtube.com/watch?v=b_nep8vMnkc",
"https://www.youtube.com/@Apify",
"https://www.youtube.com/playlist?list=PLObrtcm1Kw6PEnu5BpeEFb8XEoQXMw0g7"
],
"formats": {
"plainText": true, // Get one or many formats
"json": true,
"json3": false,
"srv1": false,
"srv2": false,
"srv3": false,
"ttml": false,
"vtt": false
},
"language": "en", // Two letter language codes: 'es', 'fr', 'pl', etc.
"useApifyProxy": true,
"delayBetweenVideos": 0 // Milliseconds
}
````
***
📥 Output
The actor outputs data to the default Apify dataset. Each item in the dataset represents a processed video and has the following structure:
| Field | Type | Description |
| :---------- | :-------------- | :---------------------------------------------------------------------------------------------- |
| `url` | `String` | The original YouTube video URL processed. |
| `language` | `String` | The language code requested for the transcript. |
| `title` | `String` | The title of the video (`N/A` or 'Processing Error' if extraction failed). |
| `duration` | `Integer` | The duration of the video in seconds (`0` or `-1` if extraction failed). |
| `videoLink` | `String` | Same as `url`, provided for convenience. |
| `uploadDate`| `String`|`null` | The publication date of the video (YYYY-MM-DD format), if found. |
| `text` | `String`|`null` | The plain text transcript, if requested and found (with improved handling for `\"`). |
| `json` | `Array`|`null` | Structured JSON transcript (start, duration, text per segment), if requested and found. |
| `json3` | `Object`|`null` | The raw JSON3 format transcript, if requested and found. |
| `srv1` | `String`|`null` | The raw SRV1 (XML) format transcript, if requested and found. |
| `srv2` | `String`|`null` | The raw SRV2 (XML) format transcript, if requested and found. |
| `srv3` | `String`|`null` | The raw SRV3 (XML) format transcript, if requested and found. |
| `ttml` | `String`|`null` | The raw TTML format transcript, if requested and found. |
| `vtt` | `String`|`null` | The raw VTT format transcript, if requested and found. |
| `error` | `String`|`null` | An error message if processing the video or fetching transcripts failed for this video. |
| `details` | `String`|`null` | Additional error details (like HTTP status code or stack trace) if an error occurred. |
#### Output Example (Success - plainText & json requested)
```json
{
"url": "https://www.youtube.com/watch?v=b_nep8vMnkc",
"language": "en",
"title": "Example Video Title",
"duration": 123,
"videoLink": "https://www.youtube.com/watch?v=b_nep8vMnkc",
"uploadDate": "2023-10-27",
"text": "This is the extracted plain text transcript...",
"json": [
{ "text": "Segment 1 text", "start": 0.5, "dur": 3.2 },
{ "text": "Segment 2 text", "start": 3.7, "dur": 2.8 }
],
"json3": null,
"srv1": null,
"srv2": null,
"srv3": null,
"ttml": null,
"vtt": null,
"error": null,
"details": null
}
```
#### Output Example (Failure - general processing error)
```json
{
"url": "https://www.youtube.com/watch?v=invalidVideoId",
"language": "en",
"title": "Processing Error",
"duration": -1,
"videoLink": "https://www.youtube.com/watch?v=invalidVideoId",
"uploadDate": null,
"text": null,
"json": null,
"json3": null,
"srv1": null,
"srv2": null,
"srv3": null,
"ttml": null,
"vtt": null,
"error": "Failed to process: Failed to extract valid playerResponse from HTML after 2 attempts.",
"details": "Error: Failed to extract valid playerResponse from HTML after 2 attempts.\n at processVideos (/actor/main.js:497:23)\n at ..."
}
```
***
📝 Usage Notes
- **Recent Uploads:** Recently upload videos may not have transcripts right away.
- **Private or Deleted Videos:** Keep in mind these videos will result in errors.
- **Live Streams:** Processing live or upcoming streams may result in errors or incomplete data, as the necessary transcript information might not be available.
- **Large Transcripts & Multiple Formats:** Apify has a 9.4mb limit for each item (transcript), keep this in mind when using multiple formats and large transcripts.
***
💬 Support
If you encounter issues or have questions, contact me @ https://x.com/t\_zerohour.
***
# Actor input Schema
## `sources` (type: `array`):
List of YouTube channels, playlists, and/or video URLs
## `formats` (type: `object`):
Select which transcript formats you want to retrieve, 'true' will return desired format
## `language` (type: `string`):
Two-letter language code (e.g., 'en' for English, 'es' for Spanish)
## `proxyConfiguration` (type: `object`):
Configure the proxies used for making requests.
## `delayBetweenVideos` (type: `integer`):
Delay between processing videos in milliseconds
## Actor input object example
```json
{
"sources": [
"https://www.youtube.com/watch?v=b_nep8vMnkc&pp=ygULYXBpZnkgaW50cm8%3D"
],
"formats": {
"plainText": true,
"json": false,
"json3": false,
"srv1": false,
"srv2": false,
"srv3": false,
"ttml": false,
"vtt": false
},
"language": "en",
"proxyConfiguration": {
"useApifyProxy": true,
"apifyProxyGroups": [
"RESIDENTIAL"
]
},
"delayBetweenVideos": 0
}
```
# API
You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.
## JavaScript example
```javascript
import { ApifyClient } from 'apify-client';
// Initialize the ApifyClient with your Apify API token
// Replace the '' with your token
const client = new ApifyClient({
token: '',
});
// Prepare Actor input
const input = {
"sources": [
"https://www.youtube.com/watch?v=b_nep8vMnkc&pp=ygULYXBpZnkgaW50cm8%3D"
],
"formats": {
"plainText": true,
"json": false,
"json3": false,
"srv1": false,
"srv2": false,
"srv3": false,
"ttml": false,
"vtt": false
},
"proxyConfiguration": {
"useApifyProxy": true,
"apifyProxyGroups": [
"RESIDENTIAL"
]
}
};
// Run the Actor and wait for it to finish
const run = await client.actor("zerohour/yt-transcript").call(input);
// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
console.dir(item);
});
// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs
```
## Python example
```python
from apify_client import ApifyClient
# Initialize the ApifyClient with your Apify API token
# Replace '' with your token.
client = ApifyClient("")
# Prepare the Actor input
run_input = {
"sources": ["https://www.youtube.com/watch?v=b_nep8vMnkc&pp=ygULYXBpZnkgaW50cm8%3D"],
"formats": {
"plainText": True,
"json": False,
"json3": False,
"srv1": False,
"srv2": False,
"srv3": False,
"ttml": False,
"vtt": False,
},
"proxyConfiguration": {
"useApifyProxy": True,
"apifyProxyGroups": ["RESIDENTIAL"],
},
}
# Run the Actor and wait for it to finish
run = client.actor("zerohour/yt-transcript").call(run_input=run_input)
# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
print(item)
# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start
```
## CLI example
```bash
echo '{
"sources": [
"https://www.youtube.com/watch?v=b_nep8vMnkc&pp=ygULYXBpZnkgaW50cm8%3D"
],
"formats": {
"plainText": true,
"json": false,
"json3": false,
"srv1": false,
"srv2": false,
"srv3": false,
"ttml": false,
"vtt": false
},
"proxyConfiguration": {
"useApifyProxy": true,
"apifyProxyGroups": [
"RESIDENTIAL"
]
}
}' |
apify call zerohour/yt-transcript --silent --output-dataset
```
## MCP server setup
```json
{
"mcpServers": {
"apify": {
"command": "npx",
"args": [
"mcp-remote",
"https://mcp.apify.com/?tools=zerohour/yt-transcript",
"--header",
"Authorization: Bearer "
]
}
}
}
```
## OpenAPI specification
```json
{
"openapi": "3.0.1",
"info": {
"title": "YouTube Transcript Master [EASY] (WebVTT & more)",
"description": "YouTube Transcripts in BULK! Easily query via channel, playlist, or video URLs. Built with simplicity & reliability in mind, with expert support. Perfect data to feed your AI or LLM. Output multiple formats: TEXT, JSON, SRV, TTML, VTT (WebVTT). Automatic YouTube captions are available as backup.",
"version": "0.0",
"x-build-id": "J1gwyM8rJ9oAn4FDs"
},
"servers": [
{
"url": "https://api.apify.com/v2"
}
],
"paths": {
"/acts/zerohour~yt-transcript/run-sync-get-dataset-items": {
"post": {
"operationId": "run-sync-get-dataset-items-zerohour-yt-transcript",
"x-openai-isConsequential": false,
"summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
"tags": [
"Run Actor"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inputSchema"
}
}
}
},
"parameters": [
{
"name": "token",
"in": "query",
"required": true,
"schema": {
"type": "string"
},
"description": "Enter your Apify token here"
}
],
"responses": {
"200": {
"description": "OK"
}
}
}
},
"/acts/zerohour~yt-transcript/runs": {
"post": {
"operationId": "runs-sync-zerohour-yt-transcript",
"x-openai-isConsequential": false,
"summary": "Executes an Actor and returns information about the initiated run in response.",
"tags": [
"Run Actor"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inputSchema"
}
}
}
},
"parameters": [
{
"name": "token",
"in": "query",
"required": true,
"schema": {
"type": "string"
},
"description": "Enter your Apify token here"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/runsResponseSchema"
}
}
}
}
}
}
},
"/acts/zerohour~yt-transcript/run-sync": {
"post": {
"operationId": "run-sync-zerohour-yt-transcript",
"x-openai-isConsequential": false,
"summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
"tags": [
"Run Actor"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inputSchema"
}
}
}
},
"parameters": [
{
"name": "token",
"in": "query",
"required": true,
"schema": {
"type": "string"
},
"description": "Enter your Apify token here"
}
],
"responses": {
"200": {
"description": "OK"
}
}
}
}
},
"components": {
"schemas": {
"inputSchema": {
"type": "object",
"required": [
"sources",
"proxyConfiguration"
],
"properties": {
"sources": {
"title": "YouTube Sources",
"type": "array",
"description": "List of YouTube channels, playlists, and/or video URLs",
"items": {
"type": "string"
}
},
"formats": {
"title": "Transcript Formats",
"type": "object",
"description": "Select which transcript formats you want to retrieve, 'true' will return desired format"
},
"language": {
"title": "Transcript Language",
"minLength": 2,
"maxLength": 2,
"type": "string",
"description": "Two-letter language code (e.g., 'en' for English, 'es' for Spanish)",
"default": "en"
},
"proxyConfiguration": {
"title": "Proxy configuration",
"type": "object",
"description": "Configure the proxies used for making requests."
},
"delayBetweenVideos": {
"title": "Delay Between Videos (ms)",
"minimum": 0,
"maximum": 30000,
"type": "integer",
"description": "Delay between processing videos in milliseconds",
"default": 0
}
}
},
"runsResponseSchema": {
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"actId": {
"type": "string"
},
"userId": {
"type": "string"
},
"startedAt": {
"type": "string",
"format": "date-time",
"example": "2025-01-08T00:00:00.000Z"
},
"finishedAt": {
"type": "string",
"format": "date-time",
"example": "2025-01-08T00:00:00.000Z"
},
"status": {
"type": "string",
"example": "READY"
},
"meta": {
"type": "object",
"properties": {
"origin": {
"type": "string",
"example": "API"
},
"userAgent": {
"type": "string"
}
}
},
"stats": {
"type": "object",
"properties": {
"inputBodyLen": {
"type": "integer",
"example": 2000
},
"rebootCount": {
"type": "integer",
"example": 0
},
"restartCount": {
"type": "integer",
"example": 0
},
"resurrectCount": {
"type": "integer",
"example": 0
},
"computeUnits": {
"type": "integer",
"example": 0
}
}
},
"options": {
"type": "object",
"properties": {
"build": {
"type": "string",
"example": "latest"
},
"timeoutSecs": {
"type": "integer",
"example": 300
},
"memoryMbytes": {
"type": "integer",
"example": 1024
},
"diskMbytes": {
"type": "integer",
"example": 2048
}
}
},
"buildId": {
"type": "string"
},
"defaultKeyValueStoreId": {
"type": "string"
},
"defaultDatasetId": {
"type": "string"
},
"defaultRequestQueueId": {
"type": "string"
},
"buildNumber": {
"type": "string",
"example": "1.0.0"
},
"containerUrl": {
"type": "string"
},
"usage": {
"type": "object",
"properties": {
"ACTOR_COMPUTE_UNITS": {
"type": "integer",
"example": 0
},
"DATASET_READS": {
"type": "integer",
"example": 0
},
"DATASET_WRITES": {
"type": "integer",
"example": 0
},
"KEY_VALUE_STORE_READS": {
"type": "integer",
"example": 0
},
"KEY_VALUE_STORE_WRITES": {
"type": "integer",
"example": 1
},
"KEY_VALUE_STORE_LISTS": {
"type": "integer",
"example": 0
},
"REQUEST_QUEUE_READS": {
"type": "integer",
"example": 0
},
"REQUEST_QUEUE_WRITES": {
"type": "integer",
"example": 0
},
"DATA_TRANSFER_INTERNAL_GBYTES": {
"type": "integer",
"example": 0
},
"DATA_TRANSFER_EXTERNAL_GBYTES": {
"type": "integer",
"example": 0
},
"PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
"type": "integer",
"example": 0
},
"PROXY_SERPS": {
"type": "integer",
"example": 0
}
}
},
"usageTotalUsd": {
"type": "number",
"example": 0.00005
},
"usageUsd": {
"type": "object",
"properties": {
"ACTOR_COMPUTE_UNITS": {
"type": "integer",
"example": 0
},
"DATASET_READS": {
"type": "integer",
"example": 0
},
"DATASET_WRITES": {
"type": "integer",
"example": 0
},
"KEY_VALUE_STORE_READS": {
"type": "integer",
"example": 0
},
"KEY_VALUE_STORE_WRITES": {
"type": "number",
"example": 0.00005
},
"KEY_VALUE_STORE_LISTS": {
"type": "integer",
"example": 0
},
"REQUEST_QUEUE_READS": {
"type": "integer",
"example": 0
},
"REQUEST_QUEUE_WRITES": {
"type": "integer",
"example": 0
},
"DATA_TRANSFER_INTERNAL_GBYTES": {
"type": "integer",
"example": 0
},
"DATA_TRANSFER_EXTERNAL_GBYTES": {
"type": "integer",
"example": 0
},
"PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
"type": "integer",
"example": 0
},
"PROXY_SERPS": {
"type": "integer",
"example": 0
}
}
}
}
}
}
}
}
}
}
```