yt-film

yt-film: filmes narrados a partir de imagens estáticas

Uma linha de produção para filmes de história: o usuário faz ~150 imagens estáticas a partir de um guia que o Claude escreve, o Claude escreve o roteiro a partir dessas imagens, uma voz o lê e o motor Python dá vida a cada imagem no ritmo das palavras. O filme de referência é o exemplo Chadwick (examples/chadwick/, A Filha de Carnegie: a mulher que tomou milhões emprestados como filha secreta de Andrew Carnegie): suas imagens, roteiro, voz, trilha sonora, listas de cenas e o vídeo de teste de efeitos de 70 segundos (examples/chadwick/video/chadwick_effects_test.mp4) mostram todas as técnicas.

REPO abaixo é a pasta deste skill (onde este arquivo está). PY é seu Python: REPO/.venv/bin/python no macOS/Linux, REPO\.venv\Scripts\python.exe no Windows. Sempre execute comandos do motor com PY, a partir da pasta tools/ do projeto. Se .venv não existir, configure primeiro: siga o Manual de instalação (para Claude) em references/install.md passo a passo (pergunte antes de instalações no sistema; o usuário cola sua própria chave de API).

Regras básicas

• Nunca renderize sem a aprovação do usuário. Verifique com stills.py (uma folha de contato em ~30 s). Renderizações em lote, pré-visualizações, o encerramento e a junção final levam de minutos a horas: diga o que você renderia e quanto tempo pode levar, e aguarde um sim. Não re-renderize nada que já foi renderizado, a menos que tenha mudado e o usuário queira.
• Pergunte as opções do usuário uma vez por projeto: qual ferramenta de imagem (references/image-generation.md), voz (Gemini TTS ou a própria: references/voice.md), música (Lyria ou a própria: references/music.md), o nicho e nome do canal, e as três escolhas que tornam o canal deles: o estilo de imagem (a abertura: gouache, editorial chapado, noir, giz, quadrinhos, livro de histórias, planta baixa, ou o próprio; personagens ou nenhum), a aparência do motor (YTF_LOOK: gouache, clean, noir, chalk, comic, storybook, blueprint; look.json para valores únicos) e o formato (story, explainer, countdown, rise-fall, storytime, kids, summary, case-study, news): references/art-styles.md, references/formats.md. Não use como padrão o estilo pastel de história real do exemplo; se o usuário não tiver preferência, mostre as opções em uma tabela curta e recomende uma que se encaixe no nicho dele.
• O nicho do usuário é dele: não o direcione para história ou para o assunto do exemplo. O exemplo é uma referência para técnicas, não um modelo para tópicos.
• Windows: caminhos com barras normais funcionam; trabalhos longos são executados em segundo plano; configurações de velocidade em references/performance.md. Nunca presuma ferramentas exclusivas do macOS.
• Sem chaves de API em arquivos além de .env. Baixe fotos ou arquivos de som reais somente após o OK do usuário (informe o arquivo, fonte, tamanho e licença).

A pilha

Tarefa	Ferramenta	Onde
Pesquisa	busca na web, lista de fatos verificados com fontes; sinalize o que não pode ser confirmado	OUTLINE.md
Imagens	a ferramenta de imagem do usuário, a partir do guia do Claude	IMAGE_GUIDE.md (+ IMAGE_PROMPTS.jsonl para a API), incoming/
Roteiro	Claude, escrito a partir do guia de imagens, uma passagem ## por batida, notas [SHOTS: …]	SCRIPT.md
Voz	Gemini TTS (voz Orus, leia devagar → 1.25x, pausas limitadas) ou o áudio do usuário via import_voice.py	tools/voice.py, tools/import_voice.py
Temporização de palavras	Whisper: mlx-whisper (Apple Silicon) ou faster-whisper (Windows/Intel/Linux)	voice/<batch>_words.json
Música	Lyria (Gemini API), uma dica por seção, ou faixas licenciadas do usuário	tools/music.py → audio/music/
Motor de filme	Python (OpenCV, Pillow, NumPy, SciPy), sem After Effects	tools/film.py, fx2.py, seq.py, signature.py, wr.py, kit.py
Listas de cenas	um arquivo por lote no seq.py, sincronizado com os tempos das palavras do lote	tools/<story>.py + tools/shots_bN.py
Renderizações	paralelas, dimensionadas para a máquina, baixa prioridade	tools/render_all.py
Encerramento	a própria vinheta animada do usuário (exemplo: cta.py)	renders/cta.mp4
Junção final	lotes + encerramento, uma trilha contínua, −14 LUFS / −2 dBTP	tools/final.py
Dublagens	Espanhol + Francês por padrão: tradução Gemini + TTS em chunks de ~3 min, ajustados aos slots em inglês	tools/dub.py
Miniaturas	a ferramenta de imagem do usuário, a partir de um guia	references/thumbnails.md

