Pricing

Rating

Developer

Actor stats

Categories

Share

Social Media Video Downloader - Apify Actor

Download videos from 21+ social media platforms with configurable quality, format, and concurrent processing.

🚀 Quick Start

Local Testing

# Install dependencies (already done if you see node_modules/)
npminstall
# Test with Instagram URLs (creates ./downloads/)
node test-runner.js
# Or test with custom URLs
echo'{"url":"https://www.youtube.com/watch?v=dQw4w9WgXcQ","quality":"720"}'> test.json
# Edit src/main.js to read test.json instead of Apify input
node src/main.js

Run with Apify CLI

# Install Apify CLI globally
npminstall-g apify-cli
# Run locally with Apify storage
npx apify run
# Configure input in: apify_storage/key_value_stores/default/INPUT.json

📋 Features

• 21 Platforms: YouTube, TikTok, Instagram, Twitter/X, Reddit, Facebook, Bilibili, Vimeo, Twitch, Pinterest, SoundCloud, Snapchat, VK, OK.ru, Rutube, Tumblr, DailyMotion, Bluesky, Streamable, Loom, Newgrounds
• Concurrent Downloads: 1-50 parallel downloads (default: 10)
• Quality Options: 144p to 4K (2160p)
• Format Support: MP4, WebM, MKV, MP3, OGG, WAV, Opus, GIF
• FFmpeg Processing: Video+audio merging, remuxing, audio extraction, GIF conversion
• Retry Logic: 3 attempts with exponential backoff
• No External APIs: Embedded Cobalt server on localhost

🎯 Input Parameters

{
"url":"https://www.youtube.com/watch?v=...",
"urls":["https://...","https://..."],
"quality":"1080",
"downloadMode":"auto",
"audioFormat":"mp3",
"audioBitrate":"128",
"videoCodec":"h264",
"filenameStyle":"basic",
"concurrency":10,
"tiktokFullAudio":true,
"tiktokH265":false,
"twitterGif":true,
"youtubeHLS":false,
"youtubeDubLang":"en",
"disableMetadata":false,
"cookies":{},
"proxyConfiguration":{}
}

Single or Multiple URLs: Use either url (string) or urls (array), not both.

Quality Options

• 144, 240, 360, 480, 720, 1080, 1440, 2160

Download Modes

• auto - Video + audio (default)
• audio - Audio only
• mute - Video without audio

Audio Formats

• best, mp3, ogg, wav, opus

Video Codecs (mainly YouTube)

• h264 - Best compatibility (default)
• av1 - Best quality
• vp9 - Good balance

Filename Styles

• classic - service_id_res.ext
• basic - Title (res, service).ext (default)
• pretty - Title (res, service).ext
• nerdy - Title (res, service, id).ext

📦 Output

Apify Run

• Files: Stored in Apify Key-Value Store
• Metadata: Pushed to Apify Dataset with:
  • Direct download URLs to Apify storage (not social media links)
  • File metadata (title, author, album, copyright, date, etc.)
  • File size, content type, status
  • Download timestamp

Local Run (test-runner.js)

• Files: Saved to ./downloads/
• Metadata: Appended to ./downloads/metadata.jsonl

Metadata Format

{
"url":"https://www.youtube.com/watch?v=...",
"service":"youtube",
"filename":"Rick Astley - Never Gonna Give You Up.mp4",
"fileSize":11839321,
"contentType":"video/mp4",
"kvStoreKey":"Rick_Astley_Never_Gonna_Give_You_Up.mp4",
"downloadUrl":"https://api.apify.com/v2/key-value-stores/abc123/records/Rick_Astley_Never_Gonna_Give_You_Up.mp4",
"status":"success",
"error":null,
"downloadedAt":"2026-04-08T18:12:27.743Z",
"metadata":{
"title":"Rick Astley - Never Gonna Give You Up (Official Video) (4K Remaster)",
"artist":"Rick Astley",
"album":"Whenever You Need Somebody",
"copyright":"© 1987 PWL",
"date":"2009-10-25",
"sublanguage":"en"
}
}

