Initial commit

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-29 22:42:55 -04:00
commit 0d7b2b1aab
389 changed files with 280296 additions and 0 deletions
--- a/docs/archive/SNAPCHAT_README.md
+++ b/docs/archive/SNAPCHAT_README.md
@@ -0,0 +1,165 @@
+# 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/<user>/)
+- 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`:
+
+```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`:
+
+```json
+{
+  "download_settings": {
+    "move_to_destination": true
+  }
+}
+```
+
+## Usage
+
+### Download from all platforms (including Snapchat):
+```bash
+cd /opt/media-downloader
+./venv/bin/python media-downloader.py --platform all
+```
+
+### Download only from Snapchat:
+```bash
+cd /opt/media-downloader
+./venv/bin/python media-downloader.py --platform snapchat
+```
+
+### Run with Xvfb (headless display):
+```bash
+./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:
+```bash
+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