tmdb-radarr-tag/README.md

# 🎭 Radarr ↔ TMDB Tagueur Automatique

Un script Python qui détecte automatiquement les spectacles vivants (stand-up, théâtre, one-man shows...) dans votre bibliothèque Radarr et leur applique un tag "spectacle".

**Important** : Les concerts de musique sont explicitement exclus.

## 📋 Sommaire

- [Installation](#installation)
- [Configuration](#configuration)
- [Utilisation](#utilisation)
- [Sécurité](#sécurité)
- [Rollback](#rollback)
- [Checklist](#checklist)

## 🚀 Installation

### 1. Cloner le repo



### 2. Créer un environnement virtuel (recommandé)



### 3. Installer les dépendances

Defaulting to user installation because normal site-packages is not writeable
Collecting requests>=2.28.0 (from -r requirements.txt (line 1))
  Downloading requests-2.32.5-py3-none-any.whl.metadata (4.9 kB)
Collecting pyyaml>=6.0 (from -r requirements.txt (line 2))
  Downloading pyyaml-6.0.3-cp313-cp313-win_amd64.whl.metadata (2.4 kB)
Collecting python-dotenv>=1.0.0 (from -r requirements.txt (line 3))
  Downloading python_dotenv-1.2.1-py3-none-any.whl.metadata (25 kB)
Collecting charset_normalizer<4,>=2 (from requests>=2.28.0->-r requirements.txt (line 1))
  Downloading charset_normalizer-3.4.4-cp313-cp313-win_amd64.whl.metadata (38 kB)
Collecting idna<4,>=2.5 (from requests>=2.28.0->-r requirements.txt (line 1))
  Downloading idna-3.11-py3-none-any.whl.metadata (8.4 kB)
Collecting urllib3<3,>=1.21.1 (from requests>=2.28.0->-r requirements.txt (line 1))
  Downloading urllib3-2.6.3-py3-none-any.whl.metadata (6.9 kB)
Collecting certifi>=2017.4.17 (from requests>=2.28.0->-r requirements.txt (line 1))
  Downloading certifi-2026.1.4-py3-none-any.whl.metadata (2.5 kB)
Downloading requests-2.32.5-py3-none-any.whl (64 kB)
Downloading charset_normalizer-3.4.4-cp313-cp313-win_amd64.whl (107 kB)
Downloading idna-3.11-py3-none-any.whl (71 kB)
Downloading urllib3-2.6.3-py3-none-any.whl (131 kB)
Downloading pyyaml-6.0.3-cp313-cp313-win_amd64.whl (154 kB)
Downloading python_dotenv-1.2.1-py3-none-any.whl (21 kB)
Downloading certifi-2026.1.4-py3-none-any.whl (152 kB)
Installing collected packages: urllib3, pyyaml, python-dotenv, idna, charset_normalizer, certifi, requests

Successfully installed certifi-2026.1.4 charset_normalizer-3.4.4 idna-3.11 python-dotenv-1.2.1 pyyaml-6.0.3 requests-2.32.5 urllib3-2.6.3

## ⚙️ Configuration

### Fichier des secrets ()

**⚠️ Important** : Ce fichier est situé **UN NIVEAU AU-DESSUS** du repo Git pour ne jamais être commité par accident.

#### Option 1 : Création automatique (recommandée)

Lancez simplement le script. S'il ne trouve pas le fichier, il vous demandera les informations :



Le script créera automatiquement  avec vos secrets.

#### Option 2 : Création manuelle

Créez le fichier  (un dossier au-dessus du repo) :



Contenu :


**Obtenir vos clés API :**
- **Radarr** : Paramètres → Général → Clé API
- **TMDB** : https://www.themoviedb.org/settings/api → Créer une clé

### Fichier de configuration ()

Copiez l'exemple et adaptez :



Modifiez selon vos besoins :



## 🎯 Utilisation

### Dry-run (par défaut - recommandé pour tester)

Analyse 5 films et montre ce qui serait tagué sans rien modifier :



**Sortie :**
- Liste des films détectés dans le terminal
- Export CSV avec les détails ()

### Appliquer les tags

Une fois satisfait du dry-run, appliquez réellement les tags :



### Options disponibles



Options :
-  : Limite à N films
-  : Applique réellement les tags (sinon dry-run)
-  : Utilise un autre fichier de config
-  ou  : Mode verbeux (plus de logs)

### Exemples



## 🔒 Sécurité

### Protection des secrets

✅ **Bien** :
- Les secrets sont dans  (hors du repo)
- Les clés API sont masquées lors de la saisie interactive
- Les secrets ne sont jamais logués ni affichés
- Le fichier CSV d'export ne contient aucun secret

❌ **Ne faites jamais** :
- Ne copiez pas  dans le repo
- Ne committez jamais vos clés API
- Ne partagez pas votre fichier CSV s'il contient des chemins sensibles

### Sauvegarde avant modifications

**Avant d'utiliser **, sauvegardez votre base Radarr :



Ou exportez vos tags actuels via l'API.

## ↩️ Rollback

En cas d'erreur, vous pouvez retirer les tags facilement.

### Méthode 1 : Via le CSV généré

Le fichier CSV contient tous les films tagués. Vous pouvez utiliser cette liste pour identifier les films à corriger.

### Méthode 2 : Via l'API Radarr (manuel)



### Méthode 3 : Via l'interface Radarr

1. Allez dans Films
2. Filtrez par tag "spectacle"
3. Sélectionnez les films concernés
4. Actions en masse → Supprimer le tag

## ✅ Checklist avant commit

Voir [checklist.txt](checklist.txt)

## 🐛 Dépannage

### Erreur : "Fichier ../.env.global non trouvé"

Le script va vous demander de créer le fichier interactivement. Suivez les instructions.

### Erreur : "Variable manquante dans ../.env.global"

Vérifiez que les 3 variables sont bien présentes :
- RADARR_URL
- RADARR_APIKEY
- TMDB_APIKEY

Supprimez le fichier et relancez le script pour le recréer.

### Erreur de connexion à Radarr

Vérifiez :
- L'URL Radarr est accessible depuis la machine
- La clé API est correcte
- Radarr est en ligne

### Rate limit TMDB

Si vous avez beaucoup de films, vous pouvez atteindre la limite de requêtes TMDB. Le script attend automatiquement, mais soyez patient.

## 📝 Notes

- Le script analyse uniquement les films ayant un ID TMDB
- Le mode "loose" (défaut) détecte plus de spectacles mais peut avoir des faux positifs
- Le mode "strict" est plus conservateur
- Les concerts de musique sont TOUJOURS exclus, même avec des mots-clés ambigus

## 🍷 Une petite touche d'humour

> *"À cinquante ans, on ne tague plus les films avec ses doigts fatigués.
> On laisse Python faire le boulot pendant qu'on savoure un bon café."*

---

**Bon tagging !** 🎭