media-downloader/docs/archive/SNAPCHAT_README.md

Snapchat Downloader Module

This module downloads Snapchat stories using the StoryClon e proxy (https://s.storyclone.com).

Features

• Downloads Snapchat stories via StoryClon e proxy (s.storyclone.com/u//)
• FastDL-compatible file naming: {username}_{YYYYMMDD_HHMMSS}_{media_id}.{ext}
• Integrated with unified database for tracking downloads
• Subprocess isolation to avoid event loop conflicts
• Browser automation with Playwright
• Cloudflare bypass support with 2captcha (optional)
• Cookie persistence for faster subsequent runs
• Automatic file organization and moving to destination

Setup

1. Add Configuration

Add the following to your config/settings.json:

{
  "snapchat": {
    "enabled": true,
    "check_interval_hours": 6,
    "twocaptcha_api_key": "",
    "cookie_file": "/opt/media-downloader/cookies/snapchat_cookies.json",
    "usernames": [
      "username1",
      "username2"
    ],
    "stories": {
      "enabled": true,
      "days_back": 7,
      "max_downloads": 50,
      "temp_dir": "temp/snapchat/stories",
      "destination_path": "/path/to/your/media/library/Snapchat"
    }
  }
}

2. Configure Settings

• enabled: Set to true to enable Snapchat downloads
• check_interval_hours: How often to check for new content (used by scheduler)
• twocaptcha_api_key: Optional - API key for 2captcha.com to solve Cloudflare challenges
• cookie_file: Path to store cookies for faster subsequent runs
• usernames: List of Snapchat usernames to download from
• stories.enabled: Enable/disable story downloads
• stories.days_back: How many days back to search for stories
• stories.max_downloads: Maximum number of stories to download per run
• stories.temp_dir: Temporary download directory
• stories.destination_path: Final destination for downloaded files

3. Set Download Settings

Make sure you have the download settings configured in settings.json:

{
  "download_settings": {
    "move_to_destination": true
  }
}

Usage

Download from all platforms (including Snapchat):

cd /opt/media-downloader
./venv/bin/python media-downloader.py --platform all

Download only from Snapchat:

cd /opt/media-downloader
./venv/bin/python media-downloader.py --platform snapchat

Run with Xvfb (headless display):

./run-with-xvfb.sh

File Naming

Files are saved using FastDL-compatible naming format:

• Format: {username}_{YYYYMMDD_HHMMSS}_{media_id}.{ext}
• Example: johndoe_20250101_143022_abc123def456.jpg

This ensures:

• Chronological sorting by file name
• Easy identification of source user
• Unique media IDs prevent duplicates

Database Tracking

The module uses the unified database to track downloaded stories:

• Platform: snapchat
• Records URL, filename, post date, and metadata
• Prevents re-downloading the same content
• Supports database queries for download history

How It Works

1. Browser Automation: Uses Playwright (Chromium) to navigate StoryClon e
2. Story Detection: Finds story media elements on the page
3. Download: Downloads images/videos via direct URL requests
4. File Processing: Saves with FastDL naming, updates timestamps
5. Database Recording: Marks downloads in unified database
6. File Moving: Moves files to destination if configured
7. Cleanup: Removes temporary files after successful processing

Limitations

• Only downloads stories (no direct posts/snaps)
• Relies on StoryClon e proxy availability
• Stories may expire after 24 hours (download frequently)
• Cloudflare protection may require 2captcha API key

Troubleshooting

No stories found

• Check if the username is correct
• Verify the user has active stories on StoryClon e
• Try accessing https://s.storyclone.com/u/{username}/ manually

Cloudflare blocking

• Add your 2captcha API key to config
• Ensure cookies are being saved and loaded
• Try running with headed mode to see the challenge

Downloads not showing in database

• Check database path in config
• Verify unified_database module is working
• Check logs for database errors

Testing

Test the module directly:

cd /opt/media-downloader
./venv/bin/python modules/snapchat_module.py username_to_test

This will download stories for the specified user and show detailed output.

Architecture

• snapchat_module.py: Main downloader class with browser automation
• snapchat_subprocess_wrapper.py: Subprocess wrapper for isolation
• SnapchatDatabaseAdapter: Database adapter in unified_database.py
• Integration: Fully integrated into media-downloader.py

Future Enhancements

Possible future improvements:

• Support for additional Snapchat proxy services
• Parallel download of multiple users
• Story metadata extraction (captions, timestamps)
• Automatic quality detection
• Retry logic for failed downloads