Legendas Incorporadas
Um catálogo, escolhido de antemão (CATALOG.md — 17 identidades; os três motores por trás são detalhes internos). Standard (padrão) constrói uma trilha limpa e literal (legenda inferior que carrega a maior parte do texto) + um clímax embed composto dentro da cena, atrás do sujeito, no pico. Cinematic é embed puro — sem trilha, cada legenda composta atrás do sujeito (tipografia heroica, acumulação, oclusão como efeito). Theme é uma constituição temática completa — paradigma corporal × peça de conjunto heroica × efeito frontal × reação da placa, composta a partir de registros (themes/README.md): ordnance terminal neonsign stardust stomp. A maioria dos vídeos explicativos / narração é Standard; embed é o pico escasso e conquistado — embutir cada palavra é o erro comum; Theme é para pedidos com nível VFX ("炸", "特效", "像 AE 做的").
Fluxo operacional (resumo)
A prosa de artesanato 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) → escolha UMA identidade do CATALOG.md (17 identidades; motor/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, então zonas seguras v2 com paleta/ótica/iluminação da cena — um comando, nada esquecido)- autor um pequeno JSON de escolhas criativas (leia
safe-zones.jsonprimeiro): Cinematic →plan.json→fill-timings.cjs→fit-fonts.cjs→make-composition.cjs; Theme →theme.json→make-theme.cjs(paradigmas trilha/painel/poema/assunção de controle;anchoré o padrão de trilha silenciosa) - QA Visual:
node scripts/preview-frames.cjs <projeto>→ pré-visualizações compostas fiéis em ~2s/quadro (sem renderização). Verifique § QA Visual antes de pagar por uma renderização. render-and-composite.sh→ portões (timing / oclusão+hero / transbordo / entrega) →final.mp4
Regras importantes que as pessoas perdem:
- trilha (padrão) + embed (promoção).
drop(preenchimento, não mostrado) /rail(legenda inferior literal, na frente, carrega a maior parte do texto) /embed(uma palavra de pico composta atrás do sujeito). O modo Standard faz ambos, embutindo apenas o(s) pico(s). Veja § Modelo de legenda. - O vídeo é entregue INALTERADO (Standard/Cinematic; o orçamento PLATE do modo Theme é a única exceção sancionada — batidas de reação registradas (carga-dim, soco, tremor, granulação) definidas por DNA do tema e aplicadas APÓS a composição mate para que sujeito+texto+placa se movam como um quadro) — legendas são a única coisa adicionada; o mate apenas permite que o sujeito oclua a trilha embed. Nunca gradiente/recoloque/scanline a filmagem.
- Dois livros de regras: trilha → references/rail.md (fino), artesanato embed → references/composition-craft.md (rico, apenas embed). Folheie por necessidade.
Modelo de legenda — trilha + embed
Cada frase falada é uma de três coisas:
| O que é | Como é mostrada | |
|---|---|---|
| drop | preenchimento — hum/ah, gaguejos, autocorreções | não mostrada |
| rail | o padrão — conteúdo falado comum (literal) | legenda inferior limpa, na frente, legível. Uma palavra marcante pode ganhar um destaque emphasis inline (cor de destaque / pop de palavra ativa) — permanece na trilha. |
| embed | um pico promovido — a batida principal | uma palavra grande composta atrás do sujeito (oclusão mate), entrada + saída projetadas |
A trilha carrega a maior parte do texto; embed é o pico escasso e conquistado. Escassez é por batida/bloco, não por clipe: ≤1 hero por bloco (pensamento), nunca dois co-visíveis, ≥ uma batida de ar entre janelas hero (o compilador avisa abaixo de 0,6s). Um clipe curto → geralmente 1–2; um explicador longo → ~um por seção. Entre múltiplos heroes, o maior autorado é o APEX (apenas ele recebe o embed de bloqueio completo + ajuste de largura); os menores são picos MENORES que viajam em sua coluna como linhas de ênfase ampliadas (fg, movimento amortecido) — nem toda batida precisa da vitrine mate, que é exatamente o que mantém o apex como um evento. Embutir cada palavra ainda é o erro comum.
Identidades de superfície de trilha constroem exatamente isso (trilha = rail.html, embed = o clímax em index.html). Identidades de fluxo em coluna abandonam a trilha e fazem tudo estilo embed — recomende-as apenas para pedidos de clima-sobre-literal, nunca para explicador / narração onde as palavras devem ser lidas (CATALOG.md codifica isso por identidade).
Passo 0 — escolha UMA identidade do CATALOG
Uma interface, 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 autoria 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 porquê de uma linha → o usuário escolhe → autorar o arquivo daquela identidade. Identidades são bloqueadas por motor (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 autorar. Não use um padrão silencioso.
(A tabela completa de identidades está em CATALOG.md — fonte única de verdade para roteamento. Os documentos do motor abaixo descrevem o contrato de autoria 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. Inseguro → anchor.
- Cinematic → escreva
plan.jsonpara um modelo travado, compilado pormake-composition.cjs. - Theme → leia themes/README.md, autor
theme.json, executebash scripts/render-theme.sh <projeto>(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 sample.png # em 20/50/80%
Leia as amostras. Recuse se:
- Múltiplos falantes / cortes duros (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 "Obrigado." sobre o silêncio); atenda e recuse em vez de legendar palavras fabricadas - Fonte já tem legendas / legendas / gráficos de texto pesados queimados — adicionar um segundo sistema de legendas conflita e a filmagem é entregue intocada (sem cobrir/inpaint). Texto queimado geralmente aparece apenas no meio do clipe: amostre uma folha de contato de 1 fps (
ffmpeg -i in.mp4 -vf "fps=1,scale=160:-1,tile=10x5" sheet.png), não confie em 3 quadros pontuais. - Transcrição é lixo — fala não nativa/com sotaque pesado pode transcrever em confiança sem sentido. Leia
transcript.jsonantes de autorar; se não for interpretável como linguagem, tenteWHISPER_MODEL=mediumuma vez, senão recuse (uma trilha literal de palavras fabricadas é pior do que nenhuma legenda). - Portátil ocupado com movimento rápido (oscilação do mate)
Sondagens de pré-voo (não custam nada, previnem as piores falhas)
- Sondagem de corte de tomada. Amostre quadros em 20%, 50%, 80%. Se um sujeito/cena diferente aparecer, corte 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 scrim glifo,180+→ texto opaco + scrim (nunca texto claro nu). Os modelos Cinematic são creme+screene TRAVADOS — use esta sondagem para escolher uma identidade adequada (cenas claras →ink, ou o temaanchorde trilha 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 trilha/painel; poético / social / "cinematográfico" → identidades de fluxo em coluna por registro; "炸 / 特效 / VFX" / mundos nomeados → identidades temáticas. Quando inseguro →
anchor(palavras lidas, cena segura) — mas apresente uma lista curta e deixe o usuário escolher.
Pipeline — 5 etapas
1. hyperframes init <projeto> --non-interactive --video <video.mp4> --skip-skills
2. bash scripts/prepare.sh <projeto> # matte ∥ transcrever (paralelo) → zonas seguras. Um comando.
# → frames_fg/ transcript.json safe-zones.json
3. [PASSO DO AGENTE — o único passo criativo] autor um pequeno JSON; veja abaixo por modo
Cinematic: autor plan.json → node scripts/fill-timings.cjs → fit-fonts.cjs → make-composition.cjs
Theme: autor theme.json → bash scripts/render-theme.sh <projeto> (compila + renderiza + fx placa)
4. node scripts/preview-frames.cjs <projeto> # ~2s/quadro pré-visualizações compostas → § QA Visual (ANTES da renderização)
5. bash scripts/render-and-composite.sh <projeto> # portões → final.mp4 + instantâneo history/
(Modo Theme: PULE etapas 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)
A etapa 3 difere por modo:
Etapa 3 — Modo Cinematic (embed puro)
- Leia
safe-zones.jsonprimeiro. Planos de narração vão emzones.hugLeft/hugRight— faixas limpas ABUTANDO a silhueta (texto longe do corpo parece flutuante, não incorporado; cantos distantes são o fallback, não o padrão). O hero padrão éheroAnchor/heroBands.best(centralizado NO sujeito, ~30–55% ocluído).recommendation:"fg"move a NARRAÇÃO para a frente para legibilidade; o hero permanece embutido sempre queheroBands.feasible— hero-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 (banda hero brilhante luma > 150 quer
ink; orientação completa de escolha está no catálogo, cobrindo todas as dez, incl. neon / glitch / chrome / velocity). Declare sua escolha + porquê; o usuário decide. O DNA trava tipo/paleta/blend/movimento + ato heroico em três partes; zonas seguras v2 (palette/optics/lighting) parametriza-o para ESTA cena automaticamente. - Autor
<projeto>/cinematic.json—"dna": "<nome>"+ pensamento-BLOCOS, não grupos crus: cada bloco = linhas de palavras (agrupadas 2–5 em limites de oração) + o plano em que empilha +csspor linha (tamanho/peso/estilo apenas — sem posições) + no máximo UMA linha marcada como"hero": true(a palavra promovida;"text"para forma de exibição). Esquema: cabeçalhoscripts/make-cinematic.cjs. - Compile:
node scripts/make-cinematic.cjs <projeto>— reduz blocos → plan.json → index.html. Gerado para você: timings sequenciados por transcrição, acumular-dentro-do-bloco, página-virada-entre-blocos, o LOCKUP hero (pré-contexto de um bloco hero, HERO e pós-contexto empilham como UMA composição unida centrada no sujeito — ordem de leitura topo→fundo = ordem falada por construção; contexto flutua na FRENTE enquanto o hero embute ATRÁS = o sanduíche de profundidade; uma regra de massa mantém o hero dominando seu contexto), divisão apex/menor hero, ordem de leitura por construção, fallback fg por zonas seguras. Então os portões rodam como de costume. (Autorar plan.json diretamente à mão permanece possível para designs que os blocos não podem expressar — então executefill-timings.cjs+fit-fonts.cjs+make-composition.cjsvocê mesmo.)
Etapa 3 — Modo Theme (constituição temática)
Leia themes/README.md PRIMEIRO — registros de paradigma/peça de conjunto, ligações, regras rígidas e o esquema exato theme.json.
- Escolha um DNA de tema por registro de conteúdo (cada
themes/<nome>.jsontemvoice+when). Declare sua escolha + porquê; o usuário decide. - Autor
<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 FORA delinespara peças de conjunto embed, mantenha DENTRO para peças de conjunto inline e painel+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 da placa →final_fx.mp4. Usepreview-frames.cjsentre a compilação e a renderização para QA Visual.
QA Visual — pré-visualize ANTES de renderizar
node scripts/preview-frames.cjs <projeto> [t…] compõe quadros de pré-visualização fiéis em ~2s cada
(camadas de legenda capturadas em tempo de busca + quadro de vídeo real + oclusão mate + sobreposição de trilha = o que
a composição final parecerá naquele momento). Amostras padrão = cada janela de grupo/clímax.
Uma renderização completa custa minutos — nunca a use para descobrir problemas de layout.
Verifique as pré-visualizações (<projeto>/preview/sheet.png) contra esta lista — estas são as falhas que os
portões geométricos não podem detectar:
- Desbotamento — texto claro sobre um brilhante...