ranger/README.md

Ranger 🎯

L'addon Stremio ultime — multi-trackers / multi-débrideurs, pensé pour le contenu français comme international. Films, séries et anime, avec parsing metadata soigné, filtres, tri par priorité, déduplication et cache.

Écrit en Python (aiohttp), sans dépendance lourde, déployable en une commande Docker sur un VPS.

---

✨ Fonctionnalités

Multi-débrideurs + priorité	AllDebrid, Real-Debrid, TorBox, DebridLink. Ordre de priorité configurable (glisser-déposer). Mode « prioritaire uniquement » ou « tous les débrideurs en cache ».
StremThru intégré	Proxy d'API débrideur pour contourner les blocages d'IP datacenter (VPS Oracle/OVH/etc.). Optionnel, par simple URL.
Compatible AIOStreams	Tags [AD+], [RD+]… (convention Torrentio) pour l'identification du service et du statut de cache.
Clé TMDB	Titres FR, détection anime, numérotation absolue des épisodes. Fallback Cinemeta sans clé.
Trackers publics	YGG (leak, relais Nostr), ThePirateBay (apibay), EZTV, Nyaa (anime). Activables à la case.
Trackers privés / semi	C411, Torr9, Tr4ker, NekoBT (clé/passkey), ABN (login), UNIT3D (multi).
Torznab générique	Branchez Jackett / Prowlarr → des centaines de trackers publics et privés.
Films / séries / anime	Parsing metadata dédié : résolution, codec, source, HDR/DV, audio, langues (MULTI/VFF/VF/VFQ/VOSTFR/VO). Matching saison/épisode + numérotation absolue anime.
Filtres	Taille min/max, résolution, codec, langue, exclusion CAM, exclusion packs, nombre de résultats (global + par résolution).
Tri multi-critères	Cache → langue → résolution → taille → seeders → tracker, ordre entièrement réordonnable.
Déduplication	Par info_hash, en gardant le tracker prioritaire et le max de seeders.
Cache-only / non-caché	Afficher uniquement le caché, ou proposer les non-cachés (le clic les ajoute au débrideur).
Mode d'affichage	Détaillé (tous les liens + infos, pour les initiés) ou Simplifié (1 choix par résolution, meilleur lien auto-sélectionné — pour la famille).
Score de qualité	Tri « meilleur d'abord » holistique (résolution + source + HDR/DV + codec + langue + seeders), sélectionnable comme critère de tri.
Cache SQLite	Statut de cache débrideur, résultats de recherche, métadonnées TMDB et liens débrideur résolus mis en cache (TTLs configurables) → épisodes suivants et seeks quasi instantanés.

---

🚀 Déploiement (VPS, Docker)

Option A — image pré-buildée (recommandé, aucun build local)

Le CI GitHub Actions publie l'image publique sur ghcr.io à chaque push sur main. Aucune authentification n'est requise pour la pull :

# récupérez le docker-compose.ghcr.yml (ou clonez le repo), puis :
docker compose -f docker-compose.ghcr.yml up -d

Pour mettre à jour : docker compose -f docker-compose.ghcr.yml pull && docker compose -f docker-compose.ghcr.yml up -d.

Option B — build depuis les sources

git clone https://github.com/vatax3/ranger.git && cd ranger
docker compose up -d --build

L'addon écoute sur le port 7000. La base de cache SQLite est persistée dans le volume ranger_data.

Derrière un reverse proxy (recommandé, HTTPS obligatoire pour Stremio Web)

Exemple Caddy :

ranger.mondomaine.fr {
    reverse_proxy localhost:7000
}

Stremio exige du HTTPS pour les addons distants — un reverse proxy avec certificat (Caddy/Traefik/nginx) est indispensable en production.

Sans Docker

python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
python main.py            # écoute sur :7000 (surchargeable via PORT)

---

⚙️ Configuration & installation dans Stremio

