tmdb-radarr-tag/WORKFLOW.md

Workflow recommandé : Dry-run puis Apply-from-CSV

🎯 Principe

Au lieu de re-scanner tous les films à chaque fois, utilisez le workflow en 2 étapes :

1. Dry-run : Scanne et génère le CSV (requêtes TMDB)
2. Apply-from-CSV : Applique les tags depuis le CSV (pas de requêtes TMDB)

Avantages :

• ✅ Performance : Pas de requêtes TMDB inutiles lors de l'application
• ✅ Vérification : Possibilité de vérifier/éditer le CSV avant application
• ✅ Flexibilité : Plusieurs tentatives d'application sans re-scanner
• ✅ Rate limits : Évite de spammer l'API TMDB

---

📋 Workflow complet

Étape 1 : Dry-run (détection)

# Scanner tous les films (ou une limite)
python script.py --limit 100

# Ou tous les films
python script.py --limit 0

Résultat :

📄 CSV généré : results_spectacle_dryrun.csv
   → 15 spectacle(s) détectés sur 100 films analysés

🔒 Dry-run terminé. Pour appliquer les tags :
   OPTION 1 (RECOMMANDÉ) : Utiliser le CSV généré
     → python script.py --apply-from-csv
   OPTION 2 : Re-scanner et appliquer
     → python script.py --limit 100 --apply

---

Étape 2 : Vérification du CSV (optionnel)

# Voir tous les spectacles détectés
cat results_spectacle_dryrun.csv | grep "True"

# Ou ouvrir dans Excel/LibreOffice

Exemple CSV :

title,year,tmdb_id,radarr_id,is_spectacle,score,reasons,excluded_by,runtime
Bérengère Krief - Le Trianon,2016,437722,194,True,18,runtime 71min; titre pattern ' - ' (+5); keyword 'stand-up' (+2),,71
Gad Elmaleh - Papa,2023,123456,195,True,16,runtime 75min; path contient 'spectacle' (+10),,75

Actions possibles :

• ✅ Éditer le CSV pour retirer des faux positifs
• ✅ Ajouter manuellement des spectacles (modifier is_spectacle à True)
• ✅ Vérifier les scores pour ajuster la config

---

Étape 3 : Application depuis le CSV

# Appliquer les tags depuis le CSV (RECOMMANDÉ)
python script.py --apply-from-csv

Résultat :

📂 MODE APPLY-FROM-CSV : Chargement depuis le CSV du dry-run
   → Pas de requêtes TMDB, lecture du CSV uniquement

📥 Chargement du CSV : results_spectacle_dryrun.csv
   → 15 spectacle(s) chargé(s) depuis le CSV

📊 RÉSUMÉ : 15 spectacle(s) chargés depuis le CSV
  Spectacles à taguer :
    🎭 Bérengère Krief - Le Trianon (2016) — score=18
    🎭 Gad Elmaleh - Papa (2023) — score=16
    ...

🏷️  Application du tag (id=42) à 15 film(s)...
  ✅ Tag ajouté : 'Bérengère Krief - Le Trianon'
  ✅ Tag ajouté : 'Gad Elmaleh - Papa'
  ⏭️  Tag déjà présent : 'Florence Foresti - Motherfucker'
  ...

📊 Bilan : 12 ajouté(s), 3 déjà tagué(s), 0 erreur(s)

✅ Terminé. Tags appliqués depuis le CSV ! 🎭

---

🔄 Cas d'usage

Cas 1 : Premier scan complet

# 1. Scanner toute la bibliothèque
python script.py --limit 0 --verbose

# 2. Vérifier le CSV
cat results_spectacle_dryrun.csv | grep "True"

# 3. Appliquer
python script.py --apply-from-csv

---

Cas 2 : Test sur un échantillon

# 1. Tester sur 50 films
python script.py --limit 50

# 2. Vérifier les résultats
cat results_spectacle_dryrun.csv

# 3. Si OK, scanner tout
python script.py --limit 0

# 4. Appliquer
python script.py --apply-from-csv

---

Cas 3 : Ajustement de la config

# 1. Scanner avec config actuelle
python script.py --limit 100

# 2. Trop de faux positifs → éditer config.yaml
vim config.yaml  # Ajouter keywords, changer sensitivity

# 3. Re-scanner (écrase le CSV précédent)
python script.py --limit 100

# 4. Appliquer la nouvelle détection
python script.py --apply-from-csv

---

Cas 4 : Application partielle (édition manuelle du CSV)

# 1. Scanner
python script.py --limit 0