Note: The downloadUrl field provides a direct link to download the file from Apify storage, making it easy for users to access their downloaded content without navigating through the platform.

🧪 Test Results

Instagram (2026-04-08)

✅ 3/3 downloads succeeded in 5.0 seconds

YouTube (2026-04-08)

✅ Download verified - 5.25 MB MP4 at 144p

🏗️ Architecture

┌─────────────────────────────────────────────────────┐
│ Apify Actor │
│ ┌────────────────────────────────────────────┐ │
│ │ src/main.js(Actor Entry) │ │
│ │ • Initialize Apify │ │
│ │ • Parse & validate input │ │
│ │ • Configure proxy │ │
│ │ • Start Cobalt server(localhost) │ │
│ └────────────┬───────────────────────────────┘ │
│ │ │
│ ┌────────────▼────────────────────────────────┐ │
│ │ Cobalt APIServer(Embedded on 127.0.0.1) │ │
│ │ • Express server on random port │ │
│ │ • 21 service handlers │ │
│ │ • FFmpeg processing │ │
│ │ • Stream encryption & tunneling │ │
│ └────────────┬────────────────────────────────┘ │
│ │ │
│ ┌────────────▼────────────────────────────────┐ │
│ │ Orchestrator(p-limit concurrency) │ │
│ │ • Queue URLs │ │
│ │ • Parallel downloads │ │
│ │ • Progress tracking │ │
│ └────────────┬────────────────────────────────┘ │
│ │ │
│ ┌────────────▼────────────────────────────────┐ │
│ │ Downloader(per URL) │ │
│ │ • POST to Cobalt API │ │
│ │ • Handle tunnel/redirect/picker │ │
│ │ • Retry withbackoff(3 attempts) │ │
│ └────────────┬────────────────────────────────┘ │
│ │ │
│ ┌────────────▼────────────────────────────────┐ │
│ │ Storage │ │
│ │ • Save file to KVStore(Buffer) │ │
│ │ • Push metadata to Dataset │ │
│ └─────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────┘

🔧 Development

Project Structure

/
├── src/
│ ├── main.js # Actor entry point
│ ├── cobalt-server.js # Embedded Cobalt launcher
│ ├── downloader.js # Single URL download
│ ├── orchestrator.js # Parallel execution
│ └── storage.js # Apify KV Store + Dataset
├── cobalt-api/ # Embedded Cobalt source
│ └── src/
│ ├── processing/services/ # 21 platform handlers
│ └── stream/ # FFmpeg,HLS, proxy
├── packages/
│ └── version-info/ # Version utilities(patched)
├── .actor/
│ ├── actor.json # Apify manifest
│ └── INPUT_SCHEMA.json # Input schema
├── Dockerfile # Node 20+ FFmpeg
├── package.json
├── test-runner.js # Local testing(no Apify)
├── test-instagram.json # Sample input
├── context.md # Full documentation
└── README.md # This file

Local Development Workflow

1. Modify source files in src/
2. Test locally: node test-runner.js
3. Update context.md with changes
4. Run with Apify: npx apify run
5. Deploy: npx apify push

Adding New Features

1. Read context.md to understand architecture
2. Make changes in appropriate module
3. Test with test-runner.js first
4. Verify with full npx apify run
5. Update context.md with what you changed

📝 Configuration

Cookies for Authentication

Some platforms require cookies for private/restricted content:

{
"cookies":{
"youtube":[
{"name":"CONSENT","value":"YES+..."},
{"name":"VISITOR_INFO1_LIVE","value":"..."}
],
"instagram":[
{"name":"sessionid","value":"..."}
],
"tiktok":[
{"name":"sessionid","value":"..."}
]
}
}

Proxy Configuration

Use Apify's built-in proxy:

{
"proxyConfiguration":{
"useApifyProxy":true,
"apifyProxyGroups":["RESIDENTIAL"]
}
}