Files

T

iliasmouhcine 7704cae4a0 Light theme default + yt-dlp search fallback

2026-08-22 13:02:32 +01:00

34 KiB

Raw Blame History

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.

L’application comporte les sections principales suivantes :

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 :

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 :

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 :

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 :

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.

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 :

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 :

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 :

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 :

youtube_personal.favorites.v1

Les favoris participent au Radar.

9. Reprise de lecture

Les positions sont stockées localement.

Clé :

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é :

youtube_personal.watch_counts.v1

Une « vue personnelle » correspond à une vraie ouverture de vidéo.

Ne doivent pas incrémenter le compteur :

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

Le menu Chaînes liste les chaînes rencontrées par l’utilisateur.

Le classement principal est basé sur :

nombre de mes vues sur cette chaîne

et non sur les vues publiques cumulées de la chaîne.

Exemple :

#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 :

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 :

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 :

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 :

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 :

[ 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 :

>= 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 :

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 :

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 :

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 :

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 :

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 :

0.50x → 2.00x

Pas fin :

0.05x

Presets rapides :

0.50x
1.00x
1.50x
2.00x

17. Raccourcis plein écran Windows

En mode plein écran :

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 :

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 :

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 :

sponsor

Ne pas ignorer automatiquement par défaut :

intro
outro
self-promo
interaction reminder
preview

21.2 Comportement

lecture normale
→ entrée dans segment sponsor
→ seek à la fin
→ reprise lecture

Notification possible :

Sponsor ignoré automatiquement • 34s

21.3 Confidentialité

Utiliser le mode k-anonymity de SponsorBlock.

Principe :

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 :

VideoItem

Champs fonctionnels :

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 :

ChannelDetails

Champs possibles :

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 :

assets/windows_hd/yt-dlp.exe

Runtime JS :

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 :

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 :

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 :

vidéo : environ 2 MiB
audio : environ 512 KiB

Le service HTTP local sert les fichiers pendant leur croissance.

Routes :

/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 :

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 :

arrêt du relais 360p

30. HD Windows

Qualités cibles :

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 :

web_embedded

Formats observés possibles :

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 :

AV1
VP9
AVC

Toute optimisation de taille doit prévoir un fallback codec si le décodage local échoue.

31. Cache Windows

Répertoire :

%LOCALAPPDATA%\YouTubePersonal\media_cache\

Structure approximative :

media_cache/
  <videoId>/
    video_<formatId>.<ext>
    audio_<formatId>.<ext>
    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 :

[HD-WINDOWS]
[HD-PROGRESSIVE]
[HD-CACHE]
[HD-DOWNLOAD]
[YT-PLAYER]

Exemples attendus étape 18.7.3 :

[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 :

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 :

1 requête de catalogue
+
1 extraction bulk yt-dlp

35. Catalogue de chaîne Windows

Architecture récente :

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é :

1080p AVC + AAC

et :

3840 × 2160 VP9

Décodage observé :

c2.qti.vp9.decoder

Le 4K Android est considéré comme fonctionnel sur le terminal testé.

37. Sélecteur qualité Android

Qualités :

Défaut historique :

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 :

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 :

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 :

shared_preferences
SharedPreferencesAsync

Clés principales :

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 :

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 :

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 :

D:\07-Logiciels\23-youtube_personal

Flutter :

D:\07-Logiciels\00-Flutter\flutter

Android SDK :

C:\Users\abmou\AppData\Local\Android\sdk

Java Android Studio :

D:\Program Files\Android\Android Studio\jbr

46. Identité du projet

Nom Flutter :

youtube_personal

Package Android :

com.studioweb.youtube_personal

Version historique de base :

1.0.0+1

47. Commandes de lancement

Windows

cd "D:\07-Logiciels\23-youtube_personal"
flutter run -d windows

Android

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 :

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

Ne pas casser le pipeline HD Windows qui fonctionne.
Éviter les requêtes watch en rafale.
Ne pas utiliser OAuth pour l’extraction vidéo.
Android doit rester autonome.
Les données inconnues doivent rester inconnues.
La lecture doit être prioritaire sur les métadonnées secondaires.
Les optimisations doivent conserver les fallbacks robustes.
Une modification de cache ne doit pas supprimer un fichier encore utilisé par media_kit.
Une bascule de qualité ne doit pas incrémenter les vues personnelles.
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 :

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 :

abonnés

mais pas toujours :

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 :

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 :

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

                    ┌──────────────────────┐
                    │   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 :

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.

34 KiB Raw Blame History Unescape Escape

YouTube Personal — Spécifications fonctionnelles et techniques

1. Objectif du projet

2. Périmètre fonctionnel

2.1 Plateformes

Windows

Android

3. Navigation principale

4. Accueil — Radar personnel

4.1 But

4.2 Sections du Radar

4.3 Humeur de session

4.4 Score de recommandation

4.5 Explication « Pourquoi ? »

4.6 Actions sur les recommandations

4.7 Navigation horizontale desktop

5. Catégorisation des vidéos

6. Recherche

6.1 Recherche vidéo

6.2 Ouverture

7. Historique

8. Favoris

9. Reprise de lecture

10. Comptage personnel des vues

11. Gestion des chaînes

11.1 Menu Chaînes

11.2 Masquage d’une chaîne

11.3 Ouverture d’une chaîne

12. Page détaillée d’une chaîne

12.1 En-tête

12.2 Likes de chaîne

12.3 Commentaires cumulés

12.4 Résumé du catalogue

12.5 Catalogue vidéo

12.6 Informations sur les cartes de chaîne

13. Tri des vidéos d’une chaîne

Plus récentes

Plus anciennes

Plus vues

Plus aimées

14. Authentification Google

14.1 But

14.2 Fonctions OAuth

14.3 Séparation sécurité

15. Abonnements YouTube

16. Lecteur vidéo — fonctions générales

16.1 Commandes

16.2 Clic vidéo

16.3 Vitesse

17. Raccourcis plein écran Windows

18. Android — gestes tactiles

19. Picture-in-Picture

Windows

Android

20. Lecture en arrière-plan Android

21. SponsorBlock

21.1 But

21.2 Comportement

21.3 Confidentialité

22. Modèle de données vidéo

23. Métadonnées chaîne

24. Sources de métadonnées

24.1 YouTube Data API officielle

24.2 youtube_explode_dart

24.3 yt-dlp

25. Architecture lecture Windows

26. Historique des contraintes Windows

27. Windows — comportement cible étape 18.7.3

28. Prébuffer Windows 360p

29. Deux relais Windows séparés

30. HD Windows

30.1 web_embedded

30.2 Codecs

31. Cache Windows

32. Politique de cache

33. Gestion des erreurs Windows

34. Rate limiting YouTube

35. Catalogue de chaîne Windows

36. Android — HD et 4K

37. Sélecteur qualité Android

34 KiB

Raw Blame History

`YoutubeService`

`LibraryService`

`RadarService`

`GoogleAuthService`

`YoutubeAccountService`

`SponsorBlockService`

`WindowsHdService`

`WindowsEmbeddedProgressiveService`