stanuser297/thumbnail-generator

Thumbnail Generator

エージェントワークフロー＋決定論的レンダラー。あらゆるチャンネルに適応可能。このパッケージはスタイルルール、レイアウトテンプレート、フォント、フレームツール、レンダラーを提供し、ホストエージェントが理解と判断を担当します。

ワークフロー

1. 動画ブリーフ（ホストによる理解、パッケージによるエビデンス）: 動画のタイトル、説明、チャプター/トランスクリプト、サンプルフレームを読み込みます。scripts/video_brief.py --video V --transcript subs.srt --scenes --out brief.json でエビデンスを収集します：トランスクリプトの用語頻度（プレーンな単語カウント、モデル不使用）と ffmpeg によるシーンカットタイムスタンプ。ホストがブリーフの main_question、show、avoid_implying フィールドを埋めます。サムネイルが正直に伝えるべきことと、決して暗示してはいけないことを指定します。パッケージ単体では動画内容を理解できません。動画メタデータ、フレーム、テキストを読み取れるホストが必要です。候補フレーム: scripts/extract_frames.py VIDEO --out frames/（均等サンプリング）または --scenes（最も強いシーンカットのフレーム - 何かが変わった瞬間を示しますが、どの瞬間が重要かの証明にはなりません）。
2. 参照選択（ホストエージェントの能力）: クリエイターのプライベート参照ライブラリから、この動画の主題に合う2～3の参照を選び、具体的なパターン（テキストサイズ/配置、コントラスト、被写体位置）をメモします。scripts/analyze_references.py FOLDER [--labels sources.csv] で、クリエイター自身のローカルライブラリフォルダからピクセルレベルの統計（明るさ、コントラスト、暗さ/カラフルさの割合）を取得し、選択を裏付けます。ライブラリはローカルディスクから出ず、このパッケージ内に出荷されることはありません。大規模ライブラリの場合、ホストはフォルダに対して1回のビジョンパスを実行し、各参照のトピック/ムード/構成をプライベートな reference_tags.json（スキーマは examples/example_reference_tags.json にあり）に記録できます。scripts/match_references.py --tags reference_tags.json --topic ... --mood ... でタグの重複により候補を絞り込み、ホストが確認します。タグファイルはライブラリの隣でリポジトリ外に保管されます。画像と同様です。
3. 不足入力の収集: サムネイルテキスト（2～4単語、動画に正直）、1つのアクセント単語、レイアウト、スタイルムード（styles.json の5つのうちの1つ）、言語（ヒンディー語/英語）、選択したフレーム（最もシャープな静止画ではなく、動画の主題に合った実際の動画の瞬間）。チャンネルプロファイル（profiles.json）でデフォルトを指定可能。明示的な選択は常に上書きします。不足しているものがあればクリエイターに尋ねます。
4. キャラクター表情編集と切り抜き（オプション。ホストの画像編集能力）: サムネイルが動画の瞬間に合った特定のリアクション（驚き、喜び、怒り）を表示する必要がある場合、ホストは画像編集モデルを使用して選択したフレームを編集できます。キャラクターの同一性、イラストスタイル、背景を維持し、表情のみを変更します。切り抜きルック（被写体を背景から浮かび上がらせ、アウトラインを付ける。参照ライブラリで支配的なパターン）の場合、ホストがキャラクターをフラットな単色背景（グリーンスクリーンが最適）に配置し、scripts/make_cutout.py shot.png --out subject.png を実行します。キーイングは完全にローカルで実行され、単色背景ショットの生成のみホストの画像ツールが必要です。--subject subject.png で合成（stack-left/bottom-left: 被写体は右側にポップアウトラインとシャドウ、テキストは被写体と重ならないように配置）。このパッケージには画像モデルは含まれていません。編集にはホスト環境が提供する画像編集機能を使用し、有料プロバイダーやサインアップは想定していません。そのような機能がない場合は、このステップをスキップし、既存の表情が適切なフレームを選択します。ルール: クリエイター自身の動画のイラスト/アバターアセットのみを編集すること。実際の人物の表情を実際のイベントの主張のために捏造しないこと。すべての編集をラン・マニフェストに記録すること（--reaction-edit）。クリエイターが編集されたことを認識できるようにします。
5. 異なるコンセプト（色のローテーションではない）: 動画ごとに、真に異なる2～3のコンセプト（異なるフック、異なるフレーム/シーン、異なる構成）をデザインし、1回の実行でレンダリングします。scripts/run_thumbnail.py --video V --concepts concepts.json --out set.jpg（JSONの各エントリは独自のタイトル、フレーム、レイアウト、コンセプトノート、オプションの subject/reaction_edit を持ち、1つのマニフェストがセット全体を記録します）。--variants N は同じテキストのスタイル/レイアウトのローテーション用で、実際の意思決定には弱い選択です。
6. レンダリング＋マニフェスト: scripts/run_thumbnail.py --video V --title T --accent A [--profile P] [--style S] [--layout L] [--variants N] [--label K] [--lang hi] [--reaction-edit "編集内容"] [--subject subject.png] [--brief brief.json] [--channel NAME] --frame F --frame-time SECONDS --concept "..." --refs IDs --ref-notes "..." --out thumb.jpg は最大N個のバリアントと *.manifest.json ラン記録（入力動画ID、プロファイル、参照したもの、コンセプト、選択したフレーム、表情編集の有無、すべての出力）を書き出します。--brief を指定すると、各出力に hook_evidence（フックの単語を共有するトランスクリプト行と、フックがトランスクリプトにない絶対的主張（dead/khatam/over/...）をした場合の警告）が含まれます。これは真実性レビューのための証拠であり、真実の判定ではありません。単語を共有していても誤解を招く可能性があります。--channel を指定すると、チャンネルごとのデザイン履歴（.thumbnail-history/、リポジトリ外）が、新しいレンダリングがそのチャンネルの最近のパターン（同じスタイルファミリーまたはレイアウトが3回連続、カットアウト被写体が直近4件中3件など）を繰り返す場合に警告します。警告であってブロックではありません。意図的なシリーズスタイリングは問題ありません。その後実行が記録されます。マニフェストなしのクイックレンダリングには scripts/make_thumbnail.py を直接使用します。--mobile-preview で380px幅のレンダリングを追加し、スマートフォンサイズでの可読性をチェックできます。
7. 品質ゲート（2層）:
   • 自動（測定可能なもののみ）: run_thumbnail.py は scripts/check_thumbnail.py をすべての出力に対して実行し、その結果をマニフェスト（quality_checks）に記録します。実行中に警告/失敗が表示されます。チェック内容: 1280x720のサイズ、2MBのYouTube制限、380px電話サイズでのテキストゾーンのコントラスト、--subject カットアウト使用時のペーストカットアウトの明るさ。被写体チェックはカットアウトの既知の配置を読み取ります。顔検出器ではなく、背景フレーム内部の顔については何も述べません。フレームベースのレンダリングは依然として人間の目での確認が必要です。スタンドアロンで実行することも可能: python3 scripts/check_thumbnail.py thumb.jpg --layout stack-left --subject subject.png（FAIL で exit 1 を返すため、ワークフローのゲートとして使用可能）。
   • 意味的（ホストの判断。決して保証されない）: ピクセルでは確認できないものをレビューします: (1) フックの真実性 - テキストは動画が実際に問う質問か、動画がサポートする主張でなければなりません。クリックのためにでっち上げられた絶対的主張であってはなりません（マニフェストの hook_evidence を出発点として証拠を確認し、その後判断）。(2) 画像とトピックの一致 - フレームは動画の主題に属している必要があります（テクノロジー解説動画の後ろに宗教的または歴史的な絵画があるのは拒否）。(3) スタイルムードの適合 - 巨大で凝縮されたハイプテキストはドラマチックなトピックに適し、穏やかな解説ではより落ち着いた構成が適切な場合があります。(4) バラエティ - すべての動画で同じレイアウトと表情の組み合わせを使用しない。次に画像とモバイルプレビューを開きます: アクセント単語がハイライトされていること、フレームの被写体と重なっていないこと、編集された表情が同じキャラクターに見えることを確認します。
