/3d-video-studio
┌──────────────────────┐
│ "Por que os Motoristas│ título pergunta sobre um comportamento, nunca nomeia a invenção
│ Começaram a Filmar│
│ a Estrada" │
│ ◕‿◕ ▶ 💥 │ gancho: o malfeito do esquecido, pagamento até 4 s
│ brecha → ganância │ escalada, resistência inexpressiva, duas viradas "Mas"
│ cara quieto aponta ▣ │ revelação pela própria visão da invenção
│ "e foi assim que a ___│ resposta final responde ao título, último shot volta ao primeiro
│ foi inventada." │
└──────────────────────┘
Siga os passos em ordem. ⏸ marca um portão: pare, mostre o resultado e aguarde a resposta do usuário. Em cada portão, diga qual é o próximo passo. Leia apenas os arquivos que o passo atual lista.
SKILL_DIR="<diretório base desta skill>"; ENGINE="$SKILL_DIR/engine"
KIT="$SKILL_DIR/kit"; [ -d "$KIT/node_modules/playwright" ] || KIT="$HOME/.claude/kit"
PY="$KIT/.venv/Scripts/python.exe"; [ -x "$PY" ] || PY="$KIT/.venv/bin/python"
[ -d "$ENGINE/node_modules/three" ] && [ -x "$PY" ] || bash "$SKILL_DIR/setup.sh"
Requer Node 18+, ffmpeg e Python 3.9+. bash "$SKILL_DIR/setup.sh" instala o resto uma vez (three.js, Playwright + Chromium, um venv Python com o modelo de temporização de palavras Parakeet). Execute cada ferramenta Python abaixo com "$PY".
O perfil de referência é a medida para cada portão.
PROFILE="$SKILL_DIR/story/examples/dashcam"contém os números medidos (profile.json), um quadro por configuração (frames/) e cada quadro de cada transição (transitions/).- Se o usuário trouxer uma nova referência, construa seu perfil primeiro ("Aprendendo com uma nova referência" abaixo) e aponte
PROFILEpara ela. - Quadros não são distribuídos no repositório público.
story/examples/dashcam/estory/examples/cashier/contêm os números medidos (profile.json) e as folhas de batidas escritas, mas não os quadros da referência (eles pertencem ao canal original). Se$PROFILE/framesestiver faltando, peça ao usuário o vídeo de referência (qualquer Short neste formato funciona) e execute o passo 2 de "Aprendendo com uma nova referência" com$PROFILEcomo pasta de saída, antes do passo 4. Se o usuário não tiver um vídeo de referência, julgue apenas com base emprofile.jsone nos exemplos escritos, e diga isso em cada portão. - Nunca julgue nossos quadros sozinhos: cada folha de revisão coloca a referência ao lado da nossa.
Passo 1 · Tópico ⏸
Leia story/topic-bank.md. Use o tópico do usuário ou ofereça três. Execute o teste de quatro perguntas e nomeie a verificação mais fraca.
Portão: o usuário escolhe um tópico.
Passo 2 · Título e roteiro ⏸
Leia story/title-formula.md, story/formula.md, story/hook-rules.md, story/script-template.md, story/script-check.md.
Leia também story/rig-check.md (o que nossos personagens chatos podem e não podem fazer) e execute "$PY" "$SKILL_DIR/tools/rig_check.py" <projeto>/script.json antes de pontuar; mostre qualquer bandeira com sua nota "Encene como". Uma linha que o rig não pode mostrar deve ser corrigida antes da gravação da voz.
Escreva o título primeiro, depois o roteiro batida por batida. Pontue-o (reescreva abaixo de 9/10).
Mostre o título, o roteiro (uma frase por linha, rótulos de batida ao lado), a contagem de palavras, a duração estimada a 3,8 palavras por segundo e a pontuação.
Portão: o usuário aprova ou edita. Salve as frases aprovadas como <projeto>/script.json
(crie o projeto com cp -r "$ENGINE/template" <projeto> primeiro; <projeto> não deve existir).
Passo 3 · Bíblia visual ⏸
Leia look/style-guide.md (o visual padrão: superfícies laqueadas brilhantes, tinta em tudo em foco, luz natural, fundos levemente desfocados, adereços densos) e look/visual-bible.md (regras e modelo).
Gere os visuais primeiro: node "$ENGINE/cast.mjs" new <projeto> --chars <papéis> --cars <papéis>. Depois escreva
<projeto>/visual_bible.md cobrindo:
- cada personagem (construção, cabeça e cabelo, camadas de roupa em hex, acessórios, as faces que a história precisa);
- cada ambiente (layout, superfícies, fontes de luz visíveis, 4 a 8 itens de adereços por parede, piadas de texto exatas, profundidade);
- os interiores (carros, cabines, telas), os adereços (a invenção herói por completo) e os gráficos 2D;
- um plano de ativos marcando cada item como
biblioteca + params,biblioteca + novo textoounovo.
Mostre a bíblia com a saída do elenco. Portão: o usuário aprova, edita ou pede uma nova geração.
Passo 4 · Folha de estilo visual ⏸
Mostre o design visual construído em 3D antes de qualquer storyboard, com detalhes finais. Leia look/setup-types.md.
lookdev.html,lookdev.jsesets.jsvieram com o template. Escreva o cenário mais movimentado da história emsets.js(heroSet()é o exemplo trabalhado do visual padrão: substitua-o, mantenha suas camadas), seguindo a bíblia exatamente. O vídeo importa o mesmosets.jsdepois, então este trabalho não é descartado.lookdev.jsjá faz os cards:- cada personagem de
cast.json, em filas de três com rótulos; - as faces do protagonista;
- o cenário herói: aberto, médio com desfoque de lente 10 e um close-up de adereço com desfoque 14;
- o carro herói.
Adicione um card para o adereço herói e para qualquer outro cenário que a bíblia marcar como
novo.
- cada personagem de
- Um card para cada tipo de configuração que a história usa (
interior,pov,tracking,house,twoshot,talker,device), cada um construído em seu cenário real com seu enquadramento real, com todos os "Deve ter" delook/setup-types.md. O POV do painel, a parede do talker e a visualização do dispositivo são os que costumam ser pulados; construa-os agora. - Emparelhe-os com a referência:
"$PY" "$SKILL_DIR/tools/sbs_sheet.py" <projeto>/review/look_pairs.jpg --ours <cards> --ref <os mesmos tipos de $PROFILE/frames>. - Adicione uma faixa de recortes de 400 px em 1:1 (medidores, piadas de parede, carroceria, estrada), para que detalhes e desfoque apareçam.
node "$ENGINE/film.mjs" check <projeto> 0 <cards> 0.5 --page lookdev.html, corrija cada FALHA (incluindoclipped-art: cabelo, chapéu ou arte da cabeça de um personagem cortada na borda), depoisnode "$ENGINE/film.mjs" sheet <projeto> <projeto>/review/look.jpg 0.5 1.5 2.5 ... --page lookdev.html --w 360 --cols 4.- Pontue em código:
node "$ENGINE/film.mjs" lookcheck <projeto> <projeto>/review/lookcheck 0.5 1.5 ... --page lookdev.html(brilho, contornos, luz, profundidade, densidade, cor, faces; 0 a 10 contralook/targets.json). Corrija cadaBAIXO, depois olhe para a folha uma vez a olho, para o que os números não podem julgar (adereços da história, apelo). Mostre as pontuações com a folha. Executelookcheckem cada quadro dos atos no passo 8 também. Entreguereview/look.jpgereview/look_pairs.jpg. Portão: o usuário aprova o visual dos personagens, o mundo e cada tipo de configuração, ou lista correções. Cada cenário no vídeo é construído neste nível de detalhe.
Passo 5 · Storyboard + roteiro de voz ⏸
Dois documentos de uma vez:
- Storyboard
<projeto>/storyboard.md: uma linha por configuração de câmera (18 a 21):# | frase(s) | batida | tipo de configuração | movimento de câmera | ação e faces | piada de adereço | transição em (quadros) | ato/humor. Regras destory/formula.md("Imagem e edição");story/examples/dashcam.mdmostra um completo.- Tipo de configuração é um dos nomes em
look/setup-types.md; torna-se otypedo shot no código. - Ação e faces nomeia uma pose do motor (
stand,walk,sitOn,point,lean,armTo…) ou um adereço para cada ação; qualquer outra coisa falha emstory/rig-check.mde é reescrita antes da construção. - Movimento de câmera: cada linha nomeia seu movimento e velocidade (por exemplo "push-in 6%/s", "pull-back para aberto", "orbit 120°"); apenas a visualização do dispositivo pode dizer "travado".
- Transição em: dissolvências são 7 a 10 quadros (até 16 para a revelação), ou nomeie a transição no mundo. Cenários, personagens e adereços vêm da bíblia visual aprovada: nomeie-os como a bíblia faz. Abaixo da tabela, copie o plano de ativos da bíblia com qualquer coisa que o storyboard adicionou.
- Tabela de continuidade (abaixo do storyboard): cada adereço ou personagem que muda de lugar ou estado ganha uma linha,
coisa: estado → estado → estado, com o número da configuração de cada mudança (por exemplochave: bolso (1) → chão (3) → boca do cachorro (5)).- Cada mudança acontece na tela em uma configuração nomeada, ou é mostrada por uma ação na tela que o espectador pode ler (ela é jogada, ela cai, ela é entregue).
- Nenhuma configuração pode começar a partir de um estado que o espectador nunca viu acontecer. Uma ação posterior que depende de uma mudança não vista (procurar algo que ninguém viu cair) é uma falha de storyboard: adicione a ação a uma configuração, ou adicione uma configuração. Através de um salto de tempo narrado, etapas comuns fora da tela são permitidas (pegar um bilhete de seu esconderijo).
- Rotule cada adereço como objeto da história (viaja com o enredo) ou adereço de piada (um esconderijo, recipiente ou objeto de piada que fica em sua própria batida). Um adereço de piada em um novo local falha a menos que a narração o nomeie lá.
- Abaixo da tabela, uma linha de transporte por local: quem está lá, o que cada um carrega e por quê.
- Verificação da vida real (
story/rig-check.md, última seção): cada ação e item carregado tem uma razão que uma pessoa real teria naquele momento. Se a única razão é continuidade, reescreva a linha.
- Tipo de configuração é um dos nomes em
- Roteiro de voz
<projeto>/voice/cartesia.md: leiastory/voice-cartesia.mde escreva os blocos marcados (emoção por bloco, conselho de velocidade, pausas apenas antes das viradas "Mas" e da resposta final).
Mostre ambos. Portão: o usuário aprova o storyboard. Em seguida, peça a voz: "Gere os blocos em
voice/cartesia.md no Cartesia e coloque os arquivos em <projeto>/audio/ (vo_01.wav, vo_02.wav... ou um vo.wav).
Enquanto isso, construirei a pré-visualização de 5 segundos." Não espere o áudio para continuar ao passo 6.
Passo 6 · Pré-visualização de 5 segundos ⏸
Construa apenas o gancho (os primeiros 5 s, geralmente configurações 1 a 3) para que o usuário possa julgar o visual antes da construção longa.
Leia engine/API.md; copie blocos de engine/template/video.js (nunca abra engine/src). Construa cada personagem
e carro de cast.json (makeChar(CAST.characters.x), buildCar(CAST.cars.x)), e use poses stand / sit.
- Temporização:
sentenceStarts/captionsFromWordscom a estimativa (estimateWords), ou o arquivo de palavras real se o áudio já chegou (passo 7). - Importe os cenários de
./sets.jse usemakeStage({ mood: withLook(mood, 'indoor' | 'outdoor') }). - O visual a julgar contra é a folha de estilo aprovada: 3D limpo com superfícies brilhantes, tinta em tudo em foco,
luz natural, um fundo levemente desfocado e cada quadro preenchido borda a borda. Se um rosto está em branco ou mostra a
parte de trás da cabeça, a câmera foi colocada após a pose (veja
engine/API.md, chars.js). - Dê a cada rosto uma
marke a cada shot seutype. Executenode "$ENGINE/film.mjs" check <projeto> 0 5 0.25; ele sai com código 1 em qualquer FALHA, então corrija todas. - Uma folha:
node "$ENGINE/film.mjs" sheet <projeto> <projeto>/review/preview.jpg 0.2 0.8 1.6 2.6 3.6 4.6 --w 180 --cols 6. Olhe para ela uma vez; corrija o que está claramente errado. - Renderize:
node "$ENGINE/film.mjs" render <projeto> <projeto>/review/preview.mp4 0 5(cerca de 1 minuto). Se a voz chegou, adicione os primeiros 5 s dela:ffmpeg -i review/preview.mp4 -i audio/vo.wav -map 0:v -map 1:a -c:v copy -t 5 review/preview_vo.mp4. - Compare o gancho com o gancho da referência:
"$PY" "$SKILL_DIR/tools/compare_video.py" <projeto>/review/preview.mp4 "$PROFILE" <projeto>/review/cmp_preview --range 0 5;- coloque nossa faixa de saída ao lado de
$PROFILE/transitions/(a saída passa pelo vidro em cerca de 4 quadros e pousa em um shot aberto). Corrija FALHAS em movimento, nitidez e detalhe antes de mostrar a pré-visualização. Entregue o caminho do mp4 e a folha de pares. Portão: o usuário aprova o visual (personagens, cores, câmera, legendas) ou pede alterações. Alterações em personagens ou estilo são baratas aqui e caras depois.
Passo 7 · Voz recebida
Quando o usuário disser que o áudio está em <projeto>/audio/: siga "Quando o áudio chega" em story/voice-cartesia.md
(junte blocos, words.py, verifique a duração e o ritmo).
- O ritmo é um portão rígido: fora de 3,5 a 4,1 palavras por segundo (
film.mjs checkfalha), peça uma nova gravação em outra velocidade e não construa sobre a lenta. O último vídeo foi adiante a 3,4 e rodou 71 s contra os 62 da referência. - Caso contrário, continue: a edição é construída em números de frase, então ela se reajusta. Se a voz não chegou até o final do passo 8, pergunte novamente; não renderize o final sem ela.
Passo 8 · Construa o resto, ato por ato
Para cada ato (1 dia, 2 crepúsculo/noite, 3 chuva), em ordem:
- Novos cenários e adereços primeiro, em
sets.js, construídos com o detalhe da folha de estilo aprovada e da bíblia (veja "Não construído ainda" emengine/API.md). - Blocos de shot para cada configuração no ato, cada um com seu
type, transições como o storyboard diz (dissolvede 7 a 10 quadros,burstcomcashBurst()/paperBurst(), um wipe, ou um corte seco). film.mjs checkpara o intervalo de tempo do ato deve sair com código 0 (sem FALHA). As FALHAS que mais importam:- uma câmera mais lenta que o limite
slow-camera(um push-in deve aplicar zoom de 6 a 10% por segundo); - um rosto herói fora do intervalo de tamanho de seu tipo;
- uma dissolvência fora de 5 a 12 quadros;
- um rótulo pendurado fora do objeto ao qual está preso (
decal-overhang): registre adesivos e rótulos comon: <superfície>; - texto chave cortado pela borda do quadro, coberto por uma cabeça ou escondido (
text-cut). Registre cada número, preço, tela e rótulo do qual a piada depende comreadable(mesh, label, { key: true })quando o cenário ou shot é construído.
- uma câmera mais lenta que o limite
- Folha de pares do ato: nossos meios de configuração na linha inferior, as configurações de referência das mesmas batidas no topo
(
tools/sbs_sheet.py, quadros de$PROFILE/frames). Adicione uma faixa de recortes de 400 px em 1:1 do ato. - Revisão de transição: renderize cada transição no ato como um clipe curto (
film.mjs renderem cerca de 1 s ao redor dela). Faça uma faixa quadro a quadro e coloque-a ao lado da transição de referência do mesmo tipo em$PROFILE/transitions/. Verifique se:- os cortes mudam em um quadro limpo;
- as dissolvências seguem uma curva suavizada enquanto ambos os shots continuam se movendo;
- um burst nunca cobre mais de cerca de dois terços do quadro, e o próximo shot surge sob ele;
- um wipe revela...