# Instagram Repost Detection - Quick Start Guide

## 🎉 Status: READY FOR TESTING

The Instagram repost detection feature has been **safely implemented and is ready for testing**. The feature is **DISABLED by default** - your existing downloads will work exactly as before.

---

## ⚡ Quick Enable (When Ready to Test)

### Option 1: Via Web UI (Recommended)
1. Open http://localhost:8000/configuration
2. Scroll to "Instagram Repost Detection" section
3. Toggle "Enabled" to ON
4. Click "Save Configuration"

### Option 2: Via Command Line
```bash
sqlite3 /opt/media-downloader/data/backup_cache.db \
  "UPDATE settings SET value = json_set(value, '$.enabled', true) WHERE key = 'repost_detection';"
```

---

## ✅ What It Does

When enabled, the system will:
1. **Detect** Instagram story reposts using OCR
2. **Download** original content from the source user via ImgInn
3. **Match** repost to original using perceptual hashing
4. **Replace** low-quality repost with high-quality original
5. **Cleanup** temporary files automatically
6. **Track** all replacements in database

---

## 🧪 Test with Real Example

You already have a test file ready:
```bash
python3 tests/test_repost_detection_manual.py \
  "/media/d$/OneDrive - LIComputerGuy/Celebrities/Eva Longoria/4. Media/social media/instagram/stories/evalongoria_20251109_154548_story6.mp4" \
  "evalongoria" \
  --live
```

Expected result: Detects @globalgiftfoundation, downloads originals, finds match, replaces file.

---

## 📊 Monitor Activity

### Check if enabled:
```bash
sqlite3 /opt/media-downloader/data/backup_cache.db \
  "SELECT json_extract(value, '$.enabled') FROM settings WHERE key = 'repost_detection';"
```

### Watch logs:
```bash
tail -f /opt/media-downloader/logs/*.log | grep -i repost
```

### View replacements:
```bash
sqlite3 /opt/media-downloader/data/backup_cache.db \
  "SELECT * FROM repost_replacements ORDER BY detected_at DESC LIMIT 10;"
```

---

## 🔒 Safety Features

- ✅ Disabled by default - zero impact on existing functionality
- ✅ Can be enabled/disabled instantly (no restart needed)
- ✅ If detection fails, original file is kept
- ✅ Backward compatible - all existing code unchanged
- ✅ Full error handling - won't break downloads

---

## 📚 Documentation

- **Full Design:** `docs/instagram_repost_detection_design.md`
- **Test Results:** `docs/repost_detection_test_results.md`
- **Testing Guide:** `docs/repost_detection_testing_guide.md`
- **Implementation Summary:** `docs/REPOST_DETECTION_IMPLEMENTATION_SUMMARY.md`

---

## 🚀 Recommended Testing Plan

1. **Day 1:** Verify feature is disabled, normal downloads work
2. **Day 2:** Enable feature, test with example file
3. **Day 3-4:** Monitor live downloads, check logs
4. **Day 5-7:** Review replacements, tune settings
5. **Week 2+:** Full production use

---

## ⚙️ Configuration Options

All configurable via Web UI:

- **Hash Distance Threshold:** How similar images must be (default: 10)
- **Fetch Cache Duration:** How long to cache downloads (default: 12 hours)
- **Max Posts Age:** How far back to check posts (default: 24 hours)
- **Cleanup Temp Files:** Auto-delete temp downloads (default: ON)

---

## 🆘 Quick Disable

If anything goes wrong, disable instantly:

```bash
# Via SQL:
sqlite3 /opt/media-downloader/data/backup_cache.db \
  "UPDATE settings SET value = json_set(value, '$.enabled', false) WHERE key = 'repost_detection';"

# Via UI:
# Configuration page → Toggle OFF → Save
```

---

## ✨ What's New

**Files Created:**
- `modules/instagram_repost_detector.py` - Core detection logic
- `tests/test_instagram_repost_detector.py` - Unit tests
- `tests/test_repost_detection_manual.py` - Manual testing
- 4 documentation files in `docs/`

**Files Modified:**
- `modules/imginn_module.py` - Added skip_database parameter
- `modules/move_module.py` - Added detection hooks
- `web/frontend/src/pages/Configuration.tsx` - Added UI controls
- Frontend rebuilt and ready

**Database:**
- Settings entry added (enabled: false)
- Two new tables created on first use

---

**Everything is ready! The feature is safe to deploy and test at your convenience.**

**Start testing:** `docs/repost_detection_testing_guide.md`