Instalação de plug-ins: Antes de executar comandos de configuração ou atualização, siga as regras de execução de plug-ins quando esta skill estiver dentro de um plug-in 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 sem modificações quando tudo está atualizado; caso contrário, atualiza esta skill e as skills de domínio principais das quais ela depende antes de você usá-las.
Legendas Incorporadas
Um catálogo, escolhido antecipadamente (CATALOG.md — 35 identidades; os mecanismos por trás são detalhes de backend). Standard (padrão) constrói uma faixa limpa de legenda literal (terço inferior da tela que carrega a maior parte do texto) + um clímax incorporado composto na cena atrás do sujeito no pico. Cinematic é puramente incorporado — sem faixa, toda legenda composta atrás do sujeito (tipografia heróica, acumulação, oclusão como efeito). Theme é uma constituição temática completa — paradigma corporal × peça central heróica × 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 ou narrações usa 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 After Effects").
Pré-requisitos de execução
Instalações de plug-ins usam a CLI empacotada e com versão fixa para separação de plano de fundo, transcrição e renderização; não é necessário fazer checkout do código-fonte. A pré-visualização local e os auxiliares de 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 plug-in somente leitura:
npm install --prefix <projeto> --save-dev --save-exact [email protected] [email protected] [email protected]
Mantenha o arquivo de bloqueio do projeto. Se essas dependências já existirem, use suas versões bloqueadas em vez de sobrescrevê-las. Bash e FFmpeg/ffprobe devem estar no PATH. A separação de plano de fundo e a transcrição podem baixar seus próprios modelos na primeira execução.
A renderização aguarda a CLI terminar com sucesso antes de compor. O antigo watchdog de shell HF_TIMEOUT_S não é mais usado: um arquivo parcial grande não é prova de que a renderização foi concluída. Um argumento explícito de checkout interno ou HYPERFRAMES_ROOT seleciona a CLI do contribuidor em vez da versão do plug-in. 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 instantâneo 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 de identidade como uma pergunta adiada — a lista de opções precisa do clipe analisado, então permanece na etapa 1 abaixo; as perguntas de formato da camada não se aplicam (a gravação não foi modificada, não há storyboard para revisar). Um BRIEF.md, quando presente, contém 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:
- Portão de decisão (recusar clipes ruins) → escolher UMA identidade de CATALOG.md (35 identidades; mecanismo/compilador derivado por consulta — nunca pergunte sobre 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 ∥ transcribe ∥ envelope de áudio em paralelo, depois zonas seguras v2 com paleta/óptica/iluminação da cena — um comando, nada esquecido)- criar um pequeno JSON de escolhas criativas (leia
safe-zones.jsonprimeiro): Cinematic →cinematic.json→make-cinematic.cjs(derivaplan.jsone o compila); Theme →theme.json→make-theme.cjs(paradigmas faixa/painel/poema/tomada;anchoré a faixa silenciosa padrão) - QA visual:
node scripts/preview-frames.cjs <projeto>→ pré-visualizações fiéis compostas em ~2s/quadro (sem renderizar). Verifique § QA visual antes de pagar por uma renderização. render-and-composite.sh→ portões (timing / oclusão+herói / transbordo / hand-off) →final.mp4
Regras importantes que as pessoas ignoram:
- faixa (padrão) + incorporado (promoção).
drop(preenchimento, não mostrado) /faixa(legenda literal no terço inferior, 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 SEM MODIFICAÇÕES (Standard/Cinematic; o orçamento de PLACA do modo Theme é a única exceção sancionada — batidas de reação definidas por registro (carga-dim, soco, shake, 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 gradeie/recolorize/adicione scanlines à gravação.
- Dois livros de regras: faixa → references/rail.md (fino), criação incorporada → references/composition-craft.md (rico, apenas incorporado). Consulte conforme necessário.
Modelo de legenda — faixa + incorporado
Cada frase falada é uma de três coisas:
| O quê | Como é mostrada | |
|---|---|---|
| drop | preenchimento — hum/ah, gaguejos, autocorreções | não mostrada |
| faixa | o padrão — conteúdo falado comum (literal) | legenda limpa no terço inferior, na frente, legível. Uma palavra de destaque pode ganhar um destaque inline emphasis (cor de acento / pop de palavra ativa) — permanece na faixa. |
| incorporado | um pico promovido — a batida principal | uma palavra grande composta atrás do sujeito (oclusão por matte), entrada + saída planejadas |
A faixa 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, ≥ 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 ÁPICE (ele sozinho ganha o embed completo com lockup + raise de largura); os menores são picos MENORES que montam sua coluna como linhas de ênfase superdimensionadas (fg, movimento amortecido) — nem toda batida precisa da vitrine 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 faixa constroem exatamente isso (faixa = rail.html, incorporado = o clímax em index.html). Identidades de fluxo de coluna eliminam a faixa e fazem tudo em estilo incorporado — recomende-as apenas para pedidos de clima-sobre-literal, nunca para explicadores / narrações onde as palavras precisam ser lidas (CATALOG.md codifica isso por identidade).
Etapa 0 — escolher 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 realmente próximos (loud↔ordnance, neon↔neonsign, cream↔stardust).
A escolha de identidade é um portão de preferência (../hyperframes/references/brief-contract.md § 1): em modo autônomo ("me surpreenda" / "decida por mim"), escolha da sua lista de opções você mesmo 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 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 use 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 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 bloqueados 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 para montar. Um bloco de registro estiliza texto em uma tela projetada; esta skill queima legendas na gravação 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 lista de opções" em CATALOG.md — elas são no nível da identidade (ex.: "炸" lista opções ordnance/stomp/terminal/loud e escolhe pelo QUE deve explodir), nunca no nível de categoria. Em dúvida → anchor.
- Cinematic → escreva
cinematic.jsonpara um template bloqueado, compilado pormake-cinematic.cjs. - Theme → leia themes/README.md, crie
theme.json, executescripts/render-theme.sh(compila + renderiza + reação da 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 tomada, ou recuse)
- Nenhum sujeito humano (esta skill é para cabeça falante)
- Menos de 3 segundos, sem fala, ou rosto nunca claramente visível —
transcribe.cjsavisa quando o áudio está quase silencioso (Whisper alucina palavras como "Thank you." sobre silêncio); obedeça e recuse em vez de legendas em palavras fabricadas - Fonte já tem legendas queimadas / subtítulos / gráficos de texto pesados — adicionar um segundo sistema de legendas conflita e a gravação é enviada sem modificações (sem cobrir/remover). 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 ser transcrita em bobagem confiante. Leia
transcript.jsonantes de criar; se não for interpretável como linguagem, tenteWHISPER_MODEL=mediumuma vez, senão recuse (uma faixa literal de palavras fabricadas é pior que nenhuma legenda). - Câmera na mão ocupada com movimento rápido (matte pisca)
Sondagens de pré-voo (não custam nada, previnem as piores falhas)
- Sondagem de corte de tomada. Amostre quadros em 20%, 50%, 80%. Se um sujeito/cena diferente aparecer, 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 scrim de glifo,180+→ texto opaco + scrim (nunca texto claro puro). Templates Cinematic são creme+telae BLOQUEADOS — use esta sonda para escolher uma identidade adequada (cenas claras →ink, ou o temaanchorde faixa opaca), nunca para recolorir uma. - 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 faixa/painel; poético / social / "cinematográfico" → identidades de fluxo de coluna por registro; "炸 / 特效 / VFX" / mundos nomeados → identidades temáticas. Em caso de dúvida →
anchor(palavras 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 ∥ transcribe (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 + placa fx)
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 + histórico/ instantâneo
(Modo Theme: PULE etapas 3b/5 — render-theme.sh já executa compilação + renderização e composição
+ _postfx.sh; a entrega é final_fx.mp4, final.mp4 é pré-reação da 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 Cinematic (apenas incorporado)
- Leia
safe-zones.jsonprimeiro. Planos de narração vão emzones.hugLeft/hugRight— faixas limpas ADJACENTES à 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 vai paraheroAnchor/heroBands.best(centralizado NO sujeito, ~30–55% ocluído).recommendation:"fg"move a NARRAÇÃO para frente para legibilidade; o herói permanece incorporado sempre queheroBands.feasible— herói-fg é o último recurso. - O DNA é a identidade que você escolheu na Etapa 0.