JoeyRedfield/videobook

VideoBook: Ein Video in ein bebildertes E-Book verwandeln

Der Nutzer gibt einen YouTube- / Bilibili-Link, und es entsteht ein online lesbares Technik-E-Book: output/<video_id>/book.md + book.html (mit eingebetteten Player-Karten, klickvergrößerbaren Screenshots, Mermaid-Diagrammen), optional transcript.corrected.txt (korrigierte Untertitel-Gegenüberstellung) und Veröffentlichung auf GitHub Pages zur Ansicht durch andere.

Dieser Skill ist die Orchestrierungsschicht und in sich geschlossen: Alle Anweisungen, die der Agent benötigt, befinden sich in diesem Verzeichnis (SKILL.md + references/). Er ist nicht abhängig von instructions.md oder README.md im Repository (diese sind für menschliche Leser und werden von diesem Skill nicht verändert). Die einzige externe Abhängigkeit ist der ausführbare Code src/*.py der Pipeline: Befehle und Parameter richten sich ausschließlich nach dem --help der Skripte; die Skriptlogik wird nicht neu geschrieben. Veränderliche Daten (z. B. die Fehlerwort-MAP in src/make_corrected.py) werden nicht in den Skill kopiert, sondern es wird nur die Regel angegeben und auf die Quelldatei verwiesen. Einzige Ausnahme sind die Formatierungsanweisungen aus Schritt 2; dieses Verzeichnis enthält eine eigene Kopie references/stitcher-prompt.md (die Repository-Version hat Vorrang).

Voraussetzungen (vor dem ersten Durchlauf unbedingt lesen)

1. Arbeitsverzeichnis = Repository-Wurzel von videobook (Erkennung: Existenz von src/dump_transcript.py und prompts/), alle relativen Pfade (output/<video_id>/...) werden relativ dazu aufgelöst. Falls das Repository nicht lokal vorhanden ist, zuerst git clone https://github.com/Luke-Evan/videobook.git in ein vom Nutzer für Code-Projekte verwendetes Verzeichnis klonen (nicht in ein temporäres Verzeichnis und auch kein eigenes projects-Verzeichnis anlegen), dann mit cd hineinwechseln.
2. Python >= 3.10 (empfohlen 3.12). Abhängigkeiten installieren: uv sync (bei Verwendung von uv) oder pip install -r requirements.txt. Die Ausführung erfolgt einheitlich mit dem Interpreter aus der Repository-Umgebung: uv run python src/xxx.py oder .venv/Scripts/python.exe src/xxx.py.
3. Einmaliger Login: python src/capture_frames.py --setup-profile öffnet einen dedizierten Chrome (Datenverzeichnis .capture-profile/), nach dem Einloggen bei Bilibili / YouTube das Fenster schließen; der Login-Status bleibt dauerhaft erhalten. Die Mitgliedsstufe des eingeloggten Kontos bestimmt die maximale Screenshot-Auflösung.
4. Ausländische Videos: Terminal benötigt Proxy (für Untertitel), Browser benötigt ebenfalls globalen Proxy (sonst ist das YouTube-Iframe auf der generierten Seite ein schwarzer Block).
5. Befehle, die eine Sandbox-Erweiterung oder erhöhte Rechte benötigen, sind in der Übersichtstabelle in der letzten Spalte gekennzeichnet; rein lokale Schritte können in der Sandbox ausgeführt werden.

Pipeline-Übersicht

Schritt	Aufgabe	Befehl	Details	Erweiterte Rechte
1	Untertitel extrahieren	python src/dump_transcript.py "<URL>"	references/transcript.md	Für Bilibili erforderlich
1b	Lokales ASR als Fallback, falls Plattform keine Untertitel hat	python src/asr_transcript.py <video_id>	references/transcript.md	Nein (zeitaufwändig)
1.5	Offizielle Kursmaterialien + 4K-Folien (standardmäßig ausführen, nur überspringen, wenn der Kurs keine Startseite hat)	python src/course_assets.py <video_id> --course-url <Kursstartseite>	references/course-assets.md	Für Rendering erforderlich
2	Große Sprachmodelle schreiben Untertitel in book.md um	Nach Formatierungsanweisungen generieren (references/stitcher-prompt.md, falls prompts/stitcher_system.md im Repository existiert, hat diese Vorrang)	references/writing.md	Nein
2b	Korrigierte Untertitel-Gegenüberstellung (optional)	python src/make_corrected.py <video_id>	references/correction.md	Nein
3	Frames erfassen und Platzhalter durch Bilder ersetzen	python src/capture_frames.py <video_id> "<URL>"	references/capture.md	Ja
4	HTML rendern + lokale Vorschau starten	python src/post_process.py "<URL>" output/<id>/book.md dann python -m http.server 8080 --directory output/<id>	—	Nein
5	Ergebnis dem Nutzer mitteilen, nach großen Dateien fragen	—	Siehe unten unter „Lieferung“	—
6	Fertiges Ergebnis auf pages-Branch veröffentlichen (optional)	python src/publish.py <video_id> dann git push origin pages	references/publish.md	Nein (Push benötigt Netzwerk)

Bei Fehlern, falscher Bildqualität, nicht erfassten Untertiteln oder ASR-Abbrüchen zuerst in references/troubleshooting.md nachschlagen.

Eiserne Regeln (nicht verhandelbar)

1. Wenn die Untertitelabdeckung < 50 % ist (Exit-Code 3), darf nicht zu Schritt 2 übergegangen werden: Zuerst Login/Proxy reparieren oder auf ASR-Fallback umschalten.
2. Screenshots müssen vom eingeloggten Browser aus dem Player der Plattform stammen; auf keinen Fall dürfen Video-/Audiodateien heruntergeladen werden (ffmpeg-Frame-Extraktion ist nur letzter Ausweg). Eine Liste der verbotenen Methoden findet sich in references/capture.md.
3. Cookies werden nur in das temporäre Systemverzeichnis geschrieben und nach Gebrauch gelöscht, sie landen niemals im Repository und es wird keine cookies.txt im Arbeitsbereich manuell abgelegt.
4. output/ wird von keinem git-Vorgang beeinflusst; fertige Ergebnisse werden nur auf den orphan-Branch pages veröffentlicht, main enthält nur Code.
5. Korrektur-Treue: Absätze behalten die originalen Worte und die Reihenfolge des Dozenten bei; es werden nur ASR-Fehlerkorrekturen + Sprachmüllbereinigung vorgenommen. Keine Absätze löschen, keine Zeilen zusammenfassen, keine großflächigen Umschreibungen (die Prüfschicht lehnt dies direkt ab).
6. E-Book-Treue-Untergrenze: Verschriftlichung bedeutet nicht Zusammenfassung; Analogien, Fallbeispiele und Ableitungsketten bleiben erhalten. Herausgeberergänzungen müssen mit „Anmerkung des Herausgebers" gekennzeichnet werden.
7. Urheberrecht von Kursmaterialien: Skripte und Folien gehören dem Dozenten (üblich CC BY-NC); im Informationsblock am Buchende und im Buchkopf müssen Quellenlink, Autorenangabe und Lizenzname erhalten bleiben.
8. Eiserne Regel zur Folienabdeckung: Jede Seite aus slides_text.md erscheint genau einmal im Buch; vor Abgabe muss --audit BESTANDEN sein.
9. Vor dem Löschen großer Dateien (audio.m4a, video_source.mp4 usw.) muss der Nutzer gefragt werden, erst nach Bestätigung löschen.
10. Bei der Erstellung oder Änderung von HTML darf der Kontrast zwischen Text und Hintergrund nicht unter WCAG AA 4.5:1 liegen.
11. Jeder Schritt ist idempotent und kann wiederholt werden: Vor der Materialisierung der Platzhalter erstellt das Skript automatisch ein Backup book.tagged.md; solange dieses existiert, kann Schritt 3 einfach wiederholt werden, um die Screenshots wiederherzustellen.

Lieferung (bei Schritt 5 auf einmal sagen)

1. Pfad zu output/<video_id>/book.md;
2. Vorschau-Adresse http://localhost:8080/book.html; zum Beenden des Servers im Terminal Strg+C drücken;
3. YouTube-Videos benötigen einen Browser, der auf YouTube zugreifen kann (Proxy); Bilibili-Videos sind direkt sichtbar;
4. Die Screenshot-Auflösung hängt von der Mitgliedsstufe des in .capture-profile/ eingeloggten Kontos ab; für höhere Auflösung ein anderes Konto verwenden und Schritt 3 wiederholen;
5. Wenn offizielle Kursmaterialien verwendet wurden, im Buch darauf hinweisen, dass die Folienabbildungen offizielle 4K-Renderings sind (Quelle und CC-Lizenz sind im Buchkopf vermerkt), die Demonstrationsframes stammen weiterhin aus dem Video; das course/-Verzeichnis kann ohne Beeinträchtigung der Lesbarkeit komplett gelöscht werden;
6. Nachfragen, ob die während der Pipeline erzeugten großen Mediendateien gelöscht werden sollen (Eiserne Regel 9).

Inhalt dieses Verzeichnisses (nur bei Bedarf lesen, nicht auf einmal alles)

Datei	Wann lesen
references/transcript.md	Schritt 1: Untertitel erfassen; wenn Plattform keine Untertitel hat, auf lokales ASR umschalten
references/writing.md	Schritt 2: Untertitel in book.md umschreiben
references/stitcher-prompt.md	Schritt 2: Originaltext der Formatierungsanweisung (falls prompts/stitcher_system.md im Repository existiert, hat die Repository-Version Vorrang)
references/course-assets.md	Schritt 1.5 für Kurse mit offizieller Startseite, eiserne Regeln zur Abdeckung, Folien-Upgrade
references/correction.md	Korrigierte Untertitel-Gegenüberstellung und KI-gestützte zeilenweise Korrekturvorschläge
references/capture.md	Schritt 3: Frame-Erfassung: Prioritäten, ausdrücklich verbotene Methoden, QA-Gepflogenheiten
references/publish.md	Schritt 6: Veröffentlichung auf dem pages-Branch
references/troubleshooting.md	Jegliche Fehler, Bildqualitätsprobleme, nicht erfasste Untertitel, abgelehnte Rechteerweiterungen

Wartungskonventionen

• Dieser Skill wird zusammen mit dem Pipeline-Code im selben Repository versioniert: Wenn Parameter, Schrittreihenfolgen oder eiserne Regeln in src/*.py geändert werden, muss dieses Verzeichnis synchron aktualisiert werden.
• Die Dateien instructions.md und README.md im Repository sind für menschliche Leser gedacht, bleiben unverändert und werden von diesem Skill nicht gewartet. Sie dürfen nicht geändert werden, damit der Skill funktioniert. Bei Überschneidungen mit diesem Verzeichnis gilt für den Agenten dieses Verzeichnis.
• Bei der Synchronisierung von references/stitcher-prompt.md die Commit-Nummer im Quellenvermerk am Dateikopf aktualisieren.
• Installation durch andere: skill-installer mit --repo Luke-Evan/videobook --path skills/videobook; oder nach dem Klonen dieses Verzeichnis nach ~/.codex/skills/ (nur Codex) oder ~/.agents/skills/ (agentenübergreifend) kopieren/verlinken.
• Dieses Verzeichnis enthält keine Cookies, Login-Status, output/-Artefakte oder Mediendateien und kann sicher öffentlich verteilt werden.