Primeiro, mantenha este skill atualizado — confirme com o usuário antes de executar:
npx hyperframes skills update embedded-captions. Uma operação rápida e sem efeitos colaterais quando tudo está atualizado; caso contrário, ele atualiza este skill e os skills de domínio principais dos quais depende, antes que você confie neles.
Legendas Incorporadas (Embedded Captions)
Um catálogo, escolhido de antemão (CATALOG.md — 35 identidades; os mecanismos por trás disso são detalhes do backend). Standard (padrão) constrói uma barra de legendas rail limpa (legenda inferior carregando a maior parte do texto) + um clímax embed composto dentro da cena atrás do sujeito no pico. Cinematic é puro embed — sem rail, 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 heroica × efeito frontal × reação de placa, composta a partir de registros (themes/README.md): ordnance terminal neonsign stardust stomp. A maioria dos vídeos explicativos / narrações é Standard; embed é o pico escasso e merecido — incorporar cada palavra é o erro comum; Theme é para pedidos de nível VFX ("炸", "特效", "como se fosse feito no AE").
Fluxo operacional (resumo)
Roteado através de /hyperframes, a camada de intenção confirma apenas a entrada (qual clipe) e anuncia a escolha da identidade como uma pergunta adiada — a lista de opções precisa do clipe analisado, então ela permanece na etapa 1 abaixo; as perguntas de forma da execução da camada não se aplicam (a filmagem está intocada, não há storyboard para revisar). Um BRIEF.md, quando presente, carrega a entrada confirmada e quaisquer notas do usuário — leia-o primeiro.
O texto de criação abaixo é longo; 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 de CATALOG.md (35 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 com 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 rail/painel/poema/tomada;anchoré o padrão rail discreto) - QA Visual:
node scripts/preview-frames.cjs <projeto>→ prévias compostas 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+hero / estouro / entrega) →final.mp4
Regras importantes que as pessoas perdem:
- rail (padrão) + embed (promoção).
drop(preenchimento, não exibido) /rail(legenda inferior verbatim, na frente, carrega a maior parte do texto) /embed(uma palavra de pico composta atrás do sujeito). O modo Standard faz ambos, incorporando apenas o(s) pico(s). Veja § Modelo de legenda. - O vídeo é entregue INTOCADO (Standard/Cinematic; o orçamento PLATE do modo Theme é a única exceção sancionada — batidas de reação registradas (dim de carga, soco, tremor, grã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 oclua a trilha de embed. Nunca corrija cor/recolorir/linhas de varredura da filmagem.
- Dois livros de regras: rail → references/rail.md (fino), criação de embed → references/composition-craft.md (rico, apenas embed). Folheie conforme a necessidade.
Modelo de legenda — rail + embed
Cada frase falada é uma de três coisas:
| O que é | Como é mostrada | |
|---|---|---|
| drop | preenchimento — hum/ah, gaguejos, autocorreções | não mostrada |
| rail | padrão — conteúdo falado comum (verbatim) | legenda inferior limpa, na frente, legível. Uma palavra de destaque pode ganhar um destaque emphasis inline (cor de acento / pop de palavra ativa) — permanece no rail. |
| embed | um pico promovido — a batida principal | uma palavra grande composta atrás do sujeito (oclusão por matte), entrada + saída projetadas |
O rail carrega a maior parte do texto; embed é o pico escasso e merecido. A escassez é por batida/bloco, não por clipe: ≤1 hero por bloco (pensamento), nunca dois co-visíveis, ≥ uma batida de ar entre janelas de hero (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 APEX (só ele recebe o lockup embed completo + elevação por largura); os menores são picos MENORES que andam em sua coluna como linhas de ênfase ampliadas (fg, movimento amortecido) — nem toda batida precisa do showcase matte, que é exatamente o que mantém o apex como um evento. Incorporar cada palavra ainda é o erro comum.
Identidades de superfície Rail constroem exatamente isso (rail = rail.html, embed = o clímax em index.html). Identidades de fluxo em coluna eliminam o rail e fazem tudo no estilo embed — recomende-as apenas para pedidos de clima sobre verbatim, nunca para explicadores/narração onde as palavras devem ser lidas (CATALOG.md codifica isso por identidade).
Etapa 0 — escolha UMA identidade do CATÁLOGO
Um front-end, três mecanismos por trás. O usuário escolhe uma IDENTIDADE de CATALOG.md (35 entradas: 10 clássicas + 25 temáticas); o mecanismo, 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 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 pares realmente próximos (loud↔ordnance, neon↔neonsign, cream↔stardust).
A escolha da identidade é um portão de preferência (../hyperframes/references/brief-contract.md § 1): em modo autônomo ("surpreenda-me" / "decida por mim"), escolha da sua própria lista de opções e declare o porquê em uma linha em vez de perguntar.
Procedimento: analise o clipe → liste 2–3 identidades do catálogo → recomende UMA com um porquê em uma linha → o usuário escolhe (modo autônomo: você escolhe, declarando o porquê) → crie o arquivo dessa identidade. As identidades são bloqueadas por mecanismo (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 assuma silenciosamente o padrão.
(A tabela completa de identidades está em CATALOG.md — fonte única da verdade para roteamento. Os documentos do mecanismo abaixo descrevem o contrato de criação de cada backend.)
CATALOG.md é todo o espaço de respostas aqui: este fluxo de trabalho não pesquisa o registro de componentes do HyperFrames. Os fluxos de composição executam npx hyperframes catalog antes de criar um visual nomeado; este não deve. Seus mecanismos são compiladores travados que consomem cinematic.json / theme.json e emitem a composição eles mesmos, então um item de registro — incluindo os blocos caption-* — não tem onde se montar. Um bloco de registro estiliza texto em uma tela projetada; este skill queima legendas na filmagem de alguém através de um matte. Quando nenhuma identidade se encaixa no pedido, diga isso e escolha a mais próxima, em vez de buscar fora do catálogo.
Heurística de recomendação: use as "Heurísticas de seleção" em CATALOG.md — elas são no nível da identidade (ex.: "炸" seleciona ordnance/stomp/terminal/loud e escolhe pelo QUE deve explodir), nunca no nível da categoria. Incerto → anchor.
- Cinematic → escreva
plan.jsonpara um template travado, 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 — EXECUTE PRIMEIRO
Analise 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 bruscos (divida e renderize cada cena, ou recuse)
- Nenhum sujeito humano (este skill é para talking-head)
- 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 legendear palavras fabricadas - 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/inpaint). 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 quadros de pontos. - A transcrição é lixo — fala não nativa/com sotaque pesado pode ser transcrita em bobagem confiante. Leia
transcript.jsonantes de criar; se não fizer sentido como linguagem, tenteWHISPER_MODEL=mediumuma vez, senão recuse (uma rail verbatim de palavras fabricadas é pior do que sem legendas). - Mão ocupada com movimento rápido (matte tremendo)
Sondagens de pré-voo (não custam nada, previnem as piores falhas)
- Sondagem de corte de cena. Amostre quadros em 20%, 50%, 80%. Se aparecer um sujeito/cena diferente, 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ê como está,60-180→ adicione o escurecimento de glifo,180+→ texto opaco + escurecimento (nunca texto claro puro). Templates Cinematic são cream+screene TRAVADOS — use esta sondagem para escolher uma identidade adequada (cenas brilhantes →ink, ou o temaanchorcom rail opaco), nunca para recolorir uma. - Recomendação de identidade por tom (você recomenda; o usuário escolhe — veja Etapa 0 + CATALOG.md). explicador / entrevista / palavras que devem ser lidas → identidades de superfície rail/painel; poético / social / "cinematográfico" → identidades de fluxo em coluna por registro; "炸 / 特效 / VFX" / mundos nomeados → identidades temáticas. Quando incerto →
anchor(palavras lidas, cena segura) — mas apresente uma lista e deixe o usuário escolher.
Pipeline — 5 etapas
1. hyperframes init <projeto> --non-interactive --video <video.mp4> --skill=embedded-captions
2. bash scripts/prepare.sh <projeto> # matte ∥ transcrição (paralelo) → zonas seguras. Um comando.
# → frames_fg/ transcript.json safe-zones.json
3. [ETAPA DO AGENTE — a única etapa criativa] 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 + fx de placa)
4. node scripts/preview-frames.cjs <projeto> # ~2s/quadro prévias compostas → § QA Visual (ANTES da renderização)
5. bash scripts/render-and-composite.sh <projeto> # portões → final.mp4 + histórico/ instantâneo
(Modo Theme: PULE as 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 1 do init verifica os skills instalados em relação ao mais recente no GitHub e atualiza o conjunto global se algum estiver desatualizado.
A etapa 3 difere por modo:
Etapa 3 — Modo Cinematic (puro embed)
- Leia
safe-zones.jsonprimeiro. Planos de narração vão emzones.hugLeft/hugRight— faixas 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 hero padrão vai paraheroAnchor/heroBands.best(centrado NO sujeito, ~30–55% ocluído).recommendation:"fg"move a NARRAÇÃO para a frente para legibilidade; o hero permanece incorporado sempre queheroBands.feasible— hero-fg é o último recurso. - O DNA é a identidade que você escolheu na Etapa 0 (CATALOG.md) — não reabra a escolha aqui. Verifique-a contra a cena (luma de banda hero brilhante > 150 quer
ink; a orientação de escolha completa 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/mistura/movimento + três atos do hero; zonas seguras v2 (palette/optics/lighting) parametrizam-no para ESTA cena automaticamente. - Crie
<projeto>/cinematic.json—"dna": "<nome>"+ BLOCOS de pensamento, não grupos crus: cada bloco = linhas de palavras (agrupadas 2–5 em limites de cláusula) + 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>— reduz 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 hero (pré-contexto de um bloco hero, HERO e pós-contexto empilham como UMA composição vinculada centrada no sujeito — ordem de leitura top→bottom = ordem falada por construção; contexto flutua na FRENTE enquanto o hero incorpora 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 deve ser a ordem das palavras do vídeo, o compilador avisa se você colocar blocos fora de ordem sequencial; compile primeiro, verifique com prévias; o usuário dá OK → etapa 5.
Etapa 3 — Modo Theme
- Leia
safe-zones.jsonprimeiro (mesmo que Cinematic). - Veja themes/README.md — contém o contrato de criação para a identidade que você escolheu: paradigma corporal que este tema usa (rail/painel/poema/tomada), o arquivo de registro que carrega (ex.:
registries/ordnance-registry.json), quais efeitos de placa estão disponíveis (carga-dim, soco, tremor, grão), o compilador de composição (make-theme.cjs) e o script de renderização (render-theme.sh). - Crie
<projeto>/theme.json— campos obrigatórios:"dna": "<nome>","paradigm": "<rail|panel|poem|takeover>","lines": [<matriz de linhas>](cada uma comtext,timingdo transcript.json,cssopcional),"plateFx": "<charge-dim|punch|shake|grain>"opcional."lines": uma matriz de objetos, cada um representando uma linha de legenda. O timing pode ser um parstart/endem segundos, ou uma string"auto"para derivar do transcript.json."plateFx": se fornecido, aplica um efeito de reação de placa (ex.: escurecimento de carga, soco) APÓS a composição principal. Veja themes/README.md para definições.
- Compile e renderize:
bash scripts/render-theme.sh <projeto>— isto executamake-theme.cjs(compila theme.json → index.html com composição tecida), depoisrender-and-composite.sh(portões → final.mp4), depois_postfx.sh(aplica plateFx → final_fx.mp4). O entregável final éfinal_fx.mp4;final.mp4é pré-fx.
QA Visual
Sempre pré-visualize antes de pagar por uma renderização completa. Execute node scripts/preview-frames.cjs <projeto> — ele gera prévias compostas fiéis (~2s/quadro) no subdiretório previews/. Verifique:
- Posicionamento do texto: está dentro das zonas seguras? O hero está adequadamente ocluído pelo sujeito?
- Visibilidade: O texto é legível contra o fundo? A cor e o escurecimento estão corretos?
- Timing: As palavras aparecem no momento certo? Há sobreposições ou lacunas?
- Fluxo de leitura: Para modo Cinematic, a ordem de leitura corresponde à ordem da fala?
Mostre 3–5 quadros ao usuário e peça aprovação antes de executar render-and-composite.sh.
Referências
- CATALOG.md — Catálogo completo de identidades (35 estilos)
- themes/README.md — Documentação de criação de temas
- references/rail.md — Guia de estilo para legendas rail
- references/composition-craft.md — Guia de criação para composições embed
- references/brief-contract.md — Contrato de resumo para modo autônomo
- dna/README.md — Validação e regras de DNA de identidade