Os projetos ficam em YTF_WORKSPACE (padrão ~/yt-film-projects/<story>/), criado por PY REPO/scripts/new_project.py <story>, que copia o motor em tools/ e cria todas as pastas. As configurações estão em .env (projeto primeiro, depois REPO): GEMINI_API_KEY, YTF_CHANNEL, nomes de voz/modelo, botões de velocidade (.env.example lista todos). engine/ytf.py encontra fontes, a chave, Whisper e a arte compartilhada em qualquer sistema operacional.

A ordem do trabalho

0. Escolha a história se não for fornecida: 3–5 candidatos com verificação de lacunas (references/story-finding.md). Inicie o projeto com seu formato e aparência: PY REPO/scripts/new_project.py <nome> --format <formato> --look <aparência> (escreve o modelo do formato em OUTLINE.md, YTF_FORMAT e YTF_LOOK no .env). Teste um novo estilo em duas imagens com stills.py antes de escrever o guia completo (references/art-styles.md, última seção).
1. História e fatos: pesquisa; OUTLINE.md com fontes. Marque qualquer coisa não confirmada e contorne depois ("supostamente"), nunca afirme como fato. Decida o gancho (references/hooks.md: nunca o mesmo tipo dos últimos três filmes do usuário). Em seguida, escreva a espinha no topo de OUTLINE.md (references/storytelling.md): uma pergunta que o filme responde e 8–12 batidas unidas por "então" / "mas"; o primeiro ato errado ou momento decisivo até ~15% do filme; uma ou duas passagens de história de fundo por pessoa principal. Mostre ao usuário antes do guia de imagens.
2. Guia de imagens primeiro (references/image-guide.md, escrito para a rota do usuário). Ele segue a espinha e a forma como o filme é narrado (mostre, depois desenhe: cada linha da batida nomeia a fala que serve e o que é desenhado nela ou depois dela). Mire em ~150 imagens: cartão de estilo, folhas de elenco, ~100 fotos de cena com cobertura (W ampla, M médio, F close-up de rosto como EDIT, D detalhe, P ponto de vista), 6 cenas com versões _lines, 12 folhas de esboço + _lines, ~10 objetos de história em branco ("bases": um caderno, um mapa antigo, um cartão, um livro-razão, um envelope, um telegrama, um jornal). Nomes de arquivo e pastas exatos. Regras de consistência: references/consistency.md.
3. Verifique as imagens à medida que os grupos chegam (mãos, rostos, detalhes de época, sem texto, formato: as imagens chegam ~16:9 e são cortadas ao centro para 2:1, então nada importante no topo/fundo). Downloads manuais: scripts/sort_images.py. Em seguida, folhas quadriculadas em px do motor (COLS=4 PY tools/egrid.py out.png IMG ...) e mapeie as chaminés, lâmpadas, velas, respiração e áreas calmas de cada imagem antes de escrever as cenas.
4. Roteiro a partir das imagens. Cada imagem gerada é usada; mapeie cada passagem para suas cenas e execute a verificação de imagem não utilizada (exemplo: examples/chadwick/tools/script_check.py), depois PY tools/story_check.py (datas faladas, aberturas de mudança de cena, onde cai a passagem [DRIVE], cada emenda de lote) e as verificações em references/storytelling.md (recontar, 15%, mas/portanto, sem explicadores empilhados, 5–7 datas faladas, mostrar → desenhar). Sem limite de comprimento: conte a história completa e sem pressa (~150 palavras por minuto; Chadwick: 1.780 palavras → 12 min). Termine com a linha de like/inscreva-se do usuário.
5. Voz: Gemini (voice.py --test primeiro, depois lotes; --pace e SPEEDS para que cada lote fique em ~140–160 ppm) ou o áudio do usuário (import_voice.py --full | --passages | --batches). Defina BATCHES (4–7 passagens, ~65–100 s cada, corte no meio do ato onde a história está se movendo; apenas 2–3 cortes nas quebras de ato; nada reintroduzido no início de um lote) e GAPS. Imprima as palavras de cada lote antes de escrever suas cenas (Whisper ouve mal nomes e escreve números como dígitos: sincronize com o que ele escreveu).
6. Música: 5–7 dicas (music.py, ou arquivos do usuário em audio/music/); mapeie dicas para lotes no MUSIC do final.py.
7. Listas de cenas por lote com seq.py (references/engine.md, examples/chadwick/tools/): um módulo de filme (<story>.py, como chad.py) guarda a tabela LIVE (as camadas vivas de cada imagem) e as configurações do mapa; cada shots_bN.py tem ~60 linhas de S.at(time, scene(...)/page(...)/drawin(...)/map_shot(...)). Verifique cada um com PY tools/stills.py bN e olhe a folha antes de renderizar qualquer coisa.
8. Renderizações (com o OK do usuário): PY tools/render_all.py executa todos os lotes em paralelo, quantos de uma vez a memória livre da máquina permitir (cerca de 1.5 GB por render; mais de uma vez é mais lento quando a memória acaba); após correções, render_all.py b3 b7 ou --changed. Inicie em sua própria janela para que fechar Claude não o pare, e siga references/performance.md quando uma renderização estiver lenta ou o computador travar (Windows especialmente). Teste uma nova transição ou efeito em dois quadros primeiro (um crash tardio desperdiça a renderização).
9. Encerramento uma vez por canal (references/cta.md), depois junção final PY tools/final.py; verifique duração, fps, volume no MP4 (−14 LUFS, pico ≤ −1.5 dB) e amostras de quadro (references/final-render.md).
10. Dublagens (references/dubs.md) e miniaturas (references/thumbnails.md) se desejado.

