stanuser297/thumbnail-generator

Gerador de Miniaturas

Fluxo de trabalho de agente + renderizador determinístico, adaptável a qualquer canal. O pacote fornece regras de estilo, modelos de layout, fontes, ferramentas de quadro e o renderizador; o agente host fornece compreensão e julgamento.

Fluxo de trabalho

1. Briefing do vídeo (compreensão do host, evidências do pacote): leia o título, descrição, capítulos/transcrição e quadros de amostra do vídeo. scripts/video_brief.py --video V --transcript subs.srt --scenes --out brief.json monta as evidências: frequências de termos da transcrição (contagens de palavras simples, sem modelo) e timestamps de cortes de cena via ffmpeg. O host então preenche os campos main_question, show e avoid_implying do brief – o que a miniatura deve comunicar honestamente e o que NÃO deve implicar. O pacote não entende o conteúdo do vídeo por si só; ele precisa de um host que possa ler metadados do vídeo, quadros e texto. Quadros candidatos: scripts/extract_frames.py VIDEO --out frames/ (amostragem uniforme) ou --scenes (quadros nos cortes de cena mais fortes – momentos em que algo mudou, não prova de qual momento importa).
2. Seleção de referências (capacidade do agente host): da biblioteca de referências privada do criador, escolha 2-3 referências cuja composição se encaixe no assunto deste vídeo e anote os padrões concretos (tamanho/posicionamento do texto, contraste de cores, posição do sujeito). scripts/analyze_references.py FOLDER [--labels sources.csv] fornece estatísticas em nível de pixel (brilho, contraste, proporção escura/colorida) sobre a própria pasta da biblioteca local do criador para fundamentar essas escolhas; a biblioteca nunca sai do disco local e nunca é distribuída dentro deste pacote. Para bibliotecas maiores, o host pode fazer UMA passagem de visão sobre a pasta e registrar os tópicos/humor/composição de cada referência em um reference_tags.json privado (esquema em examples/example_reference_tags.json); scripts/match_references.py --tags reference_tags.json --topic ... --mood ... então pré-seleciona candidatos por sobreposição de tags para o host visualizar. O arquivo de tags fica fora do repositório, ao lado da biblioteca, exatamente como as imagens.
3. Coletar entradas ausentes: texto da miniatura (2-4 palavras, honesto em relação ao vídeo), a ÚNICA palavra de destaque, layout, clima do estilo (um dos cinco em styles.json), idioma (hindi/inglês) e o quadro escolhido (um momento real do vídeo que corresponda ao assunto, não apenas o still mais nítido). Um perfil de canal (profiles.json) pode fornecer padrões; escolhas explícitas sempre substituem. Pergunte ao criador por qualquer coisa ainda faltante.
4. Edição de reação do personagem e recorte (opcional; capacidade de edição de imagem do host): quando a miniatura precisar que o personagem do vídeo mostre uma reação específica (choque, alegria, raiva) que se encaixe no momento do vídeo, o host pode editar o quadro escolhido com um modelo de edição de imagem: preserve a identidade do personagem, estilo de ilustração e fundo; mude apenas a expressão. Para o visual recortado (sujeito elevado do fundo com um contorno, o padrão dominante na biblioteca de referências), peça ao host que coloque o personagem em um fundo uniforme e liso (tela verde funciona melhor) e execute scripts/make_cutout.py shot.png --out subject.png – a separação de planos roda totalmente localmente; apenas produzir o take com fundo uniforme precisa da ferramenta de imagem do host. Componha com --subject subject.png (stack-left/bottom-left: sujeito à direita com contorno e sombra pop-up, texto mantido longe dele). Este pacote não contém modelo de imagem – as edições usam qualquer capacidade de edição de imagem que o ambiente do host forneça, sem assumir provedor pago ou cadastro. Quando tal capacidade não existir, pule esta etapa e escolha um quadro cuja expressão existente já se encaixe. Regras: edite apenas ativos ilustrados/avatar do próprio vídeo do criador; nunca fabrique a expressão de uma pessoa real para uma alegação de evento real; registre cada edição no manifesto de execução (--reaction-edit) para que o criador saiba que a expressão foi editada.
5. Conceitos distintos, não rotações de cores: para cada vídeo, projete 2-3 conceitos genuinamente diferentes – gancho diferente, quadro/cena diferente, composição diferente – e renderize-os em uma execução: scripts/run_thumbnail.py --video V --concepts concepts.json --out set.jpg (cada entrada no JSON tem seu próprio título, quadro, layout, nota de conceito e sujeito/reaction_edit opcionais; um manifesto registra todo o conjunto). --variants N permanece apenas para rotações de estilo/layout do MESMO texto, que é uma escolha mais fraca para decisões reais.
6. Renderizar + manifesto: scripts/run_thumbnail.py --video V --title T --accent A [--profile P] [--style S] [--layout L] [--variants N] [--label K] [--lang hi] [--reaction-edit "o que foi editado"] [--subject subject.png] [--brief brief.json] [--channel NAME] --frame F --frame-time SEGUNDOS --concept "..." --refs IDs --ref-notes "..." --out thumb.jpg escreve até N variantes e um registro de execução *.manifest.json (identidade do vídeo de entrada, perfil, referências inspecionadas, conceito, quadro escolhido, qualquer edição de reação, cada saída). Com --brief, cada saída obtém hook_evidence: linhas da transcrição que compartilham as palavras do gancho mais um aviso quando o gancho faz uma afirmação absoluta (morto/acabado/acabou/...) que a transcrição nunca faz – evidência para a revisão de veracidade, NÃO um veredito de verdade; um gancho pode compartilhar palavras e ainda assim deturpar. Com --channel, uma memória de design por canal (.thumbnail-history/, fora do repositório) avisa quando a nova renderização repetiria o padrão recente do canal (mesma família de estilo ou layout 3 vezes seguidas, sujeito recortado 3 das últimas 4) – avisos, nunca bloqueios, e estilo deliberado de séries é aceitável; a execução é então registrada. Para uma renderização rápida sem um manifesto, use scripts/make_thumbnail.py diretamente; --mobile-preview adiciona uma renderização de 380px de largura para a verificação de legibilidade em tamanho de telefone.
7. Portão de qualidade, duas camadas:
   • Automático (apenas mensurável): run_thumbnail.py já executa scripts/check_thumbnail.py em cada saída e registra os resultados no manifesto (quality_checks); avisos/falhas são impressos durante a execução. Verificações: dimensões 1280x720, limite de 2MB do YouTube, contraste da zona de texto no tamanho de telefone de 380px e brilho do recorte colado quando um recorte --subject foi usado. A verificação do sujeito lê o posicionamento CONHECIDO do recorte – não é um detector de rostos e não diz nada sobre rostos dentro de um quadro de fundo; renderizações baseadas em quadro ainda precisam de seus olhos. Você também pode executá-lo de forma independente: python3 scripts/check_thumbnail.py thumb.jpg --layout stack-left --subject subject.png (saída 1 em FALHA, para que possa barrar um fluxo de trabalho).
   • Semântico (julgamento do host, nunca garantido): revise o que pixels não podem: (1) veracidade do gancho – o texto deve ser uma pergunta que o vídeo realmente faz ou uma alegação que ele apoia, nunca uma invenção absoluta para cliques (use o hook_evidence do manifesto como evidência inicial, depois julgue); (2) correspondência imagem-tópico – o quadro deve pertencer ao assunto do vídeo (uma pintura religiosa ou histórica atrás de um gancho de explicador de tecnologia é uma rejeição); (3) adequação estilo-clima – texto condensado gigante de hype se adequa a tópicos dramáticos, explicadores mais calmos podem ficar melhores com uma composição mais tranquila; (4) variedade – não o mesmo layout + mesma expressão em todos os vídeos. Em seguida, abra a imagem e a prévia do celular: a palavra de destaque é a destacada, sem sobreposição com o sujeito do quadro, expressão editada ainda se parece com o mesmo personagem.