1. Ouvrez https://ranger.mondomaine.fr/configure
2. Renseignez votre clé TMDB, vos débrideurs (avec ordre de priorité), cochez les trackers, ajustez filtres et tri.
3. Cliquez Installer dans Stremio (ou copiez l'URL du manifest).

Toute la configuration est encodée dans l'URL du manifest (aucune donnée stockée côté serveur hormis le cache technique).

---

🛠️ Panel admin

Accessible sur /admin dès que RANGER_ADMIN_TOKEN est défini (sinon le panel est désactivé). Protégé par ce token.

• Statistiques : uptime, taille de la DB, requêtes stream / streams servis, résolutions, hit-rate du cache (recherches & disponibilité débrideur).
• Répartitions : disponibilité par débrideur, recherches par source.
• Force-refresh d'un média : saisir un IMDB ID supprime ses recherches et métadonnées en cache → le prochain fetch depuis Stremio réinterroge les trackers et TMDB. Idéal quand une release vient de sortir.
• Explorateur de cache : liste des recherches (source, type, IMDB, saison/épisode, âge, expiration) et des métadonnées, avec suppression unitaire.
• Maintenance : purge des entrées expirées, vidage sélectif (recherches / disponibilité / métadonnées) ou total.

---

🔧 Variables d'environnement

Variable	Défaut	Rôle
PORT	7000	Port d'écoute
RANGER_DB	/data/ranger.db	Chemin de la base SQLite
RANGER_ADMIN_TOKEN	—	Token du panel admin /admin. Non défini → panel désactivé.
RANGER_PUBLIC_URL	—	URL publique fixe (ex: https://ranger.mondomaine.fr), prioritaire sur X-Forwarded-Proto/Host. Recommandé si le port du conteneur est aussi joignable directement (headers usurpables sinon).
RANGER_TTL_CACHED	21600 (6 h)	TTL cache « en cache »
RANGER_TTL_UNCACHED	1200 (20 min)	TTL cache « non caché »
RANGER_TTL_SEARCH	1800 (30 min)	TTL résultats de recherche (non vides)
RANGER_TTL_SEARCH_EMPTY	180 (3 min)	TTL résultats de recherche vides — court exprès pour qu'un accroc passager d'un tracker s'auto-résolve vite au lieu de verrouiller "aucun résultat" pour tout le monde
RANGER_TTL_META	604800 (7 j)	TTL métadonnées TMDB
RANGER_TTL_LINK	900 (15 min)	TTL des liens débrideur résolus (seek instantané)
HTTP_PROXY / HTTPS_PROXY	—	Proxy sortant optionnel

---

🏗️ Architecture

main.py                 # Routes aiohttp : manifest, stream, resolve, configure, health
core/
  config.py             # Encodage/décodage de la config (base64 JSON dans l'URL)
  cache.py              # Cache SQLite (availability / searches / meta)
  metadata.py          # TMDB + fallback Cinemeta, détection anime, épisode absolu
  search.py            # Orchestrateur : lance tous les trackers en parallèle (avec cache)
  debrid.py            # Abstraction débrideur (natif + StremThru) unifiée
  parsing.py           # Parsing de release (résolution/codec/source/HDR/audio/langues)
  ranking.py           # Filtres, déduplication, tri multi-critères, limites
  formatting.py        # Construction des objets stream Stremio (compat AIOStreams)
services/               # Un module par tracker/débrideur (portés de Frenchio + nouveaux)
templates/configure.html

Flux d'une requête /stream

1. Décodage de la config depuis l'URL.
2. Métadonnées du média (TMDB/Cinemeta, en cache).
3. Recherche parallèle sur tous les trackers activés (en cache SQLite par tracker).
4. Filtrage pertinence (titre + saison/épisode) → dédup → filtres utilisateur.
5. Vérification de disponibilité auprès des débrideurs (en cache SQLite par hash).
6. Construction des entrées (torrent × débrideur), tri, limites.
7. Sérialisation en streams Stremio.

---

⚠️ Avertissement

Ranger est un agrégateur / proxy : il n'héberge ni n'indexe aucun contenu. Vous êtes responsable de l'usage que vous en faites et du respect des lois de votre juridiction ainsi que des conditions d'utilisation des trackers et débrideurs que vous configurez.

📝 Licence

MIT