# Remix Sniper - Quick Reference

**Location:** `~/projects/remix-sniper/`

## Bot Commands (Remi - Discord)

| Command | Description |
|---------|-------------|
| `/scan [chart] [limit]` | Scan charts for remix opportunities |
| `/top [count]` | Show top N opportunities by score |
| `/analyze <url>` | Analyze a specific song |
| `/stats` | Show current stats summary |
| `/validate` | Run validation on tracked predictions |
| `/report` | Generate weekly validation report |

## Scripts (CLI)

```bash
cd ~/projects/remix-sniper
source venv/bin/activate
```

| Script | Purpose |
|--------|---------|
| `python scripts/scan.py init-db` | Initialize database tables |
| `python scripts/scan.py scan --chart all --limit 20` | Run manual scan |
| `python scripts/daily_scan.py` | Run daily scan with alerts |
| `python scripts/update_remix_stats.py` | Update remix stats from APIs |
| `python scripts/weekly_report.py` | Generate weekly report |

## Data Sources

- **Shazam charts** (Tier 1, viral, regional)
- **Spotify Charts** (Viral 50, Top 50 by region)
- **TikTok trending sounds**
- **SoundCloud** (remix saturation)
- **YouTube Music, Deezer** (supplemental)
- **1001Tracklists** (DJ play tracking)

## Scoring Factors

| Factor | Weight | Description |
|--------|---------|-------------|
| TikTok Velocity | 30% | #1 predictor (95% accuracy, 3-6 week lead) |
| Shazam Signal | 15% | #2 predictor (85% accuracy, 2-3 week lead) |
| Spotify Viral | 10% | Confirmation signal (lagging) |
| Remix Saturation | 15% | Gap in existing remixes |
| Label Tolerance | 10% | Likelihood of takedown |
| Audio Remix Fit | 10% | BPM, key compatibility |
| Streaming Momentum | 5% | Lagging indicator |
| Community Buzz | 5% | Reddit, Genius annotations |

## Urgency Levels

- **HIGH (≥85)**: Trending now with low saturation - act fast
- **MEDIUM (50-69)**: Good opportunity, moderate time pressure
- **LOW (<50)**: Solid opportunity, no rush

## Management

```bash
# Check if bot running
launchctl list | grep remix-sniper

# Restart bot
launchctl restart com.jakeshore.remix-sniper

# View bot logs
tail -f ~/projects/remix-sniper/bot.log

# View scan logs
tail -f ~/projects/remix-sniper/daily_scan.log

# Restart Postgres (if needed)
brew services restart postgresql@16

# Connect to database
/opt/homebrew/opt/postgresql@16/bin/psql -d remix_sniper
```

## Cron Jobs

| Time | Job |
|-------|------|
| 9am daily | Scan charts (`daily_scan.py`) |
| Sunday 10am | Update remix stats (`update_remix_stats.py`) |
| Sunday 11am | Weekly report (`weekly_report.py`) |

## Tracking Data

Location: `~/.remix-sniper/tracking/`

- `predictions.json` - All scored predictions
- `remixes.json` - Remix outcomes tracked
- `snapshots/` - Daily chart snapshots

## Validation Goal

Track at least **10 remix outcomes** for meaningful validation metrics.

After each remix:
```bash
cd ~/projects/remix-sniper
source venv/bin/activate
python -c "
from packages.core.tracking.tracker import DatasetTracker
from packages.core.database.models import RemixOutcome

tracker = DatasetTracker()
# Update stats for your remix
tracker.update_remix_stats(remix_id, plays=50000, outcome=RemixOutcome.SUCCESS)
"
```

## Quick Test

```bash
cd ~/projects/remix-sniper
source venv/bin/activate
python scripts/scan.py scan --chart tier1 --limit 5
```