EssouliAnas/blender-3d-short

Curta 3D realista (Blender + Python)

Cada quadro é uma renderização real do Blender de uma cena que o Claude constrói em Python. Nenhum modelo de IA de imagem ou vídeo. Saída final: 1080x1920, 30 fps, H.264 limitado a 30 Mbps. Caminhos: <skill> = esta pasta. Os episódios ficam em <project>/blender-shorts/<slug>/, os assets baixados em <project>/blender-shorts/assets/, as escolhas do canal em <project>/blender-shorts/brand.json. Execute scripts com python <skill>/scripts/<name>.py.

Leia primeiro: references/style.md (as regras), references/traps.md (antes de inventar qualquer correção).

Configuração (uma vez por PC)

• Blender 5.x (encontrado automaticamente em Program Files; caso contrário, defina BLENDER=<caminho para blender.exe>).
• python -m pip install numpy opencv-python-headless pillow; ffmpeg no PATH.
• Prove que o pipeline funciona: copie examples/test-cell/ para blender-shorts/test-cell/, depois build, still, frames, finish. Em um RTX 3080 Laptop, EEVEE renderiza rapidamente seus 90 quadros em 1080x1920 em cerca de 2 minutos.

Etapa 0: perguntas iniciais (sempre, antes de qualquer trabalho)

Pergunte com a ferramenta AskUserQuestion, em duas rodadas de até quatro perguntas, depois uma terceira rodada que depende da resposta sobre a voz. Se blender-shorts/brand.json existir, primeiro faça uma pergunta: "Mesmas configurações da última vez?" (mostre-as em uma linha) com "Sim" / "Alterar algumas". Em "Sim" pule para as partes específicas do tópico da rodada 3. Opção recomendada primeiro. Salve cada resposta em brand.json (para todo o canal) e no episode.json do episódio.

Rodada 1: o que é e como fala

1. Tópico: "Sugira 3 para mim" / "Eu tenho um" (eles digitam em Outro). Sugestões: perguntas sobre o corpo ou como as coisas funcionam que são imagéticas, verificadas no YouTube quanto à originalidade do ângulo.
2. Voz:
   • Voz ElevenLabs (recomendado): uma voz padrão, gerada a partir do roteiro com tempos de palavra exatos.
   • Clonar minha voz (ElevenLabs): eles enviam 1-3 min de fala limpa uma vez; todo episódio subsequente fala com a voz deles. Apenas a voz deles, ou uma para a qual tenham consentimento por escrito.
   • Eu mesmo vou gravar: eles gravam o roteiro; Claude limpa, encontra os tempos das palavras, constrói a imagem para sincronizar.
   • Sem voz, apenas legendas: o roteiro é cronometrado a 2,8 palavras/s constantes, as legendas são inseridas na imagem, e um arquivo captions.srt permite que gravem ou adicionem uma voz posteriormente em seu editor exatamente nesse ritmo.
3. Duração: 30 s (recomendado para o primeiro) / 45 s / 60 s. A 2,8 palavras/s isso é ~80 / 120 / 165 palavras.
4. Vídeos de referência: "Não, use as regras de estilo incorporadas" (recomendado) / "Sim, vou fornecer arquivos ou links" (medido com measure.py, estudo privado apenas).

Rodada 2: o visual

1. Visual: Fundo de estúdio (recomendado: uma cor de assinatura atrás de tudo, o visual do gênero) / Planos de fundo com fotos do mundo real (estádio, rua, céu atrás do 3D) / Mix (fundo, com lugares reais para as batidas de "onde").
2. Cor do fundo (pule se não usar fundo): Pêssego #F2D7C9 (nosso até agora) / Menta #CFE8DF / Azul marinho escuro #1F2A44 / Personalizado (hex). Nunca a cor do canal de referência.
3. Personagem principal: "Tem um personagem principal?" (references/characters.md)
   • Vou fornecer um personagem rigged: arquivo .blend / .fbx / .glb deles (Mixamo, Character Creator, uma loja).
   • Crie um para mim (recomendado se não tiverem nenhum): construído no Blender com MPFB, sem contas, nosso logotipo na camisa.
   • Baixar um gratuito com rig (recomendado se não tiverem nenhum): Claude propõe 2-3 candidatos (fonte, licença, visual); em sites que precisam de conta (Mixamo, Renderpeople, Sketchfab) o usuário baixa e fornece o caminho.
   • Nenhum personagem: apenas objetos, partes do corpo e lugares. Uma vez que um personagem principal exista (assets/host/host.blend), esta pergunta se torna "Usar novamente?".
