134 lines
3.9 KiB
Markdown
134 lines
3.9 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
# 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](https://chrome.google.com/webstore/detail/get-cookiestxt-locally/cclelndahbckbenkjhflpdbgdldlbecc)
|
|
- [Firefox](https://addons.mozilla.org/en-US/firefox/addon/cookies-txt/)
|
|
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)
|
|
```bash
|
|
# 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
|