{
  "data": {
    "id": "tyaMzg62TcJZfZ4Pv",
    "actId": "2Dxwy6cHWqWRHqhC9",
    "userId": "IYgBDiXtHOijAaUel",
    "startedAt": "2026-10-24T16:30:00.514Z",
    "finishedAt": "2026-10-24T16:30:13.765Z",
    "status": "SUCCEEDED",
    "meta": {
      "origin": "CLI"
    },
    "stats": {
      "durationMillis": 13141,
      "runTimeSecs": 13.141,
      "computeUnits": 0.014601111111111112,
      "imageSizeBytes": 891428864
    },
    "options": {
      "useCache": true,
      "betaPackages": false,
      "memoryMbytes": 4096,
      "diskMbytes": 8192
    },
    "createdByOrganizationMemberUserId": "QYo53EZkJk0prePWY",
    "exitCode": 0,
    "inputSchema": "{\n  \"title\": \"YouTube Video Downloader Input\",\n  \"description\": \"Download metadata, video, audio, or captions for YouTube content you own or are authorized to download.\",\n  \"type\": \"object\",\n  \"schemaVersion\": 1,\n  \"properties\": {\n    \"mode\": {\n      \"title\": \"Mode\",\n      \"type\": \"string\",\n      \"description\": \"What to return: metadata only, media files, or caption files without media.\",\n      \"editor\": \"select\",\n      \"enum\": [\n        \"metadata\",\n        \"download\",\n        \"subtitles\"\n      ],\n      \"enumTitles\": [\n        \"Metadata only\",\n        \"Download media\",\n        \"Subtitles only\"\n      ],\n      \"default\": \"metadata\",\n      \"prefill\": \"metadata\"\n    },\n    \"videoUrls\": {\n      \"title\": \"Video URLs\",\n      \"type\": \"array\",\n      \"description\": \"Direct YouTube video, Shorts, live-replay, or youtu.be URLs, or 11-character video IDs.\",\n      \"editor\": \"stringList\",\n      \"items\": {\n        \"type\": \"string\"\n      },\n      \"default\": [],\n      \"prefill\": [\n        \"https://www.youtube.com/watch?v=jNQXAC9IVRw\"\n      ]\n    },\n    \"playlistUrls\": {\n      \"title\": \"Playlist URLs\",\n      \"type\": \"array\",\n      \"description\": \"YouTube playlist URLs. Videos are expanded up to maxVideos in total.\",\n      \"editor\": \"stringList\",\n      \"items\": {\n        \"type\": \"string\"\n      },\n      \"default\": [],\n      \"prefill\": []\n    },\n    \"channelUrls\": {\n      \"title\": \"Channel URLs\",\n      \"type\": \"array\",\n      \"description\": \"YouTube channel URLs, @handles, or UC channel IDs. The Videos tab is used.\",\n      \"editor\": \"stringList\",\n      \"items\": {\n        \"type\": \"string\"\n      },\n      \"default\": [],\n      \"prefill\": []\n    },\n    \"searchQueries\": {\n      \"title\": \"Search Queries\",\n      \"type\": \"array\",\n      \"description\": \"YouTube search phrases. Each query resolves public results up to maxVideos in total.\",\n      \"editor\": \"stringList\",\n      \"items\": {\n        \"type\": \"string\"\n      },\n      \"default\": [],\n      \"prefill\": []\n    },\n    \"videoQuality\": {\n      \"title\": \"Video Quality\",\n      \"type\": \"string\",\n      \"description\": \"SDR target quality. 360p-1080p prefer H.264/AAC MP4. 1440p and 2160p require allow4K and are delivered with their real codec and container.\",\n      \"editor\": \"select\",\n      \"enum\": [\n        \"360p\",\n        \"480p\",\n        \"720p\",\n        \"1080p\",\n        \"1440p\",\n        \"2160p\",\n        \"best\"\n      ],\n      \"enumTitles\": [\n        \"360p\",\n        \"480p\",\n        \"720p (default)\",\n        \"1080p\",\n        \"1440p (requires allow4K)\",\n        \"2160p / 4K (requires allow4K)\",\n        \"Best available (capped at 1080p unless allow4K)\"\n      ],\n      \"default\": \"720p\",\n      \"prefill\": \"360p\"\n    },\n    \"container\": {\n      \"title\": \"Container\",\n      \"type\": \"string\",\n      \"description\": \"Auto uses MP4 H.264/AAC when available and MKV for VP9/AV1. Explicit MP4 never relabels AV1/Opus content as MP4; if no compatible stream exists the video gets a failure row.\",\n      \"editor\": \"select\",\n      \"enum\": [\n        \"auto\",\n        \"mp4\",\n        \"webm\",\n        \"mkv\"\n      ],\n      \"enumTitles\": [\n        \"Auto (compatible first)\",\n        \"MP4 (H.264/AAC)\",\n        \"WebM (VP9/AV1 + Opus)\",\n        \"MKV (any codec)\"\n      ],\n      \"default\": \"auto\",\n      \"prefill\": \"auto\"\n    },\n    \"audioOnly\": {\n      \"title\": \"Audio Only\",\n      \"type\": \"boolean\",\n      \"description\": \"Download the source audio track without video and without re-encoding.\",\n      \"default\": false,\n      \"prefill\": false\n    },\n    \"audioFormat\": {\n      \"title\": \"Audio Format\",\n      \"type\": \"string\",\n      \"description\": \"Source audio passthrough format used when audioOnly is enabled.\",\n      \"editor\": \"select\",\n      \"enum\": [\n        \"m4a\",\n        \"opus\"\n      ],\n      \"enumTitles\": [\n        \"M4A (AAC passthrough)\",\n        \"Opus (passthrough)\"\n      ],\n      \"default\": \"m4a\",\n      \"prefill\": \"m4a\"\n    },\n    \"downloadSubtitles\": {\n      \"title\": \"Download Subtitles\",\n      \"type\": \"boolean\",\n      \"description\": \"Fetch available manual or automatic captions for the requested languages.\",\n      \"default\": false,\n      \"prefill\": false\n    },\n    \"subtitleLanguages\": {\n      \"title\": \"Subtitle Languages\",\n      \"type\": \"array\",\n      \"description\": \"Caption language codes to request. Only tracks that already exist on the video are used; translations are not promised.\",\n      \"editor\": \"select\",\n      \"items\": {\n        \"type\": \"string\",\n        \"enum\": [\n          \"en\",\n          \"en-US\",\n          \"en-GB\",\n          \"es\",\n          \"es-419\",\n          \"pt\",\n          \"pt-BR\",\n          \"fr\",\n          \"de\",\n          \"it\",\n          \"nl\",\n          \"pl\",\n          \"ru\",\n          \"uk\",\n          \"tr\",\n          \"ar\",\n          \"fa\",\n          \"he\",\n          \"hi\",\n          \"bn\",\n          \"ta\",\n          \"te\",\n          \"mr\",\n          \"ur\",\n          \"gu\",\n          \"kn\",\n          \"ml\",\n          \"pa\",\n          \"zh-Hans\",\n          \"zh-Hant\",\n          \"ja\",\n          \"ko\",\n          \"vi\",\n          \"th\",\n          \"id\",\n          \"ms\",\n          \"fil\",\n          \"sv\",\n          \"no\",\n          \"da\",\n          \"fi\",\n          \"cs\",\n          \"sk\",\n          \"hu\",\n          \"ro\",\n          \"bg\",\n          \"el\",\n          \"hr\",\n          \"sr\",\n          \"sl\",\n          \"lt\",\n          \"lv\",\n          \"et\",\n          \"is\",\n          \"sq\",\n          \"mk\",\n          \"bs\",\n          \"ca\",\n          \"gl\",\n          \"eu\",\n          \"af\",\n          \"sw\",\n          \"am\",\n          \"km\",\n          \"lo\",\n          \"my\",\n          \"ne\",\n          \"si\",\n          \"ka\",\n          \"hy\",\n          \"az\",\n          \"kk\",\n          \"ky\",\n          \"uz\",\n          \"mn\",\n          \"mt\",\n          \"cy\",\n          \"ga\"\n        ],\n        \"enumTitles\": [\n          \"English\",\n          \"English (US)\",\n          \"English (UK)\",\n          \"Spanish\",\n          \"Spanish (Latin America)\",\n          \"Portuguese\",\n          \"Portuguese (Brazil)\",\n          \"French\",\n          \"German\",\n          \"Italian\",\n          \"Dutch\",\n          \"Polish\",\n          \"Russian\",\n          \"Ukrainian\",\n          \"Turkish\",\n          \"Arabic\",\n          \"Persian\",\n          \"Hebrew\",\n          \"Hindi\",\n          \"Bengali\",\n          \"Tamil\",\n          \"Telugu\",\n          \"Marathi\",\n          \"Urdu\",\n          \"Gujarati\",\n          \"Kannada\",\n          \"Malayalam\",\n          \"Punjabi\",\n          \"Chinese (Simplified)\",\n          \"Chinese (Traditional)\",\n          \"Japanese\",\n          \"Korean\",\n          \"Vietnamese\",\n          \"Thai\",\n          \"Indonesian\",\n          \"Malay\",\n          \"Filipino\",\n          \"Swedish\",\n          \"Norwegian\",\n          \"Danish\",\n          \"Finnish\",\n          \"Czech\",\n          \"Slovak\",\n          \"Hungarian\",\n          \"Romanian\",\n          \"Bulgarian\",\n          \"Greek\",\n          \"Croatian\",\n          \"Serbian\",\n          \"Slovenian\",\n          \"Lithuanian\",\n          \"Latvian\",\n          \"Estonian\",\n          \"Icelandic\",\n          \"Albanian\",\n          \"Macedonian\",\n          \"Bosnian\",\n          \"Catalan\",\n          \"Galician\",\n          \"Basque\",\n          \"Afrikaans\",\n          \"Swahili\",\n          \"Amharic\",\n          \"Khmer\",\n          \"Lao\",\n          \"Burmese\",\n          \"Nepali\",\n          \"Sinhala\",\n          \"Georgian\",\n          \"Armenian\",\n          \"Azerbaijani\",\n          \"Kazakh\",\n          \"Kyrgyz\",\n          \"Uzbek\",\n          \"Mongolian\",\n          \"Maltese\",\n          \"Welsh\",\n          \"Irish\"\n        ]\n      },\n      \"default\": [\n        \"en\"\n      ],\n      \"prefill\": [\n        \"en\"\n      ]\n    },\n    \"subtitleFormat\": {\n      \"title\": \"Subtitle Format\",\n      \"type\": \"string\",\n      \"description\": \"File format for downloaded captions.\",\n      \"editor\": \"select\",\n      \"enum\": [\n        \"vtt\",\n        \"srt\"\n      ],\n      \"enumTitles\": [\n        \"WebVTT (.vtt)\",\n        \"SubRip (.srt)\"\n      ],\n      \"default\": \"vtt\",\n      \"prefill\": \"vtt\"\n    },\n    \"includeTranscript\": {\n      \"title\": \"Include Transcript Text\",\n      \"type\": \"boolean\",\n      \"description\": \"Add a plain-text transcript from the first requested caption track.\",\n      \"default\": false,\n      \"prefill\": false\n    },\n    \"maxVideos\": {\n      \"title\": \"Max Videos\",\n      \"type\": \"integer\",\n      \"description\": \"Total videos processed across all inputs.\",\n      \"default\": 10,\n      \"minimum\": 1,\n      \"maximum\": 50,\n      \"prefill\": 1\n    },\n    \"maxMinutes\": {\n      \"title\": \"Max Minutes Per Video\",\n      \"type\": \"integer\",\n      \"description\": \"Reject a video before download when its duration exceeds this cap. 4K opt-in downloads are additionally capped at 10 minutes.\",\n      \"default\": 30,\n      \"minimum\": 1,\n      \"maximum\": 30,\n      \"prefill\": 30\n    },\n    \"maxMB\": {\n      \"title\": \"Max MB Per Video\",\n      \"type\": \"integer\",\n      \"description\": \"Reject oversized downloads. Values above 500 are only used for 4K opt-in downloads, which are capped at 1000 MB.\",\n      \"default\": 500,\n      \"minimum\": 1,\n      \"maximum\": 1000,\n      \"prefill\": 100\n    },\n    \"allow4K\": {\n      \"title\": \"Allow 4K\",\n      \"type\": \"boolean\",\n      \"description\": \"Enable 1440p/2160p SDR downloads. These are capped at 10 minutes and 1000 MB and may use MKV with VP9/AV1 because YouTube rarely serves H.264 above 1080p.\",\n      \"default\": false,\n      \"prefill\": false\n    },\n    \"storage\": {\n      \"title\": \"Storage\",\n      \"type\": \"string\",\n      \"description\": \"Where downloaded files are written. Named KVS persists while the store exists; ephemeral KVS follows your Apify account retention.\",\n      \"editor\": \"select\",\n      \"enum\": [\n        \"ephemeral_kvs\",\n        \"named_kvs\",\n        \"s3\"\n      ],\n      \"enumTitles\": [\n        \"Ephemeral Apify KVS\",\n        \"Named Apify KVS\",\n        \"S3 or S3-compatible (R2)\"\n      ],\n      \"default\": \"ephemeral_kvs\",\n      \"prefill\": \"ephemeral_kvs\"\n    },\n    \"kvsName\": {\n      \"title\": \"KVS Name\",\n      \"type\": \"string\",\n      \"description\": \"Named key-value store name when storage=named_kvs. Defaults to youtube-downloader.\",\n      \"default\": \"\",\n      \"prefill\": \"\",\n      \"editor\": \"textfield\"\n    },\n    \"storageRetentionDays\": {\n      \"title\": \"Storage Retention Days\",\n      \"type\": \"integer\",\n      \"description\": \"Signed-link lifetime for S3/R2 storage (1-7 days). KVS retention is controlled by your Apify account.\",\n      \"default\": 7,\n      \"minimum\": 1,\n      \"maximum\": 7,\n      \"prefill\": 7\n    },\n    \"s3Bucket\": {\n      \"title\": \"S3 Bucket\",\n      \"type\": \"string\",\n      \"description\": \"Bucket name when storage=s3.\",\n      \"editor\": \"textfield\"\n    },\n    \"s3Prefix\": {\n      \"title\": \"S3 Prefix\",\n      \"type\": \"string\",\n      \"description\": \"Object key prefix when storage=s3.\",\n      \"default\": \"youtube-downloader\",\n      \"prefill\": \"youtube-downloader\",\n      \"editor\": \"textfield\"\n    },\n    \"s3Endpoint\": {\n      \"title\": \"S3 Endpoint\",\n      \"type\": \"string\",\n      \"description\": \"Custom endpoint for S3-compatible storage such as Cloudflare R2.\",\n      \"editor\": \"textfield\"\n    },\n    \"s3Region\": {\n      \"title\": \"S3 Region\",\n      \"type\": \"string\",\n      \"description\": \"Region for S3 or S3-compatible storage.\",\n      \"default\": \"auto\",\n      \"prefill\": \"auto\",\n      \"editor\": \"textfield\"\n    },\n    \"s3AccessKeyId\": {\n      \"title\": \"S3 Access Key ID\",\n      \"type\": \"string\",\n      \"editor\": \"textfield\",\n      \"isSecret\": true,\n      \"description\": \"Optional access key ID when storage=s3.\"\n    },\n    \"s3SecretAccessKey\": {\n      \"title\": \"S3 Secret Access Key\",\n      \"type\": \"string\",\n      \"editor\": \"textfield\",\n      \"isSecret\": true,\n      \"description\": \"Optional secret access key when storage=s3.\"\n    },\n    \"s3PublicBaseUrl\": {\n      \"title\": \"S3 Public Base URL\",\n      \"type\": \"string\",\n      \"description\": \"Optional public bucket URL. When set, files use public URLs instead of expiring presigned URLs.\",\n      \"editor\": \"textfield\"\n    },\n    \"cookies\": {\n      \"title\": \"Cookies (Netscape format)\",\n      \"type\": \"string\",\n      \"description\": \"Optional cookies.txt content for age-restricted or members-only videos. Public videos work without cookies.\",\n      \"editor\": \"textarea\",\n      \"isSecret\": true\n    },\n    \"proxyConfiguration\": {\n      \"title\": \"Proxy Configuration\",\n      \"type\": \"object\",\n      \"description\": \"Optional. Metadata and player extraction use this connection; media bytes are downloaded directly.\",\n      \"editor\": \"proxy\",\n      \"default\": {\n        \"useApifyProxy\": true\n      },\n      \"prefill\": {\n        \"useApifyProxy\": true\n      }\n    }\n  },\n  \"required\": [\n    \"mode\"\n  ]\n}",
    "readme": "# YouTube Video, Playlist & Channel Downloader with Metadata\r\n\r\nInspect or download YouTube videos from a direct link, a playlist, a channel, or a search phrase in one run. Every row carries the video's metadata, and download rows add a readable file link, the real container and codec, the requested and delivered quality, captions, and an optional transcript.\r\n\r\nUse this actor only for content you own or are authorized to download. YouTube's Terms of Service may prohibit downloading content without permission, and you are responsible for complying with them. This actor is not affiliated with YouTube or Google, and it does not bypass DRM, private-video access, or geographic restrictions.\r\n\r\n## What this actor does\r\n\r\n- **Four input paths:** direct video URLs, playlists, channels, and keyword search\r\n- **Metadata, download, or subtitles:** choose what each run returns\r\n- **Compatible video:** SDR 360p-1080p H.264/AAC MP4 when YouTube provides it\r\n- **Opt-in 4K:** 1440p/2160p SDR with a 10-minute and 1000 MB cap\r\n- **Audio passthrough:** M4A (AAC) or Opus, without a fake bitrate uplift\r\n- **Captions and transcript:** WebVTT, SubRip, or plain text\r\n- **Honest failures:** rows explain private, live, DRM, geo-blocked, oversized, and unavailable videos\r\n- **Empty fields are omitted** — records only contain values that are actually populated\r\n\r\n## Output per video\r\n\r\n- `record_type` — `video`, `failure`, or `input_error`\r\n- `video_url`, `video_id`, `title`, `description`\r\n- `uploader`, `uploader_id`, `uploader_url`, `channel_id`\r\n- `upload_date`, `duration_seconds`\r\n- `view_count`, `like_count`, `comment_count`\r\n- `thumbnail`, `tags[]`, `categories[]`, `is_live`\r\n- `playlist_index` — position inside a playlist, channel listing, or search result\r\n- `source_label` — `direct`, `playlist:...`, `channel:...`, or `search:...`\r\n- `download_status` — `success`, `metadata_only`, `subtitles_only`, `failed`, `skipped_unsupported`, or `upload_failed`\r\n- `failure_code` — e.g. `private`, `removed`, `live_unsupported`, `drm_unsupported`, `geo_blocked`, `bot_check`, `too_long`, `too_large`, `no_formats`, `upload_failed`, `no_captions`, `captions_unavailable`\r\n- `error`, `retryable`\r\n- `requested_quality`, `delivered_quality`, `quality_match`\r\n- `container`, `vcodec`, `acodec`, `dynamic_range`, `is_hdr`\r\n- `width`, `height`, `resolution`, `fps`, `aspect_ratio`, `audio_only`\r\n- `filesize_bytes`, `total_bitrate_kbps`, `checksum_sha256`\r\n- `download_url`, `storage_key`, `storage_mode`, `expires_at`\r\n- `four_k_cap_applied` — present when the 4K duration/size cap governed the row\r\n- `subtitle_files[]`, `subtitle_urls[]`, `subtitle_languages[]`, `caption_kind`\r\n- `caption_status` — `no_captions`, `captions_unavailable`, or `upload_failed` when no caption file was produced\r\n- `transcript` — when transcript output is requested\r\n- `video_meta` — nested technical details for the downloaded file\r\n- `downloaded_at`\r\n- `search_query` — on an input-error row for an empty search result\r\n\r\n## Input\r\n\r\n| Field | Type | Default | Description |\r\n|---|---|---|---|\r\n| `mode` | string | `metadata` | `metadata`, `download`, or `subtitles` |\r\n| `videoUrls` | array | — | Direct video, Shorts, replay, `youtu.be` URLs, or 11-character IDs |\r\n| `playlistUrls` | array | — | Playlist URLs |\r\n| `channelUrls` | array | — | Channel URLs, `@handles`, or `UC...` IDs |\r\n| `searchQueries` | array | — | Search phrases |\r\n| `videoQuality` | string | `720p` | `360p`, `480p`, `720p`, `1080p`, `1440p`, `2160p`, or `best` |\r\n| `container` | string | `auto` | `auto`, `mp4`, `webm`, or `mkv` |\r\n| `audioOnly` | boolean | `false` | Download source audio only |\r\n| `audioFormat` | string | `m4a` | `m4a` (AAC) or `opus` |\r\n| `downloadSubtitles` | boolean | `false` | Fetch existing caption tracks |\r\n| `subtitleLanguages` | array | `[\"en\"]` | Language codes to request |\r\n| `subtitleFormat` | string | `vtt` | `vtt` or `srt` |\r\n| `includeTranscript` | boolean | `false` | Add a plain-text transcript |\r\n| `maxVideos` | integer | `10` | Total videos per run (1–50) |\r\n| `maxMinutes` | integer | `30` | Per-video duration cap (1–30) |\r\n| `maxMB` | integer | `500` | Per-video size cap; 4K opt-in allows up to 1000 |\r\n| `allow4K` | boolean | `false` | Enable 1440p/2160p SDR |\r\n| `storage` | string | `ephemeral_kvs` | `ephemeral_kvs`, `named_kvs`, or `s3` |\r\n| `kvsName` | string | — | Named KVS name |\r\n| `storageRetentionDays` | integer | `7` | Presigned S3/R2 link lifetime (1–7 days) |\r\n| `s3Bucket`, `s3Prefix`, `s3Endpoint`, `s3Region` | string | — | S3 or R2 destination |\r\n| `s3AccessKeyId`, `s3SecretAccessKey` | secret | — | Optional S3/R2 credentials |\r\n| `s3PublicBaseUrl` | string | — | Use public bucket URLs instead of presigned links |\r\n| `cookies` | secret | — | Optional Netscape cookies for authorized age-restricted or members-only access |\r\n| `proxyConfiguration` | object | automatic | Optional connection override |\r\n\r\n## Examples\r\n\r\n### Metadata for one video\r\n\r\n```json\r\n{\r\n  \"mode\": \"metadata\",\r\n  \"videoUrls\": [\"https://www.youtube.com/watch?v=jNQXAC9IVRw\"]\r\n}\r\n```\r\n\r\n### Download a 720p MP4\r\n\r\n```json\r\n{\r\n  \"mode\": \"download\",\r\n  \"videoUrls\": [\"https://www.youtube.com/watch?v=dQw4w9WgXcQ\"],\r\n  \"videoQuality\": \"720p\",\r\n  \"container\": \"mp4\",\r\n  \"maxVideos\": 1\r\n}\r\n```\r\n\r\n### Playlist with captions and transcript\r\n\r\n```json\r\n{\r\n  \"mode\": \"download\",\r\n  \"playlistUrls\": [\"https://www.youtube.com/playlist?list=PLFgquLnL59alCl_2TQvOiD5Vgm1hCaGSI\"],\r\n  \"videoQuality\": \"480p\",\r\n  \"maxVideos\": 5,\r\n  \"downloadSubtitles\": true,\r\n  \"subtitleLanguages\": [\"en\"],\r\n  \"subtitleFormat\": \"srt\",\r\n  \"includeTranscript\": true\r\n}\r\n```\r\n\r\n### Search to audio\r\n\r\n```json\r\n{\r\n  \"mode\": \"download\",\r\n  \"searchQueries\": [\"public domain jazz\"],\r\n  \"audioOnly\": true,\r\n  \"audioFormat\": \"m4a\",\r\n  \"maxVideos\": 3\r\n}\r\n```\r\n\r\n### Opt-in 4K SDR\r\n\r\n```json\r\n{\r\n  \"mode\": \"download\",\r\n  \"videoUrls\": [\"https://www.youtube.com/watch?v=LXb3EKWsInQ\"],\r\n  \"videoQuality\": \"2160p\",\r\n  \"container\": \"auto\",\r\n  \"allow4K\": true,\r\n  \"maxMinutes\": 10,\r\n  \"maxMB\": 1000\r\n}\r\n```\r\n\r\n## Use cases\r\n\r\n- **Own-channel archiving** — export metadata, captions, and small compatible files for channels you manage\r\n- **Authorized media research** — collect titles, descriptions, dates, and public statistics for analysis\r\n- **Caption workflows** — pull existing VTT or SRT tracks and transcript text for translation or accessibility\r\n- **Audio libraries** — save authorized M4A or Opus audio without re-encoding\r\n- **Content audits** — compare requested and delivered quality, codecs, and file sizes\r\n- **Pipeline integrations** — one row per video with stable status and failure fields\r\n\r\n## FAQ\r\n\r\n### What can I download with this actor?\r\n\r\nContent you own or are authorized to download. The actor does not grant rights to third-party media and does not bypass DRM, private access, or geographic restrictions.\r\n\r\n### Does it support live streams?\r\n\r\nNo. Live and upcoming broadcasts have no finite file and are returned as `live_unsupported` failure rows.\r\n\r\n### Can I download age-restricted or members-only videos?\r\n\r\nSometimes, when you have authorized access and supply your own cookies. Public videos work without cookies.\r\n\r\n### Does it bypass geo-blocks or DRM?\r\n\r\nNo. Geo-restricted and DRM-protected videos are reported as failure rows. Changing proxy settings is not a guaranteed workaround.\r\n\r\n### Where is the MP3 option?\r\n\r\nThere is no MP3 option because YouTube does not serve 320 kbps MP3. The actor passes through the source M4A (AAC) or Opus audio track and reports the real codec. Claiming a higher bitrate would only mean re-encoding and inflating the file.\r\n\r\n### Why did I get 480p when I asked for 720p?\r\n\r\nNot every video has every resolution. The actor delivers the closest available quality at or below your request and sets `quality_match` to `false` when it had to step down.\r\n\r\n### Why is my 4K file MKV or WebM instead of MP4?\r\n\r\nYouTube usually serves 1440p and 2160p as VP9 or AV1 video, often with Opus audio. Those streams are not H.264/AAC MP4. The actor keeps the real codec and container instead of mislabelling a file. Choose `container: \"auto\"` or `mkv` for 4K.\r\n\r\n### What are the download caps?\r\n\r\nEach video is capped at 30 minutes and 500 MB by default, with at most 50 videos per run. Opt-in 4K is capped at 10 minutes and 1000 MB. A video outside the caps gets a `too_long` or `too_large` failure row instead of a partial file.\r\n\r\n### How long do download links last?\r\n\r\nEphemeral KVS links follow your Apify account's key-value store retention. Named KVS persists while the store exists. S3/R2 links are presigned for the configured retention period, or permanent when a public bucket URL is configured. KVS file URLs do not support HTTP Range requests, so use S3/R2 when a downstream system needs resumable or partial downloads.\r\n\r\n### Do I need to set up a proxy?\r\n\r\nNo. The actor chooses a working connection automatically for metadata and player access. Media bytes are fetched directly whenever possible.\r\n\r\n### What happens when a video fails?\r\n\r\nThe run continues and writes a failure row with `failure_code`, `error`, and `retryable`. A failed row never claims a download link.\r\n\r\n### Is this affiliated with YouTube?\r\n\r\nNo. This is an independent third-party tool and is not affiliated with, endorsed by, or sponsored by YouTube or Google.\r\n",
    "actorDefinition": {
      "actorSpecification": 1,
      "name": "youtube-video-playlist-and-channel-downloader",
      "title": "YouTube Video, Playlist & Channel Downloader with Metadata",
      "description": "Download or inspect YouTube videos from direct links, playlists, channels, or search phrases. Get metadata, H.264/AAC MP4 up to 1080p, M4A/Opus audio, VTT/SRT captions, and transcripts for content you own or are authorized to download.",
      "version": "1.0",
      "buildTag": "latest",
      "meta": {
        "templateId": "python-start"
      },
      "input": {
        "title": "YouTube Video Downloader Input",
        "description": "Download metadata, video, audio, or captions for YouTube content you own or are authorized to download.",
        "type": "object",
        "schemaVersion": 1,
        "properties": {
          "mode": {
            "title": "Mode",
            "type": "string",
            "description": "What to return: metadata only, media files, or caption files without media.",
            "editor": "select",
            "enum": [
              "metadata",
              "download",
              "subtitles"
            ],
            "enumTitles": [
              "Metadata only",
              "Download media",
              "Subtitles only"
            ],
            "default": "metadata",
            "prefill": "metadata"
          },
          "videoUrls": {
            "title": "Video URLs",
            "type": "array",
            "description": "Direct YouTube video, Shorts, live-replay, or youtu.be URLs, or 11-character video IDs.",
            "editor": "stringList",
            "items": {
              "type": "string"
            },
            "default": [],
            "prefill": [
              "https://www.youtube.com/watch?v=jNQXAC9IVRw"
            ]
          },
          "playlistUrls": {
            "title": "Playlist URLs",
            "type": "array",
            "description": "YouTube playlist URLs. Videos are expanded up to maxVideos in total.",
            "editor": "stringList",
            "items": {
              "type": "string"
            },
            "default": [],
            "prefill": []
          },
          "channelUrls": {
            "title": "Channel URLs",
            "type": "array",
            "description": "YouTube channel URLs, @handles, or UC channel IDs. The Videos tab is used.",
            "editor": "stringList",
            "items": {
              "type": "string"
            },
            "default": [],
            "prefill": []
          },
          "searchQueries": {
            "title": "Search Queries",
            "type": "array",
            "description": "YouTube search phrases. Each query resolves public results up to maxVideos in total.",
            "editor": "stringList",
            "items": {
              "type": "string"
            },
            "default": [],
            "prefill": []
          },
          "videoQuality": {
            "title": "Video Quality",
            "type": "string",
            "description": "SDR target quality. 360p-1080p prefer H.264/AAC MP4. 1440p and 2160p require allow4K and are delivered with their real codec and container.",
            "editor": "select",
            "enum": [
              "360p",
              "480p",
              "720p",
              "1080p",
              "1440p",
              "2160p",
              "best"
            ],
            "enumTitles": [
              "360p",
              "480p",
              "720p (default)",
              "1080p",
              "1440p (requires allow4K)",
              "2160p / 4K (requires allow4K)",
              "Best available (capped at 1080p unless allow4K)"
            ],
            "default": "720p",
            "prefill": "360p"
          },
          "container": {
            "title": "Container",
            "type": "string",
            "description": "Auto uses MP4 H.264/AAC when available and MKV for VP9/AV1. Explicit MP4 never relabels AV1/Opus content as MP4; if no compatible stream exists the video gets a failure row.",
            "editor": "select",
            "enum": [
              "auto",
              "mp4",
              "webm",
              "mkv"
            ],
            "enumTitles": [
              "Auto (compatible first)",
              "MP4 (H.264/AAC)",
              "WebM (VP9/AV1 + Opus)",
              "MKV (any codec)"
            ],
            "default": "auto",
            "prefill": "auto"
          },
          "audioOnly": {
            "title": "Audio Only",
            "type": "boolean",
            "description": "Download the source audio track without video and without re-encoding.",
            "default": false,
            "prefill": false
          },
          "audioFormat": {
            "title": "Audio Format",
            "type": "string",
            "description": "Source audio passthrough format used when audioOnly is enabled.",
            "editor": "select",
            "enum": [
              "m4a",
              "opus"
            ],
            "enumTitles": [
              "M4A (AAC passthrough)",
              "Opus (passthrough)"
            ],
            "default": "m4a",
            "prefill": "m4a"
          },
          "downloadSubtitles": {
            "title": "Download Subtitles",
            "type": "boolean",
            "description": "Fetch available manual or automatic captions for the requested languages.",
            "default": false,
            "prefill": false
          },
          "subtitleLanguages": {
            "title": "Subtitle Languages",
            "type": "array",
            "description": "Caption language codes to request. Only tracks that already exist on the video are used; translations are not promised.",
            "editor": "select",
            "items": {
              "type": "string",
              "enum": [
                "en",
                "en-US",
                "en-GB",
                "es",
                "es-419",
                "pt",
                "pt-BR",
                "fr",
                "de",
                "it",
                "nl",
                "pl",
                "ru",
                "uk",
                "tr",
                "ar",
                "fa",
                "he",
                "hi",
                "bn",
                "ta",
                "te",
                "mr",
                "ur",
                "gu",
                "kn",
                "ml",
                "pa",
                "zh-Hans",
                "zh-Hant",
                "ja",
                "ko",
                "vi",
                "th",
                "id",
                "ms",
                "fil",
                "sv",
                "no",
                "da",
                "fi",
                "cs",
                "sk",
                "hu",
                "ro",
                "bg",
                "el",
                "hr",
                "sr",
                "sl",
                "lt",
                "lv",
                "et",
                "is",
                "sq",
                "mk",
                "bs",
                "ca",
                "gl",
                "eu",
                "af",
                "sw",
                "am",
                "km",
                "lo",
                "my",
                "ne",
                "si",
                "ka",
                "hy",
                "az",
                "kk",
                "ky",
                "uz",
                "mn",
                "mt",
                "cy",
                "ga"
              ],
              "enumTitles": [
                "English",
                "English (US)",
                "English (UK)",
                "Spanish",
                "Spanish (Latin America)",
                "Portuguese",
                "Portuguese (Brazil)",
                "French",
                "German",
                "Italian",
                "Dutch",
                "Polish",
                "Russian",
                "Ukrainian",
                "Turkish",
                "Arabic",
                "Persian",
                "Hebrew",
                "Hindi",
                "Bengali",
                "Tamil",
                "Telugu",
                "Marathi",
                "Urdu",
                "Gujarati",
                "Kannada",
                "Malayalam",
                "Punjabi",
                "Chinese (Simplified)",
                "Chinese (Traditional)",
                "Japanese",
                "Korean",
                "Vietnamese",
                "Thai",
                "Indonesian",
                "Malay",
                "Filipino",
                "Swedish",
                "Norwegian",
                "Danish",
                "Finnish",
                "Czech",
                "Slovak",
                "Hungarian",
                "Romanian",
                "Bulgarian",
                "Greek",
                "Croatian",
                "Serbian",
                "Slovenian",
                "Lithuanian",
                "Latvian",
                "Estonian",
                "Icelandic",
                "Albanian",
                "Macedonian",
                "Bosnian",
                "Catalan",
                "Galician",
                "Basque",
                "Afrikaans",
                "Swahili",
                "Amharic",
                "Khmer",
                "Lao",
                "Burmese",
                "Nepali",
                "Sinhala",
                "Georgian",
                "Armenian",
                "Azerbaijani",
                "Kazakh",
                "Kyrgyz",
                "Uzbek",
                "Mongolian",
                "Maltese",
                "Welsh",
                "Irish"
              ]
            },
            "default": [
              "en"
            ],
            "prefill": [
              "en"
            ]
          },
          "subtitleFormat": {
            "title": "Subtitle Format",
            "type": "string",
            "description": "File format for downloaded captions.",
            "editor": "select",
            "enum": [
              "vtt",
              "srt"
            ],
            "enumTitles": [
              "WebVTT (.vtt)",
              "SubRip (.srt)"
            ],
            "default": "vtt",
            "prefill": "vtt"
          },
          "includeTranscript": {
            "title": "Include Transcript Text",
            "type": "boolean",
            "description": "Add a plain-text transcript from the first requested caption track.",
            "default": false,
            "prefill": false
          },
          "maxVideos": {
            "title": "Max Videos",
            "type": "integer",
            "description": "Total videos processed across all inputs.",
            "default": 10,
            "minimum": 1,
            "maximum": 50,
            "prefill": 1
          },
          "maxMinutes": {
            "title": "Max Minutes Per Video",
            "type": "integer",
            "description": "Reject a video before download when its duration exceeds this cap. 4K opt-in downloads are additionally capped at 10 minutes.",
            "default": 30,
            "minimum": 1,
            "maximum": 30,
            "prefill": 30
          },
          "maxMB": {
            "title": "Max MB Per Video",
            "type": "integer",
            "description": "Reject oversized downloads. Values above 500 are only used for 4K opt-in downloads, which are capped at 1000 MB.",
            "default": 500,
            "minimum": 1,
            "maximum": 1000,
            "prefill": 100
          },
          "allow4K": {
            "title": "Allow 4K",
            "type": "boolean",
            "description": "Enable 1440p/2160p SDR downloads. These are capped at 10 minutes and 1000 MB and may use MKV with VP9/AV1 because YouTube rarely serves H.264 above 1080p.",
            "default": false,
            "prefill": false
          },
          "storage": {
            "title": "Storage",
            "type": "string",
            "description": "Where downloaded files are written. Named KVS persists while the store exists; ephemeral KVS follows your Apify account retention.",
            "editor": "select",
            "enum": [
              "ephemeral_kvs",
              "named_kvs",
              "s3"
            ],
            "enumTitles": [
              "Ephemeral Apify KVS",
              "Named Apify KVS",
              "S3 or S3-compatible (R2)"
            ],
            "default": "ephemeral_kvs",
            "prefill": "ephemeral_kvs"
          },
          "kvsName": {
            "title": "KVS Name",
            "type": "string",
            "description": "Named key-value store name when storage=named_kvs. Defaults to youtube-downloader.",
            "default": "",
            "prefill": "",
            "editor": "textfield"
          },
          "storageRetentionDays": {
            "title": "Storage Retention Days",
            "type": "integer",
            "description": "Signed-link lifetime for S3/R2 storage (1-7 days). KVS retention is controlled by your Apify account.",
            "default": 7,
            "minimum": 1,
            "maximum": 7,
            "prefill": 7
          },
          "s3Bucket": {
            "title": "S3 Bucket",
            "type": "string",
            "description": "Bucket name when storage=s3.",
            "editor": "textfield"
          },
          "s3Prefix": {
            "title": "S3 Prefix",
            "type": "string",
            "description": "Object key prefix when storage=s3.",
            "default": "youtube-downloader",
            "prefill": "youtube-downloader",
            "editor": "textfield"
          },
          "s3Endpoint": {
            "title": "S3 Endpoint",
            "type": "string",
            "description": "Custom endpoint for S3-compatible storage such as Cloudflare R2.",
            "editor": "textfield"
          },
          "s3Region": {
            "title": "S3 Region",
            "type": "string",
            "description": "Region for S3 or S3-compatible storage.",
            "default": "auto",
            "prefill": "auto",
            "editor": "textfield"
          },
          "s3AccessKeyId": {
            "title": "S3 Access Key ID",
            "type": "string",
            "editor": "textfield",
            "isSecret": true,
            "description": "Optional access key ID when storage=s3."
          },
          "s3SecretAccessKey": {
            "title": "S3 Secret Access Key",
            "type": "string",
            "editor": "textfield",
            "isSecret": true,
            "description": "Optional secret access key when storage=s3."
          },
          "s3PublicBaseUrl": {
            "title": "S3 Public Base URL",
            "type": "string",
            "description": "Optional public bucket URL. When set, files use public URLs instead of expiring presigned URLs.",
            "editor": "textfield"
          },
          "cookies": {
            "title": "Cookies (Netscape format)",
            "type": "string",
            "description": "Optional cookies.txt content for age-restricted or members-only videos. Public videos work without cookies.",
            "editor": "textarea",
            "isSecret": true
          },
          "proxyConfiguration": {
            "title": "Proxy Configuration",
            "type": "object",
            "description": "Optional. Metadata and player extraction use this connection; media bytes are downloaded directly.",
            "editor": "proxy",
            "default": {
              "useApifyProxy": true
            },
            "prefill": {
              "useApifyProxy": true
            }
          }
        },
        "required": [
          "mode"
        ]
      },
      "output": {
        "actorOutputSchemaVersion": 1,
        "title": "YouTube Video, Playlist & Channel Downloader with Metadata Output",
        "description": "YouTube video metadata, media files, captions, transcripts, and honest failure rows.",
        "properties": {
          "videos": {
            "type": "string",
            "title": "YouTube Video Downloader dataset",
            "description": "Dataset containing one row per video, subtitle-only result, or failure.",
            "template": "{{links.apiDefaultDatasetUrl}}/items"
          }
        }
      },
      "dockerfile": "../Dockerfile",
      "defaultMemoryMbytes": 2048,
      "minMemoryMbytes": 1024,
      "storages": {
        "dataset": {
          "actorSpecification": 1,
          "views": {
            "overview": {
              "title": "YouTube Videos",
              "transformation": {
                "fields": [
                  "video_url",
                  "title",
                  "uploader",
                  "duration_seconds",
                  "download_status",
                  "failure_code",
                  "requested_quality",
                  "delivered_quality",
                  "resolution",
                  "filesize_bytes",
                  "download_url",
                  "storage_mode",
                  "downloaded_at"
                ]
              },
              "display": {
                "component": "table",
                "properties": {
                  "video_url": {
                    "label": "Video URL",
                    "format": "link"
                  },
                  "title": {
                    "label": "Title"
                  },
                  "uploader": {
                    "label": "Channel"
                  },
                  "duration_seconds": {
                    "label": "Duration (s)"
                  },
                  "download_status": {
                    "label": "Status"
                  },
                  "failure_code": {
                    "label": "Failure Code"
                  },
                  "requested_quality": {
                    "label": "Requested"
                  },
                  "delivered_quality": {
                    "label": "Delivered"
                  },
                  "resolution": {
                    "label": "Resolution"
                  },
                  "filesize_bytes": {
                    "label": "Bytes"
                  },
                  "download_url": {
                    "label": "Download Link",
                    "format": "link"
                  },
                  "storage_mode": {
                    "label": "Storage"
                  },
                  "downloaded_at": {
                    "label": "Processed At",
                    "format": "datetime"
                  }
                }
              }
            },
            "metadata": {
              "title": "Video Metadata",
              "transformation": {
                "fields": [
                  "video_url",
                  "video_id",
                  "title",
                  "description",
                  "uploader",
                  "upload_date",
                  "duration_seconds",
                  "view_count",
                  "like_count",
                  "comment_count",
                  "thumbnail",
                  "download_status",
                  "downloaded_at"
                ]
              },
              "display": {
                "component": "table",
                "properties": {
                  "video_url": {
                    "label": "Video URL",
                    "format": "link"
                  },
                  "video_id": {
                    "label": "Video ID"
                  },
                  "title": {
                    "label": "Title"
                  },
                  "description": {
                    "label": "Description"
                  },
                  "uploader": {
                    "label": "Channel"
                  },
                  "upload_date": {
                    "label": "Upload Date"
                  },
                  "view_count": {
                    "label": "Views"
                  },
                  "like_count": {
                    "label": "Likes"
                  },
                  "comment_count": {
                    "label": "Comments"
                  },
                  "thumbnail": {
                    "label": "Thumbnail",
                    "format": "image"
                  },
                  "download_status": {
                    "label": "Status"
                  },
                  "downloaded_at": {
                    "label": "Processed At",
                    "format": "datetime"
                  }
                }
              }
            }
          }
        }
      },
      "readme": "# YouTube Video, Playlist & Channel Downloader with Metadata\r\n\r\nInspect or download YouTube videos from a direct link, a playlist, a channel, or a search phrase in one run. Every row carries the video's metadata, and download rows add a readable file link, the real container and codec, the requested and delivered quality, captions, and an optional transcript.\r\n\r\nUse this actor only for content you own or are authorized to download. YouTube's Terms of Service may prohibit downloading content without permission, and you are responsible for complying with them. This actor is not affiliated with YouTube or Google, and it does not bypass DRM, private-video access, or geographic restrictions.\r\n\r\n## What this actor does\r\n\r\n- **Four input paths:** direct video URLs, playlists, channels, and keyword search\r\n- **Metadata, download, or subtitles:** choose what each run returns\r\n- **Compatible video:** SDR 360p-1080p H.264/AAC MP4 when YouTube provides it\r\n- **Opt-in 4K:** 1440p/2160p SDR with a 10-minute and 1000 MB cap\r\n- **Audio passthrough:** M4A (AAC) or Opus, without a fake bitrate uplift\r\n- **Captions and transcript:** WebVTT, SubRip, or plain text\r\n- **Honest failures:** rows explain private, live, DRM, geo-blocked, oversized, and unavailable videos\r\n- **Empty fields are omitted** — records only contain values that are actually populated\r\n\r\n## Output per video\r\n\r\n- `record_type` — `video`, `failure`, or `input_error`\r\n- `video_url`, `video_id`, `title`, `description`\r\n- `uploader`, `uploader_id`, `uploader_url`, `channel_id`\r\n- `upload_date`, `duration_seconds`\r\n- `view_count`, `like_count`, `comment_count`\r\n- `thumbnail`, `tags[]`, `categories[]`, `is_live`\r\n- `playlist_index` — position inside a playlist, channel listing, or search result\r\n- `source_label` — `direct`, `playlist:...`, `channel:...`, or `search:...`\r\n- `download_status` — `success`, `metadata_only`, `subtitles_only`, `failed`, `skipped_unsupported`, or `upload_failed`\r\n- `failure_code` — e.g. `private`, `removed`, `live_unsupported`, `drm_unsupported`, `geo_blocked`, `bot_check`, `too_long`, `too_large`, `no_formats`, `upload_failed`, `no_captions`, `captions_unavailable`\r\n- `error`, `retryable`\r\n- `requested_quality`, `delivered_quality`, `quality_match`\r\n- `container`, `vcodec`, `acodec`, `dynamic_range`, `is_hdr`\r\n- `width`, `height`, `resolution`, `fps`, `aspect_ratio`, `audio_only`\r\n- `filesize_bytes`, `total_bitrate_kbps`, `checksum_sha256`\r\n- `download_url`, `storage_key`, `storage_mode`, `expires_at`\r\n- `four_k_cap_applied` — present when the 4K duration/size cap governed the row\r\n- `subtitle_files[]`, `subtitle_urls[]`, `subtitle_languages[]`, `caption_kind`\r\n- `caption_status` — `no_captions`, `captions_unavailable`, or `upload_failed` when no caption file was produced\r\n- `transcript` — when transcript output is requested\r\n- `video_meta` — nested technical details for the downloaded file\r\n- `downloaded_at`\r\n- `search_query` — on an input-error row for an empty search result\r\n\r\n## Input\r\n\r\n| Field | Type | Default | Description |\r\n|---|---|---|---|\r\n| `mode` | string | `metadata` | `metadata`, `download`, or `subtitles` |\r\n| `videoUrls` | array | — | Direct video, Shorts, replay, `youtu.be` URLs, or 11-character IDs |\r\n| `playlistUrls` | array | — | Playlist URLs |\r\n| `channelUrls` | array | — | Channel URLs, `@handles`, or `UC...` IDs |\r\n| `searchQueries` | array | — | Search phrases |\r\n| `videoQuality` | string | `720p` | `360p`, `480p`, `720p`, `1080p`, `1440p`, `2160p`, or `best` |\r\n| `container` | string | `auto` | `auto`, `mp4`, `webm`, or `mkv` |\r\n| `audioOnly` | boolean | `false` | Download source audio only |\r\n| `audioFormat` | string | `m4a` | `m4a` (AAC) or `opus` |\r\n| `downloadSubtitles` | boolean | `false` | Fetch existing caption tracks |\r\n| `subtitleLanguages` | array | `[\"en\"]` | Language codes to request |\r\n| `subtitleFormat` | string | `vtt` | `vtt` or `srt` |\r\n| `includeTranscript` | boolean | `false` | Add a plain-text transcript |\r\n| `maxVideos` | integer | `10` | Total videos per run (1–50) |\r\n| `maxMinutes` | integer | `30` | Per-video duration cap (1–30) |\r\n| `maxMB` | integer | `500` | Per-video size cap; 4K opt-in allows up to 1000 |\r\n| `allow4K` | boolean | `false` | Enable 1440p/2160p SDR |\r\n| `storage` | string | `ephemeral_kvs` | `ephemeral_kvs`, `named_kvs`, or `s3` |\r\n| `kvsName` | string | — | Named KVS name |\r\n| `storageRetentionDays` | integer | `7` | Presigned S3/R2 link lifetime (1–7 days) |\r\n| `s3Bucket`, `s3Prefix`, `s3Endpoint`, `s3Region` | string | — | S3 or R2 destination |\r\n| `s3AccessKeyId`, `s3SecretAccessKey` | secret | — | Optional S3/R2 credentials |\r\n| `s3PublicBaseUrl` | string | — | Use public bucket URLs instead of presigned links |\r\n| `cookies` | secret | — | Optional Netscape cookies for authorized age-restricted or members-only access |\r\n| `proxyConfiguration` | object | automatic | Optional connection override |\r\n\r\n## Examples\r\n\r\n### Metadata for one video\r\n\r\n```json\r\n{\r\n  \"mode\": \"metadata\",\r\n  \"videoUrls\": [\"https://www.youtube.com/watch?v=jNQXAC9IVRw\"]\r\n}\r\n```\r\n\r\n### Download a 720p MP4\r\n\r\n```json\r\n{\r\n  \"mode\": \"download\",\r\n  \"videoUrls\": [\"https://www.youtube.com/watch?v=dQw4w9WgXcQ\"],\r\n  \"videoQuality\": \"720p\",\r\n  \"container\": \"mp4\",\r\n  \"maxVideos\": 1\r\n}\r\n```\r\n\r\n### Playlist with captions and transcript\r\n\r\n```json\r\n{\r\n  \"mode\": \"download\",\r\n  \"playlistUrls\": [\"https://www.youtube.com/playlist?list=PLFgquLnL59alCl_2TQvOiD5Vgm1hCaGSI\"],\r\n  \"videoQuality\": \"480p\",\r\n  \"maxVideos\": 5,\r\n  \"downloadSubtitles\": true,\r\n  \"subtitleLanguages\": [\"en\"],\r\n  \"subtitleFormat\": \"srt\",\r\n  \"includeTranscript\": true\r\n}\r\n```\r\n\r\n### Search to audio\r\n\r\n```json\r\n{\r\n  \"mode\": \"download\",\r\n  \"searchQueries\": [\"public domain jazz\"],\r\n  \"audioOnly\": true,\r\n  \"audioFormat\": \"m4a\",\r\n  \"maxVideos\": 3\r\n}\r\n```\r\n\r\n### Opt-in 4K SDR\r\n\r\n```json\r\n{\r\n  \"mode\": \"download\",\r\n  \"videoUrls\": [\"https://www.youtube.com/watch?v=LXb3EKWsInQ\"],\r\n  \"videoQuality\": \"2160p\",\r\n  \"container\": \"auto\",\r\n  \"allow4K\": true,\r\n  \"maxMinutes\": 10,\r\n  \"maxMB\": 1000\r\n}\r\n```\r\n\r\n## Use cases\r\n\r\n- **Own-channel archiving** — export metadata, captions, and small compatible files for channels you manage\r\n- **Authorized media research** — collect titles, descriptions, dates, and public statistics for analysis\r\n- **Caption workflows** — pull existing VTT or SRT tracks and transcript text for translation or accessibility\r\n- **Audio libraries** — save authorized M4A or Opus audio without re-encoding\r\n- **Content audits** — compare requested and delivered quality, codecs, and file sizes\r\n- **Pipeline integrations** — one row per video with stable status and failure fields\r\n\r\n## FAQ\r\n\r\n### What can I download with this actor?\r\n\r\nContent you own or are authorized to download. The actor does not grant rights to third-party media and does not bypass DRM, private access, or geographic restrictions.\r\n\r\n### Does it support live streams?\r\n\r\nNo. Live and upcoming broadcasts have no finite file and are returned as `live_unsupported` failure rows.\r\n\r\n### Can I download age-restricted or members-only videos?\r\n\r\nSometimes, when you have authorized access and supply your own cookies. Public videos work without cookies.\r\n\r\n### Does it bypass geo-blocks or DRM?\r\n\r\nNo. Geo-restricted and DRM-protected videos are reported as failure rows. Changing proxy settings is not a guaranteed workaround.\r\n\r\n### Where is the MP3 option?\r\n\r\nThere is no MP3 option because YouTube does not serve 320 kbps MP3. The actor passes through the source M4A (AAC) or Opus audio track and reports the real codec. Claiming a higher bitrate would only mean re-encoding and inflating the file.\r\n\r\n### Why did I get 480p when I asked for 720p?\r\n\r\nNot every video has every resolution. The actor delivers the closest available quality at or below your request and sets `quality_match` to `false` when it had to step down.\r\n\r\n### Why is my 4K file MKV or WebM instead of MP4?\r\n\r\nYouTube usually serves 1440p and 2160p as VP9 or AV1 video, often with Opus audio. Those streams are not H.264/AAC MP4. The actor keeps the real codec and container instead of mislabelling a file. Choose `container: \"auto\"` or `mkv` for 4K.\r\n\r\n### What are the download caps?\r\n\r\nEach video is capped at 30 minutes and 500 MB by default, with at most 50 videos per run. Opt-in 4K is capped at 10 minutes and 1000 MB. A video outside the caps gets a `too_long` or `too_large` failure row instead of a partial file.\r\n\r\n### How long do download links last?\r\n\r\nEphemeral KVS links follow your Apify account's key-value store retention. Named KVS persists while the store exists. S3/R2 links are presigned for the configured retention period, or permanent when a public bucket URL is configured. KVS file URLs do not support HTTP Range requests, so use S3/R2 when a downstream system needs resumable or partial downloads.\r\n\r\n### Do I need to set up a proxy?\r\n\r\nNo. The actor chooses a working connection automatically for metadata and player access. Media bytes are fetched directly whenever possible.\r\n\r\n### What happens when a video fails?\r\n\r\nThe run continues and writes a failure row with `failure_code`, `error`, and `retryable`. A failed row never claims a download link.\r\n\r\n### Is this affiliated with YouTube?\r\n\r\nNo. This is an independent third-party tool and is not affiliated with, endorsed by, or sponsored by YouTube or Google.\r\n",
      "environmentVariables": {}
    },
    "buildNumber": "1.0.4",
    "imageDigest": "48703f7ca29fcfdaaf03ebab26f9843ab2b76670949a7bd9eb86da2bc87a3096",
    "actVersion": {
      "sourceType": "SOURCE_FILES",
      "buildTag": "latest",
      "versionNumber": "1.0"
    },
    "usage": {
      "ACTOR_COMPUTE_UNITS": 0.014601111111111112
    }
  }
}