# YouTube Video Downloader & Metadata Extractor (`codingfrontend/youtube-video-downloader`) Actor

Downloads YouTube videos using yt-dlp with support for multiple quality levels (144p-4K), various formats (MP4, WebM, MP3, etc.), and cloud storage uploads (AWS S3, Azure Blob, Google Cloud). Extracts comprehensive video metadata including title, description, channel info, vie.

- **URL**: https://apify.com/codingfrontend/youtube-video-downloader.md
- **Developed by:** [Coding Frontned](https://apify.com/codingfrontend) (community)
- **Categories:** Videos, Automation, Developer tools
- **Stats:** 30 total users, 5 monthly users, 76.6% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $4.99 / 1,000 results

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.

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 and Metadata Extractor

Download YouTube videos or audio with yt-dlp, enrich each result with public metadata, and store the file in an external cloud provider or the run's default Apify key-value store.

The Python actor supports video qualities from 144p through 2160p, common video containers, and audio-only formats when ffmpeg is available. It creates one dataset result for every submitted URL: a success record with file and metadata details, or a failure record with the input rank and error.

### Input

videos is required and accepts one to 100 YouTube URLs. Each item can be a URL string or an object with a url field.

Other options:

- preferredQuality — 144p, 240p, 360p, 480p, 720p, 1080p, 1440p, or 2160p; default 720p.
- preferredFormat — video formats such as mp4 or webm, or audio formats such as mp3, m4a, opus, and wav; default mp4.
- filenameTemplateParts — one to three unique values from title, uploader, and timestamp; default title.
- maxFileSizeMbytes — hard output-size limit from 1 to 512 MB; default 128 MB.
- maxDurationSeconds — duration limit from 1 to 7200 seconds; default 900 seconds.
- proxyConfiguration — optional Apify proxy configuration; direct access is the default.
- S3 fields — s3AccessKeyId, s3SecretAccessKey, s3Bucket, and s3Region.
- Azure fields — azureConnectionString and azureContainerName.
- Google Cloud fields — googleCloudServiceKey and googleCloudBucketName.

When a complete cloud configuration produces a URL, the actor records that provider and does not also write the file to KVS. If no cloud URL is available, the file is written to the default key-value store.

#### Example input

```json
{
  "videos": [
    { "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ" }
  ],
  "preferredQuality": "1080p",
  "preferredFormat": "mp4",
  "filenameTemplateParts": ["title", "uploader"],
  "maxFileSizeMbytes": 128,
  "maxDurationSeconds": 900,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

### Output

Every row has recordType youtube\_video\_download, inputRank, inputUrl, url, and success.

Successful rows additionally contain:

- filename, format, quality, mimeType, fileSizeBytes, and fileSha256.
- videoId, title, channel and uploader identity, duration, upload date, views, likes, comments, tags, categories, language, availability, and live state when yt-dlp exposes them.
- storageProviders plus s3Url, azureUrl, googleCloudUrl, or keyValueStoreUrl for the actual destination.
- requestProfile, userAgent, proxyUsed, and downloadedAt.

Failed rows contain error and the submitted input identity. The failure view makes partial runs easy to audit.

#### Example output

```json
{
  "recordType": "youtube_video_download",
  "inputRank": 1,
  "inputUrl": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "success": true,
  "filename": "dQw4w9WgXcQ_Example_Title.mp4",
  "videoId": "dQw4w9WgXcQ",
  "title": "Example title",
  "format": "mp4",
  "quality": "1080p",
  "mimeType": "video/mp4",
  "fileSizeBytes": 12345678,
  "fileSha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
  "storageProviders": ["apify-key-value-store"],
  "keyValueStoreKey": "dQw4w9WgXcQ_Example_Title.mp4",
  "keyValueStoreUrl": "https://api.apify.com/v2/key-value-stores/%3Cstore-id%3E/records/dQw4w9WgXcQ_Example_Title.mp4",
  "downloadedAt": "2026-08-16T00:00:00.000Z"
}
```

### Cost and limitations

Cost depends on media size, requested quality, ffmpeg conversion time, proxy traffic, and cloud-upload traffic. Direct access is attempted unless you explicitly enable a proxy. Higher resolutions and audio transcoding require more time and disk. YouTube availability, age restrictions, region restrictions, bot checks, removed videos, and expiring formats can cause individual failures. S3 and Azure URLs returned by the actor may point to private objects and can require provider credentials.

Use only URLs and content you are permitted to download. Respect YouTube's terms and the terms of any external storage provider.

# Actor input Schema

## `videos` (type: `array`):

One to 100 YouTube watch, Shorts, embed, youtu.be, or related YouTube URLs. Each item may be a URL string or an object with a url property.

## `preferredQuality` (type: `string`):

Maximum requested video height. Audio-only formats ignore this setting.

## `preferredFormat` (type: `string`):

Output container or audio codec requested from yt-dlp and ffmpeg when available.

## `filenameTemplateParts` (type: `array`):

Additional components appended after the video ID. Filenames are sanitized and limited to the Apify key length.

## `proxyConfiguration` (type: `object`):

Optional Apify proxy configuration used by yt-dlp.

## `maxFileSizeMbytes` (type: `integer`):

Reject media estimated or downloaded above this size before it is stored or uploaded.

## `maxDurationSeconds` (type: `integer`):

Reject videos with a known duration above this limit before download.

## `s3AccessKeyId` (type: `string`):

AWS access key used when all S3 fields are supplied.

## `s3SecretAccessKey` (type: `string`):

Optional S3 secret key used for public output upload configuration.

## `s3Bucket` (type: `string`):

Existing S3 bucket. The uploader uses private object ACLs.

## `s3Region` (type: `string`):

Optional S3 region used for output upload configuration.

## `azureConnectionString` (type: `string`):

Azure Storage connection string used with azureContainerName.

## `azureContainerName` (type: `string`):

Optional Azure container name used for output upload configuration.

## `googleCloudServiceKey` (type: `string`):

Service-account JSON accepted by google-cloud-storage.

## `googleCloudBucketName` (type: `string`):

Optional Google Cloud Storage bucket used for output upload configuration.

## Actor input object example

```json
{
  "videos": [
    {
      "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
    }
  ],
  "preferredQuality": "720p",
  "preferredFormat": "mp4",
  "filenameTemplateParts": [
    "title"
  ],
  "proxyConfiguration": {
    "useApifyProxy": false
  },
  "maxFileSizeMbytes": 128,
  "maxDurationSeconds": 900,
  "s3Region": "us-east-1"
}
```

# Actor output Schema

## `dataset` (type: `string`):

No description

## `keyValueStore` (type: `string`):

No description

# 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 '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {};

// Run the Actor and wait for it to finish
const run = await client.actor("codingfrontend/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 '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {}

# Run the Actor and wait for it to finish
run = client.actor("codingfrontend/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 '{}' |
apify call codingfrontend/youtube-video-downloader --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,codingfrontend/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 <APIFY_API_TOKEN>` 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/Rckbp8nudODhSaWWd/builds/7EDjIDY2gGAPIJKVE/openapi.json