8. 承認: クリエイターがアップロード前に承認します。ターゲット編集: 変更するフラグのみを指定して make_thumbnail.py --spec thumb.spec.json を再実行します。

スコープ - このパッケージの機能と非機能

• 機能: 動画静止画の抽出/スコアリング、スタイルシステム（フォント、色、4つのレイアウト）の適用、ヒンディー語または英語でのバリアントレンダリング、スタイル選択のためのローカル参照フォルダの分析、サムネイルごとの編集可能なスペックと実行マニフェストの保持。
• 非機能: 動画の意味理解、フックやコンセプトの単独選択、画像の単独編集（リアクション編集はホスト自身の画像編集能力を使用。パッケージは記録のみ）、メッセージの正直さの検証、アップロード。これらはホストエージェント/クリエイターの判断と能力であり、宣言された入力として提供されます。CTR学習にはチャンネル分析アクセスと制御されたデータが必要です。このパッケージには含まれません。

レイアウトとスタイル

4つのレイアウト（bottom-left、stack-left、center-big、split）。97画像の参照ライブラリの支配的なパターンから学習: ハイライトバー付きの積み重ね大文字、中央のデスティネーションタイトル、ビフォーアフターの分割、グラデーションフレーム上の左下ブロック。styles.json に5つのカラーコンボ（documentary、finance、tech、podcast、boldred）: 1つの背景色、1つのテキスト色、1つのアクセント色。ルール: 2～4単語、1つのアクセント単語（ハイライト）、1つのフォントファミリー。

必要条件

Python 3（Pillow、numpy）、PATHに ffmpeg（フレーム抽出と動画メタデータ用）。レンダリング時にネットワーク不要。

参照ライブラリ

デザインパターンは、クリエイターのプライベート参照ライブラリ（97枚のサムネイル。リアクションフェイス、太字タイポグラフィ、ポッドキャスト、ゲーミング、旅行などのファミリーを含む）から学習されます。ライブラリは非公開のままです。画像をこのパッケージや配布物に含めないでください。analyze_references.py はクリエイターが指定したローカルフォルダのみを読み取ります。