# 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