Legendas Incorporadas
Um catálogo, escolhido de início (CATALOG.md — 17 identidades; os três motores por trás são detalhes de backend). Standard (padrão) constrói um trilho limpo e literal (legenda no terço inferior que carrega a maior parte do texto) + um clímax embed compostado dentro da cena atrás do sujeito no pico. Cinematic é embed puro — sem trilho, cada legenda compostada atrás do sujeito (tipografia heróica, acumulação, oclusão como efeito). Theme é uma constituição temática completa — paradigma corporal × peça heróica × efeito frontal × reação de placa, composta a partir de registos (themes/README.md): ordnance terminal neonsign stardust stomp. A maior parte do conteúdo explicativo / voz over é Standard; embed é o pico escasso e merecido — incorporar cada palavra é o erro comum; Theme é para pedidos de nível VFX ("炸", "特效", "像 AE 做的").
Fluxo operacional (resumo)
A prosa técnica abaixo é longa; o pipeline em si é curto — e tudo que é determinístico é calculado ou compilado, nunca escrito à mão:
- Portão de decisão (recusar clipes ruins) → escolher UMA identidade do CATALOG.md (17 identidades; motor/compilador derivado por consulta — nunca apresentar 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 safe-zones v2 com paleta/ótica/iluminação da cena — um comando, nada esquecido)- criar um pequeno JSON de escolhas criativas (ler
safe-zones.jsonprimeiro): Cinematic →plan.json→fill-timings.cjs→fit-fonts.cjs→make-composition.cjs; Theme →theme.json→make-theme.cjs(paradigmas trilho/painel/poema/takeover;anchoré o padrão silencioso) - QA visual:
node scripts/preview-frames.cjs <projeto>→ pré-visualizações fiéis da composição em ~2s/frame (sem render). Verifique § QA visual antes de pagar por um render. render-and-composite.sh→ portões (timing / oclusão+herói / overflow / hand-off) →final.mp4
Regras fundamentais que as pessoas perdem:
- trilho (padrão) + embed (promoção).
drop(preenchimento, não mostrado) /trilho(legenda literal no terço inferior, na frente, carrega a maior parte do texto) /embed(uma palavra de pico compostada atrás do sujeito). O modo Standard faz ambos, incorporando apenas o(s) pico(s). Veja § Modelo de legenda. - O vídeo é entregue INTACTO (Standard/Cinematic; o orçamento de PLACA do modo Theme é a única exceção sancionada — beats de reação registados (charge-dim, punch, shake, grain) definidos por DNA do tema e aplicados APÓS a composição do fosco para que o sujeito+texto+placa se movam como um quadro) — legendas são a única coisa adicionada; o fosco apenas permite que o sujeito oclua a faixa embed. Nunca gradear/recolorir/scanear a filmagem.
- Dois manuais de regras: trilho → references/rail.md (fino), craft embed → references/composition-craft.md (rico, apenas embed). Leia conforme necessário.
Modelo de legenda — trilho + embed
Cada frase falada é uma de três coisas:
| O que | Como é mostrada | |
|---|---|---|
| drop | preenchimento — um/uh, gaguejos, autocorreções | não mostrada |
| trilho | o padrão — conteúdo falado comum (literal) | legenda limpa no terço inferior, na frente, legível. Uma palavra de impacto pode receber um destaque emphasis inline (cor de destaque / pop de palavra ativa) — ela permanece no trilho. |
| embed | um pico promovido — o batida principal | uma palavra grande compostada atrás do sujeito (oclusão de fosco), entrada + saída projetadas |
O trilho carrega a maior parte do texto; embed é 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 espaço entre janelas de herói (o compilador avisa abaixo de 0,6s). Um clipe curto → geralmente 1–2; um explicador longo → ~um por seção. Entre múltiplos heróis, o maior criado é o ÁPICE (só ele recebe o lockup embed completo + elevação de largura); os menores são picos MENORES que andam em sua coluna como linhas de ênfase superdimensionadas (fg, movimento amortecido) — nem toda batida precisa do showcase do fosco, que é exatamente o que mantém o ápice um evento. Incorporar cada palavra ainda é o erro comum.
Identidades de superfície de trilho constroem exatamente isso (trilho = rail.html, embed = o clímax em index.html). Identidades de fluxo-coluna descartam o trilho e tornam tudo estilo embed — recomende-as apenas para pedidos de clima-sobre-literal, nunca para explicador / voz over onde as palavras devem ser lidas (CATALOG.md codifica isso por identidade).
Passo 0 — escolher UMA identidade do CATALOG
Um front-end, três motores por trás. O usuário escolhe uma IDENTIDADE do CATALOG.md (17 entradas: 12 clássicas + 5 temáticas); o motor, compilador e arquivo de criação são derivados por consulta da linha do catálogo. Nunca apresente "Standard vs Cinematic vs Theme" como uma pergunta — esses são nomes de backend (um produto tem uma UX mesmo com vários motores). 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: sondar o clipe → lista curta de 2–3 identidades do catálogo → recomendar UMA com um motivo de uma linha → o usuário escolhe → criar o arquivo dessa identidade. Identidades são bloqueadas por motor (sem combinações cruzadas; 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 use o padrão silenciosamente.
(A tabela completa de identidades está em CATALOG.md — fonte única de verdade para roteamento. Os documentos do motor abaixo descrevem o contrato de criação de cada backend.)
Heurística de recomendação: use as "Heurísticas de lista curta" em CATALOG.md — elas são no nível da identidade (ex.: "炸" lista curta ordnance/stomp/terminal/loud e escolhe pelo QUE deve explodir), nunca no nível da categoria. Em dúvida → anchor.
- Cinematic → escreva
plan.jsonpara um template fixo, compilado pormake-composition.cjs. - Theme → leia themes/README.md, crie
theme.json, executescripts/render-theme.sh(compila + renderiza + reação de placa → final_fx.mp4).
Portão de decisão — EXECUTAR 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 sample.png # aos 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 cabeça falante)
- Menos de 3 segundos, sem fala, ou rosto nunca claramente visível —
transcribe.cjsavisa quando o áudio está quase silencioso (Whisper alucina palavras como "Thank you." sobre o silêncio); obedeça e recuse em vez de legendar palavras fabricadas - Fonte já tem legendas queimadas / subtítulos / gráficos de texto pesados — adicionar um segundo sistema de legenda conflita e a filmagem é enviada intacta (sem cobrir/restaurar). Texto queimado geralmente aparece apenas no meio do clipe: amostre uma folha de contato a 1fps (
ffmpeg -i in.mp4 -vf "fps=1,scale=160:-1,tile=10x5" sheet.png), não confie em 3 frames de ponto. - Transcrição é lixo — fala não-nativa/com sotaque pesado pode ser transcrita em confuso jargão. Leia
transcript.jsonantes de criar; se não fizer sentido como linguagem, tenteWHISPER_MODEL=mediumuma vez, senão recuse (um trilho literal de palavras fabricadas é pior que sem legendas). - Câmera na mão ocupada com movimento rápido (fosco pisca)
Sondagens pré-voo (não custam nada, evitam as piores falhas)
- Sondagem de corte de tomada. Amostre frames a 20%, 50%, 80%. Se um sujeito/cena diferente aparecer, apare o clipe antes do corte.
- Sondagem de letterbox / pillarbox. Barras pretas no primeiro frame? 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 scrim de glifo,180+→ texto opaco + scrim (nunca texto claro sem revestimento). Os templates Cinematic são cream+screene TRAVADOS — use esta sondagem para escolher uma identidade adequada (cenas claras →ink, ou o temaanchorde trilho opaco), nunca para recolorir uma. - Recomendação de identidade por tom (você recomenda; o usuário escolhe — veja Passo 0 + CATALOG.md). explicador / entrevista / palavras que devem ser lidas → identidades de superfície de trilho/painel; poético / social / "cinemático" → identidades de fluxo-coluna por registro; "炸 / 特效 / VFX" / mundos nomeados → identidades temáticas. Em dúvida →
anchor(palavras lidas, cena segura) — mas apresente uma lista curta 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) → safe-zones. Um comando.
# → frames_fg/ transcript.json safe-zones.json
3. [PASSO DO AGENTE — o único passo criativo] crie um pequeno JSON; veja abaixo por modo
Cinematic: crie plan.json → node scripts/fill-timings.cjs → fit-fonts.cjs → make-composition.cjs
Theme: crie theme.json → bash scripts/render-theme.sh <projeto> (compila + renderiza + efeitos de placa)
4. node scripts/preview-frames.cjs <projeto> # ~2s/frame pré-visualizações compostas → § QA visual (ANTES do render)
5. bash scripts/render-and-composite.sh <projeto> # portões → final.mp4 + snapshot em history/
(Modo Theme: PULE passos 3b/5 — render-theme.sh já executa compilação + render-and-composite
+ _postfx.sh; o entregável é final_fx.mp4, final.mp4 é pré-reação de placa)
O passo 1 init verifica as skills instaladas contra as mais recentes no GitHub e atualiza o conjunto global se alguma estiver desatualizada.
O passo 3 difere por modo:
Passo 3 — Modo Cinematic (embed puro)
- Leia
safe-zones.jsonprimeiro. Os planos de narração vão emzones.hugLeft/hugRight— faixas limpas ADJACENTES à silhueta (texto longe do corpo parece flutuante, não incorporado; cantos distantes são o fallback, não o padrão). O herói padrão vai emheroAnchor/heroBands.best(centrado NO sujeito, ~30–55% ocluído).recommendation:"fg"move a NARRAÇÃO para a frente para legibilidade; o herói permanece embed sempre queheroBands.feasible— herói-fg é o último recurso. - O DNA é a identidade que você escolheu no Passo 0 (CATALOG.md) — não reabra a escolha aqui. Verifique-a contra a cena (luminância da faixa do herói > 150 quer
ink; a orientação completa de escolha está no catálogo, cobrindo todas as dez incl. neon / glitch / chrome / velocity). Declare sua escolha + motivo; o usuário decide. O DNA trava tipo/paleta/mistura/movimento + três atos do herói; safe-zones v2 (palette/optics/lighting) 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 nos limites de oração) + o plano em que empilha +csspor linha (tamanho/peso/estilo apenas — 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>— abaixa blocos → plan.json → index.html. Gerado para você: timings sequenciados por transcrição, acumular dentro do bloco, virar página entre blocos, o LOCKUP do herói (pré-contexto do bloco herói, HERÓI e pós-contexto empilham como UMA composição vinculada centrada no sujeito — ordem de leitura topo→fundo = ordem falada por construçã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 safe-zones. Depois os portões rodam como de costume. (Criar plan.json manualmente permanece possível para designs que blocos não podem expressar — depois executefill-timings.cjs+fit-fonts.cjs+make-composition.cjsvocê mesmo.)
Passo 3 — Modo Theme (constituição temática)
Leia themes/README.md PRIMEIRO — registos de paradigma/peça, ligações, regras rígidas e o esquema exato de theme.json.
- Escolha um DNA de tema pelo registro de conteúdo (cada
themes/<nome>.jsontemvoice+when). Declare sua escolha + motivo; o usuário decide. - Crie
<projeto>/theme.json—dna,lines(literal, ordem da transcrição; 1–5 palavras cada — paratakeovercada linha é um CARD),minors(palavras de ênfase),hero:{match}(a palavra/frase clímax; deixe-a FORA delinespara peças embed, mantenha-a DENTRO para peças inline e panel+redact). - Renderize:
bash scripts/render-theme.sh <projeto>— compila (portão de completude literal em tempo de compilação), renderiza ambas as camadas, compõe, aplica a reação de placa →final_fx.mp4. Usepreview-frames.cjsentre a compilação e o render para QA visual.
QA visual — pré-visualize ANTES de renderizar
node scripts/preview-frames.cjs <projeto> [t…] compõe pré-visualizações fiéis em ~2s cada
(camadas de legenda capturadas no tempo de busca + frame de vídeo real + oclusão de fosco + sobreposição de trilho = o que a composição final parecerá naquele momento). Amostras padrão = cada janela de grupo/clímax.
Um render completo custa minutos — nunca use para descobrir problemas de layout.
Verifique as pré-visualizações (<projeto>/preview/sheet.png) contra:
- Oclusão: o herói está atrás do sujeito? O fosco está intacto em torno da cabeça/ombros? (Se a testa/queixo do sujeito estiverem cortadas, o fosco falhou — refine
erode/dilateemsafe-zones.jsonantes de renderizar.) - Colisões: algum texto colide com texto ao lado ou com o sujeito?
- Hierarquia: o ápice domina os heróis menores? Heróis menores dominam a narração? (A narração nunca deve competir com um herói.)
- Estilo: a cor/tamanho/posição correspondem à identidade escolhida? A paleta está ajustada a esta cena? (Se não, atualize os ajustes de
safe-zones.v2.)
O script de pré-visualização NÃO valida automaticamente — você inspeciona a folha de contato e retrabalha se algo parecer errado. Se a pré-visualização estiver boa, vá para o passo 5.
Regras de renderização
- O vídeo de origem NUNCA é tocado — legendas são a única adição. Sem gradear, recolorir, adicionar vinheta, scanear, deslocar ou alterar a cena de qualquer forma. O fosco apenas permite que o sujeito oclua a faixa embed; não aplique um fosco de frente a nenhuma camada de trilho fg.
- O vídeo final é
final.mp4(Standard/Cinematic) oufinal_fx.mp4(Theme — inclui efeitos de placa pós-compostagem). O script de renderização aplica a composição embed ATRÁS do sujeito, a legenda de trilho NA FRENTE, e (apenas em Theme) os efeitos de reação de placa registados. render-and-composite.shaplica portões:- Portão de placa: a composição embed (index.html + fosco) cabe dentro dos limites seguros? Se não, recua para o texto fg puro.
- Portão de hand-off: a última palavra desaparece antes que a cena termine? O portão adiciona um fade-out de 1s se necessário.
- Apenas para Theme:
render-theme.shexecutarender-and-composite.shprimeiro (pré-efeitos) e então adiciona a reação de placa (shake, grain, charge-dim, punch) como uma pós-passagem que move sujeito+texto+placa como um quadro único.
Modo de degradação: sem hyperframes / sem fosco
Se hyperframes prepare produzir matte/frames_fg vazio (fosco falhou para este clipe — movimento rápido, curto prazo, fundo complexo), NÃO finja que funcionou. Informe o usuário e oferte:
- Fallback embed apenas — embed funciona como texto fg sobreposto (sem oclusão; compositado sobre o vídeo como uma faixa de estilo). Especifique antes de prosseguir.
- Invoque uma ferramenta de segmentação externa (ex.:
segment-anything-2/ REMOVE) e re-tente com mattes corrigidos. - Abandone este clipe — legendas com fosco falho parecem piores do que nenhuma legenda.
Se o usuário escolher a opção 1, defina occlusion: none em plan.json (ou theme.json para Theme) — o compilador renderizará o texto embed na frente com um scrim de glifo, sem tentar fosco. O trilho (quando presente) permanece inalterado na frente.
Resolução de problemas
| Problema | Causa provável | Ação |
|---|---|---|
| Texto embed cortado | heroAnchor errado / bandas não cabem | Re-sample safe-zones; mude o plano (hugLeft/hugRight); caia para fg. |
| Fosco pisca / buracos | Fundo complexo / movimento rápido | Fallback para embed apenas (passo de degradação); ou refine erode/dilate. |
| Transcrição lixo | Sotaque pesado / ruído / silêncio | Tente WHISPER_MODEL=medium; veja amostras; recuse se não fizer sentido. |
| Texto embaixo ilegível | Luminância alta + sem scrim | Use a sondagem de luminância; adicione scrim ou escolha ink/anchor. |
| "Drop" não removido | Palavra de preenchimento marcada como trilho | Edite transcript.json (mude "type":"rail" para "type":"drop" na palavra ofensiva); re-compile. |
| Herói não incorpora | heroBands.inviavel | Mova herói para o plano fg (fg:true no cinematic.json) e avise o usuário: quedas de imersão. |
| Ápice não domina heróis menores | Bloco de herói com >1 herói, ou nenhum ápice | Verifique cinematic.json — exatamente UMA linha hero:true no bloco do ápice; os heróis menores devem estar em blocos separados com linha marcada como herói, mas com tamanho/texto menor. |
| Efeitos de placa não aparecem | Modo Theme não usado; ou efeitos não registados | Certifique-se de que está usando Theme com theme.json e scripts/render-theme.sh. Verifique se o DNA do tema tem efeitos registados em seu arquivo de registo. |
| Legenda queimada existente conflita | Amostragem de folha de contato perdida | Refaça a sondagem de 1fps; recuse se qualquer texto queimado for encontrado — a skill não cobre/inpinta. |
| Compilação falha | JSON malformado | Valide JSON (node -e "JSON.parse(require('fs').readFileSync('plan.json','utf8'))"); verifique o esquema no cabeçalho do script. |
Referências
- CATALOG.md — CATALOG.md — fonte única de verdade para identidades (17 entradas; 12 clássicas + 5 temáticas). Heurísticas de roteamento, recomendações de superfície de leitura, notas de adjacência.
- Craft do trilho — references/rail.md — compostagem de trilho, modelo de destaque inline, posição, construção de trilho no modo Standard.
- Craft da composição — references/composition-craft.md — compostagem embed (apenas Cinematic/Theme): oclusão, acumulação, movimentos heróicos, três atos do embed.
- Registo de temas — themes/README.md — registos de paradigma/peça para temas: linkagem de DNA, esquema
theme.json, regras de reação de placa. - DNA — dna/README.md — como as identidades são definidas (paleta, tipo, mistura, três atos do herói, movimento, peça de setpiece).