stanuser297/thumbnail-generator

Thumbnail Generator

Agenten-Workflow + deterministischer Renderer, an jeden Kanal anpassbar. Das Paket liefert Stilregeln, Layout-Vorlagen, Schriftarten, Frame-Tools und den Renderer; der Host-Agent liefert Verständnis und Urteilsvermögen.

Workflow

1. Video-Brief (Host-Verständnis, Paket-Beweise): Lies den Titel, die Beschreibung, Kapitel/Transkript und Beispiel-Frames des Videos. scripts/video_brief.py --video V --transcript subs.srt --scenes --out brief.json sammelt die Beweise: Transkript-Termfrequenzen (einfache Wortzählungen, kein Modell) und Szenenschnitt-Zeitstempel via ffmpeg. Der Host füllt dann die Felder main_question, show und avoid_implying des Briefs – was das Thumbnail ehrlich kommunizieren muss und was es NICHT implizieren darf. Das Paket versteht Videoinhalte nicht selbstständig; es benötigt einen Host, der Video-Metadaten, Frames und Text lesen kann. Kandidaten-Frames: scripts/extract_frames.py VIDEO --out frames/ (gleichmäßige Abtastung) oder --scenes (Frames an den stärksten Szenenschnitten – Momente, in denen sich etwas geändert hat, kein Beleg dafür, welcher Moment wichtig ist).
2. Referenzauswahl (Host-Agent-Fähigkeit): Wähle aus der privaten Referenzbibliothek des Erstellers 2–3 Referenzen aus, deren Komposition zum Thema des Videos passt, und notiere die konkreten Muster (Textgröße/-platzierung, Farbkontrast, Subjektposition). scripts/analyze_references.py FOLDER [--labels sources.csv] liefert Pixel-Statistiken (Helligkeit, Kontrast, Anteil dunkel/bunt) über den eigenen lokalen Bibliotheksordner des Erstellers, um diese Entscheidungen zu fundieren; die Bibliothek verlässt nie die lokale Festplatte und wird nie im Paket ausgeliefert. Bei größeren Bibliotheken kann der Host EINEN visuellen Durchlauf über den Ordner machen und die Themen/Stimmung/Komposition jeder Referenz in einer privaten reference_tags.json (Schema in examples/example_reference_tags.json) aufzeichnen; scripts/match_references.py --tags reference_tags.json --topic ... --mood ... filtert dann Kandidaten nach Tag-Überschneidungen, die der Host ansehen kann. Die Tags-Datei bleibt außerhalb des Repos neben der Bibliothek, genau wie die Bilder.
3. Fehlende Eingaben sammeln: Thumbnail-Text (2–4 Wörter, ehrlich zum Video), das EINE Akzentwort, Layout, Stimmungsstil (eine der fünf in styles.json), Sprache (Hindi/Englisch) und der gewählte Frame (ein echter Videomoment, der zum Thema passt, nicht nur das schärfste Standbild). Ein Kanalprofil (profiles.json) kann Standardwerte liefern; explizite Wahl überschreibt immer. Frage den Ersteller nach allem, was noch fehlt.
4. Charakter-Reaktionsbearbeitung und Freisteller (optional; Host-Bildbearbeitungsfähigkeit): Wenn das Thumbnail eine bestimmte Reaktion des Videocharakter (Schock, Freude, Wut) zeigen muss, die zum Videomoment passt, kann der Host den gewählten Frame mit einem Bildbearbeitungsmodell bearbeiten: Identität, Illustrationsstil und Hintergrund des Charakters beibehalten; nur den Ausdruck ändern. Für den Cut-Out-Look (Subjekt vom Hintergrund abgehoben mit einer Kontur, das dominante Muster der Referenzbibliothek) lasse den Host den Charakter auf einen gleichmäßigen Hintergrund (idealerweise Greenscreen) setzen und scripts/make_cutout.py shot.png --out subject.png ausführen – das Keying läuft vollständig lokal; nur das Erstellen des gleichmäßigen Hintergrunds benötigt das Bildtool des Hosts. Komponiere mit --subject subject.png (stack-left/bottom-left: Subjekt rechts mit Pop-Kontur und Schatten, Text bleibt frei davon). Dieses Paket enthält kein Bildmodell – Bearbeitungen nutzen die Bildbearbeitungsfähigkeit der Host-Umgebung, ohne Annahme eines kostenpflichtigen Anbieters oder einer Anmeldung. Wenn keine solche Fähigkeit existiert, überspringe diesen Schritt und wähle einen Frame, dessen vorhandener Ausdruck bereits passt. Regeln: nur illustrierte/Avatar-Assets aus dem eigenen Video des Erstellers bearbeiten; niemals den Ausdruck einer echten Person für eine reale Behauptung erfinden; jede Bearbeitung im Ausführungsmanifest vermerken (--reaction-edit), sodass der Ersteller weiß, dass der Ausdruck bearbeitet wurde.
5. Unterschiedliche Konzepte, keine Farbrotationen: Entwerfe für jedes Video 2–3 wirklich unterschiedliche Konzepte – unterschiedlicher Hook, anderer Frame/Szene, andere Komposition – und rendere sie in einem Durchlauf: scripts/run_thumbnail.py --video V --concepts concepts.json --out set.jpg (jeder Eintrag im JSON hat eigenen Titel, Frame, Layout, Konzeptnotiz und optionales Subjekt/reaction_edit; ein Manifest zeichnet den gesamten Satz auf). --variants N bleibt für Stil-/Layout-Rotationen des GLEICHEN Texts, was für echte Entscheidungen eine schwächere Wahl ist.
6. Rendern + Manifest: scripts/run_thumbnail.py --video V --title T --accent A [--profile P] [--style S] [--layout L] [--variants N] [--label K] [--lang hi] [--reaction-edit "was bearbeitet wurde"] [--subject subject.png] [--brief brief.json] [--channel NAME] --frame F --frame-time SEKUNDEN --concept "..." --refs IDs --ref-notes "..." --out thumb.jpg schreibt bis zu N Varianten und einen *.manifest.json-Ausführungsdatensatz (eingebettete Video-Identität, Profil, geprüfte Referenzen, Konzept, gewählter Frame, eventuelle Reaktionsbearbeitung, jede Ausgabe). Mit --brief erhält jede Ausgabe hook_evidence: Transkriptzeilen, die die Wörter des Hooks teilen, plus eine Warnung, wenn der Hook eine absolute Behauptung (dead/khatam/over/...) aufstellt, die das Transkript nie macht – Beweise für die Wahrheitsprüfung, KEIN Wahrheitsurteil; ein Hook kann Wörter teilen und trotzdem eine Falschdarstellung sein. Mit --channel warnt eine kanalspezifische Design-Erinnerung (.thumbnail-history/, außerhalb des Repos), wenn das neue Rendering das aktuelle Muster des Kanals wiederholen würde (gleiche Stilfamilie oder Layout 3 Mal in Folge, Cut-Out-Subjekt 3 der letzten 4) – Warnungen, niemals Blockaden, und bewusste Serienstilisierung ist in Ordnung; die Ausführung wird dann aufgezeichnet. Für ein schnelles Rendering ohne Manifest verwende direkt scripts/make_thumbnail.py; --mobile-preview fügt ein 380px breites Rendering für die Überprüfung der Lesbarkeit auf Telefongröße hinzu.
7. Qualitätskontrolle, zwei Ebenen:
   • Automatisch (nur messbar): run_thumbnail.py führt bereits scripts/check_thumbnail.py für jede Ausgabe aus und zeichnet die Ergebnisse im Manifest auf (quality_checks); Warnungen/Fehler werden während des Laufs ausgegeben. Prüfungen: 1280x720 Abmessungen, 2MB YouTube-Limit, Textzonen-Kontrast bei 380px Telefongröße und Helligkeit des eingefügten Cut-Outs, wenn ein --subject-Cutout verwendet wurde. Die Subjekt-Prüfung liest die BEKANNTE Platzierung des Cut-Outs – es ist kein Gesichtsdetektor und sagt nichts über Gesichter innerhalb eines Hintergrundframes; frame-basierte Renderings benötigen weiterhin Ihre Augen. Du kannst es auch eigenständig ausführen: python3 scripts/check_thumbnail.py thumb.jpg --layout stack-left --subject subject.png (Exit 1 bei FEHLER, sodass es einen Workflow blockieren kann).
   • Semantisch (Host-Urteil, niemals garantiert): Überprüfe, was Pixel nicht können: (1) Hook-Wahrhaftigkeit – der Text muss eine Frage sein, die das Video wirklich stellt, oder eine Behauptung, die es unterstützt, niemals eine absolute, die für Klicks erfunden wurde (nutze die hook_evidence des Manifests als Ausgangsbeweis, dann urteile); (2) Bild-Thema-Übereinstimmung – der Frame muss zum Thema des Videos gehören (ein religiöses oder historisches Gemälde hinter einem Tech-Erklärer-Hook ist eine Ablehnung); (3) Stil-Stimmungs-Passung – riesige kondensierte Hype-Schrift passt zu dramatischen Themen, ruhigere Erklärer lesen sich oft besser mit einer ruhigeren Komposition; (4) Abwechslung – nicht dasselbe Layout + derselbe Ausdruck bei jedem Video. Öffne dann das Bild und die mobile Vorschau: Akzentwort ist das hervorgehobene, kein Überlappen mit dem Subjekt des Frames, bearbeiteter Ausdruck sieht noch wie derselbe Charakter aus.
