Instalação de plugins: Antes de executar comandos de configuração ou atualização, siga as regras de execuçã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. Um no-op rápido quando tudo está atualizado; caso contrário, ele atualiza este skill e os skills de domínio principais dos quais ele depende antes de você usá-los.
Legendas Embutidas (Embedded Captions)
Um catálogo, escolhido de início (CATALOG.md — 35 identidades; os mecanismos por trás são detalhes de implementação). Padrão (default) constrói uma trilha rail limpa e literal (legenda no terço inferior que carrega a maior parte do texto) + um clímax embed composto dentro da cena, atrás do sujeito no pico. Cinematográfico é puro embed — sem trilha rail, cada legenda composta atrás do sujeito (tipografia de destaque, acumulação, oclusão como efeito). Temático é uma constituição temática completa — paradigma corporal × peça de destaque × efeito frontal × reação da placa, composta a partir de registros (themes/README.md): ordnance terminal neonsign stardust stomp. A maioria das explicações / narrações usa o modo Padrão; embed é o pico escasso e merecido — embutir cada palavra é o erro comum; Temático é para pedidos de nível VFX ("炸", "特效", "como se fosse feito no AE").
Pré-requisitos de execução
Instalações de plugin usam a CLI agrupada e fixada no manifesto para separação de sujeito, transcrição e renderização; nenhum checkout de código-fonte é necessário. Os ajudantes 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. A separação de sujeito e a 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 de que a renderização terminou. Um argumento explícito de checkout construído ou HYPERFRAMES_ROOT seleciona a CLI do contribuidor em vez do pino do plugin. Cancele uma renderização travada normalmente através da CLI/terminal; o helper de legendas não força a interrupção nem recupera uma renderização a partir de um snapshot do processo.
Fluxo operacional (TL;DR)
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 candidatos precisa do clipe sondado, então ela fica na etapa 1 abaixo; as perguntas de formato 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 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.cjsadotam qualquer vídeo no diretório como source.mp4) →bash scripts/prepare.sh <projeto>(matte ∥ transcrição ∥ envelope de áudio em paralelo, depois zonas seguras v2 com paleta de 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 rail/panel/poem/takeover;anchoré o padrão da trilha silenciosa) - QA Visual:
node scripts/preview-frames.cjs <projeto>→ pré-visualizações compostas fiéis 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 / estouro / hand-off) →final.mp4
Regras importantes que as pessoas ignoram:
- trilha rail (padrão) + embed (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, embutindo apenas o(s) pico(s). Veja § Modelo de legenda. - O vídeo é entregue SEM ALTERAÇÕES (Padrão/Cinematográfico; o orçamento PLATE do modo Temático é a única exceção sancionada — batidas de reação com portão de registro (carga-dim, soco, tremor, 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 oclua a trilha embed. Nunca gradear/recorrilinearize a filmagem.
- Dois livros de regras: trilha rail → references/rail.md (fino), criação embed → references/composition-craft.md (rico, apenas embed). Folheie conforme necessário.
Modelo de legenda — rail + embed
Cada frase falada é uma de três coisas:
| O que é | Como é exibida | |
|---|---|---|
| drop | preenchimento — hum/ah, gaguejos, autocorreções | não exibido |
| 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 inline (cor de acento / pop de palavra ativa) — ela permanece na trilha rail. |
| embed | um pico promovido — a batida principal | uma palavra grande composta atrás do sujeito (oclusão do matte), entrada + saída projetadas |
A trilha 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; uma explicação longa → ~um por seção. Entre vários heróis, o maior criado é o APEX (só ele recebe o embed completo de lockup + aumento 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 apex como um evento. Embutir cada palavra ainda é o erro comum.
Identidades de superfície rail constroem exatamente isso (rail = rail.html, embed = o clímax em index.html). Identidades de fluxo de coluna descartam a trilha rail e tornam tudo estilo embed — recomende-as apenas para pedidos de humor sobre literalidade, nunca para explicações/narrações onde as palavras precisam 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 "Padrão vs Cinematográfico vs Temático" como uma pergunta — esses são nomes internos (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 ("surpreenda-me" / "decida por mim"), escolha da sua lista de candidatos você mesmo e declare o motivo em uma linha em vez de perguntar.
Procedimento: sonde o clipe → liste 2–3 identidades do catálogo → recomende UMA com um motivo em uma linha → o usuário escolhe (modo autônomo: você escolhe, declarando o motivo) → crie o arquivo dessa identidade. Identidades são travadas por mecanismo (sem combos cruzados; 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 da 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 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 do registro — os blocos caption-* incluídos — não tem nada onde montar. Um bloco de registro estiliza texto em uma tela projetada; este 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 procurar fora do catálogo.
Heurística de recomendação: use as "Heurísticas de listagem" 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 de categoria. Em dúvida → anchor.
- Cinematográfico → escreva
cinematic.jsonpara um template travado, 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
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 plano, ou recuse)
- Nenhum sujeito humano (este skill é para 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 o silêncio); obedeça e recuse em vez de legendas de palavras fabricadas - A fonte já tem legendas/legendas embutidas / gráficos de texto pesados — adicionar um segundo sistema de legendas conflita e a filmagem é entregue intocada (sem cobrir/inpaint). 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 de ponto. - A transcrição é lixo — fala não-nativa/com sotaque pesado pode ser transcrita em um absurdo confiante. Leia
transcript.jsoncom sanidade antes de criar; se não fizer sentido como linguagem, tenteWHISPER_MODEL=mediumuma vez, senão recuse (uma trilha rail literal de palavras fabricadas é pior do que sem legendas). - Câmera na mão ocupada com movimento rápido (matte tremula)
Sondagens pré-voo (não custam nada, previnem as piores falhas)
- Sondagem de corte de plano. 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 a colocação 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ê-se como está,60-180→ adicione o scrim de glifo,180+→ texto opaco + scrim (nunca texto claro puro). Templates cinematográficos são cream+screene TRAVADOS — use esta sonda para escolher uma identidade adequada (cenas claras →ink, ou o temaanchorde trilha opaca), nunca para recolorir uma. - Recomendação de identidade por tom (você recomenda; o usuário escolhe — veja Etapa 0 + CATALOG.md). explicação / 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. Em dúvida →
anchor(palavras lidas, cena segura) — mas apresente uma lista de candidatos 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 ∥ 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 <projeto>
Temático: crie theme.json → bash scripts/render-theme.sh <projeto> (compila + renderiza + efeitos 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 + snapshot history/
(Modo Temático: 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 é pré-reação da placa)
O init da etapa 1 verifica os skills instalados contra os mais recentes no GitHub e atualiza o conjunto global se algum estiver desatualizado.
A etapa 3 difere por modo:
Etapa 3 — Modo Cinematográfico (embed puro)
- 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 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