4. Motor de renderização:
   • Auto (recomendado): EEVEE rápido em todos os lugares, Cycles rápido apenas para tomadas que falham no julgamento em close-ups de pele, nuvens, vidro ou cabelo.
   • Apenas EEVEE rápido: o mais rápido, ~1 s por quadro.
   • Apenas Cycles rápido: cerca de 2x mais lento, luz mais suave e natural.
   • Alta qualidade: predefinições high, cerca de 2-3x mais lento que rápido.

Rodada 3: depende da resposta sobre a voz

• ElevenLabs ou clone: a chave. Verifique se há ELEVENLABS_API_KEY= em um .env no projeto ou acima (nunca imprima). Se estiver lá, diga "Encontrei sua chave ElevenLabs" e não pergunte. Se não estiver, pergunte: "Adicione sua chave: cole aqui e salvarei em .env, ou adicione a linha ELEVENLABS_API_KEY=... ao .env você mesmo (mantém fora do chat)". Salve uma chave colada em <project>/.env apenas, nunca a ecoe, nunca a coloque em nenhum outro arquivo, commit ou log.
• ElevenLabs: Voz: Narrador calmo (id padrão em sound.py) / "Escolher da minha biblioteca ElevenLabs" (listar com GET /v1/voices, mostrar apenas nomes) / ID da Voz (eles digitam). Modelo de voz: eleven_multilingual_v2 (recomendado: estável, melhores tempos de palavra) / eleven_v3 (mais expressivo, menos previsível).
• Clone: peça os arquivos de amostra (caminhos), depois sound.py <ep> clone <files> --name "<nome da pessoa> voice"; o id da voz é salvo e reutilizado por todos os episódios posteriores.
• Gravação própria: diga para esperarem até o roteiro ser aprovado, depois gravarem em uma única tomada, telefone à distância do braço, sala silenciosa, e fornecerem o caminho do arquivo. (Gravar sobre o roteiro aprovado é o que mantém imagem e voz sincronizadas.)
• Personagem principal, conforme a resposta da rodada 2:
  • Fornecer: peça o caminho do arquivo (e a pasta de texturas se separada).
  • Criar um: peça faixa etária, biotipo, e estilo de cabelo e roupa (palavras simples); depois peça para instalar o MPFB.
  • Baixar: mostre os 2-3 candidatos como opções (nome, visual, licença, conta necessária) e deixe-os escolher.
• Toda opção de voz: Legendas inseridas na imagem? Sim / Não (sem voz sempre ganha legendas).
• Toda opção: Música: Nenhuma, apenas efeitos e tom de ambiente (recomendado para o primeiro) / Minha própria faixa (caminho do arquivo, eles confirmam que têm os direitos) / Faixa da Biblioteca de Áudio do YouTube (eles baixam e fornecem o caminho).

Não pergunte sobre mais nada; tudo abaixo tem um padrão. Perguntas sobre "modelo específico": não há modelo de IA de imagem ou vídeo neste pipeline. As escolhas que agem como tal são o motor de renderização (rodada 2), o modelo de voz ElevenLabs (rodada 3) e o modelo Claude que executa a skill: Opus com esforço alto funciona melhor.

Predefinições do motor (as configurações escolhidas pelo usuário, mantenha-as)

• EEVEE rápido (padrão, b3d.EEVEE_PRESETS['fast']): 16 amostras, ray tracing e GI meia resolução, 1 raio de sombra. ~0,9-1,2 s por quadro em 1080p na 3080, 99-99,9% semelhante a high.
• Cycles rápido (b3d.CYCLES_PRESETS['fast']): 32 amostras, limite de tempo de 1 s, denoiser OptiX, 2-3 reflexões, aproximação Fast GI, Dados Persistentes. ~1,7 s por quadro. Se o borrão do denoiser aparecer em um close-up, dê a essa tomada um limite de 2 s.
• --quality draft | fast | high no momento da renderização, sem reconstrução. Motor por cena: setup_render(engine=...), ou B3D_ENGINE=CYCLES python render.py <ep> build para testar A/B sem editar. Motores mistos em um único curta são aceitáveis (renderizar o intervalo de quadros de cada tomada a partir de seu próprio .blend) se o fundo e a gradação corresponderem.

Pipeline (salve após cada etapa; mostre ao usuário stills, não paredes de texto)

