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. É um no-op rápido quando tudo está atualizado; caso contrário, atualiza esta skill e as skills de domínio essenciais das quais ela depende antes de você confiar nelas.
Legendas Incorporadas
Um catálogo, escolhido no início (CATALOG.md — 35 identidades; os mecanismos por trás são detalhes de backend). Padrão (padrão) cria um trilho limpo e literal (legenda no terço 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 trilho, cada legenda é composta atrás do sujeito (tipografia heróica, acumulação, oclusão como efeito). Temático é uma constituição temática completa — paradigma de corpo × conjunto heróico × 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 com narração é Padrão; a incorporação é o pico escasso e merecido — incorporar cada palavra é o erro comum; Temático é para solicitações de nível VFX ("炸", "特效", "como se fosse feito no AE").
Pré-requisitos de execução
Instalações de plugin usam a CLI empacotada e fixada no manifesto para separação de fundo, transcrição e renderização; nenhum checkout de código-fonte é necessário. A visualização local e os auxiliares de medição de legenda 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 <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 bloqueadas em vez de sobrescrevê-las. Bash e FFmpeg/ffprobe devem estar no PATH. A separação de fundo e a transcrição podem baixar seus próprios modelos na primeira execução.
A renderização aguarda a CLI sair com sucesso antes da composição. O antigo watchdog de shell 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 de construção ou HYPERFRAMES_ROOT seleciona a CLI do colaborador em vez do plugin fixado. Cancele uma renderização travada normalmente através da CLI/terminal; o auxiliar de legendas não força a morte ou recupera uma renderização de um snapshot de processo.
Fluxo operacional (resumo)
Roteado através do /hyperframes, a camada de intenção confirma apenas a entrada (qual clipe) e anuncia a escolha de identidade como uma solicitação adiada — a lista de opções 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 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 de criação abaixo é longo; o pipeline em si é curto — e tudo que é determinístico é computado ou compilado, nunca escrito à mão:
- 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)
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>(separação de fundo ∥ transcrição ∥ envelope de áudio em paralelo, então zonas seguras v2 com paleta da cena/óptica/iluminação — um comando, nada esquecido)- crie um pequeno JSON de escolhas criativas (leia
safe-zones.jsonprimeiro): Cinematográfico →cinematic.json→make-cinematic.cjs(derivaplan.jsone o compila); Temático →theme.json→make-theme.cjs(paradigmas de trilho/painel/poema/tomada de controle;anchoré o trilho discreto padrão) - QA visual:
node scripts/preview-frames.cjs <project>→ prévias 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 (timing / oclusão+herói / estouro / entrega) →final.mp4
Regras importantes que as pessoas perdem:
- trilho (padrão) + incorporação (promoção).
drop(preenchimento, não exibido) /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 Padrão faz ambos, incorporando apenas o(s) pico(s). Veja § Modelo de legenda. - O vídeo é entregue SEM EDIÇÃO (Padrão/Cinematográfico; o orçamento de PLACA do modo Temático é a única exceção sancionada — batidas de reação com portão de registro (dim de carga, soco, chacoalhão, granulação) definidas por DNA do tema e aplicadas APÓS a composição da separação para que sujeito+texto+placa se movam como um quadro) — legendas são a única coisa adicionada; a separação apenas permite que o sujeito oculte a trilha incorporada. Nunca corrija cor/adicione scanlines à filmagem.
- Dois manuais: trilho → references/rail.md (curto), criação incorporada → references/composition-craft.md (rico, apenas incorporado). Folheie conforme necessário.
Modelo de legenda — trilho + incorporação
Cada frase falada é uma de três coisas:
| O que é | Como é exibida | |
|---|---|---|
| drop | preenchimento — hã/uh, gaguejos, autocorreções | não exibida |
| rail | o padrão — conteúdo falado comum (literal) | legenda limpa no terço inferior, na frente, legível. Uma palavra de destaque pode receber um destaque emphasis em linha (cor de realce / 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 de separação), entrada + saída projetadas |
O trilho carrega a maior parte do texto; a incorporação é 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 longo explicativo → ~um por seção. Entre vários heróis, o maior criado é o ÁPICE (só ele recebe a incorporação completa de lockup + 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 exibição de separação, 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 = rail.html, incorporação = o clímax em index.html). Identidades de fluxo de coluna abandonam o trilho e tornam tudo no estilo incorporação — recomende-as apenas para solicitações de clima-sobre-literal, nunca para explicativo / 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 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 Temático" 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 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 e declare 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, declarando o porquê) → crie o arquivo dessa identidade. As identidades são vinculadas ao 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 de identidades completa está em CATALOG.md — fonte única de 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 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 própria composição, então um item de registro — incluindo os blocos caption-* — não tem nada onde montar. Um bloco de registro estiliza texto em uma tela projetada; esta skill grava legendas na filmagem de alguém através de uma separação. Quando nenhuma identidade se encaixa na solicitação, diga e escolha a mais próxima, em vez de sair 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 da categoria. Em dúvida → anchor.
- Cinematográfico → escreva
cinematic.jsonpara um modelo bloqueado, compilado pormake-cinematic.cjs. - Temático → 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
Sonhe 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 (esta skill é para uma pessoa falando)
- Menos de 3 segundos, sem fala, ou rosto nunca claramente visível —
transcribe.cjsavisa quando o áudio está quase silencioso (Whisper alucina palavras como "Obrigado." sobre silêncio); siga o aviso 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 sem edição (sem cobrir/inpaint). Texto incorporado 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. - A transcrição é lixo — fala não nativa com sotaque pesado pode ser transcrita como um absurdo confiante. Leia
transcript.jsonantes de criar; se não for interpretável como linguagem, tenteWHISPER_MODEL=mediumuma vez, senão recuse (um trilho literal de palavras fabricadas é pior do que sem legendas). - Câmera na mão agitada com movimento rápido (separação tremula)
Sondagens de pré-voo (não custam nada, previnem as piores falhas)
- Sonda de corte de plano. Amostre quadros em 20%, 50%, 80%. Se um sujeito/cena diferente aparecer, apare o clipe antes do corte.
- Sonda de letterbox / pillarbox. Barras pretas no primeiro quadro? Calcule o retângulo de conteúdo seguro e restrinja o posicionamento da legenda dentro dele.
- Sonda de luminância. Amostre a luminância média da região da legenda —
abaixo de 60→ texto claro é legível como está,60-180→ adicione o scrim do glifo,180+→ texto opaco + scrim (nunca texto claro simples). Os modelos cinematográficos são creme+screene BLOQUEADOS — use esta sonda para escolher uma identidade adequada (cenas claras →ink, ou o trilho opacoanchordo tema), 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 / redes sociais / "cinematográfico" → identidades de fluxo de coluna por registro; "炸 / 特效 / VFX" / mundos nomeados → identidades temáticas. Em 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 <project> --non-interactive --video <video.mp4> --skill=embedded-captions
2. bash scripts/prepare.sh <project> # separação ∥ 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 <project>
Temático: crie theme.json → bash scripts/render-theme.sh <project> (compila + renderiza + efeitos de placa)
4. node scripts/preview-frames.cjs <project> # ~2s/quadro de prévias compostas → § QA Visual (ANTES da renderização)
5. bash scripts/render-and-composite.sh <project> # portões → final.mp4 + snapshot history/
(Modo Temático: PULE as 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 Cinematográfico (apenas incorporação)
- Leia
safe-zones.jsonprimeiro. Os 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 plano de fallback, não o padrão). O herói é padronizado paraheroAnchor/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 queheroBands.feasible— herói-fg é o último recurso. - O DNA é a identidade que você escolheu na Etapa 0 — está no catálogo.
...
[truncado para tradução]