embedded-captions (Legendas Incorporadas)

Instalação de plugins: Antes de comandos de configuração ou atualização, siga as regras de execução de plugins quando esta skill estiver dentro de um plugin HyperFrames. Instalações independentes mantêm as instruções de atualização abaixo.

Primeiro, mantenha esta skill atualizada — confirme com o usuário antes de executar: npx hyperframes skills update embedded-captions. Uma operação rápida e sem efeitos quando tudo está atualizado; caso contrário, atualiza esta skill junto com as skills do domínio principal das quais ela depende, antes que você dependa delas.

Legendas Incorporadas

Um catálogo, escolhido antecipadamente (CATALOG.md — 35 identidades; os mecanismos por trás dele são detalhes de implementação). Padrão (padrão) constrói uma barra limpa e literal (legenda inferior que carrega a maior parte do texto) + um clímax incorporado composto na 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 heróica × 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ção é Padrão; o incorporado é o pico escasso e merecido — incorporar cada palavra é o erro comum; Tema é para pedidos com efeitos VGCF ("炸", "特效", "像 AE 做的").

---

Pré-requisitos de execução

Instalações de plugin usam a CLI agrupada e fixada pelo manifesto para remoção de fundo, transcrição e renderização; nenhum checkout do código-fonte é necessário. Os ajudantes de pré-visualização local e medição de legendas também precisam de Sharp, Puppeteer (com seu navegador Chromium) e GSAP. Instale estes no projeto de legendas, não dentro do plugin somente leitura:

npm install --prefix <projeto> --save-dev --save-exact [email protected] [email protected] [email protected]

Mantenha o arquivo de lock do projeto. Se essas dependências já existirem, use suas versões travadas em vez de sobrescrevê-las. Bash e FFmpeg/ffprobe devem estar no PATH. A remoção de fundo e a transcrição podem baixar seus próprios modelos no primeiro uso.

A renderização aguarda a CLI terminar com sucesso antes de compor. O antigo watchdog HF_TIMEOUT_S não é mais usado: um arquivo parcial grande não é prova de que a renderização terminou. Um argumento --built-checkout explícito ou HYPERFRAMES_ROOT seleciona a CLI do contribuidor em vez do pino do plugin. Cancele uma renderização travada normalmente através da CLI/terminal; o ajudante de legendas não finaliza à força nem recupera uma renderização a partir de um snapshot do processo.

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 selecionados precisa do clipe sondado, então ela permanece na etapa 1 abaixo; as perguntas de formato de execução da camada não se aplicam (a filmagem não é tocada, não há storyboard para revisar). Um BRIEF.md, quando presente, carrega a entrada confirmada e quaisquer notas do usuário — leia-o primeiro.

A prosa artesanal abaixo é longa; o pipeline em si é curto — e tudo o que é determinístico é calculado ou compilado, nunca escrito à mão:

