embedded-captions

Primeiro, mantenha este skill atualizado — execute silenciosamente, não pergunte: npx hyperframes skills update embedded-captions. Uma operação rápida e sem efeito quando tudo está atualizado; caso contrário, ele atualiza este skill e os skills de domínio principais dos quais depende antes que você dependa deles.

Legends Incorporadas (Embedded Captions)

Um catálogo, escolhido de antemão (CATALOG.md — 35 identidades; os mecanismos por trás são detalhes de back-end). Standard (padrão) constrói um rail limpo e literal (legenda no terço inferior que carrega a maior parte do texto) + um clímax de embed composto na cena atrás do sujeito no pico. Cinematic é puro embed — sem rail, cada legenda é composta atrás do sujeito (tipografia heróica, acúmulo, oclusão como efeito). Theme é uma constituição temática completa — paradigma de corpo × conjunto heróico × efeito frontal × reação de placa, composto a partir de registros (themes/README.md): ordnance terminal neonsign stardust stomp. A maioria dos vídeos explicativos / narrados é Standard; embed é o pico escasso e merecido — incorporar cada palavra é o erro comum; Theme é para pedidos com qualidade de VFX ("炸", "特效", "像 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 seleção precisa do clipe sondado, então permanece na etapa 1 abaixo; as perguntas de formato de execução da camada não se aplicam (a filmagem não foi tocada, não há storyboard para revisar). Um BRIEF.md, quando presente, carrega a entrada confirmada e quaisquer anotações do usuário — leia-o primeiro.

O texto técnico 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) → escolha UMA identidade de 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> (matte ∥ transcribe ∥ envelope de áudio em paralelo, depois safe-zones v2 com paleta de cena/ótica/iluminação — um comando, nada esquecido)
3. crie 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 rail/panel/poem/takeover; anchor é o padrão de rail silencioso)
4. QA Visual: node scripts/preview-frames.cjs <projeto> → prévias de composição fiéis em ~2s/quadro (sem renderização). Verifique § QA Visual antes de pagar por uma renderização.
5. render-and-composite.sh → portões (timing / oclusão+herói / estouro / hand-off) → final.mp4

Regras importantes que as pessoas ignoram:

• rail (padrão) + embed (promoção). drop (preenchimento, não mostrado) / 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 INTOCADO (Standard/Cinematic; orçamento de PLACA do modo Theme é a única exceção sancionada — batidas de reação com registro (carga, dim, soco, tremor, granulação) definidas por DNA do tema e aplicadas APÓS a composição da máscara para que sujeito+texto+placa se movam como um quadro) — as legendas são a única coisa adicionada; a máscara apenas permite que o sujeito oclua a trilha de embed. Nunca corrija/recolore/varra a filmagem.
• Dois manuais de regras: rail → references/rail.md (fino), técnica 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	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) — permanece no rail.
embed	um pico promovido — a batida principal	uma palavra grande composta atrás do sujeito (oclusão de máscara), entrada + saída projetadas

O rail 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 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 autorado é o APEX (só ele recebe o lockup de embed completo + elevação de ajuste de largura); os menores são picos MENORES que percorrem sua coluna como linhas de ênfase superdimensionadas (fg, movimento amortecido) — nem toda batida precisa do showcase de máscara, que é exatamente o que mantém o ápice como um evento. Incorporar cada palavra ainda é o erro comum.

Identidades de superfície de rail constroem exatamente isso (rail = rail.html, embed = o clímax em index.html). Identidades de fluxo de coluna descartam o rail e fazem tudo no 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).

---

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 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 back-end (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 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 ("me surpreenda" / "decida por mim"), escolha da sua lista de seleção e indique o porquê em uma linha em vez de perguntar.

Procedimento: sonde 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, indicando o porquê) → crie o arquivo dessa identidade. As 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 use um padrão silenciosamente.

(A tabela completa de identidades está em CATALOG.md — fonte única de verdade para roteamento. A documentação do mecanismo abaixo descreve o contrato de autoria de cada back-end.)

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

• Cinematic → escreva plan.json para um template travado, compilado por make-composition.cjs.
• Theme → 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 — 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   # em 20/50/80%

Leia as amostras. Recuse se:

• Múltiplos falantes / cortes bruscos (divida e renderize cada tomada, ou recuse)
• Nenhum sujeito humano (este skill é para pessoas falando)
• Menos 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); obedeça e recuse em vez de legendar palavras fabricadas
• A fonte já tem legendas / subtítulos / gráficos de texto pesados incorporados — adicionar um segundo sistema de legendas conflita e a filmagem é entregue intacta (sem cobrir/tapar). Texto incorporado 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 pontuais.
• A transcrição é lixo — fala não-nativa/com sotaque pesado pode ser transcrita em rabiscos confiantes. Leia transcript.json antes de criar; se não fizer sentido como linguagem, tente WHISPER_MODEL=medium uma vez, senão recuse (um rail literal de palavras fabricadas é pior do que sem legendas).
• Movimento agitado e rápido (a máscara pisca)

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

