Social Media Collection Downloader

Automatically downloads TikTok collections and Instagram saved posts, then unsaves them.

Requirements

• Python 3.10+
• Chrome, Firefox, or Edge (for cookie extraction or headless automation)

Quick Start

# 1. Install dependencies
pip install -r requirements.txt
playwright install chromium

# 2. Run the interactive setup wizard (recommended)
python setup.py

# 3. Or run directly if config already exists
python downloader.py

---

Getting Your Cookies (Required for Private Content)

TikTok and Instagram require you to be logged in. The app needs your session cookies.

Option A — Export from browser (recommended)

1. Install the "Get cookies.txt LOCALLY" extension:
   • Chrome
   • Firefox
2. Log into tiktok.com and/or instagram.com
3. Click the extension icon → choose JSON format → Export
4. Save the files somewhere safe (e.g. config/tiktok_cookies.json)
5. Enter the paths during setup.py

Option B — Auto-read from browser

During setup, choose option 2 (browser auto-read) and enter your browser name (chrome, firefox, edge).

⚠ Your browser must be closed (or using a separate profile) when this runs.

---

Finding Your Collection URLs

TikTok

1. Go to your profile → tap Collections (bookmark icon)
2. Open the collection you want to download
3. Copy the URL from your browser — it looks like: https://www.tiktok.com/@yourhandle/collection/MyVideos-1234567890

Instagram

1. Go to your profile → tap the bookmark icon (Saved)
2. Open the collection you want to download
3. Copy the URL — it looks like: https://www.instagram.com/yourhandle/saved/my-collection/1234567890/

---

Configuration

Edit config/config.json directly, or use setup.py to regenerate it.

See config/config.example.json for all available options.

Key options:

Option	Description
enabled	Enable/disable a platform
cookies_file	Path to exported cookies JSON
cookies_from_browser	Auto-read from chrome/firefox/edge
collections	List of collection URLs to process
unsave_after_download	Remove posts after downloading
headless	Hide browser window during unsaving
delay_between_downloads	Seconds between each download (avoid rate limits)
delay_between_unsaves	Seconds between each unsave click

---

Downloaded Files

Files are saved to:

downloads/
  tiktok/
    Username - Video Title [video_id].mp4
    Username - Video Title [video_id].info.json
  instagram/
    Username - Post Title [post_id].mp4
    Username - Post Title [post_id].jpg

---

Scheduling (run automatically)

Windows Task Scheduler

Create a task that runs:

python C:\path\to\social-dl\downloader.py

macOS / Linux (cron)

# Run every day at 9am
0 9 * * * cd /path/to/social-dl && python downloader.py

---

Troubleshooting

yt-dlp says "login required" → Your cookies are missing or expired. Re-export them from your browser.

Unsave doesn't work / button not found → TikTok/Instagram may have updated their UI. Set "headless": false to watch the browser and inspect what's happening. Open an issue with a screenshot.

Rate limited / banned temporarily → Increase delay_between_downloads to 5 or more.

Instagram downloads fail → Instagram heavily restricts scraping. Use fresh cookies from a recently-logged-in session. Try cookies_from_browser with your browser open to Instagram.

---

Notes

• Downloads are skipped if the file already exists (--no-overwrites)
• Logs are saved to logs/session_YYYYMMDD_HHMMSS.log
• The unsave step opens a browser window (unless headless: true) — this is normal
• This tool uses your own account cookies; it does not share or store credentials anywhere