1. Tópico e fatos. Descubra cada número e escreva-o com sua fonte em episode.json science. Números famosos duvidosos recebem "Os cientistas estimam". O mesmo tópico de um grande canal é aceitável, as palavras deles não.
2. Meça a referência (apenas se a rodada 1 disse sim): measure.py <pasta> --out <ep>/reference.json. Caso contrário, os padrões em style.md.
3. Roteiro em episode.json (examples/episode.template.json): segunda pessoa, ~2,8 palavras/s, duração escolhida, formato de batida em style.md. Mostre e aguarde um OK. Após o OK, "apenas faça" até os stills.
4. Voz e tempo, conforme a resposta da rodada 1:
   • ElevenLabs / clone: sound.py <ep> voice -> audio/voice.wav, words.json, captions.srt.
   • Gravação própria: aguarde o arquivo, depois sound.py <ep> own <arquivo> (tempos de palavra: faster-whisper se instalado, senão ElevenLabs speech-to-text se houver chave, senão estimado a partir de silêncios; ofereça pip install faster-whisper se a estimativa estiver errada).
   • Sem voz: sound.py <ep> captions -> words.json + captions.srt em "wps" (2,8). Em seguida, escreva shots.md: por batida, o intervalo de quadros (a partir dos tempos das palavras), o movimento da câmera (dolly para dentro / segurar+rastejar / puxar para fora / voo) e o que continua se movendo durante cada pausa. Máximo de um corte brusco a cada ~7 transições.
5. O teste de 9 segundos primeiro. Uma batida em todo o pipeline antes do curta completo: scene.py com helpers b3d. Renderize, finalize, measure.py, e compare.py reference.json ours.json se houver uma referência. O delta é a lista de tarefas. Corrija a câmera até que o solavanco e o deslize lateral correspondam (um eixo, chaves easing).
6. Mundo e personagem. Personagem primeiro, pelo caminho em references/characters.md, sempre através de b3d.import_character(path, height=1.75): ele o escala para a altura real com os pés no chão, remove câmeras e luzes perdidas, vincula partes com peso ao rig e imprime um relatório (tipo de rig, partes não seguindo o rig, formas faciais x/52, texturas faltando). Corrija cada item do relatório, depois um still de giro, depois salve assets/host/host.blend. Mundo a partir de references/assets.md (lista de downloads, fonte + licença + tamanho, pergunte uma vez). Regra: se um real existir, baixe-o, nunca o modele.
7. Stills e o juiz. render.py <ep> still <frames...> --pct 50 para cada batida. Em seguida, crie um agente separado (ferramenta Agent) com os stills e references/realism.md; ele pontua de 0 a 10 e nomeia os três piores indícios de falsidade. Corrija, re-renderize, re-julgue. Renderize apenas com 8,5+. Mostre ao usuário os stills e a pontuação. No motor "Auto", uma tomada que falha em um atalho do EEVEE muda para Cycles rápido aqui.
8. Renderize. Execute render.py <ep> frames no painel Terminal do usuário (run_in_terminal) para que eles vejam a barra ao vivo (quadros concluídos, s por quadro, ETA); leia <ep>/progress.json para responder "quanto falta?". Retomável. Depois render.py <ep> times; se muito lento, trabalhe descendo references/render-speed.md nos quadros mais lentos.
9. Som. beds (um tom de ambiente por mundo) e sfx (cada um em sua palavra: "batida de osso" em "ossos") em episode.json, depois sound.py <ep> sfx (precisa de chave; sem uma, pule efeitos ou use arquivos que o usuário fornecer em audio/sfx/<nome>.mp3) e sound.py <ep> mix. Regra de mixagem: música +3 dB, efeitos na metade, voz inalterada.
10. Finalize. finish.py <ep> --audio <ep>/audio/mix.wav [--captions] -> out/<slug>-final.mp4. Assista em tamanho de celular. Episódios sem voz: também entregue captions.srt e diga que a voz entra nesses momentos.
11. Relatório: o caminho final, a última pontuação do juiz, minutos de renderização, créditos ElevenLabs (costs.json), e o texto de créditos para a descrição (licenças assets.md). Nunca afirme que o canal de referência usa qualquer ferramenta.

Scripts

Script	Executa em	Faz
b3d.py	Blender	configuração de renderização + predefinições (EEVEE/Cycles, GPU, visual), fundo + HDRI, pegador de sombra (real no Cycles, simulado no EEVEE), luzes, câmera dolly com easing em um eixo, materiais, import_character (qualquer .blend/.fbx/.glb com rig, escalado, vinculado, relatado), parent_to_bone, shape keys, compositor, cronômetro
render.py	shell	build, still, frames (barra de progresso ao vivo, progress.json, retomável), times; --quality
sound.py	shell	voice (ElevenLabs), clone, own (gravação do usuário), captions (sem voz), sfx, mix; todo modo de voz escreve captions.srt
finish.py	shell	quadros + mix -> mp4 1080x1920, camada de câmera real, inserção de --captions
measure.py / compare.py	shell	métricas quadro a quadro de qualquer vídeo; referência vs nosso com uma lista de TAREFAS

scene.py é chamado como blender -b --factory-startup --python scene.py -- <skill>/scripts <ep>/scene.blend; comece a partir de examples/test-cell/scene.py (chame shadow_catcher após as luzes).