Youtube Video Downloader

--- # 🌟 YouTube WebM Video Downloader — Fast WebM (and more) links, downloads & metadata 📖 Summary A production-ready Apify Actor that extracts direct media links (merged/video/audio), optionally downloads and uploads files, and returns rich metadata from YouTube URLs — plug-and-play on Apify Console, secure by design, and built for fast, reliable runs. --- ## 💡 Use cases / When to use * Extract direct media URLs (merged HLS/DASH, video-only, audio-only) for downstream processing * Download and upload webm/mp4/mkv media files to Apify storage for archiving or post-processing * Quickly harvest metadata (title, description, thumbnails, duration, views) for indexing or QA * Build queues for media ingestion, CDN pre-fetch, or batch downloads * Programmatic audiovisual dataset creation with filename templating and concurrency control --- ## ⚡ Quick Start (Console — one-click) 1. Open this Actor in the Apify Console. 2. Paste a JSON input (see input.example.json in this repo) into the Console Input field. 3. Click Run Actor — results stream directly to the Dataset and OUTPUT key-value store. If download_mode is set to download_and_upload, files will be saved to your chosen storage target. > Instant insights, secure by design — runs in seconds for most videos. --- ## ⚙️ Quick Start (CLI + API) CLI (apify-cli) bash # Runs the actor with an input file and prints run summary apify run --input input.example.json Python (apify-client) — minimal example python from apify_client import ApifyClient client = ApifyClient('<APIFY_TOKEN>') run = client.actor('<ACTOR_ID>').call(run_input={ "video_urls": ["https://www.youtube.com/watch?v=EXAMPLE"], "output_types": ["merged","links_only"], "download_mode": "direct_links", "concurrency": 2, }) print('Run finished, dataset available at:', run['defaultDatasetId']) > Replace <APIFY_TOKEN> and <ACTOR_ID> with your values. See CONFIG.md for deployment tips. --- ## 📝 Inputs (fields & schema) This Actor uses a strict input schema (see actor.json). Key fields: * video_urls — required: array of video URL objects or strings. Prefill sample: https://www.youtube.com/watch?v=dQw4w9WgXcQ. * output_types — optional array (select one or more): merged, video_only, audio_only, links_only. Default: ["merged","links_only"]. * output_format — optional string (used for merged output): webm, mp4, mkv. Default: webm. * download_mode — optional string: direct_links (returns links) or download_and_upload (download files and upload to chosen storage). Default: direct_links. * storage_target — optional string (used only when download_and_upload): key_value_store or dataset. Default: key_value_store. * video_resolution — optional string: best, 2160, 1440, 1080, 720, 480, 360, 240. Default: best. * resolution_policy — optional string: nearest_below, nearest_any. Default: nearest_below. * use_apify_proxy — optional boolean: enable Apify Proxy. Default: true. * proxy — optional object: custom proxy configuration (Apify Proxy or user-defined proxy object). * cookies — optional secret string: cookie file contents for age-restricted/private videos. * include_subtitles — optional boolean: download subtitles if available. Default: false. * concurrency — optional integer: how many videos to process in parallel. Default: 2. Min: 1, Max: 8. * filename_template — optional string: naming template for downloaded files. Available vars: {uploader}, {upload_date}, {id}, {ext}. Default: {uploader}_{upload_date}_{id}.{ext}. ### Console JSON input example json { "video_urls": [ {"url": "https://www.youtube.com/watch?v=EXAMPLE1"}, {"url": "https://www.youtube.com/watch?v=EXAMPLE2"} ], "output_types": ["merged", "links_only"], "output_format": "webm", "download_mode": "direct_links", "storage_target": "key_value_store", "include_subtitles": false, "concurrency": 2, "use_apify_proxy": true, "filename_template": "{uploader}_{upload_date}_{id}.{ext}" } --- ## ⚙️ Configuration | 🔑 Name | 📝 Type | ❓ Required | ⚙️ Default | 📌 Example | 🧠 Notes | | ----------------- | ------- | -------------- | ------------------------------------- | ------------------------------------------------------------ | -------------------------------------------------------------------------------------------------- | | video_urls | array | ✅ Yes | None | [{"url": "https://.../watch?v=..."}] | One or more video URLs (string or object with url key). | | output_types | array | ⚙️ Optional | ["merged","links_only"] | ["merged","audio_only"] | Which link types to return (merged/video/audio/links_only). | | output_format | string | ⚙️ Optional | "webm" | "mp4" | Container used when merging audio+video. Choices: webm, mp4, mkv. | | download_mode | string | ⚙️ Optional | "direct_links" | "download_and_upload" | direct_links returns URLs; download_and_upload downloads files and uploads to storage target. | | storage_target | string | ⚙️ Conditional | "key_value_store" | "dataset" | Where downloaded files are saved when download_and_upload is used. | | video_resolution | string | ⚙️ Optional | "best" | "1080" | Preferred resolution; actor follows resolution_policy. | | resolution_policy | string | ⚙️ Optional | "nearest_below" | "nearest_any" | Policy for selecting closest available resolution. | | include_subtitles | boolean | ⚙️ Optional | false | true | Fetches embedded/automatic subtitles when available. | | cookies | string | ⚙️ Optional | None | "" | Paste cookie contents if needed; store as secret in Console. | | proxy | object | ⚙️ Optional | {"useApifyProxy": true} | {"useApifyProxy": false, "proxyUrl": "..." } | Proxy object (use Apify Console proxy or your custom proxy). | | use_apify_proxy | boolean | ⚙️ Optional | true | false | Set false to skip Apify-managed proxy. | | concurrency | integer | ⚙️ Optional | 2 | 4 | Number of concurrent workers (1–8). | | filename_template | string | ⚙️ Optional | "{uploader}{upload_date}{id}.{ext}" | "{uploader}{upload_date}{id}.{ext}" | Template for downloaded filenames. Available vars: {uploader}, {upload_date}, {id}, {ext}. | Example Console setup: Paste the Console JSON (above) into the Input field and click Run Actor. --- ## 📄 Outputs (Dataset / KV examples) This Actor pushes one entry per processed URL to the default Dataset and saves OUTPUT in the key-value store. If download_and_upload is used, file locations are recorded in the Dataset or Key-Value store entries depending on storage_target. Example Dataset item (download_mode: direct_links) json { "url": "https://www.youtube.com/watch?v=EXAMPLE1", "id": "EXAMPLE1", "title": "Example Video Title", "duration": 123, "views": 12345, "thumbnails": ["https://.../hqdefault.jpg"], "merged": "https://.../playlist.m3u8", "video_only": null, "audio_only": "https://.../audio.mp4", "links_only": "https://.../format.mp4" } Example Dataset item (download_mode: download_and_upload) json { "url": "https://www.youtube.com/watch?v=EXAMPLE1", "id": "EXAMPLE1", "title": "Example Video Title", "duration": 123, "views": 12345, "file": { "storage": "key_value_store", "path": "OUTPUT/videos/ExampleUploader_20250101_EXAMPLE1.webm", "size": 12345678 } } > The complete run results are also stored under the key-value store key OUTPUT. --- ## 🔑 Environment Variables & Memory * APIFY_TOKEN — required for CLI / API runs. Use Console secrets or CI secrets. * APIFY_RUN_ID — automatically provided by Apify Console (read-only). * HTTP_PROXY / HTTPS_PROXY — optional when using custom proxies (see Proxy Configuration). Actor runtime memory: minMemoryMbytes: 256, maxMemoryMbytes: 4096 — adjust concurrency or format choices if you hit memory limits on large downloads. Placeholders used in examples: <APIFY_TOKEN>, <PROXY_USER:PASS@HOST:PORT> --- ## ▶️ How to Run (Console, CLI, API) Console * Paste the JSON input and click Run Actor. CLI bash apify run --input input.example.json API (see Quick Start above) — use apify-client to call the actor with a JSON payload. Results are available in the Dataset and OUTPUT KV. --- ## ⏰ Scheduling & Webhooks * Use the Apify Console scheduler to run on a cron schedule. * Configure a Webhook in the Console to receive run-completed notifications (e.g., to trigger downstream processing or a notification system). --- ## 🕾️ Logs & Troubleshooting * Console logs stream live while the run executes. * Common failures: blocked requests (geo-restrictions, sign-in required), missing video_urls, malformed input, or memory limits when merging large files. * If a run returns an error for a URL, re-run with use_apify_proxy: true and/or provide cookies as a secret. * If you see persistent HTTP 403/429 errors, try using Apify Proxy or add credentials via cookies. --- ## 🔒 Permissions & Storage Notes * The Actor does not store secrets in plaintext in logs. Always provide cookies or proxy credentials as Console secrets. * If using download_and_upload, be mindful of storage consumption (key-value store & dataset quotas). Files uploaded to the Key-Value store are persisted; cleaning policies should be applied if needed. --- ## 🔟 Changelog / Versioning * v1.0 — Initial production-ready release: metadata extraction, merged/video/audio link selection, download+upload option, filename templating, concurrency control, proxy and cookie fallback flows. --- ## 🖌 Notes / TODOs * TODO: Confirm exact semantics for filename_template placeholders across platforms (marked here to verify formatting rules). * TODO: Add CDNs / post-processing examples for download_and_upload flows (e.g., how to move files from KV to external storage). --- ## 🌍 Proxy Configuration This Actor supports Apify Proxy and custom proxies. Quick enable (Console): * In the Apify Console Run form, toggle Use Apify Proxy or set use_apify_proxy: true in the input. The Actor will automatically request a proxy URL from the Apify Proxy service. Custom proxy example (set as environment variables or in input via proxy object): bash # Common environment variables export HTTP_PROXY="http://<PROXY_USER:PASS@HOST:PORT>" export HTTPS_PROXY="http://<PROXY_USER:PASS@HOST:PORT>" Input-level proxy (example placeholder) json {"proxy": {"useApifyProxy": false, "proxyUrl": "http://<PROXY_USER:PASS@HOST:PORT>"}} Security notes: Store proxy credentials as Console secrets — never paste them as plaintext in public inputs or logs. Advanced: TODO: Consider proxy rotation for large-scale scraping or high-volume runs. --- ## 📚 References * Apify Actor README best practices — (official Apify Console docs) * Apify input/output schema docs — (official Apify docs) * Apify CLI & apify-client usage — (official Apify docs) --- ## 🤔 What I inferred from actor.json * This Actor schema (actor.json) defines: output_format choices (webm,mp4,mkv), download_mode (direct links vs download_and_upload), storage_target (key_value_store or dataset), concurrency limits (1–8), filename templating and secret cookies. * Runtime memory hints (minMemoryMbytes / maxMemoryMbytes) are included to help users tune concurrency and format choices. * TODOs: confirm filename_template formatting rules and add post-processing examples for uploaded files. --- # input.example.json json { "video_urls": [ {"url": "https://www.youtube.com/watch?v=EXAMPLE1"}, {"url": "https://www.youtube.com/watch?v=EXAMPLE2"} ], "output_types": ["merged", "links_only"], "output_format": "webm", "download_mode": "direct_links", "storage_target": "key_value_store", "include_subtitles": false, "concurrency": 2, "use_apify_proxy": true, "filename_template": "{uploader}_{upload_date}_{id}.{ext}" } # CONFIG.md # CONFIG.md — Quick deploy notes * Set your APIFY_TOKEN in your environment or Console secrets before using the CLI or API. * Replace placeholders like <APIFY_TOKEN> and <PROXY_USER:PASS@HOST:PORT> with your secrets stored securely. * If you plan large-scale runs, increase concurrency cautiously and enable proxy rotation (see TODO in README). * Note the Actor's memory footprint: minMemoryMbytes: 256, maxMemoryMbytes: 4096. Increase memory when merging high-resolution streams or processing many concurrent downloads. ---