tmdb-radarr-tag/PATH_DETECTION.md

# Détection automatique par path Radarr

## 🎯 Fonctionnalité

Si vos spectacles sont déjà organisés dans un dossier spécifique (ex: `/data/media/Spectacles/`), le script les détecte **automatiquement** sans analyser les keywords TMDB.

---

## 🔍 Comment ça fonctionne ?

### Détection
Le script vérifie le **path** de chaque film dans Radarr :
- Si le path contient `"spectacle"` ou `"spectacles"` (insensible à la casse)
- **ET** que le runtime est valide (> 0 et dans la fourchette [15-240] min)
- **ALORS** le film est automatiquement détecté comme spectacle

### Bonus de score
- **+10 points** si path contient "spectacle"
- Détection automatique même sans keywords TMDB

---

## 📂 Exemples de paths détectés

### ✅ Détectés automatiquement

```
/data/media/Spectacles/Gad Elmaleh - Papa est en haut
/mnt/movies/spectacle/Florence Foresti - Motherfucker
/volume1/Spectacles/Jamel Debbouze/
C:\Media\Spectacles\Kev Adams
/home/user/Spectacles/Stand-Up/Louis CK
```

### ❌ Non détectés (path normal)

```
/data/media/Movies/Yannick
/mnt/films/Comedies/La Syndicaliste
/volume1/Films/Je verrai toujours vos visages
```

---

## 🧪 Tests

**Test effectué (test_path_detection.py) :**

| Film | Path | Runtime | Résultat | Raison |
|------|------|---------|----------|--------|
| Gad Elmaleh - Papa est en haut | `/data/media/Spectacles/...` | 75 min | ✅ DÉTECTÉ | Path + runtime valide |
| Florence Foresti | `/data/media/spectacle/...` | 90 min | ✅ DÉTECTÉ | Path (lowercase) + runtime |
| Film Normal | `/data/media/Movies/...` | 120 min | ❌ EXCLU | Pas de path bonus |
| Jamel Debbouze | `/data/media/Spectacles/...` | 0 min | ❌ EXCLU | Runtime invalide |

**Résultats : 4/4 tests passés** ✅

---

## 🎬 Cas d'usage typique

### Scénario 1 : Organisation existante
Vous avez déjà organisé vos spectacles dans un dossier dédié :

```
/data/media/
├── Movies/
│   ├── Yannick (2023)/
│   └── La Syndicaliste (2023)/
└── Spectacles/
    ├── Gad Elmaleh - Papa est en haut/
    ├── Florence Foresti - Motherfucker/
    └── Bérengère Krief - Le Trianon/
```

**Résultat :**
- Tous les films dans `Spectacles/` sont **auto-détectés**
- Les films dans `Movies/` sont analysés normalement (keywords TMDB)

---

### Scénario 2 : Migration progressive
Vous voulez migrer vos spectacles vers un dossier dédié :

1. **Avant** - Tout dans `Movies/` :
   ```bash
   python script.py --limit 0 --verbose
   # Analyse TMDB pour tous les films
   ```

2. **Déplacer les spectacles détectés** dans Radarr :
   ```
   Film → Edit → Path → /data/media/Spectacles/
   ```

3. **Après** - Re-scanner :
   ```bash
   python script.py --limit 0 --apply
   # Les films dans Spectacles/ sont auto-détectés
   # Plus rapide, moins d'appels TMDB
   ```

---

## ⚙️ Configuration

### Aucune configuration nécessaire !
La détection par path est **automatique**.

### Personnalisation (avancé)
Si vous voulez changer le mot-clé détecté (autre que "spectacle"), modifiez `script.py` ligne 662 :

```python
# Ligne 662-667 (script.py)
if movie_path and ("spectacle" in movie_path or "spectacles" in movie_path):
    # Changer ici pour d'autres mots-clés
```

