# YouTube Video Downloader - 4K, MP4 & MP3 (`titan_network/titan-youtube-video-downloader`) Actor Download YouTube videos and Shorts in MP4 up to 4K, extract MP3 audio, metadata, and subtitles in bulk, with direct links or S3 delivery. Powered by Titan Network. - **URL**: https://apify.com/titan\_network/titan-youtube-video-downloader.md - **Developed by:** [Titan Network](https://apify.com/titan_network) (community) - **Categories:** - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $0.04 / 1,000 video download successes 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/actors/running/actors-in-store.md#pay-per-event ## What's an Apify Actor? Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows. 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. - **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use). - **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`. - **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`. - **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`. - **Any other language** — 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 Video Downloader - 4K, MP4 & MP3 YouTube video downloader for URLs or plain 11-character video IDs: process a batch in one Gateway-backed run and receive videos up to 4K in MP4/WebM, MP3 audio, standalone `.info.json` metadata, or subtitle files through direct links or supported S3-compatible storage. *** ### What you can download - **Four Output Modes in One Actor**: `outputType` selects `media` (video or MP3 audio), `metadata` (standalone `.info.json`), or `subtitles` (standalone subtitle files). - **High Quality Video Downloads**: Full videos in up to 4K (2160p), 2K (1440p), 1080p Full HD, 720p HD, 480p or 360p. - **Audio-Only Extraction (MP3)**: `outputType=media` + `format=mp3`. Current Gateway supports **MP3 only** (no M4A/FLAC). - **Standalone Metadata**: `outputType=metadata` delivers `.info.json` only — no media bytes. - **Standalone Subtitles**: `outputType=subtitles` + `subtitleLanguages` delivers VTT/SRT/JSON3/SRV1-3/TTML subtitle files (manual + automatic), one row per video with every language in `downloadFiles`. - **Shorts & Standard Videos**: Fully supports standard YouTube videos, YouTube Shorts, and `youtu.be` short links. - **Zero Memory Overhead (Ultra-Lightweight)**: Runs smoothly on Apify's minimal **128MB RAM** tier. - **Direct High-Speed Delivery**: Download links are generated as direct pre-signed URLs (retained ~24h), eliminating slow double-transfers and bandwidth bottlenecks. - **Custom Cloud Storage Integration**: Pipe outputs directly into your Amazon S3, Google Cloud Storage, or DigitalOcean Spaces bucket. Azure is **not** supported. - **Real-time Live Progress & ETA**: Transparent progress tracking via Apify Console (fetching metadata / downloading / processing / uploading). - **Bounded Concurrency + Configurable Timeout**: Default 20 concurrent "submit + SSE" worker units (1-50), and per-mode task timeouts (metadata/subtitles 30 min, audio 2 h, video 4 h) — both configurable. - **One-Run Batch Grouping**: All URLs in one run share the same `batch_id` (`:`), which the Gateway groups into a single Titan project (one project, N tasks, parallel downloads). Duplicate video IDs are deduplicated (one Dataset row + one charge). *** ### 📋 Input Configuration | Parameter | Type | Required | Default | Description | | :--- | :--- | :--- | :--- | :--- | | `startUrls` | Array of strings | **Yes** | - | YouTube URLs (watch, Shorts, `youtu.be`) or plain 11-char video IDs. | | `outputType` | String | No | `"media"` | `media` (video/audio), `metadata` (standalone `.info.json`), `subtitles` (standalone subtitle files). One run uses exactly one mode. | | `quality` | String | No | `"720"` | Media/video only: `360`, `480`, `720`, `1080`, `1440`, `2160`. Ignored for audio/metadata/subtitles. | | `format` | String | No | `"mp4"` | Media only: `mp4`, `webm` (video), `mp3` (audio only). Ignored for metadata/subtitles. | | `subtitleLanguages` | Array of strings | Subtitles | - | 1-10 language codes (e.g. `en`, `zh-Hans`) or `["all"]` for every available subtitle. | | `subtitleFormat` | String | No | `"vtt"` | `srt`, `vtt`, `json3`, `srv1`, `srv2`, `srv3`, `ttml`. | | `storageType` | String | No | `"apify"` | `apify` (Titan platform storage / pre-signed links), `aws`, `gcp`, `digitalocean`. Azure is not supported. | | `s3Bucket` | String | External | - | Bucket/container name for `aws`/`gcp`/`digitalocean`. | | `s3Region` | String | No | - | Storage region (`us-east-1`, `auto`, `nyc3`). Required for DigitalOcean. | | `s3AccessKeyId` | String | External | - | Access key ID for external storage. | | `s3SecretAccessKey` | String | External | - | Secret access key for external storage. | | `maxWaitSec` | Integer | No | mode default | Per-task SSE timeout in seconds (metadata/subtitles 1800, audio 7200, video 14400). | | `maxConcurrency` | Integer | No | `20` | Bounded concurrency (1-50) for submit + SSE worker units. | > **Field combination rules** (sending forbidden fields returns `OUTPUT_CONFIG_CONFLICT`): > > - **Video**: `outputType=media`, `quality`, `format=mp4/webm` — no subtitle fields. > - **Audio**: `outputType=media`, `format=mp3`, fixed `quality=720` — no subtitle fields. > - **Metadata**: `outputType=metadata` — omit `quality`/`format` and all subtitle fields. > - **Subtitles**: `outputType=subtitles` + `subtitleLanguages` — omit `quality` and media `format`. #### Example Input JSON ```json { "startUrls": [ "https://www.youtube.com/watch?v=dQw4w9WgXcQ", "https://youtu.be/jNQXAC9IVRw", "9bZkp7q19f0" ], "outputType": "media", "quality": "1080", "format": "mp4" } ``` Audio run: ```json { "startUrls": ["dQw4w9WgXcQ"], "outputType": "media", "format": "mp3" } ``` Metadata run: ```json { "startUrls": ["dQw4w9WgXcQ"], "outputType": "metadata" } ``` Subtitles run: ```json { "startUrls": ["dQw4w9WgXcQ"], "outputType": "subtitles", "subtitleLanguages": ["en", "zh-Hans"], "subtitleFormat": "vtt" } ``` *** ### 📊 Output Dataset Format Each processed video produces a structured dataset record with metadata and download links. The **`downloadFiles`** array is the authoritative delivery record and is always persisted in full (audio tasks include the attached `.info.json`; multi-language subtitles include one entry per delivered language). | Field | Type | Description | | :--- | :--- | :--- | | `id` | String | Unique YouTube video ID. | | `input` | String | Original input URL provided. | | `title` | String | Video title. | | `durationSec` | Integer | Total duration in seconds. | | `outputType` | String | `media`, `metadata`, or `subtitles`. | | `quality` / `format` | String | Media mode only. | | `subtitleLanguages` / `subtitleFormat` | Array / String | Subtitles mode only. | | `fileSizeBytes` / `fileSizeMB` | Number | Main delivered file size. | | `downloadedFileUrl` | String | Main file's direct download link (~24h retention on platform storage; may be absent when external storage only returns an object key). | | `fileKey` | String | Main file's storage object key. | | `downloadFiles` | Array | Complete list of delivered files (`kind`, `filename`, `fileSizeBytes`, `downloadedFileUrl`, `fileKey`, `status`). **Authoritative.** | | `status` | String | `completed`, `failed`, `timeout`, or `skipped`. | | `note` | String | Expiration / usage instructions. | #### Example Output Record ```json { "id": "dQw4w9WgXcQ", "input": "https://www.youtube.com/watch?v=dQw4w9WgXcQ", "title": "Rick Astley - Never Gonna Give You Up (Official Music Video)", "durationSec": 213, "outputType": "media", "format": "mp3", "fileSizeMB": 4.12, "downloadedFileUrl": "https://.../dQw4w9WgXcQ.mp3", "fileKey": ".../dQw4w9WgXcQ.mp3", "downloadFiles": [ { "kind": "audio", "filename": "dQw4w9WgXcQ.mp3", "fileSizeBytes": 4321000, "downloadedFileUrl": "https://.../dQw4w9WgXcQ.mp3", "fileKey": ".../dQw4w9WgXcQ.mp3", "status": "available" }, { "kind": "metadata", "filename": "dQw4w9WgXcQ.info.json", "fileSizeBytes": 245000, "downloadedFileUrl": "https://.../dQw4w9WgXcQ.info.json", "fileKey": ".../dQw4w9WgXcQ.info.json", "status": "available" } ], "status": "completed", "note": "Audio download link is retained for approximately 24h after delivery." } ``` *** ### Use cases - Archive authorized YouTube videos or Shorts for offline viewing in MP4 or WebM up to 4K. - Extract MP3 audio and the accompanying `.info.json` for a batch of video URLs or IDs. - Export standalone video metadata without downloading media bytes. - Collect manual and automatic captions for selected languages or every available subtitle. - Deliver completed files through temporary direct links or an AWS, GCP, or DigitalOcean bucket. ### FAQ #### Can I submit multiple YouTube URLs or video IDs? Yes. Put all URLs or plain 11-character IDs in `startUrls`; duplicate video IDs are deduplicated within a run. #### How long do platform download links remain valid? Pre-signed links from Titan platform storage are retained for approximately 24 hours. External storage returns the configured object's delivery details instead. #### Which video, audio, metadata, and subtitle formats are supported? Video uses MP4 or WebM, audio uses MP3 only, metadata is delivered as `.info.json`, and subtitles support VTT, SRT, JSON3, SRV1-3, and TTML. ### Related YouTube Actors - [YouTube Video Downloader](https://apify.com/titan_network/titan-youtube-video-downloader) - [YouTube MP3 Audio Downloader](https://apify.com/titan_network/titan-youtube-audio) - [YouTube Video Metadata Scraper](https://apify.com/titan_network/titan-youtube-meta) - [YouTube Transcript & Subtitles Scraper](https://apify.com/titan_network/titan-youtube-subtitles) *** ### 💰 Pricing & Monetization (Pay-Per-Event) This Actor uses Apify's [Pay-Per-Event (PPE)](https://help.apify.com/en/articles/10700066-what-is-pay-per-event) model with a **No Success, No Charge** guarantee: - Billing event is chosen by the delivered output: - `video-download-success` — video (media + mp4/webm) - `audio-download-success` — audio (media + mp3) - `metadata-download-success` — standalone metadata - `subtitles-download-success` — standalone subtitles - You are only charged when **all** of these hold: Gateway returns `completed`, the requested output files exist, and the Dataset row was written successfully. - Zero cost on failures, timeouts, cancellations, or missing output files. - Minimal compute units: the Actor streams direct storage links without proxying raw bytes through the container. *** ### ⚖️ Legal & Fair Use Disclaimer This Actor is designed solely for archiving, offline viewing of authorized content, or educational and fair-use research. Please respect the copyright of creators and YouTube's Terms of Service when using this Actor. # Actor input Schema ## `startUrls` (type: `array`): List of YouTube video URLs (watch links, Shorts, youtu.be) or plain 11-character video IDs. One item per line. Duplicate video IDs are processed once. ## `outputType` (type: `string`): What this run should produce: media (video or audio), metadata (standalone .info.json), or subtitles (standalone subtitle files). One run uses exactly one output configuration. ## `quality` (type: `string`): Media mode (video) only: maximum desired video resolution. If not available, the highest available quality below this cap is selected. Audio (format=mp3) always uses the fixed value 720. Metadata/subtitles modes ignore this field. ## `format` (type: `string`): Media mode only: mp4/webm for merged video, mp3 for audio-only extraction. Metadata/subtitles modes ignore this field. ## `subtitleLanguages` (type: `array`): Subtitles mode only (required): 1-10 language codes (e.g. en, zh-Hans, de), or \["all"] to receive every available subtitle of the video. Manual and automatic subtitles are both attempted. ## `subtitleFormat` (type: `string`): Subtitles mode only: subtitle container format. ## `storageType` (type: `string`): Destination where downloaded files will be stored: apify (Titan platform storage, returns pre-signed links valid ~24h; files are NOT copied to the Apify Key-Value Store), aws (Amazon S3), gcp (Google Cloud Storage), digitalocean (DigitalOcean Spaces). Azure is not supported. ## `s3Bucket` (type: `string`): Bucket or container name if using custom cloud storage (required for aws/gcp/digitalocean). ## `s3Region` (type: `string`): Region of your storage bucket (e.g. us-east-1, auto, nyc3). Required for DigitalOcean Spaces. ## `s3AccessKeyId` (type: `string`): Access Key ID for your cloud storage provider (required for aws/gcp/digitalocean). ## `s3SecretAccessKey` (type: `string`): Secret Access Key for your cloud storage provider (required for aws/gcp/digitalocean). ## `maxWaitSec` (type: `integer`): Maximum seconds to wait for each task's SSE completion before cancelling it. Defaults by mode: metadata/subtitles 1800, audio 7200, video 14400. ## `maxConcurrency` (type: `integer`): Maximum number of concurrent submit + SSE worker units (1-50). Default 20. ## Actor input object example ```json { "startUrls": [ "https://www.youtube.com/watch?v=dQw4w9WgXcQ" ], "outputType": "media", "quality": "720", "format": "mp4", "subtitleFormat": "vtt", "storageType": "apify", "maxWaitSec": 0, "maxConcurrency": 20 } ``` # Actor output Schema ## `results` (type: `string`): Dataset of download results — one item per requested media, including download link and status. # 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 = { "startUrls": [ "https://www.youtube.com/watch?v=dQw4w9WgXcQ" ] }; // Run the Actor and wait for it to finish const run = await client.actor("titan_network/titan-youtube-video-downloader").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 = { "startUrls": ["https://www.youtube.com/watch?v=dQw4w9WgXcQ"] } # Run the Actor and wait for it to finish run = client.actor("titan_network/titan-youtube-video-downloader").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}") for item in client.dataset(run.default_dataset_id).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "startUrls": [ "https://www.youtube.com/watch?v=dQw4w9WgXcQ" ] }' | apify call titan_network/titan-youtube-video-downloader --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "type": "http", "url": "https://mcp.apify.com/?tools=fetch-actor-details,titan_network/titan-youtube-video-downloader" } } } ``` The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer ` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations). ## OpenAPI specification Download the OpenAPI definition: https://api.apify.com/v2/actors/wPcJinxakFEmdTQYu/builds/cBPS6mAqjPhGvYJjM/openapi.json