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/)
npm install

# 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
npm install -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

URL	Type	Size	Status
reel/DWyB-FxAY1p	Video	2.59 MB	✅ Success
p/DWmtt6SkVAL	Photo	0.06 MB	✅ Success
reel/DTdLffwjkN-	Video	0.43 MB	✅ Success

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 API Server (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 with backoff (3 attempts)          │   │
│  └────────────┬────────────────────────────────┘   │
│               │                                      │
│  ┌────────────▼────────────────────────────────┐   │
│  │ Storage                                      │   │
│  │  • Save file to KV Store (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"]
  }
}