# YouTube Personal — Spécifications fonctionnelles et techniques > **Document de référence du projet** > Version de référence : **étape 18.7.3** > Plateformes cibles : **Windows 11** et **Android** > Type de projet : application Flutter personnelle de lecture YouTube sans publicité classique, avec recommandations locales, gestion de bibliothèque, lecture HD/4K et enrichissement des métadonnées. --- ## 1. Objectif du projet **YouTube Personal** est une application Flutter personnelle destinée à proposer une expérience YouTube plus maîtrisée, plus légère et plus personnalisable que le client officiel. L’application vise à : - rechercher et lire des vidéos YouTube ; - supprimer l’exposition aux publicités classiques de la plateforme dans le lecteur ; - détecter et ignorer automatiquement les segments sponsorisés intégrés aux vidéos lorsqu’ils sont connus de SponsorBlock ; - proposer un moteur de recommandations local nommé **Radar personnel** ; - gérer l’historique, les favoris, la reprise de lecture et les chaînes ; - permettre l’accès aux abonnements YouTube officiels via OAuth ; - proposer une lecture HD/4K sur Android ; - proposer une lecture progressive haute définition sur Windows ; - rester utilisable sans dépendre d’un backend personnel ; - fonctionner de façon autonome sur Android ; - éviter autant que possible les dépendances à une session Google pour la lecture vidéo ; - séparer strictement les usages OAuth officiels de l’extraction non officielle des flux vidéo. --- # 2. Périmètre fonctionnel ## 2.1 Plateformes ### Windows Plateforme desktop principale. Fonctions spécifiques : - interface large avec `NavigationRail` ; - lecture vidéo via `media_kit` / libmpv ; - raccourcis clavier ; - Picture-in-Picture sous forme de fenêtre toujours au premier plan ; - extraction HD via `yt-dlp` ; - runtime JavaScript `Deno` embarqué ; - cache média local ; - relais HTTP local progressif ; - démarrage rapide 360p puis bascule HD progressive. ### Android Plateforme mobile autonome. Fonctions spécifiques : - `NavigationBar` mobile ; - lecteur direct Android ; - HD jusqu’à 4K ; - décodage matériel MediaCodec ; - lecture en arrière-plan ; - lecture écran verrouillé ; - Picture-in-Picture natif ; - gestes tactiles ; - aucune dépendance à un PC ou serveur local. --- # 3. Navigation principale L’application comporte les sections principales suivantes : ```text Accueil Recherche Abonnements Chaînes Historique Favoris ``` Sur desktop, ces sections utilisent un rail latéral. Sur Android, elles utilisent une barre de navigation adaptée au mobile. --- # 4. Accueil — Radar personnel ## 4.1 But Le Radar personnel est le moteur de recommandations propre à YouTube Personal. Il ne doit pas simplement recopier les recommandations de YouTube. Il doit construire localement un profil de session à partir de : - l’historique ; - les favoris ; - les chaînes déjà regardées ; - les thèmes récurrents ; - les mots-clés des titres ; - les catégories détectées ; - les choix faits dans le Radar ; - les vidéos ignorées ; - les chaînes masquées. --- ## 4.2 Sections du Radar L’accueil peut contenir notamment : ```text Pour toi maintenant Continuer à regarder Vues récemment Favoris récents Explorer par catégorie À redécouvrir Quelque chose de différent ``` Le contenu exact peut évoluer, mais le Radar doit toujours distinguer les vidéos purement historiques des nouvelles recommandations. --- ## 4.3 Humeur de session L’utilisateur peut modifier temporairement le comportement du Radar avec une humeur de session. Options prévues : ```text Comme d’habitude Je veux du nouveau Apprendre Détente Courtes vidéos Long format ``` Ces choix influencent le classement uniquement pour la session ou la période définie par l’implémentation. --- ## 4.4 Score de recommandation Chaque recommandation peut afficher un pourcentage de proximité, par exemple : ```text 84 % 76 % 68 % ``` Ce score est un score local de pertinence. Il ne correspond pas à une probabilité calculée par YouTube. --- ## 4.5 Explication « Pourquoi ? » Chaque recommandation peut expliquer pourquoi elle a été proposée. Exemples : ```text Proche de ce que tu regardes maintenant Même chaîne que plusieurs vidéos récentes Même thème que tes favoris Sujet fréquent dans ton historique Vidéo différente pour casser la routine ``` --- ## 4.6 Actions sur les recommandations L’utilisateur doit pouvoir : - ouvrir la vidéo ; - demander pourquoi elle est proposée ; - masquer une recommandation ; - réduire la présence d’un auteur ; - masquer définitivement une chaîne des recommandations. --- ## 4.7 Navigation horizontale desktop Les rangées horizontales doivent être réellement navigables sur desktop. Comportement attendu : - bouton précédent si du contenu existe à gauche ; - bouton suivant si du contenu existe à droite ; - scrollbar horizontale ; - glisser à la souris ; - trackpad ; - swipe sur écran tactile. Les boutons disparaissent automatiquement quand le début ou la fin est atteint. --- # 5. Catégorisation des vidéos Le Radar classe automatiquement les vidéos dans des catégories locales. Catégories prévues : ```text Jeux vidéo Culture & histoire OVNI & mystères Technologie & IA Science & espace Auto & transport Musique Société & actualité Tutoriels & apprentissage Divers ``` La détection est basée sur les métadonnées textuelles disponibles : - titre ; - description ; - chaîne ; - mots-clés détectés localement. Exemples : ```text UFO, UAP, Roswell, OVNI → OVNI & mystères Fortnite, Roblox, Minecraft → Jeux vidéo GPU, PC, IA, Android → Technologie & IA ``` --- # 6. Recherche ## 6.1 Recherche vidéo L’utilisateur peut saisir une requête et obtenir des résultats YouTube réels. Chaque carte peut afficher : - miniature ; - titre ; - chaîne ; - durée ; - vues ; - likes si disponibles ; - description courte ; - date si disponible. --- ## 6.2 Ouverture Un clic ou tap ouvre le lecteur interne de YouTube Personal. La lecture ne doit pas ouvrir le navigateur externe par défaut. --- # 7. Historique L’historique est stocké localement. Clé persistante : ```text youtube_personal.history.v1 ``` Caractéristiques : - maximum historique actuel : environ 100 vidéos ; - déduplication par vidéo ; - la dernière ouverture remonte la vidéo ; - conservation locale via `SharedPreferencesAsync`. --- # 8. Favoris L’utilisateur peut ajouter et retirer une vidéo des favoris. Clé persistante : ```text youtube_personal.favorites.v1 ``` Les favoris participent au Radar. --- # 9. Reprise de lecture Les positions sont stockées localement. Clé : ```text youtube_personal.positions.v1 ``` Règles : - ne pas mémoriser une position inférieure à environ 5 secondes ; - considérer la vidéo terminée lorsque la fin est proche ; - effacer une position lorsqu’il reste environ 15 secondes ou moins ; - reprendre à la dernière position pertinente ; - éviter d’afficher l’image de départ avant un seek de reprise lorsque cela est techniquement possible. --- # 10. Comptage personnel des vues YouTube Personal distingue les vues publiques YouTube des vues personnelles dans l’application. Clé : ```text youtube_personal.watch_counts.v1 ``` Une « vue personnelle » correspond à une vraie ouverture de vidéo. Ne doivent pas incrémenter le compteur : ```text changement 1080p → 4K changement 4K → 720p seek changement de vitesse pause/reprise ``` Le menu **Chaînes** utilise ces vues personnelles pour classer les chaînes. --- # 11. Gestion des chaînes ## 11.1 Menu Chaînes Le menu Chaînes liste les chaînes rencontrées par l’utilisateur. Le classement principal est basé sur : ```text nombre de mes vues sur cette chaîne ``` et non sur les vues publiques cumulées de la chaîne. Exemple : ```text #1 Gamerawi 12 de mes vues 4 vidéos différentes #2 Aburob 7 de mes vues 2 vidéos différentes ``` --- ## 11.2 Masquage d’une chaîne Action : ```text Cette chaîne ne m’intéresse pas ``` Effets : - retirer la chaîne de la liste principale ; - l’exclure du Radar ; - conserver l’historique existant ; - mémoriser le choix localement ; - proposer une action Annuler immédiatement après. --- ## 11.3 Ouverture d’une chaîne Depuis : - le lecteur vidéo ; - la page Chaînes ; - éventuellement une carte recommandée. L’ouverture d’une chaîne affiche : - avatar ; - nom ; - description ; - pays si disponible ; - nombre d’abonnés ; - vues de chaîne si disponibles ; - nombre de vidéos publiques si disponible ; - date de création ou date d’arrivée si disponible ; - statistiques calculées sur les vidéos chargées ; - catalogue vidéo. --- # 12. Page détaillée d’une chaîne ## 12.1 En-tête Informations possibles : ```text Nom Avatar Description Pays Abonnés Vues chaîne Vidéos publiques Date de création ``` Toutes les informations ne sont pas garanties par les chemins publics non authentifiés. L’interface ne doit pas inventer une donnée indisponible. --- ## 12.2 Likes de chaîne YouTube ne fournit pas de compteur officiel global de likes pour une chaîne. YouTube Personal calcule donc : ```text likes cumulés des vidéos chargées ``` Ce compteur doit être clairement présenté comme une agrégation locale. --- ## 12.3 Commentaires cumulés Même principe pour les commentaires lorsque `commentCount` est disponible. --- ## 12.4 Résumé du catalogue La page peut afficher : ```text Vidéos chargées Vues cumulées Moyenne de vues par vidéo Likes cumulés Durée totale chargée Période couverte par les vidéos ``` --- ## 12.5 Catalogue vidéo Présentation desktop recommandée : ```text [ vidéo 1 ] [ vidéo 2 ] [ vidéo 3 ] [ vidéo 4 ] [ vidéo 5 ] [ vidéo 6 ] [ vidéo 7 ] [ vidéo 8 ] ``` Responsive : ```text >= 1500 px : 4 colonnes >= 1080 px : 3 colonnes >= 720 px : 2 colonnes mobile : 1 colonne ``` --- ## 12.6 Informations sur les cartes de chaîne Chaque vidéo peut afficher : - miniature ; - durée ; - titre ; - vues ; - likes ; - commentaires ; - date de publication ; - description courte. Une valeur non connue ne doit pas être affichée comme `0` si `0` signifie en réalité « donnée inconnue ». --- # 13. Tri des vidéos d’une chaîne Tri prévu : ```text Plus récentes Plus vues Plus aimées Plus anciennes ``` ### Plus récentes Date de publication décroissante. ### Plus anciennes Date de publication croissante. ### Plus vues Nombre de vues publiques décroissant. Quand le fallback public sait appliquer un tri natif de popularité, celui-ci doit être privilégié. ### Plus aimées Nombre de likes publics décroissant lorsque cette donnée est disponible. --- # 14. Authentification Google ## 14.1 But OAuth sert uniquement aux fonctions officielles du compte YouTube. Scope : ```text youtube.readonly ``` --- ## 14.2 Fonctions OAuth OAuth permet notamment : - lire les abonnements ; - récupérer les chaînes suivies ; - utiliser certaines données YouTube Data API officielles. --- ## 14.3 Séparation sécurité Règle stricte : ```text OAuth Google officiel ≠ extraction vidéo non officielle ``` Les éléments OAuth ne doivent pas être injectés automatiquement dans : - yt-dlp ; - l’extracteur de flux ; - les URLs vidéo ; - les requêtes PO Token ; - les flux `googlevideo`. Ne pas automatiser : - likes ; - commentaires ; - abonnements ; - vues artificielles. --- # 15. Abonnements YouTube L’utilisateur connecté peut voir ses abonnements réels. Une chaîne d’abonnement peut ouvrir son catalogue vidéo. Le chargement via Data API utilise idéalement : ```text channels.list → contentDetails.relatedPlaylists.uploads → playlistItems.list → videos.list ``` avec pagination. Objectif : - éviter `search.list` lorsque cela n’est pas nécessaire ; - réduire l’utilisation du quota API ; - récupérer durée, statistiques et date via `videos.list`. --- # 16. Lecteur vidéo — fonctions générales ## 16.1 Commandes Le lecteur doit fournir : ```text Play / Pause -10 secondes +10 secondes Recommencer Picture-in-Picture Sélecteur de qualité Sélecteur de vitesse ``` --- ## 16.2 Clic vidéo Un clic ou tap sur la surface vidéo bascule Play/Pause. --- ## 16.3 Vitesse Plage : ```text 0.50x → 2.00x ``` Pas fin : ```text 0.05x ``` Presets rapides : ```text 0.50x 1.00x 1.50x 2.00x ``` --- # 17. Raccourcis plein écran Windows En mode plein écran : ```text Espace → pause / lecture Flèche gauche → recul Flèche droite → avance Flèche haut → volume + Flèche bas → volume - ``` Le lecteur doit rester utilisable au clavier sans afficher de contrôles supplémentaires obligatoires. --- # 18. Android — gestes tactiles Le lecteur Android conserve des gestes adaptés au mobile. Exemples : - double tap gauche → recul ; - double tap droite → avance ; - autres gestes définis dans le lecteur mobile selon la version. --- # 19. Picture-in-Picture ## Windows Utiliser une fenêtre compacte : ```text 480 × 300 environ always-on-top ``` via `window_manager`. ## Android Utiliser le Picture-in-Picture natif Android. --- # 20. Lecture en arrière-plan Android Android doit continuer la lecture audio lorsque : - l’application passe en arrière-plan ; - l’écran est verrouillé. Architecture : ```text Player vidéo foreground + Player audio-only background + audio_service ``` Le système doit : - synchroniser la position ; - conserver seek/pause ; - éviter un décalage important ; - restaurer le Player principal lorsque l’utilisateur revient. --- # 21. SponsorBlock ## 21.1 But Détecter et ignorer automatiquement les segments sponsorisés intégrés au contenu. Catégorie actuellement visée : ```text sponsor ``` Ne pas ignorer automatiquement par défaut : ```text intro outro self-promo interaction reminder preview ``` --- ## 21.2 Comportement ```text lecture normale → entrée dans segment sponsor → seek à la fin → reprise lecture ``` Notification possible : ```text Sponsor ignoré automatiquement • 34s ``` --- ## 21.3 Confidentialité Utiliser le mode k-anonymity de SponsorBlock. Principe : ```text SHA-256(videoId) → envoyer seulement le préfixe court → filtrer localement la réponse ``` Le système doit rester non bloquant. Si SponsorBlock échoue, la lecture normale continue. --- # 22. Modèle de données vidéo Modèle principal : ```text VideoItem ``` Champs fonctionnels : ```text id title author channelId thumbnailUrl duration viewCount likeCount commentCount description uploadDate ``` Toutes les données doivent être optionnelles lorsqu’elles ne sont pas garanties par la source. --- # 23. Métadonnées chaîne Modèle : ```text ChannelDetails ``` Champs possibles : ```text channelId title description thumbnailUrl publishedAt joinDateLabel viewCount subscriberCount hiddenSubscriberCount videoCount country ``` --- # 24. Sources de métadonnées YouTube Personal utilise plusieurs chemins, avec des rôles distincts. ## 24.1 YouTube Data API officielle Utilisation : - abonnements ; - statistiques officielles chaîne ; - uploads d’une chaîne lorsque OAuth est actif ; - durée / statistiques / date de vidéos. Avantage : - métadonnées structurées. Inconvénient : - quota ; - session Google nécessaire. --- ## 24.2 youtube_explode_dart Utilisation : - recherche ; - métadonnées vidéo publiques ; - chaînes publiques ; - liste publique d’uploads ; - fallback stable Android selon le contexte. Limite connue : YouTube peut appliquer du rate limiting sur les pages `/watch`. L’application doit éviter les rafales de requêtes par vidéo. --- ## 24.3 yt-dlp Utilisation Windows : - extraction HD ; - extraction `web_embedded` ; - récupération groupée de certaines métadonnées de chaîne ; - catalogue public en mode bulk ; - fallback lorsque `youtube_explode_dart` est limité. Le binaire est embarqué dans : ```text assets/windows_hd/yt-dlp.exe ``` Runtime JS : ```text assets/windows_hd/deno.exe ``` --- # 25. Architecture lecture Windows La lecture Windows est la partie la plus spécifique du projet. Objectifs : - démarrage rapide ; - éviter les 403 historiques des URLs directes ; - éviter le rate limit du `/watch` public ; - permettre 1080p, 1440p et 2160p lorsque disponibles ; - conserver le son ; - reprendre au bon timestamp ; - utiliser le cache. --- # 26. Historique des contraintes Windows Plusieurs approches ont été abandonnées ou conservées comme fallback : ```text URLs googlevideo directes vers mpv → instables / timeouts / 403 mweb + PO Token → téléchargements partiels / 403 web_safari HLS → disponibilité trop variable relay Dart simple → limitations yt-dlp natif par URL signée → 403 selon les URLs growing file direct → ouverture mpv instable download complet local → robuste mais lent ``` La solution actuelle privilégie un mécanisme progressif local. --- # 27. Windows — comportement cible étape 18.7.3 La lecture doit suivre : ```text clic vidéo ↓ yt-dlp web_embedded 360p ↓ petit prébuffer ↓ lecture 360p ↓ préparation HD en arrière-plan ↓ bascule à la position courante ``` Le 360p de démarrage ne doit pas utiliser le endpoint public `/watch` de `youtube_explode_dart`. --- # 28. Prébuffer Windows 360p Objectif de démarrage : ```text vidéo : environ 2 MiB audio : environ 512 KiB ``` Le service HTTP local sert les fichiers pendant leur croissance. Routes : ```text /video /audio ``` Cela permet à `media_kit` de commencer à lire avant la fin du téléchargement. --- # 29. Deux relais Windows séparés Deux instances de `WindowsEmbeddedProgressiveService` : ```text Relais startup 360p Relais HD ``` Le cache startup doit être isolé afin d’éviter : - suppression du fichier en cours de lecture ; - concurrence de fichiers ; - réécriture de l’audio ; - erreurs Windows de type fichier utilisé par un autre processus. Après confirmation HD : ```text arrêt du relais 360p ``` --- # 30. HD Windows Qualités cibles : ```text 360p 720p 1080p 1440p 2160p Auto ``` Auto vise généralement une qualité haute adaptée, historiquement 1080p comme cible de démarrage HD. --- ## 30.1 web_embedded Client principal : ```text web_embedded ``` Formats observés possibles : ```text 137 → AVC 1080p30 299 → AVC 1080p60 399 → AV1 1080p60 308 → VP9 1440p60 400 → AV1 1440p60 315 → VP9 2160p60 401 → AV1 2160p60 251 → Opus audio ``` La sélection exacte dépend de la vidéo. --- ## 30.2 Codecs Préférences possibles selon les branches : ```text AV1 VP9 AVC ``` Toute optimisation de taille doit prévoir un fallback codec si le décodage local échoue. --- # 31. Cache Windows Répertoire : ```text %LOCALAPPDATA%\YouTubePersonal\media_cache\ ``` Structure approximative : ```text media_cache/ / video_. audio_. startup360_video_... startup360_audio_... ``` Objectifs : - réutiliser les médias déjà téléchargés ; - accélérer les relectures ; - éviter les requêtes réseau inutiles. --- # 32. Politique de cache Le cache doit : - valider qu’un fichier existe et est exploitable ; - éviter de considérer comme valide un fichier incomplet ; - réutiliser l’audio si compatible ; - limiter progressivement l’espace disque ; - conserver les éléments récents ; - pouvoir supprimer les caches les plus anciens. Une stratégie LRU via fichier `.last_access` est utilisée ou prévue. --- # 33. Gestion des erreurs Windows Le lecteur doit produire des logs lisibles. Préfixes historiques : ```text [HD-WINDOWS] [HD-PROGRESSIVE] [HD-CACHE] [HD-DOWNLOAD] [YT-PLAYER] ``` Exemples attendus étape 18.7.3 : ```text [HD-WINDOWS][18.7.3] démarrage rapide 360p ... [HD-WINDOWS][18.7.3] 360p prêt ... [HD-WINDOWS][18.7.3] lecture 360p confirmée ... [HD-WINDOWS][18.7.3] 360p en lecture -> préparation HD ... [HD-WINDOWS][17.19] HD progressive confirmée ... [HD-WINDOWS][18.7.3] relais 360p arrêté après bascule HD ``` --- # 34. Rate limiting YouTube Problème connu : ```text RequestLimitExceededException ``` Cause typique : - trop de requêtes aux pages watch ; - récupération individuelle des métadonnées de nombreuses vidéos. Règle technique : **ne pas lancer une requête watch par vidéo pour tout un catalogue.** Préférer : ```text 1 requête de catalogue + 1 extraction bulk yt-dlp ``` --- # 35. Catalogue de chaîne Windows Architecture récente : ```text liste publique légère + yt-dlp --flat-playlist --dump-json ``` Objectif : - obtenir un grand catalogue sans lancer une page watch pour chaque vidéo ; - réduire le risque de rate-limit ; - enrichir les cartes en masse. Les données non présentes dans `flat-playlist` ne doivent pas être inventées. --- # 36. Android — HD et 4K Android utilise un chemin natif spécifique. L’application a déjà validé : ```text 1080p AVC + AAC ``` et : ```text 3840 × 2160 VP9 ``` Décodage observé : ```text c2.qti.vp9.decoder ``` Le 4K Android est considéré comme fonctionnel sur le terminal testé. --- # 37. Sélecteur qualité Android Qualités : ```text Auto 360 720 1080 1440 2160 ``` Défaut historique : ```text 1080p ``` La disponibilité réelle dépend des formats fournis par la vidéo. --- # 38. Interface et design ## 38.1 Thème Thème sombre. Palette dominante : - noir / gris très foncé ; - accents rouges / saumon ; - textes blancs / gris. --- ## 38.2 Responsive Desktop : - densité plus élevée ; - cartes multiples ; - grilles ; - contrôles souris/clavier. Mobile : - cartes plus compactes ; - swipe ; - gestures ; - NavigationBar. --- # 39. Description vidéo La page vidéo doit afficher : ```text vues likes commentaires date description ``` Comportement : - 3 lignes environ par défaut ; - bouton `Afficher plus` ; - bouton `Afficher moins`. Les aperçus peuvent afficher 1 à 2 lignes. --- # 40. Informations chaîne sous une vidéo Sous le lecteur, la zone chaîne peut afficher : ```text Nom de chaîne Abonnés Vues chaîne si disponible Nombre de vidéos si disponible Date si disponible Likes de la vidéo ``` Une donnée inconnue ne doit pas être remplacée par `0`. --- # 41. Persistance locale Technologie : ```text shared_preferences SharedPreferencesAsync ``` Clés principales : ```text youtube_personal.history.v1 youtube_personal.favorites.v1 youtube_personal.positions.v1 youtube_personal.watch_counts.v1 youtube_personal.hidden_channels.v1 ``` D’autres clés Radar peuvent être ajoutées pour : - dismissals ; - auteurs réduits ; - préférences locales. --- # 42. Confidentialité Principes : - aucune vente ou partage de données ; - application personnelle ; - préférences conservées localement ; - OAuth utilisé uniquement pour les appels officiels Google ; - aucune URL signée sensible ne doit être enregistrée dans un document utilisateur ; - aucun secret OAuth ne doit être exposé dans les logs ou la documentation ; - pas de cookies compte injectés automatiquement dans yt-dlp ; - SponsorBlock utilisé en k-anonymity. --- # 43. Sécurité fonctionnelle Ne pas automatiser : ```text like commentaire abonnement désabonnement vue artificielle interaction sociale ``` Le projet reste un lecteur et un gestionnaire de contenu personnel. --- # 44. Dépendances Flutter principales Référence du projet : ```yaml youtube_explode_dart: ^3.1.0 media_kit: ^1.2.6 media_kit_video: ^2.0.1 media_kit_libs_video: ^1.0.7 shared_preferences: ^2.5.5 window_manager: ^0.5.2 google_sign_in: ^7.2.0 http: ^1.5.0 crypto: ^3.0.6 url_launcher: ^6.3.2 audio_service: ^0.18.19 ``` --- # 45. Environnement de développement de référence Projet : ```text D:\07-Logiciels\23-youtube_personal ``` Flutter : ```text D:\07-Logiciels\00-Flutter\flutter ``` Android SDK : ```text C:\Users\abmou\AppData\Local\Android\sdk ``` Java Android Studio : ```text D:\Program Files\Android\Android Studio\jbr ``` --- # 46. Identité du projet Nom Flutter : ```text youtube_personal ``` Package Android : ```text com.studioweb.youtube_personal ``` Version historique de base : ```text 1.0.0+1 ``` --- # 47. Commandes de lancement ## Windows ```powershell cd "D:\07-Logiciels\23-youtube_personal" flutter run -d windows ``` ## Android ```powershell cd "D:\07-Logiciels\23-youtube_personal" flutter run -d f10778d8 ``` `flutter clean` ne doit être utilisé que lorsqu’il est réellement nécessaire. --- # 48. Structure logique du code Structure principale : ```text lib/ main.dart models/ video_item.dart subscription_channel.dart channel_details.dart channel_rank_item.dart screens/ home_page.dart search_page.dart subscriptions_page.dart channel_videos_page.dart channels_page.dart video_player_page.dart library pages... services/ youtube_service.dart library_service.dart radar_service.dart google_auth_service.dart google_oauth_config_service.dart youtube_account_service.dart background_playback_service.dart hidden_channels_service.dart channel_catalog_service.dart channel_preview_metadata_service.dart sponsor_block_service.dart windows_hd_service.dart windows_embedded_download_service.dart windows_embedded_progressive_service.dart windows_channel_metadata_service.dart windows_channel_video_catalog_service.dart windows relay / cache services... widgets/ video_result_card.dart ``` --- # 49. Responsabilités des principaux services ## `YoutubeService` Responsabilités : - recherche ; - métadonnées vidéo ; - métadonnées chaîne publiques ; - uploads publics ; - fallback non authentifié. --- ## `LibraryService` Responsabilités : - historique ; - favoris ; - positions ; - compteur personnel de vues ; - persistance locale. --- ## `RadarService` Responsabilités : - construire le profil local ; - calculer les recommandations ; - catégoriser ; - expliquer les recommandations ; - gérer dismissals et réduction d’auteurs ; - exclure les chaînes masquées. --- ## `GoogleAuthService` Responsabilités : - session Google ; - access token officiel ; - renouvellement lorsque prévu. --- ## `YoutubeAccountService` Responsabilités : - appels YouTube Data API ; - abonnements ; - playlists uploads ; - statistiques officielles. --- ## `SponsorBlockService` Responsabilités : - récupération des segments sponsor ; - cache de segments ; - k-anonymity ; - non-blocage du lecteur. --- ## `WindowsHdService` Responsabilités : - interrogation yt-dlp ; - choix des formats ; - qualité cible ; - métadonnées HD. --- ## `WindowsEmbeddedProgressiveService` Responsabilités : - téléchargement progressif ; - relais HTTP local ; - Range requests ; - surveillance du cache en croissance ; - prébuffer ; - lecture pendant téléchargement. --- # 50. Critères d’acceptation fonctionnels ## Accueil - les recommandations s’affichent ; - la liste est navigable ; - la fin de la liste reste accessible ; - les chaînes masquées n’apparaissent plus ; - les catégories fonctionnent. ## Recherche - une requête retourne des vidéos ; - une carte ouvre le lecteur ; - les métadonnées disponibles sont visibles. ## Lecteur - lecture/pause ; - seek ; - vitesse ; - qualité ; - reprise ; - description ; - chaîne cliquable ; - PiP. ## Windows - une vidéo non en cache doit commencer en 360p rapidement ; - la HD se prépare ensuite ; - la bascule conserve la position courante ; - si 360p est explicitement sélectionné, aucune HD automatique ne doit être lancée ; - les erreurs de téléchargement ne doivent pas geler toute l’application. ## Android - lecture autonome ; - HD/4K ; - PiP ; - arrière-plan ; - écran verrouillé. ## Chaînes - classement selon vues personnelles ; - suppression/masquage ; - ouverture catalogue ; - tri réel ; - cartes riches ; - aucune fausse statistique à zéro. ## SponsorBlock - segment sponsor connu → seek automatique ; - segment inconnu → lecture normale ; - erreur réseau SponsorBlock → lecture normale. --- # 51. Contraintes techniques importantes 1. **Ne pas casser le pipeline HD Windows qui fonctionne.** 2. **Éviter les requêtes watch en rafale.** 3. **Ne pas utiliser OAuth pour l’extraction vidéo.** 4. **Android doit rester autonome.** 5. **Les données inconnues doivent rester inconnues.** 6. **La lecture doit être prioritaire sur les métadonnées secondaires.** 7. **Les optimisations doivent conserver les fallbacks robustes.** 8. **Une modification de cache ne doit pas supprimer un fichier encore utilisé par media_kit.** 9. **Une bascule de qualité ne doit pas incrémenter les vues personnelles.** 10. **Les nouveaux fichiers ou modifications du projet doivent être livrés dans un ZIP avec chemins relatifs au projet.** --- # 52. Limitations connues actuelles ## YouTube rate limiting Le endpoint public `/watch` peut être temporairement limité. Conséquence : ```text RequestLimitExceededException ``` La stratégie actuelle consiste à réduire le nombre de requêtes et à privilégier yt-dlp Windows. --- ## Informations chaîne incomplètes Les chemins publics peuvent fournir : ```text abonnés ``` mais pas toujours : ```text vues chaîne date création nombre vidéos ``` Le fallback yt-dlp est utilisé lorsque possible. --- ## 360p Windows + HD La logique 18.7.3 est conçue pour restaurer : ```text 360p rapide → HD ``` tout en évitant le endpoint rate-limité. Cette partie doit être validée en conditions réelles sur vidéo non mise en cache. --- ## Téléchargement progressif Windows Des erreurs historiques observées peuvent inclure : ```text yt-dlp exit code négatif fichier en cours d’utilisation sous Windows cache incomplet download interrompu ``` Le système doit isoler les caches et ne pas considérer un fichier partiel comme complet. --- # 53. Évolutions possibles Évolutions compatibles avec le projet : - page de réglages Radar ; - poids par catégorie ; - bouton « moins de vidéos comme celle-ci » ; - fréquence maximale par chaîne ; - déduplication avancée des recommandations ; - import/export des préférences ; - gestion taille maximale du cache ; - nettoyage cache manuel ; - file d’attente ; - playlist locale ; - historique par session ; - recherche dans une chaîne ; - filtre durée ; - filtre année ; - filtre popularité ; - indicateur vidéo déjà regardée ; - indicateur progression dans les cartes ; - statistiques personnelles avancées ; - dashboard « temps regardé par chaîne » ; - dashboard « catégories regardées » ; - bouton SponsorBlock configurable par catégorie. --- # 54. Règles de développement du projet Pour les évolutions futures : - partir de la dernière version fonctionnelle validée ; - ne pas réécrire une architecture stable sans nécessité ; - préserver les fonctionnalités Windows et Android existantes ; - diagnostiquer les logs avant de changer le pipeline vidéo ; - ne pas demander à l’utilisateur d’éditer manuellement le code ; - livrer chaque modification sous forme de ZIP contenant uniquement les fichiers modifiés ou ajoutés ; - conserver les chemins relatifs à la racine du projet ; - ne jamais exposer les secrets OAuth, URLs signées, tokens, POT ou données sensibles dans les réponses ou documents. --- # 55. Résumé d’architecture ```text ┌──────────────────────┐ │ Interface Flutter │ └──────────┬───────────┘ │ ┌──────────────────────┼──────────────────────┐ │ │ │ ▼ ▼ ▼ Radar local Bibliothèque Compte Google │ │ │ ▼ ▼ ▼ RadarService LibraryService GoogleAuthService │ │ │ ▼ │ YoutubeAccountService │ └──────────────┐ ▼ YoutubeService │ ┌────────────┴────────────┐ │ │ ▼ ▼ Android Windows │ │ │ ▼ │ WindowsHdService │ │ │ ▼ │ yt-dlp │ │ │ ▼ │ Progressive local cache │ │ │ ▼ │ HTTP local │ │ └──────────────► media_kit ``` --- # 56. État de référence La version de référence fonctionnelle actuelle est basée sur la série : ```text 17.x : lecture HD Windows 18.x : Radar, chaînes, métadonnées, SponsorBlock 18.7.x : enrichissement chaîne, réduction rate-limit, restauration startup 360p 18.7.3 : 360p progressif rapide puis HD ``` Ce document doit être mis à jour à chaque évolution importante de l’architecture ou des spécifications.