8. Aprovar: o criador aprova antes de qualquer upload. Edições direcionadas: execute novamente make_thumbnail.py --spec thumb.spec.json apenas com os sinalizadores alterados.

Escopo – o que este pacote faz e não faz

• Ele FAZ: extrair/pontuar stills de vídeo, aplicar o sistema de estilo (fontes, cores, 4 layouts), renderizar variantes em hindi ou inglês, analisar uma pasta de referências local para escolhas de estilo fundamentadas, manter uma especificação editável e um manifesto de execução por miniatura.
• Ele NÃO faz: entender o vídeo semanticamente, escolher o gancho ou conceito por conta própria, editar imagens por conta própria (edições de reação usam a própria capacidade de edição de imagem do host; o pacote apenas as registra), verificar a honestidade da mensagem ou fazer upload de qualquer coisa. Esses são julgamentos do criador/agente host e capacidades do host, fornecidos como entradas declaradas. Aprendizado de CTR precisaria de acesso a análises de canal e dados controlados – não faz parte deste pacote.

Layouts e estilos

Quatro layouts (bottom-left, stack-left, center-big, split), aprendidos dos padrões dominantes em uma biblioteca de referência de 97 imagens: palavras enormes empilhadas com barra de destaque, títulos de destino centralizados, divisões antes/depois e blocos no canto inferior esquerdo sobre quadros gradientes. Cinco combinações de cores em styles.json (documentário, finanças, tecnologia, podcast, boldred): um fundo, uma cor de texto, um destaque. Regras: 2-4 palavras, UMA palavra de destaque (destacada), uma família de fontes.

Requisitos

Python 3 com Pillow e numpy; ffmpeg no PATH para extração de quadros e metadados de vídeo. Nenhuma rede necessária no momento da renderização.

Biblioteca de referência

Os padrões de design são aprendidos a partir da biblioteca de referência privada do criador (97 miniaturas em famílias de rosto de reação, tipografia ousada, podcast, jogos, viagens e outras). A biblioteca permanece privada: nunca inclua suas imagens neste pacote ou em qualquer distribuição. analyze_references.py lê apenas uma pasta local para a qual o criador aponte.