Initial commit

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

docs/archive/HIGH_RES_DOWNLOAD.md

@@ -0,0 +1,167 @@
+# FastDL High-Resolution Download Mode
+
+## Overview
+
+The high-resolution download mode solves the problem where FastDL profile downloads return low-resolution images (640x640). By searching individual Instagram post URLs instead of downloading from the profile grid, we can get the original high-resolution images.
+
+## How It Works
+
+### The Workflow:
+1. **Load Profile** → Search username on FastDL to get the profile grid
+2. **Extract Media IDs** → Extract Instagram media IDs from FastDL's proxied URLs
+3. **Convert to Instagram URLs** → Convert media IDs to Instagram shortcodes
+4. **Search Each URL** → Search individual Instagram URLs on FastDL
+5. **Download High-Res** → Get high-resolution versions instead of thumbnails
+
+### Technical Details:
+
+FastDL URLs contain Instagram media IDs in this format:
+```
+561378837_18538674661006538_479694548187839800_n.jpg
+           ^^^^^^^^^^^^^^^^^^^^
+           This is the media ID
+```
+
+We convert the media ID `18538674661006538` to Instagram shortcode `BB3NONxpzK` using Instagram's custom base64 alphabet, then search for `https://www.instagram.com/p/BB3NONxpzK/` on FastDL.
+
+## Usage
+
+### Python API:
+
+```python
+from fastdl_module import FastDLDownloader
+
+# Create downloader with high_res=True
+downloader = FastDLDownloader(
+    headless=True,
+    use_database=True,
+    high_res=True  # Enable high-resolution mode
+)
+
+# Download high-res posts
+count = downloader.download(
+    username="username",
+    content_type="posts",
+    output_dir="downloads/highres",
+    max_downloads=10
+)
+
+print(f"Downloaded {count} high-resolution items")
+```
+
+### Command Line:
+
+```bash
+# Using media-downloader.py with --high-res flag
+./media-downloader.py --platform fastdl --username evalongoria --posts --high-res --limit 10
+```
+
+## Important Limitations
+
+### ⚠️ Old Posts May Fail
+
+FastDL may not be able to fetch very old Instagram posts (e.g., from 2016). When this happens, you'll see:
+```
+FastDL encountered an error fetching this post (may be deleted/unavailable)
+```
+
+The downloader will skip these posts and continue with the next one.
+
+### ⏱️ Slower Download Speed
+
+High-res mode is significantly slower than regular profile downloads because:
+- Each post requires a separate search on FastDL (~10-15 seconds per post)
+- Regular mode downloads all items in batch from one page
+- High-res mode: ~10-15 seconds per post
+- Regular mode: ~2-5 seconds per post
+
+**Example timing:**
+- 10 posts in regular mode: ~30 seconds
+- 10 posts in high-res mode: ~2-3 minutes
+
+### 📊 When to Use Each Mode
+
+**Use High-Res Mode (`high_res=True`) when:**
+- Image quality is critical
+- Downloading recent posts (last few years)
+- Willing to wait longer for better quality
+- Need original resolution for professional use
+
+**Use Regular Mode (`high_res=False`, default) when:**
+- Speed is more important than max quality
+- Downloading many posts (50+)
+- 640x640 resolution is acceptable
+- Downloading stories/highlights (already optimized)
+
+## Resolution Comparison
+
+| Mode | Resolution | Speed | Best For |
+|------|-----------|--------|----------|
+| Regular | 640x640px (thumbnail) | Fast | Bulk downloads, previews |
+| High-Res | Up to 1440x1800px (original) | Slow | Professional use, archiving |
+
+## Testing
+
+Test the high-res mode with a recent Instagram post:
+
+```python
+#!/usr/bin/env python3
+import os
+os.environ['PLAYWRIGHT_BROWSERS_PATH'] = '/opt/media-downloader/.playwright'
+
+import sys
+sys.path.insert(0, '/opt/media-downloader/modules')
+
+from fastdl_module import FastDLDownloader
+
+# Test with a recent post
+downloader = FastDLDownloader(headless=True, high_res=True, use_database=False)
+
+count = downloader.download(
+    username="evalongoria",  # Or any public profile
+    content_type="posts",
+    output_dir="test_highres",
+    max_downloads=2  # Test with just 2 posts
+)
+
+print(f"Downloaded {count} items")
+```
+
+## Troubleshooting
+
+### No download links found
+- Post may be too old or deleted
+- Instagram may have changed their URL structure
+- Check if the post is accessible on Instagram
+
+### "Something went wrong" error
+- FastDL couldn't fetch the post from Instagram
+- Common with old posts (2+ years)
+- Downloader will skip and continue with next post
+
+### Timeout errors
+- Increase timeout in settings
+- Check internet connection
+- Try with fewer posts first
+
+## Implementation Files
+
+- **fastdl_module.py** - Main module with high-res implementation
+  - `_media_id_to_shortcode()` - Converts media IDs to shortcodes
+  - `_extract_media_ids_from_fastdl_url()` - Extracts IDs from URLs
+  - `_search_instagram_url_on_fastdl()` - Searches individual URLs
+  - `_download_content_highres()` - High-res download workflow
+
+- **instagram_id_converter.py** - Standalone converter utility
+
+## Future Improvements
+
+Potential optimizations:
+- Parallel URL searches (currently sequential)
+- Caching of Instagram URL → download link mappings
+- Batch processing for better performance
+- Automatic fallback to regular mode for old posts
+
+---
+
+Generated on 2025-10-12