stanuser297/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]는 제작자의 로컬 라이브러리 폴더에 대해 픽셀 수준 통계(밝기, 대비, 어두움/화려함 비율)를 제공하여 선택을 뒷받침합니다. 라이브러리는 로컬 디스크를 떠나지 않으며 이 패키지에 포함되지 않습니다. 더 큰 라이브러리의 경우, 호스트는 폴더에 대해 한 번의 비전 검사를 수행하고 각 참조의 주제/분위기/구성을 비공개 reference_tags.json에 기록할 수 있습니다(스키마는 examples/example_reference_tags.json 참조). 그런 다음 scripts/match_references.py --tags reference_tags.json --topic ... --mood ...는 태그 중복을 통해 후보를 선별하여 호스트가 검토할 수 있게 합니다. 태그 파일은 이미지와 마찬가지로 라이브러리 옆 저장소 외부에 유지됩니다.
3. 누락된 입력 수집: 썸네일 텍스트(2-4단어, 동영상에 정직함), 하나의 악센트 단어, 레이아웃, 스타일 분위기(styles.json의 다섯 가지 중 하나), 언어(힌디어/영어), 선택된 프레임(가장 선명한 정지 이미지가 아닌, 주제와 일치하는 실제 동영상 순간). 채널 프로필(profiles.json)은 기본값을 제공할 수 있습니다. 명시적 선택은 항상 재정의됩니다. 누락된 항목이 있으면 제작자에게 문의하세요.
4. 캐릭터 반응 편집 및 컷아웃 (선택 사항, 호스트 이미지 편집 능력): 썸네일에 동영상의 캐릭터가 동영상 순간에 맞는 특정 반응(충격, 기쁨, 분노)을 보여줘야 할 때, 호스트는 이미지 편집 모델을 사용하여 선택한 프레임을 편집할 수 있습니다: 캐릭터의 정체성, 일러스트레이션 스타일 및 배경은 유지하고 표정만 변경합니다. 컷아웃 모양(참조 라이브러리의 지배적인 패턴인 배경에서 분리된 윤곽선이 있는 피사체)의 경우, 호스트가 캐릭터를 평평한 단일 배경(녹색 화면이 가장 좋음)에 배치하고 scripts/make_cutout.py shot.png --out subject.png를 실행하도록 합니다 - 키잉은 완전히 로컬에서 실행됩니다. 단일 배경 샷을 생성하는 것만 호스트의 이미지 도구가 필요합니다. --subject subject.png로 합성합니다(왼쪽 아래 스택: 피사체가 오른쪽에 팝 윤곽선과 그림자와 함께 배치되고 텍스트는 피사체와 겹치지 않게 유지됨). 이 패키지에는 이미지 모델이 포함되어 있지 않습니다. 편집은 호스트 환경이 제공하는 모든 이미지 편집 능력을 사용하며, 유료 제공업체나 가입을 가정하지 않습니다. 그러한 능력이 없으면 이 단계를 건너뛰고 기존 표정이 이미 적합한 프레임을 선택합니다. 규칙: 제작자 자신의 동영상에 있는 일러스트/아바타 자산만 편집하고, 실제 사건 주장에 대해 실제 인물의 표정을 조작하지 마십시오. 모든 편집을 실행 매니페스트에 기록하십시오(--reaction-edit).
5. 고유한 컨셉, 색상 회전이 아님: 각 동영상에 대해 2-3개의 진정으로 다른 컨셉(다른 훅, 다른 프레임/장면, 다른 구성)을 디자인하고 한 번에 렌더링합니다: scripts/run_thumbnail.py --video V --concepts concepts.json --out set.jpg (JSON의 각 항목에는 고유한 제목, 프레임, 레이아웃, 컨셉 노트 및 선택적 피사체/반응_편집이 있으며, 하나의 매니페스트가 전체 세트를 기록합니다). --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가 포함됩니다: 훅의 단어를 공유하는 자막 줄과 훅이 자막에서 절대 하지 않는 절대 주장(죽음/끝/종료/...)을 할 때 경고 - 진실성 검토를 위한 증거이지, 진실 판결이 아닙니다. 훅은 단어를 공유할 수 있지만 여전히 잘못 표현할 수 있습니다. --channel과 함께 채널별 디자인 메모리(.thumbnail-history/, 저장소 외부)는 새 렌더링이 채널의 최근 패턴을 반복할 때 경고합니다(동일한 스타일 패밀리 또는 레이아웃 3회 연속, 컷아웃 피사체 최근 4개 중 3개) - 차단이 아닌 경고이며, 의도적인 시리즈 스타일링은 문제없습니다. 그런 다음 실행이 기록됩니다. 매니페스트 없이 빠른 렌더링을 위해서는 scripts/make_thumbnail.py를 직접 사용하십시오. --mobile-preview는 휴대폰 크기 가독성 확인을 위해 380px 너비의 렌더링을 추가합니다.
7. 품질 게이트, 두 계층:
   • 자동 (측정 가능만): 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 시 종료 코드 1이므로 워크플로우를 차단할 수 있음).
   • 의미론적 (호스트 판단, 절대 보장되지 않음): 픽셀이 할 수 없는 것을 검토합니다: (1) 훅 진실성 - 텍스트는 동영상이 실제로 묻는 질문이거나 지지하는 주장이어야 하며, 클릭을 위해 조작된 절대 주장이 아니어야 합니다(매니페스트의 hook_evidence를 시작 증거로 사용한 후 판단). (2) 이미지-주제 일치 - 프레임은 동영상의 주제에 속해야 합니다(기술 설명 훅 뒤에 있는 종교적 또는 역사적 그림은 거부). (3) 스타일-분위기 적합성 - 거대하고 압축된 과장 텍스트는 극적인 주제에 적합하고, 더 차분한 설명 영상은 조용한 구성이 더 잘 읽힐 수 있습니다. (4) 다양성 - 모든 동영상에 동일한 레이아웃 + 동일한 표정을 사용하지 마십시오. 그런 다음 이미지와 모바일 미리보기를 엽니다: 악센트 단어는 강조 표시된 단어이며, 프레임의 피사체와 겹치지 않고, 편집된 표정이 여전히 동일한 캐릭터처럼 보입니다.
