---

🌟 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)

# Runs the actor with an input file and prints run summary
apify run --input input.example.json

Python (apify-client) — minimal example

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

{
  "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	"<COOKIE_FILE_CONTENT>"	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)

{
  "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)

{
  "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

$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):

# 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)

{"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

{
  "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.

---