Legendas Embutidas

---

name: embedded-captions description: > Adiciona legendas ou subtítulos a um vídeo existente de uma única pessoa falando sem editar o material. Use para legendas literais, legendas cinematográficas embutidas atrás do sujeito, legendas com efeitos VFX, "炸/特效/酷炫字幕", ou uma identidade nomeada do catálogo de 35 estilos. Roteie pela identidade visual, não pelo motor interno. O trilho anchor silencioso é o padrão; incorpore cada palavra apenas quando o usuário explicitamente desejar um tratamento totalmente cinematográfico. O fluxo de trabalho é executado localmente de ponta a ponta, incluindo transcrição e matting do sujeito; divida o material com múltiplos planos antes de aplicar.

Primeiro, mantenha esta skill atualizada — confirme com o usuário antes de executar: npx hyperframes skills update embedded-captions. Um no-op rápido quando tudo está atualizado; caso contrário, atualiza esta skill além das skills de domínio principais das quais ela depende, antes de você confiar nelas.

O que Legendas Embutidas faz?

Um catálogo, escolhido antecipadamente (CATALOG.md — 35 identidades; os motores por trás disso são detalhes do 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 incorporado composto na cena atrás do sujeito no pico. Cinematic é puramente incorporado — sem trilho, cada legenda composta atrás do sujeito (tipografia heróica, acumulação, oclusão como efeito). Theme é uma constituição temática completa — paradigma do corpo × conjunto heróico × efeitos frontais × reação da placa, composta a partir de registros (themes/README.md): ordnance terminal neonsign stardust stomp. A maioria de vídeos explicativos / narração é Standard; incorporado é 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 curta precisa do clipe sondado, então permanece na etapa 1 abaixo; as perguntas de formato de execução da camada não se aplicam (o material não foi editado, 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:

1. Portão de decisão (recusar clipes ruins) → escolher UMA identidade do CATALOG.md (35 identidades; motor/compilador derivado por consulta — nunca apresente uma pergunta de modo/categoria)
2. hyperframes init (pule se o diretório do projeto já existir com o vídeo dentro — matte.cjs/transcribe.cjs adotam 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 de cena/óptica/iluminação — um comando, nada esquecido)
3. autorar um pequeno JSON de escolhas criativas (leia safe-zones.json primeiro): Cinematic → plan.json → fill-timings.cjs → fit-fonts.cjs → make-composition.cjs; Theme → theme.json → make-theme.cjs (paradigmas de trilho/ painel / poema / tomada; anchor é o padrão de trilho silencioso)
4. QA visual: node scripts/preview-frames.cjs <projeto> → pré-visualizações de composição fiéis em ~2s/quadro (sem renderizar). Verifique § Visual QA antes de pagar por uma renderização.
5. render-and-composite.sh → portões (timing / oclusão+herói / estouro / entrega) → final.mp4

Regras importantes que as pessoas ignoram:

• trilho (padrão) + incorporado (promoção). drop (preenchimento, não exibido) / rail (legenda literal no terço inferior, 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 SEM ALTERAÇÕES (Standard/Cinematic; o orçamento da PLACA do modo Theme é a única exceção sancionada — batidas de reação registradas e controladas (diminuir carregamento, 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 gradear/recorolorir/escaneamento de linhas o material.
• Dois livros de regras: trilho → references/rail.md (fino), criação incorporada → references/composition-craft.md (rico, apenas incorporado). Folheie conforme necessário.

---

Modelo de legenda — trilho + incorporado

Cada frase falada é uma de três coisas:

	O quê	Como é exibida
drop	preenchimento — hum/ah, gaguejos, autocorreções	não exibida
rail	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 inline emphasis (cor de destaque / pop de palavra ativa) — ela permanece no trilho.
embed	um pico promovido — a batida principal	uma palavra grande composta atrás do sujeito (oclusão do matte), entrada + saída projetadas

O trilho carrega a maior parte do texto; incorporado é o pico escasso e merecido. Escassez é por batida/bloco, não por clipe: ≤1 herói por bloco (pensamento), nunca dois co-visíveis, ≥ um intervalo de ar 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 autorado é o APEX (apenas ele recebe o incorporado completo + elevação 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 exibição do matte, que é exatamente o que mantém o apex como um evento. Incorporar cada palavra ainda é o erro comum.

Identidades de superfície de trilho constroem exatamente isso (rail = rail.html, incorporado = o clímax em index.html). Identidades de fluxo de coluna eliminam o trilho e fazem tudo no estilo incorporado — recomende-as apenas para pedidos de clima sobre literalidade, nunca para explicador / 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 motores atrás. O usuário escolhe uma IDENTIDADE do CATALOG.md (35 entradas: 10 clássicas + 25 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).

A escolha da identidade é um portão de preferência (../hyperframes-core/references/brief-contract.md § 1): em modo autônomo ("surpreenda-me" / "decida por mim"), escolha da sua lista curta e declare o porquê em uma linha em vez de perguntar.

Procedimento: sondar o clipe → listar 2–3 identidades do catálogo → recomendar UMA com um porquê em uma linha → o usuário escolhe (modo autônomo: você escolhe, declarando o porquê) → autorar 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 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 listagem curta" em CATALOG.md — elas são em nível de identidade (ex.: "炸" lista curta ordnance/stomp/terminal/loud e escolhe pelo QUE deve explodir), nunca em nível de categoria. Incerto → anchor.

• Cinematic → escreva plan.json para um modelo travado, compilado por make-composition.cjs.
• Theme → leia themes/README.md, autorar theme.json, executar scripts/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 sample.png   # em 20/50/80%

Leia as amostras. Recuse se:

• Múltiplos falantes / cortes bruscos (divida e renderize cada plano, ou recuse)
• Nenhum sujeito humano (esta skill é para cabeça falante)
• Menos de 3 segundos, nenhuma fala, ou rosto nunca claramente visível — transcribe.cjs avisa quando o áudio está quase silencioso (Whisper alucina palavras como "Thank you." sobre silêncio); atenda ao aviso e recuse em vez de legendas fabricadas
• Fonte já tem legendas / subtítulos embutidos / gráficos de texto pesados — adicionar um segundo sistema de legendas conflita e o material é enviado sem alterações (sem cobrir/inpaint). Texto embutido frequentemente 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 ponto.
• Transcrição é lixo — fala não nativa/com sotaque pesado pode ser transcrita como bobagem confiante. Leia transcript.json antes de autorar; se não for interpretável como idioma, tente WHISPER_MODEL=medium uma vez, caso contrário recuse (um trilho literal de palavras fabricadas é pior que sem legendas).
• Câmera na mão ocupada com movimento rápido (matte pisca)

Sondagens pré-voo (não custam nada, evitam as piores falhas)

1. Sondagem de corte de plano. Amostre quadros em 20%, 50%, 80%. Se um sujeito/cena diferente aparecer, apare o clipe antes do corte.
2. 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.
3. Sondagem de luminância. Amostre a luminância média da região da legenda — abaixo de 60 → texto claro é legível como está, 60-180 → adicione o véu do glifo, 180+ → texto opaco + véu (nunca texto claro sem véu). Os modelos Cinematic são creme+screen e TRAVADOS — use esta sondagem para escolher uma identidade adequada (cenas brilhantes → ink, ou o tema anchor de trilho opaco), nunca para recolorir um.
4. 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 de trilho/painel; poético / social / "cinematográfico" → identidades de fluxo de coluna por registro; "炸 / 特效 / VFX" / mundos nomeados → identidades temáticas. Quando incerto → anchor (palavras são 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> --skill=embedded-captions
2. bash scripts/prepare.sh <projeto>       # matte ∥ transcrever (paralelo) → safe-zones. Um comando.
                                           #   → frames_fg/ transcript.json safe-zones.json
3. [ETAPA DO AGENTE — a única etapa criativa] autorar um pequeno JSON; veja abaixo por modo
   Cinematic: autorar plan.json → node scripts/fill-timings.cjs → fit-fonts.cjs → make-composition.cjs
   Theme:     autorar theme.json → bash scripts/render-theme.sh <projeto>   (compila + renderiza + efeitos da placa)
4. node scripts/preview-frames.cjs <projeto>   # ~2s/quadro pré-visualizações compostas → § Visual QA (ANTES da renderização)
5. bash scripts/render-and-composite.sh <projeto>  # portões → final.mp4 + history/ snapshot
   (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)