# 2. Éditer le CSV manuellement
# Retirer les faux positifs (changer True → False)
# Ajouter des spectacles manqués (changer False → True)
vim results_spectacle_dryrun.csv

# 3. Appliquer le CSV édité
python script.py --apply-from-csv

---

Cas 5 : Re-application après erreur

# 1. Première tentative (erreur réseau ou Radarr down)
python script.py --apply-from-csv
# ❌ Erreur : 5 films taggés, 10 échoués

# 2. Corriger le problème (réseau, Radarr, etc.)

# 3. Re-lancer SANS re-scanner
python script.py --apply-from-csv
# Les films déjà taggés seront skippés automatiquement

---

⚠️ Avertissements

CSV trop ancien

Si le CSV a plus de 24h, un warning s'affiche :

⚠️  Le CSV a 2 jour(s). Les données TMDB peuvent avoir changé.
   → Recommandé : relancer un dry-run d'abord.

Raison : Les métadonnées TMDB peuvent changer (nouveaux keywords, runtime corrigé, etc.)

Action :

• Si les données TMDB sont stables → continuer avec --apply-from-csv
• Sinon → re-scanner d'abord

---

Film supprimé de Radarr

Si un film du CSV n'existe plus dans Radarr :

⚠️  Film ID 123 (Titre du Film) non trouvé dans Radarr

Raison : Le film a été supprimé/déplacé entre le dry-run et l'application

Action : Ignoré automatiquement, pas d'erreur

---

CSV manquant

Si le CSV n'existe pas :

❌ CSV introuvable : results_spectacle_dryrun.csv
   → Lance d'abord un dry-run : python script.py --limit 100

Action : Lancer un dry-run d'abord

---

🎯 Comparaison des modes

Mode	Commande	Requêtes TMDB	Génère CSV	Applique tags
Dry-run	python script.py --limit 100	✅ Oui	✅ Oui	❌ Non
Apply direct	python script.py --limit 100 --apply	✅ Oui	✅ Oui	✅ Oui
Apply from CSV	python script.py --apply-from-csv	❌ Non	❌ Non	✅ Oui

---

📊 Performance

Exemple : 1000 films

Méthode classique (--apply) :

Temps : ~45 minutes
- 1000 requêtes TMDB (GET /movie/{id})
- 1000 requêtes TMDB (GET /movie/{id}/keywords)
- Délai 0.25s entre chaque film
- Application des tags

Méthode optimisée (dry-run + apply-from-csv) :

Dry-run : ~45 minutes
- 1000 requêtes TMDB (GET /movie/{id})
- 1000 requêtes TMDB (GET /movie/{id}/keywords)
- Génération CSV

Apply-from-csv : ~30 secondes
- 0 requête TMDB ✅
- Lecture CSV
- Application des tags

Gain si plusieurs tentatives :

• 1 dry-run + 5 apply-from-csv : 48 minutes
• 6 apply direct : 270 minutes (4h30)

Économie : 222 minutes (3h42) ! 🚀

---

💡 Conseils

1. Toujours faire un dry-run d'abord

# ❌ Mauvais (aucune vérification)
python script.py --limit 0 --apply

# ✅ Bon (vérification possible)
python script.py --limit 0
cat results_spectacle_dryrun.csv | grep "True"
python script.py --apply-from-csv

2. Garder l'historique des CSV

# Archiver les anciennes versions
cp results_spectacle_dryrun.csv backups/results_$(date +%Y%m%d).csv

# Nouveau scan
python script.py --limit 0

# Comparer avec l'ancien
diff backups/results_20260222.csv results_spectacle_dryrun.csv

3. Utiliser --verbose pour débugger

# Si un film n'est pas détecté
python script.py --limit 100 --verbose | grep "Titre du Film"

4. Éditer le CSV pour corrections manuelles

# Ouvrir dans un éditeur
vim results_spectacle_dryrun.csv

# Changer is_spectacle de True à False (faux positif)
# Ou de False à True (faux négatif)

# Appliquer les modifications
python script.py --apply-from-csv

---

🔧 Arguments disponibles

Argument	Description	Exemple
--limit N	Nombre de films (0=tous)	--limit 100
--apply	Scanner + appliquer	--apply --limit 0
--apply-from-csv	Appliquer depuis CSV	--apply-from-csv
--output FILE	Nom du CSV	--output mon_scan.csv
--verbose	Logs détaillés	--verbose
--quiet	Logs minimaux	--quiet

---

Date : 22 février 2026
Version : 2.2 (ajout --apply-from-csv)
Statut : ✅ Implémenté et documenté