Instalação do Plugin: Antes dos comandos de configuração ou atualização, siga as regras de execução do plugin 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 quando tudo está atualizado; caso contrário, ela atualiza esta skill e as skills de domínio principal das quais ela depende antes de você usá-las.
Legendas Embutidas (Embedded Captions)
Um catálogo, escolhido no início (CATALOG.md — 35 identidades; os mecanismos por trás disso são detalhes de backend). Standard (padrão) constrói uma faixa limpa e literal (legenda inferior que carrega a maior parte do texto) + um clímax embutido composto dentro da cena atrás do sujeito no pico. Cinematic é puramente embutido — sem faixa, cada legenda composta atrás do sujeito (tipografia de herói, acúmulo, oclusão como efeito). Theme é uma constituição temática completa — paradigma corporal × peça central herói × efeito frontal × reação de placa, composta a partir de registros (themes/README.md): ordnance terminal neonsign stardust stomp. A maioria das explicações / narrações é Standard; o embutido é o pico escasso e merecido — embutir cada palavra é o erro comum; Theme é para pedidos de nível VFX ("炸", "特效", "像 AE 做的").
Pré-requisitos de execução
Instalações de plugin usam a CLI fornecida e com versão fixa para matte, transcrição e renderização; não é necessário checkout do código-fonte. A pré-visualização local e as ferramentas de medição de legenda também precisam de Sharp, Puppeteer (com seu navegador Chromium) e GSAP. Instale-os no projeto de legenda, não dentro do plugin somente leitura:
npm install --prefix <project> --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. Matte e transcrição podem baixar seus próprios modelos na primeira execução.
A renderização espera a CLI sair com sucesso antes da composição. 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 explícito de checkout ou HYPERFRAMES_ROOT seleciona a CLI do contribuidor em vez do plugin. Cancele uma renderização travada normalmente através da CLI/terminal; o auxiliar de legenda não força a parada nem recupera uma renderização a partir 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 selecionados 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 está intocada, 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 é computado ou compilado, nunca escrito manualmente:
- 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.cjsadotam qualquer vídeo no diretório como source.mp4) →bash scripts/prepare.sh <project>(matte ∥ transcribe ∥ envelope de áudio em paralelo, depois safe-zones v2 com paleta de cena/óptica/iluminação — um comando, nada esquecido)- crie 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 de faixa/painel/poema/tomada de controle;anchoré o padrão de faixa silenciosa) - QA Visual:
node scripts/preview-frames.cjs <project>→ pré-visualizações fiéis da composição em ~2s/quadro (sem renderização). Consulte § QA Visual antes de pagar por uma renderização. render-and-composite.sh→ portões (timing / oclusão+herói / estouro / hand-off) →final.mp4
Regras importantes que as pessoas ignoram:
- faixa (padrão) + embutido (promoção).
drop(preenchimento, não exibido) /rail(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, embutindo apenas o(s) pico(s). Veja § Modelo de legenda. - O vídeo é entregue INTOCADO (Standard/Cinematic; o orçamento PLATE do modo Theme é a única exceção sancionada — batidas de reação definidas por registro (carga-dim, soco, trepidação, granulação) definidas por DNA do tema e aplicadas APÓS a composição do matte para que sujeito+texto+plate se movam como um quadro) — legendas são a única coisa adicionada; o matte apenas permite que o sujeito oclua a trilha embutida. Nunca gradear/recolorir/escandir a filmagem.
- Dois livros de regras: faixa → references/rail.md (fino), arte de embutir → references/composition-craft.md (rico, apenas embutido). Folheie conforme a necessidade.
Modelo de legenda — faixa + embutido
Cada frase falada é uma de três coisas:
| O quê | Como é mostrado | |
|---|---|---|
| drop | preenchimento — hum/ah, gaguejos, autocorreções | não mostrado |
| rail | o padrão — conteúdo falado comum (literal) | legenda inferior limpa, na frente, legível. Uma palavra de destaque pode receber um realce emphasis inline (cor de destaque / pop de palavra ativa) — ela permanece na faixa. |
| embed | um pico promovido — a batida principal | uma palavra grande composta atrás do sujeito (oclusão de matte), entrada + saída projetadas |
A faixa carrega a maior parte do texto; embutido é 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; uma explicação longa → ~um por seção. Entre vários heróis, o maior escrito é o APEX (ele sozinho recebe o embed completo + 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 matte, que é exatamente o que mantém o ápice como um evento. Embutir cada palavra ainda é o erro comum.
Identidades de superfície de faixa constroem exatamente isso (faixa = rail.html, clímax = em index.html). Identidades de fluxo de coluna descartam a faixa e fazem tudo no estilo embutido — recomende-as apenas para pedidos de clima-sobre-literal, nunca para explicações / narrações onde as palavras devem ser lidas (CATALOG.md codifica isso por identidade).
Etapa 0 — escolha UMA identidade do CATALOG
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 criação 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 da 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 selecionados e declare o porquê em uma linha em vez de perguntar.
Procedimento: analise o clipe → selecione 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 criação 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 — incluindo os blocos caption-* — não tem onde se encaixar. Um bloco de registro estiliza texto em uma tela projetada; esta skill queima legendas na filmagem 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 recorrer a algo fora do catálogo.
Heurística de recomendação: use as "Heurísticas de pré-seleção" em CATALOG.md — elas são em nível de identidade (por exemplo, "炸" pré-seleciona ordnance/stomp/terminal/loud e escolhe pelo QUE deve explodir), nunca em nível de categoria. Em caso de dúvida → anchor.
- Cinematic → escreva
cinematic.jsonpara um modelo travado, compilado pormake-cinematic.cjs. - Theme → leia themes/README.md, crie
theme.json, executescripts/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> # specs
ffmpeg -ss <t> -i <video.mp4> -vframes 1 sample.png # em 20/50/80%
Leia as amostras. Recuse se:
- Vários 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 o silêncio); obedeça e recuse em vez de legendar palavras fabricadas - Fonte já tem legendas queimadas / subtítulos / gráficos de texto pesados — adicionar um segundo sistema de legendas conflita e a filmagem é enviada intocada (sem cobrir/pintar). Texto queimado geralmente 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 como bobagens confiantes. Leia
transcript.jsonpor sanidade antes de criar; se não for interpretável como linguagem, tenteWHISPER_MODEL=mediumuma vez, caso contrário recuse (uma faixa literal de palavras fabricadas é pior do que sem legendas). - Filmagem instável com movimento rápido (matte pisca)
Sondagens pré-voo (não custam nada, evitam 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 é lido como está,60-180→ adicione o escurecimento do glifo,180+→ texto opaco + escurecimento (nunca texto claro puro). Modelos Cinematic são creme+telae TRAVADOS — use esta sonda para escolher uma identidade adequada (cenas brilhantes →ink, ou o temaanchorde faixa opaca), nunca para recolorir um. - Recomendação de identidade por tom (você recomenda; o usuário escolhe — veja Etapa 0 + CATALOG.md). explicação / entrevista / palavras que devem ser lidas → identidades de superfície de faixa/painel; poético / social / "cinemático" → 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 selecionados e deixe o usuário escolher.
Pipeline — 5 etapas
1. hyperframes init <project> --non-interactive --video <video.mp4> --skill=embedded-captions
2. bash scripts/prepare.sh <project> # 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 cinematic.json → node scripts/make-cinematic.cjs <project>
Theme: crie theme.json → bash scripts/render-theme.sh <project> (compila + renderiza + placa fx)
4. node scripts/preview-frames.cjs <project> # ~2s/quadro pré-visualizações compostas → § QA Visual (ANTES da renderização)
5. bash scripts/render-and-composite.sh <project> # portões → final.mp4 + snapshot history/
(Modo Theme: PULE etapas 3b/5 — render-theme.sh já executa compilação + render-and-composite
+ _postfx.sh; a entrega é final_fx.mp4, final.mp4 é pré-reação de placa)
O init da Etapa 1 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 (puramente embutido)
- Leia
safe-zones.jsonprimeiro. Planos de narração vão emzones.hugLeft/hugRight— faixas limpas JUSTAPOSTAS à 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 é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 queheroBands.feasible— herói-fg é o último recurso. - O DNA é a identidade que você escolheu na Etapa 0. Consulte sua referência no catálogo para comportamento de texto/tempo e parâmetros de composição (por exemplo,
fadeInMs,holdMs,parallaxHeightRange, ~4 parâmetros). - Crie
cinematic.json(documentado abaixo). - Compile o cinematic:
node scripts/make-cinematic.cjs <project>verifica, derivaplan.json, compila os quadros embutidos e gravacomposite-inputs.json(para a Etapa 5). Sesafe-zones.jsonindica que nenhum ponto é viável, o compilador recusa com uma explicação.
Etapa 3 — Modo Theme (compilação de registro completa)
- Leia a especificação do tema. Consulte themes/README.md — componentes:
body(fundação da faixa),hero(peça central embutida, gerenciada pelo mesmosafe-zonesda cinematográfica),fx(front-end VFX) eplate(reação da filmagem base).body+herosão sempre compostos;fxeplatesão opcionais (a especificação do tema os declara). - Crie
theme.json. O contrato está emscripts/make-theme.cjs— procure PROPS esperadas na sua fonte; a maioria dos temas tem suas próprias referências em themes/. - Renderize:
bash scripts/render-theme.sh <project>executa compile, composição e pós-efeitos. A entrega éfinal_fx.mp4(a versãofinal.mp4é apenas a composição básica, sem reações de placa).
QA Visual (ANTES de pagar por uma renderização)
node scripts/preview-frames.cjs <project> amostra 3–6 quadros igualmente espaçados, gera composições fiéis em ~2s/quadro e as escreve em xxx/yyy-project/preview/. Abra-as. Verifique:
- O herói está embutido atrás do sujeito (o matte o oclui)?
- A faixa/narração está legível, na zona correta, correta?
- A identidade parece correta, não uma mistura?
Refaça a Etapa 3 (criação do JSON criativo) se algo estiver errado — é barato e iterativo. Pule para a Etapa 5 somente quando as pré-visualizações estiverem boas.
O que pode dar errado
- O matte pisca — cena ocupada / mão única / luz mudando / ângulo extremo. Verifique os quadros
frames_fg/antes de criar. Se piscar na pré-visualização, mude para uma identidade de faixaanchorque funciona sem matte (a faixa fica na frente, sem embutido). - O herói está flutuando, não embutido — o ponto
safe-zone.jsonprovavelmente está muito longe do corpo. Re-criecinematic.jsoncom zonas mais próximas (veja a Etapa 3 — as zonas padrão sãohugLeft/hugRight). - O vídeo original corta antes disso — o compilador avisa se a janela do herói cruza um corte. Apare o vídeo naquele ponto.
- Tempo de renderização — renderizações longas não estão travadas. Se a CLI ficar vários minutos sem saída, cancele com Ctrl-C normalmente e inspecione a filmagem (o matte paralelo pode ter baixado um modelo grande na primeira vez).
Cinematic.json
{
"safeZones": "safe-zones.json", // lido primeiro
"identity": "anchor", // deve corresponder à identidade CATALOG.md da Etapa 0
"mode": "cinematic",
"narration": [ // 0 ou mais pontos de narração
{
"word": "revolution",
"timeMs": 12500,
"zone": "hugLeft"
}
],
// Um herói (ou nenhum). Se omitido, o compilador seleciona o melhor
// candidato do transcript.json.
"hero": {
"word": "breakthrough",
"timeMs": 8200,
"zone": "heroAnchor",
"presentation": {
"fadeInMs": 300,
"holdMs": 1200,
"parallaxHeightRange": 0.04
}
},
// Sub-herois: palavras de pico menores que não são apex
"minorHeroes": [
{ "word": "future", "timeMs": 6100, "zone": "hugLeft", "emphasis": "oversize" }
]
}
hero e minorHeroes são mutuamente restritivos dentro de um bloco de pensamento (o compilador valida distância de tempo). Se houver poucos heróis, apenas alguns recebem o tratamento embutido — o resto é faixa.
Theme.json
Consulte a referência individual do tema em themes/README.md. Em resumo:
{
"identity": "ordnance",
"mode": "theme",
"body": { "paradigm": "rail", "words": "full-transcript" },
"hero": {
"word": "impact",
"timeMs": 4500,
"presentation": { "blastRadius": 0.6, "shockwave": true }
},
"fx": { "type": "charge-dim", "over": "hero", "holdMs": 200 },
"plate": { "type": "punch", "on": "hero", "intensity": 0.3 }
}