tmdb-radarr-tag/README.md

# 🎭 Radarr-TMDB Spectacle Tagger

> Parce qu'à 50 ans, on a le droit d'avoir une bibliothèque Radarr bien rangée
> ET de savoir distinguer un one-man-show d'un concert de Céline Dion.

## Quoi ?

Un script Python qui :
1. Scanne ta bibliothèque Radarr
2. Interroge TMDB pour chaque film
3. Détecte les **spectacles vivants** (stand-up, théâtre, one-man/woman show, cabaret, monologues, etc.)
4. Exclut explicitement les **concerts de musique**
5. Ajoute un tag **"spectacle"** dans Radarr

**Dry-run par défaut** — on ne touche à rien sans `--apply`.

---

## 📁 Structure du projet

mon-projet/
├── .env.global          ← UN NIVEAU AU-DESSUS (../), JAMAIS commité
├── spectacle-tagger/    ← TON REPO
│   ├── script.py
│   ├── config.yaml           ← ta config personnalisée (optionnel)
│   ├── config.yaml.example
│   ├── requirements.txt
│   ├── .gitignore
│   ├── README.md
│   └── checklist.txt

---

## 🔐 Gestion des secrets (../.env.global)

Le fichier `../.env.global` contient tes clés API. Il est stocké **un niveau au-dessus** du repo pour ne jamais être commité accidentellement.

### Création automatique

Si `../.env.global` n'existe pas au lancement du script, **il te demandera les 3 valeurs interactivement** (les clés sont saisies en mode masqué) :
  Création de ../.env.global
  (Tes secrets restent entre toi et ton serveur)
  RADARR_URL (ex: http://localhost:7878) : http://mon-radarr:7878
  RADARR_APIKEY (saisie masquée) : ********
  TMDB_APIKEY   (saisie masquée) : ********
  ✅ Fichier créé : /home/moi/projets/.env.global
  ⚠️  Ne le commite JAMAIS. Jamais. Nada. Que dalle.

### Création manuelle

Tu peux aussi le créer toi-même :

```bash
cat > ../.env.global << 'EOF'
RADARR_URL="http://localhost:7878"
RADARR_APIKEY="ta-clé-radarr-ici"
TMDB_APIKEY="ta-clé-tmdb-ici"
EOF
chmod 600 ../.env.global
Messages d'erreur courants
Copier le tableau


Situation
Message



Fichier absent
Fichier ../.env.global introuvable → création interactive


Variable manquante
Variables manquantes dans ../.env.global : TMDB_APIKEY


Radarr injoignable
Impossible de vérifier/créer le tag dans Radarr


Rate limit TMDB
Rate limit TMDB — on patiente Xs



🚀 Installation
# Cloner le repo
git clone https://ta-forge-gitea.local/ton-user/spectacle-tagger.git
cd spectacle-tagger

# Environnement virtuel (recommandé, on n'est plus des sauvages)
python3 -m venv venv
source venv/bin/activate  # Linux/Mac
# venv\Scripts\activate   # Windows

# Dépendances
pip install -r requirements.txt

# Config (optionnel — le script marche avec les défauts)
cp config.yaml.example config.yaml
# Édite config.yaml selon tes goûts

🎮 Utilisation
Dry-run (par défaut — on regarde, on touche pas)
# 5 premiers films
python script.py

# 50 films
python script.py --limit 50

# Tous les films
python script.py --limit 0

# Mode verbeux
python script.py --verbose

# Mode silencieux
python script.py --quiet
Application réelle des tags
# Tagger les spectacles détectés (5 films)
python script.py --limit 5 --apply

# Tagger TOUT (fais un backup Radarr avant !)
python script.py --limit 0 --apply
Tous les arguments
Copier le tableau


Argument
Description
Défaut



--apply
Applique réellement les tags
dry-run


--limit N
Nombre de films (0 = tous)
5


--tag NOM
Nom du tag Radarr
spectacle


--output FICHIER
Chemin du CSV
results_spectacle_dryrun.csv


--sensitivity strict|loose
strict = keyword+runtime, loose = keyword suffit
loose


--verbose
Logs détaillés
non


--quiet
Logs minimaux
non



⚙️ Configuration (config.yaml)
Copie config.yaml.example en config.yaml et adapte :
TAG_NAME: "spectacle"
DRY_RUN: true
MIN_RUNTIME: 15
MAX_RUNTIME: 240
LIMIT: 5
SENSITIVITY: "loose"  # ou "strict"
OUTPUT_CSV: "results_spectacle_dryrun.csv"
LOG_LEVEL: "INFO"

EXTRA_KEYWORDS:
  - "stand-up"
  - "one-man"
  - "théâtre"
  # ... voir config.yaml.example pour la liste complète

EXCLUDE_KEYWORDS:
  - "concert"
  - "music"
  # ... voir config.yaml.example

🔄 Rollback (retirer un tag)
Si tu as tagué un film par erreur :
Via l'interface Radarr
Ouvre le film → Éditer → Retire le tag "spectacle" → Sauvegarder.
Via l'API (curl)
# 1. Trouver l'ID du tag
curl -s -H "X-Api-Key: TA_CLÉ" http://localhost:7878/api/v3/tag | python3 -m json.tool

# 2. Récupérer le film (ex: id=42)
curl -s -H "X-Api-Key: TA_CLÉ" http://localhost:7878/api/v3/movie/42 > film.json

# 3. Éditer film.json : retirer l'ID du tag du tableau "tags"
# 4. Mettre à jour
curl -X PUT -H "X-Api-Key: TA_CLÉ" -H "Content-Type: application/json" \
     -d @film.json http://localhost:7878/api/v3/movie/42

⚠️ Sécurité — Les trucs importants

../.env.global n'est JAMAIS commité (il est dans .gitignore ET un niveau au-dessus)
Les clés ne sont jamais loggées ni écrites dans le CSV
Fais une sauvegarde Radarr avant toute modification massive :
Radarr → System → Backup → Backup Now


Le dry-run est activé par défaut — il faut explicitement passer --apply