ohm_streaming/Projet_descriptions.md

Ohm Stream Downloader — Description fonctionnelle

Cahier des charges pour une réécriture à partir de zéro.

🎯 Le but du projet

Une application web auto-hébergée (pensée pour un homelab, usage personnel) qui sert de centre de contrôle unique pour les contenus vidéo en français (animes, séries TV, VOSTFR) :

1. Découvrir du contenu en cherchant sur plusieurs sites/sources en même temps,
2. Regarder directement dans l'application via un lecteur intégré,
3. Télécharger des épisodes ou des saisons complètes,
4. Ne rien rater : suivre des titres et télécharger automatiquement chaque nouvel épisode dès sa sortie.

L'application agrège donc le rôle de moteur de recherche, de plateforme de streaming, de gestionnaire de téléchargements et d'outil d'automatisation.

👤 Parcours utilisateur type

1. L'utilisateur se connecte (ou s'inscrit).
2. Il lance une recherche unifiée : une seule requête interroge tous les sites d'animes et de séries activés, les résultats sont fusionnés.
3. Il consulte la fiche détaillée d'un titre : poster, bannière, synopsis, genres, note, année, nombre d'épisodes, liste des saisons et épisodes.
4. Depuis la fiche, il peut :
   • streamer un épisode dans le lecteur intégré,
   • télécharger un épisode précis ou une saison entière d'un coup,
   • l'ajouter à sa watchlist pour un suivi automatique,
   • l'ajouter aux favoris.
5. Il suit l'avancement des téléchargements en temps réel, puis regarde les fichiers téléchargés dans une bibliothèque locale (streaming depuis le serveur, reprise de lecture, épisode suivant).

⚙️ Fonctionnalités détaillées

1. Recherche multi-sources

• Sources « animes » : environ 5 sites francophones (Anime-Sama, Neko-Sama, Anime-Ultime, Vostfree, French-Manga).
• Sources « séries/films » : environ 2 sites (FS7/French-Stream, Zone-Téléchargement).
• Chaque source est un module interchangeable avec le même contrat : chercher, lister les épisodes, récupérer les métadonnées, extraire le lien vidéo réel.
• Résolution automatique : pour une URL donnée, le système trouve tout seul le bon module (site → hébergeur vidéo → générique).
• Extraction en 2 niveaux : la page de l'épisode contient des lecteurs embarqués hébergés ailleurs (une quinzaine d'hébergeurs supportés : DoodStream, VidMoly, 1fichier, Uptobox, Sibnet, Uqload, SendVid, etc.). Le système sait résoudre l'URL directe du fichier pour chacun d'eux.

2. Métadonnées enrichies

• Les infos de base viennent du site scrappé, puis sont enrichies/complétées via une base externe de données anime (Kitsu, en alternative à MAL) : synopsis, genres, notes, année, images.
• Fusion intelligente : on ne remplit que les champs manquants, avec normalisation des formats entre sources.
• Cache des métadonnées pour limiter les appels externes.

3. Streaming et lecteur