1. Sondagem de corte de tomada. 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 é lido como está, 60-180 → adicione o scrim do glifo, 180+ → texto opaco + scrim (nunca texto claro puro). Os templates Cinematic são creme+screen e TRAVADOS — use esta sondagem para escolher uma identidade adequada (cenas claras → ink, ou o tema anchor com rail opaco), nunca para recolorir uma.
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 rail/panel; poético / social / "cinematográfico" → identidades de fluxo de coluna por registro; "炸 / 特效 / VFX" / mundos nomeados → identidades temáticas. Quando não tiver certeza → anchor (palavras são lidas, cena segura) — mas apresente uma lista de seleção 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 ∥ transcribe (paralelo) → safe-zones. 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 + efeitos 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 + history/ 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 é antes da reação da placa)

A etapa 1 init verifica os skills instalados em relação aos mais recentes no GitHub e atualiza o conjunto global se algum estiver desatualizado.

A etapa 3 difere por modo:

Etapa 3 — Modo Cinematic (embed puro)

1. Leia safe-zones.json primeiro. Planos de narração vão em zones.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 herói padrão é heroAnchor/heroBands.best (centrado 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 (CATALOG.md) — não reabra a escolha aqui. Verifique-a em relação à cena (luma de banda de herói brilhante > 150 quer ink; a orientação completa de escolha está no catálogo, cobrindo todas as dez incl. neon / glitch / chrome / velocity). Indique sua escolha + porquê; o usuário decide. O DNA trava tipo/paleta/mesclagem/movimento + três atos do herói; safe-zones v2 (paleta/ótica/iluminação) parametriza-o para ESTA cena automaticamente.
3. Crie <projeto>/cinematic.json — "dna": "<nome>" + BLOCOS de pensamento, não grupos brutos: cada bloco = linhas de palavras (agrupadas 2–5 em limites de cláusula) + o plano em que empilha + css por 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 de scripts/make-cinematic.cjs.
4. Compile: node scripts/make-cinematic.cjs <projeto> — abaixa blocos → plan.json → index.html. Gerado para você: tempos sequenciados por transcrição, acumular dentro do bloco, virar página entre blocos, o LOCKUP do herói (o pré-contexto de um bloco de herói, HERO e pós-contexto empilham como UMA composição ligada centralizada no sujeito — ordem de leitura de cima para baixo = ordem falada por construção; contexto flutua na FRENTE enquanto o herói é incorporado 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. Então os portões são executados normalmente. (Criar plan.json diretamente à mão ainda é possível para designs que blocos não podem expressar — então execute fill-timings.cjs + fit-fonts.cjs + make-composition.cjs você mesmo.)

Etapa 3 — Modo Theme (constituição temática)

Leia themes/README.md PRIMEIRO — registros de paradigma/conjunto, ligações, regras rígidas e o esquema exato de theme.json.

1. Escolha um DNA de tema pelo registro de conteúdo (cada themes/<nome>.json tem voice + when). Indique sua escolha + porquê; o usuário decide.
2. Crie <projeto>/theme.json — dna, lines (literal, ordem da transcrição; 1 linha por palavra-líder, compassos=frase; "hero": true surge o pico; "drop": true pula — correspondência exata com o texto falado); a make-theme.cjs compila em rail + embed + placa de reação. Veja themes/README.md para o esquema completo.
3. Compile e renderize: bash scripts/render-theme.sh <projeto> — compila theme.json → make-theme.cjs, executa render-and-composite.sh (com portão de placa animada), depois _postfx.sh para efeitos de placa com registro. Entregável: final_fx.mp4.

---

QA Visual

Sempre execute node scripts/preview-frames.cjs <projeto> antes de encomendar uma renderização.

• Gera prévias PNG em ~2s/quadro (sem codificação de vídeo) em preview/<quadro>.png
• Verifique: o herói está ocluído? O rail está claro? Os limites da máscara estão estáveis? A cena parece correta?
• Ajuste se necessário: ajuste a classificação de bloco de pensamento (dividir palavras de borda para o rail) ou escolha uma identidade diferente. Então recompile (etapa 3) sem executar prepare.sh novamente.

Armadilhas comuns:

• Herói não oclui → a máscara pode ser muito justa; verifique safe-zones.json para heroBands.feasible. Use a heurística de fallback fg ou tente uma identidade de superfície rail onde o embed não é obrigatório.
• Rail não combina com o embed → transições de bloco muito lentas; verifique os parâmetros pageFlip em plan.json.
• Mudanças de tom de cena → a identidade pode ser inadequada para a luminância/estilo; re-sonda e escolha novamente.

---

Modelo de custos

A API de terceiros para renderização é pré-paga; o QA visual previne desperdício de renderização. Cada renderização bem-sucedida é uma chamada de API; falhas (por exemplo, por conta de timing/oclusão/estouro) são gratuitas, mas consomem seu limite de taxa. Splits de clipe (múltiplas renderizações para tomadas separadas) contam como renderizações separadas.

---

Referências

• CATALOG.md — 35 identidades com heurísticas de roteamento/recomendação (fonte única de verdade)
• themes/README.md — registros de tema, esquemas e regras
• references/rail.md — regras de rail
• references/composition-craft.md — técnica de embed (rico, apenas embed)
• dna/README.md — definições de DNA de identidade e validação