1. Portão de decisão (recusar clipes ruins) → escolha UMA identidade do CATALOG.md (35 identidades; mecanismo/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> (remoção de fundo ∥ transcrição ∥ envelope de áudio em paralelo, depois zonas seguras v2 com paleta de cena/óptica/iluminação — um comando, nada esquecido)
3. crie um pequeno JSON de escolhas criativas (leia safe-zones.json primeiro): Cinematográfico → cinematic.json → make-cinematic.cjs (deriva plan.json e o compila); Tema → theme.json → make-theme.cjs (paradigmas barra/painel/poema/apropriação; anchor é o padrão silencioso para barra)
4. QA Visual: node scripts/preview-frames.cjs <projeto> → pré-visualizações compostas fiéis em ~2s/quadro (sem renderizar). Consulte § QA Visual antes de pagar por uma renderização.
5. render-and-composite.sh → portões (timing / oclusão+herói / transbordo / hand-off) → final.mp4

Regras importantes que as pessoas perdem:

• barra (padrão) + incorporado (promoção). drop (preenchimento, não mostrado) / barra (legenda inferior literal, na frente, carrega a maior parte do texto) / incorporado (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 PLATE do modo Tema é a única exceção sancionada — batidas de reação com registro (dim, soco, tremor, grão) definidas por DNA do tema e aplicadas APÓS a composição do 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 incorporada. Nunca grade/recolora/scaline a filmagem.
• Dois livros de regras: barra → references/rail.md (fino), arte de incorporação → references/composition-craft.md (rico, apenas incorporado). Folheie conforme necessário.

---

Modelo de legenda — barra + incorporado

Cada frase falada é uma de três coisas:

	O quê	Como é mostrada
drop	preenchimento — hum/ah, gaguejos, autocorreções	não mostrado
barra	o padrão — conteúdo falado comum (literal)	legenda inferior limpa, na frente, legível. Uma palavra marcante pode ter um destaque emphasis inline (cor de destaque / pop de palavra ativa) — ela permanece na barra.
incorporado	um pico promovido — a batida do título	uma palavra grande composta atrás do sujeito (oclusão do mate), entrada + saída projetada

A barra carrega a maior parte do texto; o incorporado é o pico escasso e merecido. A 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ói (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 APEX (apenas ele recebe o bloco de incorporação completo + elevação de ajuste 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 da vitrine do mate, que é exatamente o que mantém o apex como um evento. Incorporar cada palavra ainda é o erro comum.

Identidades de superfície de barra constroem exatamente isso (barra = rail.html, incorporado = o clímax em index.html). Identidades de fluxo de coluna abandonam a barra e tornam tudo 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 mecanismos internos. O usuário escolhe uma IDENTIDADE do 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 "Padrão vs Cinematográfico vs Tema" 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): no modo autônomo ("surpreenda-me" / "decida por mim"), escolha da sua lista de selecionados você mesmo e declare o porquê em uma linha em vez de perguntar.

Procedimento: sonde o clipe → lista de 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. Identidades são travadas 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 um padrão silenciosamente.

(A tabela de identidades completa está em CATALOG.md — fonte única da verdade para roteamento. Os documentos de mecanismo abaixo descrevem o contrato de criação de cada backend.)

CATALOG.md é todo o espaço de resposta aqui: este fluxo de trabalho não pesquisa o registro de componentes do HyperFrames. Os fluxos de trabalho 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 — os blocos caption-* incluídos — não tem nada em que montar. Um bloco de registro estiliza texto em uma tela projetada; esta skill queima legendas na filmagem de alguém através de um mate. Quando nenhuma identidade se encaixa no pedido, diga isso e escolha a mais próxima, em vez de ir além do catálogo.

Heurística de recomendação: use as "Heurísticas de lista de selecionados" em CATALOG.md — elas são no nível de identidade (por exemplo, "炸" lista selecionados ordnance/stomp/terminal/loud e escolhe pelo QUE deve explodir), nunca no nível de categoria. Em dúvida → anchor.

• Cinematográfico → escreva cinematic.json para um modelo travado, compilado por make-cinematic.cjs.
• Tema → leia themes/README.md, crie theme.json, execute scripts/render-theme.sh (compila + renderiza + reação de 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 (renderize cada tomada separadamente, ou recuse)
• Nenhum sujeito humano (esta skill é para cabeça falante)
• Abaixo de 3 segundos, sem fala, ou rosto nunca claramente visível — transcribe.cjs avisa quando o áudio está quase silencioso (Whisper alucina palavras como "Obrigado." sobre o silêncio); preste atenção e recuse em vez de legendas de palavras fabricadas
• Fonte já tem legendas queimadas / subtítulos / gráficos de texto pesados — adicionar um segundo sistema de legendas conflita e a filmagem é entregue intocada (sem cobrir/inpaint). Texto queimado muitas vezes 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.
• Transcrição é lixo — fala não-nativa / com sotaque pesado pode transcrever em rabiscos confiantes. Leia transcript.json para verificar a sanidade antes de criar; se não for interpretável como idioma, tente WHISPER_MODEL=medium uma vez, caso contrário recuse (uma barra literal de palavras fabricadas é pior do que sem legendas).
• Câmera na mão agitada com movimento rápido (mate pisca)

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

1. Sondagem de corte de tomada. Amostre quadros em 20%, 50%, 80%. Se um sujeito/cena diferente aparecer, corte 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 lê como está, 60-180 → adicione o scrim de glifo, 180+ → texto opaco + scrim (nunca texto claro nu). Modelos cinematográficos são cream+screen e TRAVADOS — use esta sonda para escolher uma identidade adequada (cenas claras → ink, ou o tema anchor de barra opaca), 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 devem ser lidas → identidades de superfície de barra/painel; poético / social / "cinematográfico" → identidades de fluxo de coluna por registro; "炸 / 特效 / VFX" / mundos nomeados → identidades temáticas. Quando em dúvida → anchor (palavras lidas, cena segura) — mas apresente uma lista de selecionados 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>       # mate ∥ 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
   Cinematográfico: crie cinematic.json → node scripts/make-cinematic.cjs <projeto>
   Tema:            crie theme.json → bash scripts/render-theme.sh <projeto>   (compila + renderiza + efeitos de 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 + snapshot history/
   (Modo Tema: PULE as etapas 3b/5 — render-theme.sh já executa compile + render-and-composite
    + _postfx.sh; o entregável é final_fx.mp4, final.mp4 é pré-reação de placa)

A etapa 1 init verifica as skills instaladas em relação às mais recentes no GitHub e atualiza o conjunto global se alguma estiver desatualizada.

A etapa 3 difere por modo:

Etapa 3 — Modo Cinematográfico (puramente incorporado)

1. Leia safe-zones.json primeiro. Planos de narração vão em zones.hugLeft/hugRight — faixas limpas JUSTAPOSTAS à silhueta (texto longe do corpo lê como flutuante, não incorporado; cantos distantes são o fallback, não o padrão). O herói assume o padrão heroAnchor/heroBands.best (centralizado NO sujeito, ~30–55% ocluído). recommendation:"fg" move a NARRAÇÃO para a frente para legibilidade; o herói permanece incorporado sempre que heroBands.feasible — herói-fg é o último recurso.
2. O DNA é a identidade que você escolheu na Etapa 0.