Todd
149
docs/REPOST_DETECTION_QUICKSTART.md
Normal file
149
docs/REPOST_DETECTION_QUICKSTART.md
Normal file
@@ -0,0 +1,149 @@
|
||||
# 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`
|
||||
Reference in New Issue
Block a user