Legendas Incorporadas
Um catálogo, escolhido antecipadamente (CATALOG.md — 17 identidades; os três mecanismos por trás são detalhes de backend). Padrão (default) constrói uma barra literal limpa (subtítulo no terço inferior carregando a maior parte do texto) + um clímax incorporado composto dentro da cena atrás do sujeito no pico. Cinematográfico é puramente incorporado — sem barra, cada legenda composta atrás do sujeito (tipografia heróica, acumulação, oclusão como efeito). Tema é uma constituição temática completa — paradigma corporal × peça central heroica × efeitos frontais × reação da placa, composta a partir de registros (temas/README.md): ordnance terminal neonsign stardust stomp. A maioria dos vídeos explicativos / narração é Padrão; incorporação é o pico escasso e merecido — incorporar cada palavra é o erro comum; Tema é para pedidos de nível VFX ("炸", "特效", "como se fosse feito no AE").
Fluxo operacional (resumão)
A prosa técnica abaixo é longa; o pipeline em si é curto — e tudo que é determinístico é computado ou compilado, nunca escrito à mão:
- Portão de decisão (recusar clipes ruins) → escolha UMA identidade do CATALOG.md (17 identidades; mecanismo/compilador derivado por consulta — nunca apresente uma pergunta de modo/categoria)
hyperframes init(pule se o diretório do projeto já existir com o vídeo dentro —matte.cjs/transcribe.cjsadotam qualquer vídeo no diretório como source.mp4) →bash scripts/prepare.sh <projeto>(matte ∥ transcrever ∥ envelope de áudio em paralelo, depois zonas seguras v2 com paleta de cena/óptica/iluminação — um comando, nada esquecido)- crie um pequeno JSON de escolhas criativas (leia
safe-zones.jsonprimeiro): Cinematográfico →plan.json→fill-timings.cjs→fit-fonts.cjs→make-composition.cjs; Tema →theme.json→make-theme.cjs(paradigmas barra/painel/poema/tomada;anchoré o padrão de barra tranquila) - QA Visual:
node scripts/preview-frames.cjs <projeto>→ prévias de composição fiéis em ~2s/frame (sem renderizar). Verifique § QA Visual antes de pagar por uma renderização. render-and-composite.sh→ portões (timing / oclusão+herói / estouro / entrega) →final.mp4
Regras importantes que as pessoas perdem:
- barra (padrão) + incorporação (promoção).
drop(preenchimento, não mostrado) /barra(subtítulo literal no terço inferior, na frente, carrega a maior parte do texto) /incorporação(uma palavra de pico composta atrás do sujeito). O modo Padrão faz ambos, incorporando apenas o(s) pico(s). Veja § Modelo de legenda. - O vídeo é entregue INTOCADO (Padrão/Cinematográfico; o orçamento de PLACA do modo Tema é a única exceção sancionada — batidas de reação registradas (escurecimento de carga, soco, tremor, granulação) definidas por DNA do tema e aplicadas APÓS a composição do matte para que sujeito+texto+placa se movam como um quadro) — legendas são a única coisa adicionada; o matte apenas permite que o sujeito oculte a trilha incorporada. Nunca gradiente/recor/linhas de varredura da filmagem.
- Dois manuais de regras: barra → referencias/barra.md (fino), arte de incorporar → referencias/arte-de-composicao.md (rico, apenas incorporação). Consulte conforme necessário.
Modelo de legenda — barra + incorporação
Cada frase falada é uma de três coisas:
| O quê | Como é mostrada | |
|---|---|---|
| drop | preenchimento — hum/ah, gaguejos, autocorreções | não mostrada |
| barra | o padrão — conteúdo falado comum (literal) | subtítulo limpo no terço inferior, na frente, legível. Uma palavra de impacto pode ganhar um destaque ênfase inline (cor de destaque / pop de palavra ativa) — ela permanece na barra. |
| incorporação | um pico promovido — a batida principal | uma grande palavra composta atrás do sujeito (oclusão com matte), entrada e saída projetadas |
A barra carrega a maior parte do texto; a incorporação é o pico escasso e merecido. Escassez é por batida/bloco, não por clipe: ≤1 herói por bloco (pensamento), nunca dois co-visíveis, ≥ uma batida de ar entre janelas de heróis (o compilador avisa abaixo de 0,6s). Um clipe curto → geralmente 1–2; um explicador longo → ~um por seção. Entre vários heróis, o maior criado é o ÁPICE (só ele recebe o bloco de composição completo + elevação de ajuste de largura); os menores são picos MENORES que viajam em sua coluna como linhas de ênfase superdimensionadas (fg, movimento amortecido) — nem toda batida precisa da vitrine com matte, que é exatamente o que mantém o ápice como um evento. Incorporar cada palavra ainda é o erro comum.
Identidades de superfície de barra constroem exatamente isso (barra = barra.html, incorporação = o clímax em index.html). Identidades de fluxo em coluna descartam a barra e fazem tudo no estilo incorporação — recomende-as apenas para pedidos de clima sobre literalidade, nunca para vídeos explicativos / narração onde as palavras precisam ser lidas (CATALOG.md codifica isso por identidade).
Passo 0 — escolha UMA identidade do CATÁLOGO
Um front-end, três mecanismos por trás. O usuário escolhe uma IDENTIDADE do CATALOG.md (17 entradas: 12 clássicas + 5 temáticas); o mecanismo, compilador e arquivo de criação são derivados por consulta da linha do catálogo. Nunca apresente "Padrão vs Cinematográfico vs Tema" como pergunta — esses são nomes de backend (um produto tem uma UX mesmo com vários mecanismos). O catálogo codifica tudo que o roteamento precisa: superfície de leitura, voz, recomendar-para, necessidades de cena, notas de adjacência para os pares realmente próximos (loud↔ordnance, neon↔neonsign, cream↔stardust).
Procedimento: sonda o clipe → faça uma shortlist de 2–3 identidades do catálogo → recomende UMA com um porquê de uma linha → o usuário escolhe → crie o arquivo dessa identidade. Identidades são bloqueadas por mecanismo (sem combos cruzados; abrir uma é um evento de validação — veja dna/README.md).
Sempre apresente sua recomendação e deixe o usuário escolher antes de criar. Não assuma o padrão silenciosamente.
(A tabela de identidades completa está em CATALOG.md — fonte única de verdade para roteamento. A documentação do mecanismo abaixo descreve o contrato de criação de cada backend.)
Heurística de recomendação: use as "Heurísticas de shortlist" em CATALOG.md — elas são no nível da identidade (p.ex. "炸" faz shortlist de ordnance/stomp/terminal/loud e escolhe pelo QUE deve explodir), nunca no nível da categoria. Em dúvida → anchor.
- Cinematográfico → escreva
plan.jsonpara um template bloqueado, compilado pormake-composition.cjs. - Tema → leia temas/README.md, crie
theme.json, executescripts/render-theme.sh(compila + renderiza + reação da placa → final_fx.mp4).
Portão de decisão — EXECUTE PRIMEIRO
Sonde o vídeo e classifique a cena antes de qualquer modo.
ffprobe <video.mp4> # especificações
ffmpeg -ss <t> -i <video.mp4> -vframes 1 amostra.png # em 20/50/80%
Leia as amostras. Recuse se:
- Múltiplos falantes / cortes bruscos (divida e renderize cada tomada, ou recuse)
- Nenhum sujeito humano (esta skill é para vídeos de pessoa falando)
- Menos de 3 segundos, sem fala, ou rosto nunca claramente visível —
transcribe.cjsavisa quando o áudio está quase silencioso (Whisper alucina palavras como "Obrigado." sobre silêncio); obedeça e recuse em vez de legendar palavras fabricadas - A fonte já tem legendas queimadas / subtítulos / gráficos de texto pesados — adicionar um segundo sistema de legendas conflita e a filmagem é enviada intocada (sem cobrir/reparar). Texto queimado geralmente aparece apenas no meio do clipe: amostre uma folha de contato de 1fps (
ffmpeg -i in.mp4 -vf "fps=1,scale=160:-1,tile=10x5" sheet.png), não confie em 3 quadros pontuais. - A transcrição é lixo — fala não-nativa/com sotaque pesado pode ser transcrita como rabiscos confiantes. Faça uma leitura de sanidade de
transcript.jsonantes de criar; se não fizer sentido como linguagem, tenteWHISPER_MODEL=mediumuma vez, senão recuse (uma barra literal de palavras fabricadas é pior do que nenhuma legenda). - Cenas agitadas com movimento rápido (cintilação do matte)
Sondagens de pré-voo (não custam nada, previnem os piores fracassos)
- Sondagem de corte de cena. Amostre quadros em 20%, 50%, 80%. Se um sujeito/cena diferente aparecer, apare o clipe antes do corte.
- Sondagem de letterbox / pillarbox. Barras pretas no primeiro quadro? Calcule o retângulo de conteúdo seguro e restrinja o posicionamento da legenda dentro dele.
- Sondagem de luminância. Amostre a luminância média da região da legenda —
abaixo de 60→ texto claro lê-se como está,60-180→ adicione o escudo de glifo,180+→ texto opaco + escudo (nunca texto claro puro). Templates cinematográficos são cream+screene TRAVADOS — use esta sonda para escolher uma identidade adequada (cenas claras →ink, ou o temaanchorde barra opaca), nunca para recolorir uma. - Recomendação de identidade por tom (você recomenda; o usuário escolhe — veja Passo 0 + CATALOG.md). explicador / entrevista / palavras devem ser lidas → identidades de superfície de barra/painel; poético / social / "cinematográfico" → identidades de fluxo em coluna por registro; "炸 / 特效 / VFX" / mundos nomeados → identidades temáticas. Em dúvida →
anchor(palavras lidas, cena segura) — mas apresente uma shortlist e deixe o usuário escolher.
Pipeline — 5 passos
1. hyperframes init <projeto> --non-interactive --video <video.mp4>
2. bash scripts/prepare.sh <projeto> # matte ∥ transcrever (paralelo) → zonas seguras. Um comando.
# → frames_fg/ transcript.json zonas-seguras.json
3. [PASSO DO AGENTE — o único passo criativo] crie um pequeno JSON; veja abaixo por modo
Cinematográfico: crie plan.json → node scripts/fill-timings.cjs → fit-fonts.cjs → make-composition.cjs
Tema: crie theme.json → bash scripts/render-theme.sh <projeto> (compila + renderiza + fx de placa)
4. node scripts/preview-frames.cjs <projeto> # ~2s/frame prévias de composição → § QA Visual (ANTES da renderização)
5. bash scripts/render-and-composite.sh <projeto> # portões → final.mp4 + history/ snapshot
(Modo Tema: PULE os passos 3b/5 — render-theme.sh já executa compilação + render-and-composite
+ _postfx.sh; a entrega é final_fx.mp4, final.mp4 é pré-reação de placa)
O init do passo 1 verifica as skills instaladas contra as últimas no GitHub e atualiza o conjunto global se alguma estiver desatualizada.
O passo 3 difere por modo:
Passo 3 — Modo Cinematográfico (apenas incorporação)
- Leia
zonas-seguras.jsonprimeiro. Planos de narração vão emzonas.hugLeft/hugRight— tiras limpas ENCOSTANDO na silhueta (texto longe do corpo parece flutuante, não incorporado; cantos distantes são o fallback, não o padrão). O herói assume como padrãoheroAnchor/heroBands.melhor(centralizado NO sujeito, ~30–55% ocluído).recommendation:"fg"move a NARRAÇÃO para a frente para legibilidade; o herói permanece incorporado sempre queheroBands.viavel— herói-fg é o último recurso. - O DNA é a identidade que você escolheu no Passo 0 (CATALOG.md) — não reabra a escolha aqui. Faça uma verificação de sanidade contra a cena (luma de banda heróica brilhante > 150 quer
ink; orientação completa de escolha está no catálogo, cobrindo todas as dez, incluindo neon / glitch / chrome / velocity). Declare sua escolha + porquê; o usuário decide. O DNA bloqueia tipo/paleta/mistura/movimento + três atos do herói; zonas seguras v2 (paleta/óptica/iluminação) parametriza-o para ESTA cena automaticamente. - Crie
<projeto>/cinematic.json—"dna": "<nome>"+ BLOCOS de pensamento, não grupos brutos: cada bloco = linhas de palavras (agrupadas 2–5 em limites de cláusula) + o plano em que empilha +csspor linha (apenas tamanho/peso/estilo — sem posições) + no máximo UMA linha marcada"hero": true(a palavra promovida;"text"para forma de exibição). Esquema: cabeçalho descripts/make-cinematic.cjs. - Compile:
node scripts/make-cinematic.cjs <projeto>— reduz blocos → plan.json → index.html. Gerado para você: tempos sequenciados por transcrição, acumular-dentro-do-bloco, virar-página-entre-blocos, o BLOCO DE COMPOSIÇÃO DO HERÓI (o pré-contexto, HERÓI e pós-contexto de um bloco heróico empilham como UMA composição vinculada centralizada no sujeito — ordem de leitura de cima para baixo = ordem falada por construção; o contexto flutua na FRENTE enquanto o herói incorpora ATRÁS = o sanduíche de profundidade; uma regra de massa mantém o herói dominando seu contexto), divisão ápice/herói menor, ordem de leitura por construção, fallback fg por zonas seguras. Então os portões executam como de costume. (Criar manualmente plan.json diretamente ainda é possível para designs que blocos não podem expressar — então executefill-timings.cjs+fit-fonts.cjs+make-composition.cjsvocê mesmo.)
Passo 3 — Modo Tema (constituição temática)
Leia temas/README.md PRIMEIRO — registros de paradigma/peça central, ligações, regras rígidas e o esquema exato de theme.json.
- Escolha um DNA de tema pelo registro de conteúdo (cada
temas/<nome>.jsontemvoz+quando). Declare sua escolha + porquê; o usuário decide. - Crie
<projeto>/theme.json—dna,linhas(literal, ordem da transcrição; 1–5 palavras cada — paratomadacada linha é um CARTÃO),menores(palavras de ênfase),hero:{match}(a palavra/frase clímax; deixe-a FORA delinhaspara peças centrais incorporadas, mantenha-a DENTRO para peças centrais inline e painel+redação). - Renderize:
bash scripts/render-theme.sh <projeto>— compila (portão de completude literal no tempo de compilação), renderiza ambas as camadas, compõe, aplica a reação da placa →final_fx.mp4. Usepreview-frames.cjsentre a compilação e a renderização para QA Visual.
QA Visual — prévia ANTES de renderizar
node scripts/preview-frames.cjs <projeto> [t…] compõe prévias de quadro fiéis em ~2s cada
(camadas de legenda capturadas no tempo de busca + quadro de vídeo real + oclusão de matte + sobreposição de barra = como a
composição final se parecerá naquele momento). O padrão amostra = cada janela de grupo/clímax.
Uma renderização completa custa minutos — nunca a use para descobrir problemas de layout.
Verifique as prévias (<projeto>/preview/sheet.png) contra os critérios de aceitação:
- Oclusão: o matte do sujeito cobre o suficiente da palavra incorporada (30–55%)? A palavra está visível através do cabelo/ombro?
- Legibilidade: texto na barra é legível? Contraste suficiente? Nenhum conflito com o fundo?
- Arte: a composição parece intencional, não acidental?
Nunca pule a QA Visual. Uma rodada de ~5 quadros (15s) evita uma renderização perdida de 5 minutos + re-renderização.
Pós-produção
Após a renderização (final.mp4 ou final_fx.mp4), você pode:
- Adicionar áudio (música de fundo, efeitos sonoros) sobreposto ao vídeo renderizado —
ffmpeg -i final.mp4 -i audio.wav -c:v copy -c:a aac -map 0:v:0 -map 1:a:0 final_com_audio.mp4 - Cortar/redimensionar para plataformas sociais (9:16, 1:1) — os templates presumem 16:9 e zonas seguras; um recorte 9:16 pode cortar texto se não re-renderizar. Re-renderizar com
hyperframes init --video ... --aspect 9:16é a rota segura. - Adicionar logotipo/marca d'água — sobreposição no canto, separada da composição de legendas.
Referências
- CATALOG.md — o catálogo de identidades. Leia primeiro antes de qualquer modo.
- Referências/barra.md — manual de regras para legendas de barra.
- Referências/arte-de-composicao.md — manual de regras para arte de incorporação.
- temas/README.md — registros e esquemas para modo Temática.
- dna/README.md — documentação de validação de DNA.
- scripts/ — scripts de pipeline. Veja cabeçalhos para uso e esquemas.