A aparência (padrão do exemplo; cada canal escolhe a sua)

• O exemplo: pessoas com cabeça de ovo (cabeça de ovo, dois olhos ovais escuros, boca de uma linha, sem nariz/orelhas/sobrancelhas, mãos arredondadas simples) em um mundo real preciso da época; linha de tinta + guache pastel fosco; aparência do motor gouache. Outros canais escolhem seu próprio estilo de imagem, personagens (ou nenhum) e aparência do motor (references/art-styles.md); as regras abaixo valem para todos os estilos.
• A aparência do motor define as camadas adicionadas: gradiente, granulado, vinheta, tinta, papel de etiqueta, acento, fontes, som de desenho (engine/look.py: YTF_LOOK, look.json). Nunca codifique uma cor ou fonte em um arquivo de cenas quando a aparência tem uma (look.rgb("accent"), look.L.type_font); a aparência de um canal deve mudar em um só lugar.
• Sem 2.5D, sem recortes, sem vídeo de IA. Imagens únicas com movimentos de câmera suavizados (aproximações, panorâmicas, deriva lenta).
• Nunca segure uma imagem por muito tempo: corte para a próxima cena do momento (W→M→F→D→P) ou para uma página desenhada.
• Explicadores de esboço são desenhos reais, não ícones: levantados da arte linear das folhas ou desenhados pelo motor onde o código faz bem (mapas precisos, rotas, marcas, figuras simples).
• Bases em branco são desenhadas ao vivo em seu próprio meio: grafite no papel, giz em um quadro, tinta de pincel, fotos de meio-tom imprimindo em um jornal, rotas de tinta em um mapa.
• Linhas carregam significado: marcas de contagem para anos, anéis de som, caminhos de papel caindo, linhas de fumaça, figuras riscadas.
• Rótulos (datas, lugares, nomes) são texto digitado nivelado na fonte de tipo da aparência (máquina de escrever em gouache), digitados uma tecla de cada vez com um clique suave.
• Escrita em um objeto fica nas linhas reais desse objeto em seu ângulo; a impressão ilegível abaixo é limpa primeiro (fx2.clean_text).
• Contraste sempre: nada escuro sobre escuro. Rótulos escolhem automaticamente creme/tinta com um halo. Nunca force color="ink" sem verificar o que está abaixo.
• O sprite da ferramenta é pequeno (escala 0.28) para nunca roubar o foco.

