# YouTube Subtitle & Transcript Scraper (`autofacts/youtube-subtitle-transcript-scraper`) Actor Extract YouTube subtitles & transcripts from videos, Shorts, playlists, and channels. Output as JSON, SRT, VTT, or clean LLM-ready text. 100+ languages. Rich metadata: views, description, thumbnail. Multi-fallback engine for maximum reliability. Fair billing — failures are free. - **URL**: https://apify.com/autofacts/youtube-subtitle-transcript-scraper.md - **Developed by:** [Richard Feng](https://apify.com/autofacts) (community) - **Categories:** AI, Developer tools, SEO tools - **Stats:** 19 total users, 13 monthly users, 98.1% runs succeeded, NaN bookmarks - **User rating**: No ratings yet ## Pricing from $5.00 / 1,000 transcript extracteds 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 Subtitle & Transcript Scraper Extract subtitles and transcripts from any YouTube video — fast, reliable, and ready for AI pipelines. Supports single videos, Shorts, playlists, and entire channels. Works with 100+ languages including auto-generated captions. ### What you get For each video, the scraper returns: - **Full transcript text** with timestamps - **Rich video metadata** — title, channel, description, view count, thumbnail, publish date - **Language info** — detected language, auto-generated flag, all available languages listed - **Multiple output formats** — pick what fits your workflow ### Output formats | Format | Best for | |--------|----------| | **JSON** | Apps, databases, APIs — structured data with timestamps per segment | | **SRT** | Video editors, media players — standard subtitle file format | | **VTT** | Web players, HTML5 video — WebVTT subtitle format | | **Text** | Search indexing, content analysis — plain text joined together | | **LLM** | AI/ML pipelines, RAG, fine-tuning — clean text with annotations stripped | The **LLM format** automatically removes `[Music]`, `[Applause]`, speaker labels, and other non-speech annotations so you get pure spoken content ready for language models. ### Supported URL types You can pass any of these as input: - `https://www.youtube.com/watch?v=dQw4w9WgXcQ` — standard video - `https://youtu.be/dQw4w9WgXcQ` — short link - `https://www.youtube.com/shorts/dQw4w9WgXcQ` — YouTube Shorts - `https://www.youtube.com/playlist?list=PLxxxxx` — full playlist - `https://www.youtube.com/@channelname` — all videos from a channel - `dQw4w9WgXcQ` — just the video ID Mix and match in a single run — the scraper handles them all. ### Input options | Option | Default | Description | |--------|---------|-------------| | **urls** | — | List of YouTube URLs or video IDs to process | | **outputFormat** | `json` | Output format: `json`, `srt`, `vtt`, `text`, or `llm` | | **languages** | `["en"]` | Preferred languages in priority order (e.g. `["en", "ja", "de"]`) | | **includeAutoGenerated** | `true` | Use YouTube's auto-generated captions when manual ones aren't available | | **maxVideos** | `0` (unlimited) | Limit how many videos to process from playlists/channels | | **maxConcurrency** | `3` | How many videos to process in parallel (1–10) | | **proxy** | Apify Proxy | Proxy settings — residential proxies recommended | You can also use **startUrls** (the `[{url: "..."}]` format) instead of **urls** — both work. ### Example input ```json { "urls": [ "https://www.youtube.com/watch?v=dQw4w9WgXcQ", "https://youtu.be/JGwWNGJdvx8" ], "outputFormat": "llm", "languages": ["en"], "maxConcurrency": 2 } ```` ### Example output Each video produces one result in the dataset: ```json { "videoId": "dQw4w9WgXcQ", "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ", "title": "Rick Astley - Never Gonna Give You Up (Official Video)", "channelName": "Rick Astley", "channelId": "UCuAXFkgsw1L7xaCfnd5JJOw", "description": "The official video for \"Never Gonna Give You Up\" by Rick Astley...", "publishDate": "2009-10-25", "viewCount": 1761003712, "thumbnail": "https://i.ytimg.com/vi/dQw4w9WgXcQ/sddefault.jpg", "availableLanguages": ["en", "de-DE", "ja", "pt-BR", "es-419"], "language": "en", "languageName": "English", "isAutoGenerated": false, "duration": 213, "wordCount": 487, "segmentCount": 61, "text": "We're no strangers to love, you know the rules and so do I...", "segments": [ { "text": "We're no strangers to love", "start": 18.64, "end": 21.88 }, { "text": "You know the rules and so do I", "start": 22.64, "end": 26.96 } ], "extractedAt": "2026-04-10T07:00:00.000Z", "error": null } ``` When using **SRT** or **VTT** format, the result includes an `srt` or `vtt` field with the formatted subtitle file content. ### Recommendations **For best results:** - Use **residential proxies** (the default) — they work much better with YouTube than datacenter proxies - Start with **maxConcurrency: 1** if you're processing many videos, then increase gradually - Set **languages** to your target language — the scraper picks the best available match - Use the **LLM format** if you're feeding transcripts into AI models — it strips all the noise **For large jobs:** - Use playlists or channel URLs to batch-process videos in one run - Set **maxVideos** to limit playlist/channel scrapes during testing - The scraper handles failures gracefully — if one video fails, the rest still process. Failed videos show up in the results with an `error` field so you can retry them later **For AI/ML workflows:** - The **LLM output format** gives you clean, annotation-free text optimized for context windows - **JSON format** preserves timestamps, which is useful for building time-aligned datasets - The `segments` array gives you natural sentence boundaries from the original captions ### Fair billing You're never charged for videos that fail to extract. You only pay for successful results. ### Language support The scraper supports all languages that YouTube captions are available in — over 100 languages. Set your preferred languages in priority order and the scraper will pick the best available match. If manual captions aren't available in your language, YouTube's auto-generated captions are used as a fallback (unless you disable this with `includeAutoGenerated: false`). ### Error handling The scraper is designed to be resilient: - If a video has no captions, it reports the error and moves on - If YouTube rate-limits a request, the scraper retries with backoff - If one extraction method fails, it automatically tries alternatives - Failed videos appear in the dataset with a descriptive `error` field — successful videos have `error: null` ### Need help? If you run into issues or have questions, open an issue on the [Apify Store page](https://apify.com/autofacts/youtube-subtitle-scraper/issues). # Actor input Schema ## `urls` (type: `array`): List of YouTube URLs to extract subtitles from. Supports video URLs, Shorts, youtu.be short links, playlist URLs, and channel URLs. ## `startUrls` (type: `array`): Alternative URL input format. Array of objects with 'url' field. ## `outputFormat` (type: `string`): Format for the transcript output. ## `languages` (type: `array`): Preferred subtitle languages in order of priority (ISO 639-1 codes, e.g. 'en', 'ja', 'zh-Hans'). Leave empty for any available language. ## `includeAutoGenerated` (type: `boolean`): Whether to include YouTube's auto-generated captions if manually-created ones are not available. ## `maxVideos` (type: `integer`): Maximum number of videos to process (useful for limiting playlist/channel scrapes). 0 = unlimited. ## `maxConcurrency` (type: `integer`): Maximum number of videos to process in parallel. Higher values are faster but increase rate-limit risk. ## `youtubeCookies` (type: `string`): Paste your YouTube cookies to dramatically improve success on videos that trigger 'Sign in to confirm you're not a bot'. Accepts either a raw Cookie header (copy from DevTools → Network → a youtube.com request → Cookie) or a Netscape cookies.txt file (export with a browser extension like 'Get cookies.txt LOCALLY'). Leave empty to scrape anonymously. ## Actor input object example ```json { "urls": [ "https://www.youtube.com/watch?v=dQw4w9WgXcQ" ], "outputFormat": "json", "languages": [ "en" ], "includeAutoGenerated": true, "maxVideos": 0, "maxConcurrency": 3 } ``` # Actor output Schema ## `results` (type: `string`): Dataset containing extracted transcripts with timestamps, metadata, and formatted text for each video. # 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 = { "urls": [ "https://www.youtube.com/watch?v=dQw4w9WgXcQ" ], "languages": [ "en" ] }; // Run the Actor and wait for it to finish const run = await client.actor("autofacts/youtube-subtitle-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 = { "urls": ["https://www.youtube.com/watch?v=dQw4w9WgXcQ"], "languages": ["en"], } # Run the Actor and wait for it to finish run = client.actor("autofacts/youtube-subtitle-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 '{ "urls": [ "https://www.youtube.com/watch?v=dQw4w9WgXcQ" ], "languages": [ "en" ] }' | apify call autofacts/youtube-subtitle-transcript-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=autofacts/youtube-subtitle-transcript-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "YouTube Subtitle & Transcript Scraper", "description": "Extract YouTube subtitles & transcripts from videos, Shorts, playlists, and channels. Output as JSON, SRT, VTT, or clean LLM-ready text. 100+ languages. Rich metadata:\n views, description, thumbnail. Multi-fallback engine for maximum reliability. Fair billing — failures are free.", "version": "0.0", "x-build-id": "iAdyxAt6lg0UDWH0z" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/autofacts~youtube-subtitle-transcript-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-autofacts-youtube-subtitle-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/autofacts~youtube-subtitle-transcript-scraper/runs": { "post": { "operationId": "runs-sync-autofacts-youtube-subtitle-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/autofacts~youtube-subtitle-transcript-scraper/run-sync": { "post": { "operationId": "run-sync-autofacts-youtube-subtitle-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", "properties": { "urls": { "title": "Video URLs", "type": "array", "description": "List of YouTube URLs to extract subtitles from. Supports video URLs, Shorts, youtu.be short links, playlist URLs, and channel URLs.", "items": { "type": "string" } }, "startUrls": { "title": "Start URLs (alternative)", "type": "array", "description": "Alternative URL input format. Array of objects with 'url' field.", "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL of a web page", "format": "uri" } } } }, "outputFormat": { "title": "Output Format", "enum": [ "json", "srt", "vtt", "text", "llm" ], "type": "string", "description": "Format for the transcript output.", "default": "json" }, "languages": { "title": "Preferred Languages", "type": "array", "description": "Preferred subtitle languages in order of priority (ISO 639-1 codes, e.g. 'en', 'ja', 'zh-Hans'). Leave empty for any available language.", "default": [ "en" ], "items": { "type": "string" } }, "includeAutoGenerated": { "title": "Include Auto-Generated Captions", "type": "boolean", "description": "Whether to include YouTube's auto-generated captions if manually-created ones are not available.", "default": true }, "maxVideos": { "title": "Max Videos", "minimum": 0, "type": "integer", "description": "Maximum number of videos to process (useful for limiting playlist/channel scrapes). 0 = unlimited.", "default": 0 }, "maxConcurrency": { "title": "Max Concurrency", "minimum": 1, "maximum": 10, "type": "integer", "description": "Maximum number of videos to process in parallel. Higher values are faster but increase rate-limit risk.", "default": 3 }, "youtubeCookies": { "title": "YouTube Cookies (optional)", "type": "string", "description": "Paste your YouTube cookies to dramatically improve success on videos that trigger 'Sign in to confirm you're not a bot'. Accepts either a raw Cookie header (copy from DevTools → Network → a youtube.com request → Cookie) or a Netscape cookies.txt file (export with a browser extension like 'Get cookies.txt LOCALLY'). Leave empty to scrape anonymously." } } }, "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 } } } } } } } } } } ```