8. 승인: 제작자는 업로드 전에 승인합니다. 대상 편집: 변경된 플래그만 사용하여 make_thumbnail.py --spec thumb.spec.json을 다시 실행합니다.

범위 - 이 패키지가 수행하는 것과 수행하지 않는 것

• 수행: 동영상 스틸을 추출/평가하고, 스타일 시스템(폰트, 색상, 4가지 레이아웃)을 적용하며, 힌디어 또는 영어로 변형을 렌더링하고, 로컬 참조 폴더를 분석하여 근거 있는 스타일 선택을 하며, 썸네일당 편집 가능한 스펙과 실행 매니페스트를 유지합니다.
• 수행하지 않음: 동영상을 의미론적으로 이해하거나, 훅이나 컨셉을 자체적으로 선택하거나, 이미지를 자체적으로 편집(반응 편집은 호스트의 이미지 편집 능력을 사용하며 패키지는 기록만 함), 메시지의 정직성을 확인하거나, 무엇이든 업로드합니다. 이러한 것들은 호스트 에이전트/제작자의 판단과 호스트 능력이며, 선언된 입력으로 제공됩니다. CTR 학습은 채널 분석 액세스와 통제된 데이터가 필요하며, 이 패키지의 일부가 아닙니다.

레이아웃 및 스타일

네 가지 레이아웃(bottom-left, stack-left, center-big, split), 97개의 이미지 참조 라이브러리의 지배적인 패턴에서 학습됨: 강조 표시줄이 있는 쌓인 큰 단어, 중앙 정렬 목적지 제목, before/after 분할, 그라데이션 프레임 위의 왼쪽 아래 블록. styles.json의 다섯 가지 색상 조합(다큐멘터리, 금융, 기술, 팟캐스트, 볼드레드): 하나의 배경색, 하나의 텍스트 색상, 하나의 악센트 색상. 규칙: 2-4단어, 하나의 악센트 단어(강조 표시됨), 하나의 글꼴 패밀리.

요구 사항

Pillow와 numpy가 포함된 Python 3, 프레임 추출 및 동영상 메타데이터를 위한 PATH의 ffmpeg. 렌더링 시간에 네트워크가 필요하지 않습니다.

참조 라이브러리

디자인 패턴은 제작자의 비공개 참조 라이브러리(반응 얼굴, 볼드 타이포그래피, 팟캐스트, 게임, 여행 및 기타 패밀리에 걸친 97개의 썸네일)에서 학습됩니다. 라이브러리는 비공개로 유지됩니다. 이미지를 이 패키지나 배포에 포함하지 마십시오. analyze_references.py는 제작자가 가리키는 로컬 폴더만 읽습니다.