Instalação de plugins: Antes de executar comandos de configuração ou atualização, siga as regras de instalação de plugins quando este skill estiver dentro de um plugin HyperFrames. Instalações independentes mantenham as instruções de atualização abaixo.

Primeiro, mantenha este skill atualizado — confirme com o usuário antes de executar: npx hyperframes skills update embedded-captions. Uma operação rápida sem efeito quando tudo está atualizado; caso contrário, ele atualiza este skill e os skills de domínio principal dos quais depende antes de você usá-los.

Legendas Embutidas

Um catálogo, escolhido antecipadamente (CATALOG.md — 35 identidades; os mecanismos por trás disso são detalhes de backend). Standard (padrão) constrói um trilho limpo e literal (legenda inferior que carrega a maior parte do texto) + um clímax embed composto na cena atrás do sujeito no pico. Cinematic é puro embed — sem trilho, cada legenda composta atrás do sujeito (tipografia heroica, acúmulo, oclusão como efeito). Theme é uma constituição temática completa — paradigma do corpo × peça central 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 usa Standard; o 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").

Pré-requisitos de execução

Instalações de plugin usam a CLI empacotada e com versão fixa para matting, transcrição e renderização; não é necessário fazer checkout do código-fonte. Os auxiliares de pré-visualização local e medição de legendas também precisam de Sharp, Puppeteer (com seu navegador Chromium) e GSAP. Instale-os 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. Matting e transcrição podem baixar seus próprios modelos no primeiro uso.

A renderização aguarda a saída bem-sucedida da CLI antes de compor. O antigo watchdog de shell HF_TIMEOUT_S não é mais usado: um arquivo parcial grande não prova que a renderização terminou. Um argumento explícito de built-checkout ou HYPERFRAMES_ROOT seleciona a CLI do contribuidor em vez da versão fixa do plugin. Cancele uma renderização travada normalmente através da CLI/terminal; o auxiliar de legendas não força a interrupção nem recupera uma renderização de um snapshot de 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 opções precisa do clipe analisado, então ela permanece na etapa 1 abaixo; as perguntas de forma 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.

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.cjs adotam 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/óptica/iluminação da cena — um comando, nada esquecido)
crie um pequeno JSON de escolhas criativas (leia safe-zones.json primeiro): Cinematic → cinematic.json → make-cinematic.cjs (deriva plan.json e o compila); Theme → theme.json → make-theme.cjs (paradigmas de trilho/painel/poema/tomada; anchor é o trilho padrão silencioso)
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 (temporização / oclusão+herói / estouro / entrega) → final.mp4

Regras importantes que as pessoas perdem:

trilho (padrão) + embed (promoção). drop (preenchimento, não mostrado) / trilho (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, incorporando apenas o(s) pico(s). Veja § Modelo de legenda.
O vídeo é entregue SEM ALTERAÇÕES (Standard/Cinematic; o orçamento de PLACA do modo Theme é a única exceção sancionada — batidas de reação registradas (charge-dim, punch, shake, grain) 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 de embed. Nunca gradere/recollora/adicione scanline na filmagem.
Dois livros de regras: trilho → references/rail.md (fino), criação de embed → references/composition-craft.md (rico, apenas embed). Folheie conforme necessário.

Modelo de legenda — trilho + embed

Cada frase falada é uma de três coisas:

	O quê	Como é mostrada
drop	preenchimento — hum/uh, gaguejos, autocorreções	não mostrada
trilho	o padrão — conteúdo falado comum (literal)	legenda inferior limpa, na frente, legível. Uma palavra de destaque pode ganhar um destaque `emphasis` inline (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; o 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 vídeo explicativo longo → ~um por seção. Entre vários heróis, o maior criado é o ÁPICE (só ele recebe o embed de lockup completo + aumento 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 do showcase do matte, que é exatamente o que mantém o ápice como um evento. Incorporar cada palavra ainda é o erro comum.

Identidades de superfície de trilho constroem exatamente isso (trilho = trilho.html, embed = o clímax em index.html). Identidades de fluxo de coluna descartam o trilho e fazem tudo no estilo embed — recomende-as apenas para pedidos de clima sobre literal, nunca para vídeos explicativos / 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 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 os pares genuinamente 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 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. 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 completa de identidades está em CATALOG.md — fonte única de verdade para roteamento. Os documentos do mecanismo abaixo descrevem o contrato de autoria 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 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 onde montar. Um bloco de registro estiliza texto em uma tela projetada; este skill grava legendas na filmagem de alguém através de um matte. Quando nenhuma identidade se encaixar no pedido, diga isso e escolha a mais próxima, em vez de recorrer fora do catálogo.

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

Cinematic → escreva cinematic.json para um template travado, compilado por make-cinematic.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 — 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 plano, ou recuse)
Nenhum sujeito humano (este skill é para talking-head)
Menos de 3 segundos, sem fala, ou rosto nunca claramente visível — transcribe.cjs avisa quando o áudio está próximo do silêncio (Whisper alucina palavras como "Thank you." sobre o silêncio); preste atenção e recuse em vez de legendar palavras fabricadas
A fonte já tem legendas queimadas / subtítulos / gráficos de texto pesados — adicionar um segundo sistema de legendas causa conflito e a filmagem é enviada intocada (sem cobrir/retocar). Texto queimado muitas vezes 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 amostra.
A transcrição é lixo — fala não nativa/com sotaque pesado pode ser transcrita em rabisco confiante. Faça uma leitura de sanidade do transcript.json antes de criar; se não fizer sentido como linguagem, tente WHISPER_MODEL=medium uma vez, senão recuse (um trilho literal de palavras fabricadas é pior do que sem legendas).
Câmera na mão ocupada com movimento rápido (matte pisca)

Verificações pré-voo (não custam nada, previnem as piores falhas)

Verificação de corte de plano. Amostre quadros em 20%, 50%, 80%. Se um sujeito/cena diferente aparecer, apare o clipe antes do corte.
Verificação de letterbox / pillarbox. Barras pretas no primeiro quadro? Calcule o retângulo de conteúdo seguro e restrinja o posicionamento das legendas dentro dele.
Verificação 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 do glifo, 180+ → texto opaco + scrim (nunca texto claro puro). Templates Cinematic são cream+screen e TRAVADOS — use esta verificação para escolher uma identidade adequada (cenas claras → ink, ou o tema anchor com trilho opaco), nunca para recolorir uma.
Recomendação de identidade por tom (você recomenda; o usuário escolhe — veja Etapa 0 + CATALOG.md). explicativo / entrevista / palavras devem ser lidas → identidades de superfície de trilho/painel; poético / mídia social / "cinematográfico" → identidades de fluxo de coluna por registro; "炸 / 特效 / VFX" / mundos nomeados → identidades temáticas. Na dúvida → anchor (palavras são lidas, cena segura) — mas apresente uma lista de opções 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) → 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 cinematic.json → node scripts/make-cinematic.cjs <projeto>
   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é-visualizações compostas → § QA Visual (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 compilar + render-and-composite
    + _postfx.sh; a entrega é final_fx.mp4, final.mp4 é pré-reação de placa)

O init da etapa 1 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)

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 embutido; cantos distantes são o plano de fallback, não o padrão). O herói padrão vai para 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 embutido sempre que heroBands.feasible — herói-fg é o último recurso.
O DNA é a identidade que você escolheu na Etapa 0

…

[truncado para tradução]

kinyias/hyperframes-templates

O que é hyperframes-templates?

Perguntar na sua IA favorita

Documentação