JoeyRedfield/videobook

VideoBook : Transformer une vidéo en eBook technique illustré

L'utilisateur fournit un lien YouTube / Bilibili, et le skill produit un eBook technique consultable en ligne : output/<video_id>/book.md + book.html (avec cartes lecteur intégrées, images cliquables, diagrammes Mermaid), optionnellement transcript.corrected.txt (transcription corrigée), et publication sur GitHub Pages.

Ce skill est une couche d'orchestration et est autonome : toutes les instructions nécessaires à l'agent se trouvent dans ce répertoire (SKILL.md + references/), il ne dépend pas de instructions.md / README.md du dépôt (ces fichiers sont destinés aux lecteurs humains et ne sont pas modifiés par ce skill). La seule dépendance externe est le code exécutable du pipeline src/*.py : les commandes et paramètres sont toujours définis par le --help des scripts, ne réécrivez pas la logique des scripts. Les données volatiles (par exemple la MAP des mots erronés dans src/make_corrected.py) ne doivent pas être copiées dans le skill, indiquez simplement la règle et pointez vers le fichier source ; la seule exception est la deuxième étape (instructions de mise en page), ce répertoire contient une copie synchronisée references/stitcher-prompt.md (la version du dépôt prime).

Prérequis (à lire avant la première exécution)

1. Le répertoire de travail = racine du dépôt videobook (vérifiez la présence de src/dump_transcript.py et prompts/), tous les chemins relatifs (output/<video_id>/...) sont résolus par rapport à lui. Si le dépôt n'est pas local, commencez par git clone https://github.com/Luke-Evan/videobook.git dans le répertoire où l'utilisateur stocke ses projets de code (pas dans un répertoire temporaire, et ne créez pas de nouveau répertoire projects), puis cd dedans.
2. Python >= 3.10 (recommandé 3.12). Installez les dépendances : uv sync (si vous utilisez uv) ou pip install -r requirements.txt. Exécutez toujours via l'interpréteur de l'environnement du dépôt : uv run python src/xxx.py ou .venv/Scripts/python.exe src/xxx.py.
3. Connexion unique : python src/capture_frames.py --setup-profile ouvre un Chrome dédié (répertoire de données .capture-profile/), connectez-vous à Bilibili / YouTube, puis fermez la fenêtre. La session de connexion est réutilisée longtemps. Le niveau d'abonnement du compte connecté = limite de qualité des captures.
4. Vidéos étrangères : le terminal doit utiliser un proxy (pour les sous-titres), le navigateur aussi doit être en mode proxy global (sinon l'iframe YouTube dans la page générée sera un bloc noir).
5. Les commandes nécessitant des privilèges élevés sont indiquées dans la dernière colonne du tableau récapitulatif ; les étapes purement locales peuvent être exécutées dans la sandbox.

Aperçu du pipeline

Étape	Action	Commande	Détails	Privilèges
1	Extraction des sous-titres	python src/dump_transcript.py "<URL>"	references/transcript.md	Nécessaire pour Bilibili
1b	Secours ASR local si la plateforme n'a pas de sous-titres	python src/asr_transcript.py <video_id>	references/transcript.md	Non (long)
1.5	Supports de cours officiels + diapositives 4K (exécuté par défaut, ignoré si le cours n'a pas de page d'accueil)	python src/course_assets.py <video_id> --course-url <URL du cours>	references/course-assets.md	Nécessaire pour le rendu
2	Réécriture des sous-titres en book.md par LLM	Selon les instructions de mise en page (references/stitcher-prompt.md, ou prompts/stitcher_system.md du dépôt s'il existe)	references/writing.md	Non
2b	Transcription corrigée (optionnelle)	python src/make_corrected.py <video_id>	references/correction.md	Non
3	Capture d'images et matérialisation des placeholders	python src/capture_frames.py <video_id> "<URL>"	references/capture.md	Oui
4	Rendu HTML + prévisualisation locale	python src/post_process.py "<URL>" output/<id>/book.md puis python -m http.server 8080 --directory output/<id>	—	Non
5	Informer l'utilisateur du résultat, demander le nettoyage des gros fichiers	—	Voir ci-dessous « Livraison »	—
6	Publication sur la branche pages (optionnelle)	python src/publish.py <video_id> puis git push origin pages	references/publish.md	Non (push nécessite réseau)

En cas d'erreur, de mauvaise qualité d'image, d'absence de sous-titres ou d'interruption de l'ASR, consultez d'abord references/troubleshooting.md.

Règles absolues (non négociables)

1. Couverture des sous-titres < 50 % (code de sortie 3) : ne passez pas à l'étape 2 : corrigez d'abord la session/proxy, ou passez au secours ASR.
2. Les images capturées doivent provenir du lecteur de la plateforme via un navigateur connecté, aucun téléchargement de fichier vidéo/audio n'est autorisé à l'étape 3 (ffmpeg en dernier recours). Liste des méthodes interdites dans references/capture.md.
3. Les cookies ne sont écrits que dans le répertoire temporaire système, supprimés après usage, jamais dans le dépôt, et ne placez pas manuellement de cookies.txt dans l'espace de travail.
4. output/ n'est pas affecté par les opérations git ; les livrables sont publiés uniquement sur la branche orpheline pages, main ne contient que le code.
5. Fidélité de la transcription corrigée : conservez mot pour mot les paroles du formateur et leur ordre, ne faites que remplacer les mots erronés de l'ASR + supprimer les tics de langage ; ne supprimez pas de segments, ne fusionnez pas de lignes, ne réécrivez pas massivement (la couche de validation rejettera directement).
6. Fidélité de l'écriture du livre : la mise en forme écrite n'est pas un résumé ; conservez les analogies, les cas concrets, les chaînes de déduction ; les ajouts de l'éditeur doivent être marqués « Note de l'éditeur ».
7. Droits d'auteur des supports de cours : les supports et diapositives appartiennent au formateur (souvent sous licence CC BY-NC), le bloc d'information en tête de livre et la fin doivent conserver le lien vers la source, le nom de l'auteur et le nom de la licence.
8. Règle absolue sur les diapositives : chaque page de slides_text.md doit apparaître exactement une fois dans le livre, avant la soumission, --audit doit PASSER.
9. Suppression des fichiers volumineux (audio.m4a, video_source.mp4, etc.) : demandez toujours à l'utilisateur avant de les supprimer, ne les supprimez qu'après confirmation.
10. Lors de la génération ou de la modification du HTML, le contraste entre le texte et l'arrière-plan ne doit pas être inférieur à 4,5:1 (norme WCAG AA).
11. Chaque étape est idempotente et peut être relancée : avant la matérialisation des placeholders, le script sauvegarde automatiquement book.tagged.md ; tant qu'il existe, relancer l'étape 3 permet de restaurer les captures.

Livraison (à l'étape 5, à dire en une fois)

1. Emplacement de output/<video_id>/book.md ;
2. Adresse de prévisualisation http://localhost:8080/book.html, fermez le service en appuyant sur Ctrl+C dans le terminal ;
3. Les vidéos YouTube nécessitent que le navigateur puisse accéder à YouTube (proxy), les vidéos Bilibili sont directement lisibles ;
4. La qualité des captures dépend du niveau du compte connecté dans .capture-profile/ ; pour une meilleure qualité, connectez-vous avec un autre compte et relancez l'étape 3 ;
5. Si des supports de cours officiels ont été utilisés, précisez que les illustrations des diapositives sont des rendus 4K officiels (la source et la licence CC sont mentionnées en tête de livre), que les images des démonstrations sont toujours des images vidéo, et que le répertoire course/ peut être supprimé sans affecter la lecture ;
6. Demandez si l'utilisateur souhaite supprimer les fichiers médias volumineux générés pendant le pipeline (règle absolue 9).

Contenu de ce répertoire (lire selon les besoins, ne pas tout lire en une fois)

Fichier	Quand le lire
references/transcript.md	Étape 1 : extraction des sous-titres ; pas de sous-titres sur la plateforme → passer à l'ASR local
references/writing.md	Étape 2 : réécriture des sous-titres en book.md
references/stitcher-prompt.md	Instructions de mise en page de l'étape 2 (la version du dépôt prompts/stitcher_system.md prime si elle existe)
references/course-assets.md	Étape 1.5 si le cours a une page d'accueil officielle, règles absolues sur les supports, amélioration des diapositives
references/correction.md	Génération de la transcription corrigée et des propositions de correction par l'IA au niveau des lignes
references/capture.md	Étape 3 : capture d'images, priorités, méthodes explicitement interdites, bonnes pratiques QA
references/publish.md	Étape 6 : publication sur la branche pages
references/troubleshooting.md	Toute erreur, anomalie de qualité d'image, sous-titres introuvables, refus de privilèges

Conventions de maintenance

• Ce skill est versionné avec le code du pipeline dans le même dépôt : si les paramètres, l'ordre des étapes ou les règles absolues de src/*.py changent, ce répertoire doit être mis à jour en conséquence.
• Les fichiers instructions.md et README.md du dépôt sont destinés aux lecteurs humains, ils restent inchangés et ne sont pas maintenus par ce skill, ne les modifiez pas pour faire fonctionner le skill ; en cas de chevauchement de contenu, l'agent se base sur ce répertoire.
• Lors de la synchronisation de references/stitcher-prompt.md, mettez à jour le numéro de commit dans la note de source en en-tête du fichier.
• Installation par un tiers : skill-installer avec --repo Luke-Evan/videobook --path skills/videobook ; ou après clone, copiez/placez un lien symbolique de ce répertoire vers ~/.codex/skills/ (Codex uniquement) ou ~/.agents/skills/ (multi-agent).
• Ce répertoire ne contient pas de cookies, de sessions, de fichiers de sortie output/ ni aucun fichier média, il peut être distribué publiquement en toute sécurité.