8. Genehmigen: Ersteller genehmigt vor jedem Upload. Gezielte Bearbeitungen: erneutes Ausführen von make_thumbnail.py --spec thumb.spec.json nur mit den geänderten Flags.

Umfang – was dieses Paket tut und was nicht

• Es TUT: Videostills extrahieren/bewerten, das Stilsystem anwenden (Schriftarten, Farben, 4 Layouts), Varianten auf Hindi oder Englisch rendern, einen lokalen Referenzordner auf fundierte Stilentscheidungen analysieren, eine bearbeitbare Spezifikation und ein Ausführungsmanifest pro Thumbnail behalten.
• Es tut NICHT: das Video semantisch verstehen, den Hook oder das Konzept selbstständig wählen, Bilder selbstständig bearbeiten (Reaktionsbearbeitungen nutzen die Bildbearbeitungsfähigkeit des Hosts; das Paket zeichnet sie nur auf), die Ehrlichkeit der Nachricht überprüfen oder etwas hochladen. Das sind Host-Agent-/Ersteller-Urteile und Host-Fähigkeiten, die als deklarierte Eingaben bereitgestellt werden. CTR-Lernen würde Kanalanalytikzugriff und kontrollierte Daten benötigen – nicht Teil dieses Pakets.

Layouts und Stile

Vier Layouts (bottom-left, stack-left, center-big, split), gelernt aus den dominanten Mustern einer 97-Bilder-Referenzbibliothek: gestapelte große Wörter mit einer Hervorhebungsleiste, zentrierte Ziel-Titel, Vorher/Nachher-Teilungen und Blöcke unten links über abgestuften Frames. Fünf Farbkombinationen in styles.json (Dokumentation, Finanzen, Technik, Podcast, Boldred): eine Hintergrundfarbe, eine Textfarbe, eine Akzentfarbe. Regeln: 2–4 Wörter, EIN Akzentwort (hervorgehoben), eine Schriftfamilie.

Anforderungen

Python 3 mit Pillow und numpy; ffmpeg im PATH für Frameextraktion und Video-Metadaten. Kein Netzwerk zur Renderzeit erforderlich.

Referenzbibliothek

Designmuster werden aus der privaten Referenzbibliothek des Erstellers gelernt (97 Thumbnails in den Kategorien Reaktionsgesicht, fette Typografie, Podcast, Gaming, Reisen und anderen). Die Bibliothek bleibt privat: niemals ihre Bilder in dieses Paket oder eine Verteilung aufnehmen. analyze_references.py liest nur einen lokalen Ordner, auf den der Ersteller verweist.