proxmox-infra/scripts/cleanup/README.md

# Media Organization Script

## Purpose

This script identifies and organizes media files by comparing them against what Radarr and Sonarr are actively managing. Files that are not managed by either service are moved to a processing folder for manual review.

## Location

Script: `/home/kavren/proxmox-infra/scripts/cleanup/organize-media.py`

## Usage

### On pm2 (where media is mounted)

The script needs to be run on pm2 where the media directories are mounted.

```bash
# Copy script to pm2
scp /home/kavren/proxmox-infra/scripts/cleanup/organize-media.py pm2:/root/organize-media.py

# Run in DRY RUN mode (recommended first)
ssh pm2 "python3 /root/organize-media.py"

# Run with execution (actually move files)
ssh pm2 "python3 /root/organize-media.py --execute"

# Run quietly (only show summary)
ssh pm2 "python3 /root/organize-media.py --quiet"
```

## What It Does

1. **Queries Radarr API** (http://10.4.2.16:7878)
   - Gets all movies and their file paths
   - Identifies which files are actively managed

2. **Queries Sonarr API** (http://10.4.2.20:8989)
   - Gets all TV series and their episode files
   - Identifies which files are actively managed

3. **Scans Media Directories**
   - `/media/movies` - all video files
   - `/media/tv` - all video files
   - `/media/anime` - all video files
   - Supported extensions: .mkv, .mp4, .avi, .m4v, .ts, .wmv, .flv, .webm

4. **Categorizes Files**
   - **Managed**: Files that exist in Radarr/Sonarr (kept in place)
   - **Unmanaged**: Files not in Radarr/Sonarr (marked for moving)

5. **Processes Unmanaged Files** (when --execute is used)
   - Creates `/media/processing/from-movies/`, `/media/processing/from-tv/`, `/media/processing/from-anime/`
   - Moves unmanaged files preserving relative directory structure
   - Creates log file: `/media/processing/cleanup-log-{timestamp}.txt`

6. **Reports Empty Directories**
   - Lists directories that would be empty after cleanup
   - Does NOT automatically delete them (for safety)

## Safety Features

- **DRY RUN by default**: Shows what would happen without actually moving files
- **Requires --execute flag**: Must explicitly enable actual file operations
- **Detailed logging**: All operations logged with timestamps
- **Preserves structure**: Maintains relative paths when moving files
- **Permission handling**: Gracefully handles access errors
- **Empty directory detection**: Only reports, doesn't delete

## Output

The script provides:
- Real-time progress updates (unless --quiet is used)
- Summary report showing:
  - Total files scanned
  - Files managed by Radarr/Sonarr
  - Unmanaged files found
  - Breakdown by media type
  - Empty directories detected
- Log file written to `/media/processing/cleanup-log-{timestamp}.txt`

## Example Output

```
================================================================================
SUMMARY REPORT
================================================================================

Mode: DRY RUN MODE

Total files scanned: 2847
Files managed by Radarr/Sonarr: 2847
Unmanaged files found: 0

Unmanaged files by category:
  movies: 0 files
  tv: 0 files
  anime: 0 files

================================================================================
```

## Configuration

The script has hardcoded configuration at the top:

```python
RADARR_URL = "http://10.4.2.16:7878"
RADARR_API_KEY = "5e6796988abf4d6d819a2b506a44f422"
SONARR_URL = "http://10.4.2.20:8989"
SONARR_API_KEY = "b331fe18ec2144148a41645d9ce8b249"

MEDIA_DIRS = {
    "movies": "/media/movies",
    "tv": "/media/tv",
    "anime": "/media/anime"
}

PROCESSING_DIR = "/media/processing"
VIDEO_EXTENSIONS = {'.mkv', '.mp4', '.avi', '.m4v', '.ts', '.wmv', '.flv', '.webm'}
```

## Troubleshooting

### Permission Errors
If you see permission errors, ensure the script is running as root on pm2:
```bash
ssh pm2 "whoami"  # Should show 'root'
```

### API Connection Errors
If the script can't connect to Radarr/Sonarr:
- Verify the services are running
- Check the URLs and API keys are correct
- Ensure network connectivity from pm2 to the services

### Missing Directories
If media directories don't exist, the script will log warnings and skip them.

## Maintenance

After running with --execute and reviewing files in `/media/processing/`:
1. Review the moved files
2. Add them to Radarr/Sonarr if needed
3. Delete if they're truly unwanted
4. Review empty directory list from log
5. Manually remove empty directories if desired

## Future Enhancements

Possible improvements:
- Add support for custom media directories via CLI arguments
- Add configuration file support
- Add ability to automatically delete empty directories
- Add dry-run output to file for review
- Add email notifications on completion