**Exemples possibles :**
```python
# Détecter "Stand-Up" dans le path
if "stand-up" in movie_path or "standup" in movie_path:

# Détecter plusieurs patterns
if any(kw in movie_path for kw in ["spectacle", "stand-up", "humour"]):
```

---

## 🔄 Interaction avec le scoring normal

### Priorité de détection

1. **Exclusions** (priorité maximale)
   - Patterns musicaux dans titre
   - Keywords d'exclusion
   - Runtime invalide

2. **Path bonus** (auto-détection)
   - Si path contient "spectacle" + runtime valide
   - **Détection immédiate**, pas besoin de keywords

3. **Scoring normal** (si pas de path bonus)
   - Keywords TMDB
   - Pattern titre " - "
   - Seuil minimum score >= 5

### Exemple combiné

**Cas 1 : Path bonus active**
```
Film: "Gad Elmaleh - Papa est en haut"
Path: /data/media/Spectacles/Gad Elmaleh
Runtime: 75 min

Score: 11 (+10 path, +1 runtime)
Résultat: DÉTECTÉ (auto, pas besoin de keywords)
```

**Cas 2 : Path normal, scoring classique**
```
Film: "Bérengère Krief - Le Trianon"
Path: /data/media/Movies/Bérengère Krief
Runtime: 71 min
Keywords TMDB: stand-up, comedy special, one-woman show

Score: 11 (+1 runtime, +5 titre pattern, +2 stand-up, +3 one-woman show)
Résultat: DÉTECTÉ (via keywords)
```

---

## 📊 Avantages

### ✅ Performance
- **Moins d'appels TMDB** pour les films déjà classés
- Détection instantanée si path match

### ✅ Précision
- **100% de confiance** sur les films que VOUS avez déjà classés
- Pas de faux positifs si votre organisation est correcte

### ✅ Flexibilité
- Fonctionne avec n'importe quelle structure de dossiers
- Compatible avec les paths Windows et Linux/macOS

---

## ⚠️ Limitations

### 1. Runtime toujours obligatoire
Même avec path bonus, le runtime doit être **> 0** et dans la fourchette [15-240] min.

**Exemple :**
```
Path: /data/media/Spectacles/Mon Spectacle
Runtime: 0 min
Résultat: EXCLU (runtime invalide prioritaire)
```

### 2. Sensible à la casse du mot "spectacle"
La détection cherche `"spectacle"` ou `"spectacles"` en **lowercase**.

**OK :**
- `/Spectacles/` → détecté ✅
- `/spectacle/` → détecté ✅
- `/SPECTACLES/` → détecté ✅

**KO (si vous utilisez un autre nom) :**
- `/Stand-Up/` → non détecté ❌ (utilisez keywords TMDB)
- `/Humour/` → non détecté ❌
- `/Comedy/` → non détecté ❌

---

## 🎯 Recommandations

### Pour une détection optimale

1. **Organisez vos spectacles dans un dossier dédié** :
   ```
   /data/media/Spectacles/
   ```

2. **Utilisez le format "Artiste - Titre"** dans les noms de dossiers :
   ```
   /Spectacles/Gad Elmaleh - Papa est en haut/
   /Spectacles/Florence Foresti - Motherfucker/
   ```

3. **Vérifiez que les runtimes sont remplis** dans Radarr/TMDB

4. **Lancez le script** :
   ```bash
   python script.py --limit 0 --apply
   ```

---

## 📝 Logs de détection

Avec `--verbose`, vous verrez :

```
[15:30:42] DEBUG    ✅ BONUS PATH : 'spectacle' trouvé dans /data/media/spectacles/gad elmaleh
[15:30:42] DEBUG    ✅ Détection automatique : path bonus + runtime valide
[15:30:42] INFO     → 🎭 SPECTACLE détecté ! (score=11) — runtime 75min; path contient 'spectacle' (+10)
```

---

**Date :** 22 février 2026  
**Version :** 2.1 (ajout détection par path)  
**Statut :** ✅ Testé et validé  
**Tests :** 4/4 passés