• Lecteur vidéo intégré pour les liens extraits des hébergeurs (avec contournement des protections courantes de ces hébergeurs).
• Bibliothèque locale : tous les fichiers téléchargés sont streamables depuis le serveur (page « watch » avec reprise de lecture, navigation épisode suivant, streaming avec support des requêtes de plage pour l'avance rapide).

4. Gestionnaire de téléchargements

• File d'attente avec téléchargements parallèles limités (~3–5 simultanés).
• Statuts : en attente, en cours, en pause, terminé, échec, annulé.
• Pause / reprise (via requêtes de plage HTTP), retry, annulation, « tout annuler », nettoyage des tâches finies.
• Progression temps réel : pourcentage, vitesse, temps restant — rafraîchie dynamiquement côté interface.
• Anti-doublons : si un téléchargement de la même source est déjà actif/en attente, on retourne la tâche existante au lieu d'en créer une.
• Persistance : au démarrage, le dossier de téléchargements est scanné pour restaurer les tâches terminées.
• Noms de fichiers nettoyés et sécurisés automatiquement (suppression de caractères interdits, protection contre la traversée de répertoires).
• Les URLs circulent au format interne video_url|page_url|titre pour ne pas perdre le contexte entre l'extraction et le téléchargement.

5. Watchlist + téléchargement automatique (le cœur de l'app)

• L'utilisateur suit un titre ; chaque item a un statut : actif, en pause, terminé, archivé.
• Mémorisation du dernier épisode téléchargé et du dernier épisode disponible.
• Un planificateur interne vérifie périodiquement (intervalle configurable, d'1 h à 168 h) tous les titres « dus » :
  • détecte les nouveaux épisodes par comparaison au dernier connu,
  • les télécharge automatiquement,
  • journalise un rapport (nouveaux épisodes trouvés / téléchargés).
• Réglages globaux de la watchlist (activation de l'auto-download, intervalle, etc.), statistiques de suivi.
• Vérification manuelle possible à la demande (« vérifier maintenant »).

6. Intégration Sonarr (homelab)

• Réception de webhooks Sonarr (événements type « épisode importé/téléchargé ») avec vérification d'authenticité (signature HMAC + secret) optionnelle.
• Mapping entre séries Sonarr et sources de scraping : pour chaque série suivie dans Sonarr, on associe le titre/URL correspondant sur un site d'animes, pour que Sonarr déclenche le téléchargement dans la bonne source.
• Endpoints d'aide : recherche Sonarr, recherche d'épisodes, suggestions automatiques de mapping, configuration (langue, qualité, provider par défaut, activation du webhook, journalisation).

7. Favoris

• Sauvegarde de titres aimés avec leurs métadonnées et images, avec statistiques et pagination/navigation.

8. Recommandations et découvertes

• Analyse de l'historique de téléchargement (parsing des noms de fichiers pour extraire titres, groupes, saisons, qualité) → profil de goûts (genres, titres) → suggestions personnalisées.
• Sections découverte : dernières sorties, sorties saisonnières, calendrier des sorties, top actuel.

9. Comptes et administration

• Inscription/connexion/déconnexion avec sessions par tokens (token court + refresh token longue durée).
• Rôles admin / utilisateur, activation/désactivation de comptes.
• Interface d'administration : liste des utilisateurs, stats, bascule admin/actif, suppression.

10. Paramètres et gestion des sources

• Activation/désactivation de chaque source individuellement (sans redémarrage), avec état de santé vérifiable (test manuel + contrôle automatique périodique par le planificateur).
• Réglages de l'interface utilisateur, configuration persistée.
• Endpoints publics de santé de l'application et liste des sources disponibles.

🧩 Principes de conception pour la réécriture

• Architecture à 3 niveaux de scrapers : sites de catalogues (animes / séries) → hébergeurs vidéo → extraction générique. Chaque niveau a une classe de base et un registre ; ajouter une nouvelle source = écrire un module qui implémente le contrat et le déclarer dans le registre. Point le plus important : les sites changent souvent, il faut pouvoir en ajouter un en une heure.
• Configuration de scraping externalisée : piloter au moins certaines sources par fichier de configuration (sélecteurs), pour réparer un site cassé sans toucher au code.
• Un seul format interne pour transporter le contexte (vidéo|page|titre) du scraping jusqu'au téléchargement.
• Sécurité non négociable : nettoyage systématique des noms de fichiers, secrets hors fichiers de config, tokens signés.
• Une seule source de vérité pour les données (pas de double stockage JSON + base).
• Pas d'erreurs silencieuses : chaque échec de scraping/téléchargement est journalisé et exposé (statut d'échec visible dans l'UI).
• Injection de dépendances entre les composants (vérificateur d'épisodes ↔ gestionnaire de téléchargements) pour éviter les dépendances circulaires.