Animação de assinatura (tudo em código nas imagens estáticas)

engine/signature.py, engine/fx2.py, ajudantes de cena engine/wr.py, engine/seq.py. Um quadro de cada em examples/chadwick/look/; todos em movimento no vídeo de teste de efeitos.

• Quadros vivos (a imagem nunca se move; camadas vivem nela): fumaça de partículas de cada chaminé, respiração no frio, chamas vivas e a luz que projetam, as próprias lâmpadas da imagem encontradas e respirando (fx2.lamps), neve, chuva, folhas caindo, brilhos. Sem distorção de pixel (sg.Flow) em fumaça, vapor, fogo ou água: borra a pintura (look/flow_smear_avoid.png).
• Rostos que atuam, apenas onde importa: sem piscar automático ou expressões. Um rosto atua apenas quando uma cena passa act= / talk=, e apenas um rosto com um par de olhos combinados (sg.face_audit([...], out.jpg): atue apenas onde ambos os olhos estão circulados de verde). Sinais: blinks, glances, widen, mouth_fx, expr (sorriso, grin, franzir, o, rir, olhos fechados, apertar os olhos...), talk=(ta, tb), marcas de reação (sweat, shake, !, ?, zzz). Um punhado de batidas reais por lote, nunca decoração.
• Páginas de quadrinhos no quadro em branco (sg.Comic): bordas se entintam, cada painel entinta e pinta, a câmera visita painéis e mergulha no último. Duas por filme (o gancho, o primeiro grande evento). Cada painel segura ≥ 1.8 s.
• Desenhos feitos ao vivo (fx2.Draw): um desenho em folha entinta em sua ordem de traço (sprite de caneta e som), depois sua lavagem de cor entra; card=True coloca uma lavagem creme suave primeiro em imagens cheias. Uma folha nunca é mostrada como uma página de quatro: cada desenho aparece quando o narrador o nomeia, ligado por setas e rótulos curtos digitados.
• O cartão explicador (uma base reutilizada): nomes digitados e riscados, um mecanismo como uma cadeia de desenhos com setas, três desenhos com três palavras.
• Vocabulário de marca, escolhido por significado, nunca a mesma marca toda vez: sublinhado, visto, cruz, colchete, linhas de movimento, anéis de som, rota (caminho pontilhado + seta), líder (ponto, linha, rótulo digitado), contagem; sg.Stamp (selo de borracha: FORJADO, FECHADO, 14 ANOS), sg.Tag (etiqueta de papel rasgado), sg.Inset, sg.Flip (flip flap), sg.Pin, fx2.Counter (contador de dinheiro rolante).
• Efeitos com peso (alguns momentos sentidos por lote): fx2.Lift (corte um objeto da imagem e anime-o, fill_from= preenche o buraco por clonagem), fx2.Tear (a imagem rasga ao meio), a transição ("shatter", s, (cx, cy)), sg.Papers (papéis caindo), fogo + golpe, tremor + baque, flashes de imprensa + obturador, sg.Rays, sg.Haze.
• O mapa vivo (seq.map_shot): costas reais se entintam, água entra, bordas entram pontilhadas, lagos e cidades digitam, uma viagem vermelha...