# YouTube Transcript & Subtitle Scraper (`abotapi/youtube-transcript-scraper`) Actor Extract transcripts and subtitles from YouTube videos in bulk using video, playlist, channel URLs, or keyword search. Returns timed transcript segments, plain text, SRT, and WebVTT subtitle files, with optional auto-translation to other languages. - **URL**: https://apify.com/abotapi/youtube-transcript-scraper.md - **Developed by:** [AbotAPI](https://apify.com/abotapi) (community) - **Categories:** Videos, Developer tools, AI - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, NaN bookmarks - **User rating**: No ratings yet ## Pricing from $1.00 / 1,000 transcript fetcheds This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## 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 & Subtitles Scraper Pull transcripts and subtitles for YouTube videos in bulk. Give it video URLs, playlist URLs, channel URLs, or just keywords to search YouTube, and it returns each video's transcript as timed segments, as plain text, and as ready-to-use SRT and WebVTT subtitle files. It can also auto-translate transcripts into another language. ### Why this scraper - Four ways in: direct video URLs or IDs, playlist URLs, channel URLs (`@handle`, `/channel/UC...`, `/c/...`, `/user/...`), and keyword searches, all in one run. - Every output record carries the transcript three ways: timed `segments`, a single plain-text `transcript` field, and `srt` plus `vtt` strings you can save straight to disk. - Language control: list your preferred languages in priority order, or translate the result into any language YouTube supports. - Handles both human-written captions and auto-generated ones, and falls back to whatever the video offers when your preferred language is not available. - Concurrent fetching with automatic connection rotation, so large playlists and channels move quickly. - Per-source time windows: trim each video's transcript to a specific second range (and only pay for the trimmed text). - Pay only for what you get: failed or captions-disabled videos are not billed. ### Data you get Per video (one dataset record). Values below are illustrative placeholders, not from a live video. | Field | Example | |---|---| | `videoId` | `EXAMPLE_ID1` | | `videoUrl` | `https://www.youtube.com/watch?v=EXAMPLE_ID1` | | `videoTitle` | `Sample Video Title` | | `channelName` | `Sample Channel` | | `channelUrl` | `https://www.youtube.com/@SampleChannel` | | `durationSeconds` | `213` | | `source` | `python tutorial` | | `sourceType` | `search` (one of `video`, `playlist`, `channel`, `search`) | | `language` | `English` | | `languageCode` | `en` | | `isGenerated` | `false` | | `isTranslated` | `false` | | `translatedTo` | `null` | | `charCount` | `5234` | | `segmentCount` | `142` | | `transcript` | `"Hello and welcome to this sample transcript ..."` | | `segments` | `[{ "text": "Hello and welcome", "start": 0.0, "duration": 1.84 }, ...]` | | `srt` | `"1\n00:00:00,000 --> 00:00:01,840\nHello and welcome\n\n2\n..."` | | `vtt` | `"WEBVTT\n\n00:00:00.000 --> 00:00:01.840\nHello and welcome\n\n..."` | | `trimmedStart` | `0` (start of the time window applied; `0` = no trim) | | `trimmedDuration` | `0` (length of the time window applied; `0` = no trim) | | `success` | `true` | | `error` | `null` (a short message when a transcript could not be fetched) | ### How to use Pick a `mode`: - `mode: "url"` reads `videoUrls` (paste video, playlist, or channel URLs). - `mode: "search"` reads `searchQueries` (find videos by keyword). The other field is ignored. Optionally set `startSec` and `durationSec` to trim every video's transcript to the same time window (`durationSec: 0` means "until end of video"). Fetch one video's transcript: ```json { "mode": "url", "videoUrls": ["https://www.youtube.com/watch?v=dQw4w9WgXcQ"], "languages": ["en"], "proxyConfiguration": { "useApifyProxy": true, "apifyProxyGroups": ["RESIDENTIAL"] } } ```` Several videos at once (URLs or bare IDs both work): ```json { "mode": "url", "videoUrls": [ "https://www.youtube.com/watch?v=dQw4w9WgXcQ", "https://youtu.be/dQw4w9WgXcQ", "dQw4w9WgXcQ" ], "languages": ["en", "en-US"], "proxyConfiguration": { "useApifyProxy": true, "apifyProxyGroups": ["RESIDENTIAL"] } } ``` Search YouTube by keyword and transcribe the top results: ```json { "mode": "search", "searchQueries": ["langgraph tutorial", "apify actor development"], "maxVideosPerSource": 5, "languages": ["en"], "proxyConfiguration": { "useApifyProxy": true, "apifyProxyGroups": ["RESIDENTIAL"] } } ``` Expand a playlist and a channel, capped per source, and translate everything to English: ```json { "mode": "url", "videoUrls": [ "https://www.youtube.com/playlist?list=PLxxxxxxxxxxxxxxxx", "https://www.youtube.com/@SomeChannel" ], "maxVideosPerSource": 25, "maxVideos": 100, "languages": ["en"], "translateToLanguage": "en", "proxyConfiguration": { "useApifyProxy": true, "apifyProxyGroups": ["RESIDENTIAL"] } } ``` Trim every video's transcript to seconds 30 to 60: ```json { "mode": "url", "videoUrls": ["https://www.youtube.com/watch?v=dQw4w9WgXcQ"], "startSec": 30, "durationSec": 30, "languages": ["en"], "proxyConfiguration": { "useApifyProxy": true, "apifyProxyGroups": ["RESIDENTIAL"] } } ``` The trimmed `transcript`, `segments`, `srt`, and `vtt` only contain snippets inside the window, and the `transcript` billing event counts only the trimmed characters. ### Input parameters | Parameter | Type | Default | Description | |---|---|---|---| | `mode` | string enum | `"url"` | One of `"url"` (read `videoUrls`) or `"search"` (read `searchQueries`). The other field is ignored. | | `videoUrls` | array of strings | `[]` | Used when `mode = url`. Watch URLs, youtu.be URLs, shorts URLs, playlist URLs, channel URLs (@handle, /channel/, /c/, /user/), or 11-character video IDs. Playlists and channels are expanded to their videos. | | `searchQueries` | array of strings | `[]` | Used when `mode = search`. Free-form keywords. Top results per query are fetched. | | `startSec` | integer | `0` | Trim every transcript to start at this second. `0` keeps from the beginning. | | `durationSec` | integer | `0` | Trim every transcript to this many seconds from `startSec`. `0` keeps until the end of each video. | | `maxVideosPerSource` | integer | `10` | How many videos to take from each playlist, channel, or search query. | | `maxVideos` | integer | `0` | Hard cap on the total number of videos across all sources. `0` means no overall cap. | | `languages` | array of strings | `["en"]` | Preferred transcript language codes in priority order. The first available one is used; if none are available, any transcript the video offers is returned. | | `translateToLanguage` | string | `""` | Optional language code to translate the transcript into using YouTube's auto-translation. Empty keeps the original language. | | `preserveFormatting` | boolean | `false` | Keep inline formatting tags (such as italics) in the transcript text instead of stripping them. | | `proxyConfiguration` | object | Apify Proxy, `RESIDENTIAL` | Proxy settings. YouTube blocks most datacenter / cloud IPs from fetching transcripts, so the `RESIDENTIAL` group is strongly recommended. | ### Output example > Sample shape: values are illustrative placeholders, not from a live video. ```json { "videoId": "EXAMPLE_ID1", "videoUrl": "https://www.youtube.com/watch?v=EXAMPLE_ID1", "videoTitle": "Sample Video Title", "channelName": "Sample Channel", "channelUrl": "https://www.youtube.com/@SampleChannel", "durationSeconds": 213, "source": "https://www.youtube.com/watch?v=EXAMPLE_ID1", "sourceType": "video", "language": "English", "languageCode": "en", "isGenerated": false, "isTranslated": false, "translatedTo": null, "charCount": 5234, "segmentCount": 142, "transcript": "Hello and welcome to this sample transcript.\nThis is the second line of the transcript.\n...", "segments": [ { "text": "Hello and welcome to this sample transcript.", "start": 0.0, "duration": 2.32 }, { "text": "This is the second line of the transcript.", "start": 2.32, "duration": 2.08 } ], "srt": "1\n00:00:00,000 --> 00:00:02,320\nHello and welcome to this sample transcript.\n\n2\n00:00:02,320 --> 00:00:04,400\nThis is the second line of the transcript.\n", "vtt": "WEBVTT\n\n00:00:00.000 --> 00:00:02.320\nHello and welcome to this sample transcript.\n\n00:00:02.320 --> 00:00:04.400\nThis is the second line of the transcript.\n", "success": true, "error": null } ``` ### Billing You are charged once per run, plus a small amount per keyword search that was successfully resolved (URL inputs are not charged for resolution), plus a length-based unit per fetched transcript. One transcript unit covers roughly 4,000 characters of transcript text, about 1,000 LLM tokens. A short clip is about one unit, a 1-hour podcast around twelve, and a 3-hour video around thirty-five. Videos whose captions are disabled, unavailable, or could not be fetched are not billed. If you trim the transcript with `startSec` and `durationSec`, you only pay for the trimmed text. Exact amounts are shown on this actor's Store page. ### Plan requirement Works on any Apify plan, but YouTube blocks most datacenter and cloud IP ranges from fetching transcripts. For reliable results use Apify Proxy with the `RESIDENTIAL` group, which is available on the Starter plan and higher. On the free plan, expect many videos to return an error; the run will log a notice and add a record explaining the upgrade path. # Actor input Schema ## `mode` (type: `string`): Pick how to specify videos. ## `videoUrls` (type: `array`): One per line. Watch URLs, youtu.be URLs, shorts URLs, playlist URLs, channel URLs (@handle, /channel/UC..., /c/..., /user/...), or 11-character video IDs. Playlists and channels are expanded to their videos. ## `searchQueries` (type: `array`): One per line. Top results per query (up to 'Max videos per source') are fetched. ## `startSec` (type: `integer`): Trim each transcript to start at this second. 0 keeps from the beginning of each video. ## `durationSec` (type: `integer`): Trim each transcript to this many seconds from Start above. 0 keeps until the end of each video. ## `maxVideosPerSource` (type: `integer`): How many videos to take from each playlist, channel, or search query. ## `maxVideos` (type: `integer`): Hard cap on the total number of videos processed across all sources. 0 means no overall cap. ## `languages` (type: `array`): Language codes in priority order, for example \["en", "en-US", "de"]. The first available one is used; if none are available, any transcript YouTube offers is returned. ## `translateToLanguage` (type: `string`): Optional. A language code (e.g. "en") to translate the transcript into using YouTube's auto-translation. Leave empty to keep the original. ## `preserveFormatting` (type: `boolean`): Keep inline formatting tags (e.g. italics) in the transcript text instead of stripping them. ## `proxyConfiguration` (type: `object`): YouTube blocks most datacenter / cloud IPs from fetching transcripts. The RESIDENTIAL group is strongly recommended; without it many videos return errors. Free Apify plans do not include residential proxy. ## Actor input object example ```json { "mode": "url", "videoUrls": [ "https://www.youtube.com/watch?v=dQw4w9WgXcQ" ], "searchQueries": [ "python tutorial" ], "startSec": 0, "durationSec": 0, "maxVideosPerSource": 10, "maxVideos": 0, "languages": [ "en" ], "translateToLanguage": "", "preserveFormatting": false, "proxyConfiguration": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ] } } ``` # Actor output Schema ## `transcripts` (type: `string`): Per-video transcripts: timed segments, plain text, SRT and WebVTT. # 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 = { "videoUrls": [ "https://www.youtube.com/watch?v=dQw4w9WgXcQ" ], "searchQueries": [ "python tutorial" ], "languages": [ "en" ], "proxyConfiguration": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ] } }; // Run the Actor and wait for it to finish const run = await client.actor("abotapi/youtube-transcript-scraper").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 = { "videoUrls": ["https://www.youtube.com/watch?v=dQw4w9WgXcQ"], "searchQueries": ["python tutorial"], "languages": ["en"], "proxyConfiguration": { "useApifyProxy": True, "apifyProxyGroups": ["RESIDENTIAL"], }, } # Run the Actor and wait for it to finish run = client.actor("abotapi/youtube-transcript-scraper").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 '{ "videoUrls": [ "https://www.youtube.com/watch?v=dQw4w9WgXcQ" ], "searchQueries": [ "python tutorial" ], "languages": [ "en" ], "proxyConfiguration": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ] } }' | apify call abotapi/youtube-transcript-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=abotapi/youtube-transcript-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "YouTube Transcript & Subtitle Scraper", "description": "Extract transcripts and subtitles from YouTube videos in bulk using video, playlist, channel URLs, or keyword search. Returns timed transcript segments, plain text, SRT, and WebVTT subtitle files, with optional auto-translation to other languages.", "version": "1.1", "x-build-id": "NrliBzhwNy3MCBXJU" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/abotapi~youtube-transcript-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-abotapi-youtube-transcript-scraper", "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/abotapi~youtube-transcript-scraper/runs": { "post": { "operationId": "runs-sync-abotapi-youtube-transcript-scraper", "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/abotapi~youtube-transcript-scraper/run-sync": { "post": { "operationId": "run-sync-abotapi-youtube-transcript-scraper", "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": [ "mode" ], "properties": { "mode": { "title": "Mode", "enum": [ "url", "search" ], "type": "string", "description": "Pick how to specify videos.", "default": "url" }, "videoUrls": { "title": "Video / playlist / channel URLs", "type": "array", "description": "One per line. Watch URLs, youtu.be URLs, shorts URLs, playlist URLs, channel URLs (@handle, /channel/UC..., /c/..., /user/...), or 11-character video IDs. Playlists and channels are expanded to their videos.", "items": { "type": "string" }, "default": [] }, "searchQueries": { "title": "Keyword searches", "type": "array", "description": "One per line. Top results per query (up to 'Max videos per source') are fetched.", "items": { "type": "string" }, "default": [] }, "startSec": { "title": "Time window - start (seconds)", "minimum": 0, "type": "integer", "description": "Trim each transcript to start at this second. 0 keeps from the beginning of each video.", "default": 0 }, "durationSec": { "title": "Time window - duration (seconds)", "minimum": 0, "type": "integer", "description": "Trim each transcript to this many seconds from Start above. 0 keeps until the end of each video.", "default": 0 }, "maxVideosPerSource": { "title": "Max videos per source", "minimum": 1, "maximum": 1000, "type": "integer", "description": "How many videos to take from each playlist, channel, or search query.", "default": 10 }, "maxVideos": { "title": "Max videos (overall)", "minimum": 0, "type": "integer", "description": "Hard cap on the total number of videos processed across all sources. 0 means no overall cap.", "default": 0 }, "languages": { "title": "Preferred transcript languages", "type": "array", "description": "Language codes in priority order, for example [\"en\", \"en-US\", \"de\"]. The first available one is used; if none are available, any transcript YouTube offers is returned.", "items": { "type": "string" }, "default": [ "en" ] }, "translateToLanguage": { "title": "Translate transcript to", "type": "string", "description": "Optional. A language code (e.g. \"en\") to translate the transcript into using YouTube's auto-translation. Leave empty to keep the original.", "default": "" }, "preserveFormatting": { "title": "Preserve text formatting", "type": "boolean", "description": "Keep inline formatting tags (e.g. italics) in the transcript text instead of stripping them.", "default": false }, "proxyConfiguration": { "title": "Proxy configuration", "type": "object", "description": "YouTube blocks most datacenter / cloud IPs from fetching transcripts. The RESIDENTIAL group is strongly recommended; without it many videos return errors. Free Apify plans do not include residential proxy.", "default": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ] } } } }, "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 } } } } } } } } } } ```