embedded-captions — camada mute-feed

Instalação de plugins: Antes dos comandos de configuração ou atualização, siga as regras de execução de plugins 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 sem efeito quando tudo está atualizado; caso contrário, atualiza esta skill e as skills de domínio principal das quais ela depende antes de utilizá-las.

Legendas Incorporadas

Um catálogo, escolhido de início (CATALOG.md — 35 identidades; os mecanismos por trás são detalhes de backend). Padrão (default) constrói um trilho limpo e fiel (legenda no terço inferior que carrega a maior parte do texto) + um clímax incorporado composto na cena atrás do assunto no pico. Cinematográfico é puramente incorporado — sem trilho, cada legenda composta atrás do assunto (tipografia heroica, acumulação, oclusão como efeito). Tema é uma constituição temática completa — paradigma do corpo × peça 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 / com narração é Padrão; o incorporado é o pico escasso e merecido — incorporar cada palavra é o erro comum; Tema é para pedidos com nível de VFX ("炸", "特效", "像 AE 做的").

---

Pré-requisitos de execução

Instalações de plugin usam a CLI fornecida e fixada pelo manifesto para matting, 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 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 substituí-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 de que a renderização terminou. Um argumento explícito de built-checkout ou HYPERFRAMES_ROOT seleciona a CLI do contribuidor em vez do pin 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 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 questão adiada — a shortlist precisa do clipe sondado, então 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 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:

1. Portão de decisão (recusar clipes ruins) → escolha UMA identidade de CATALOG.md (35 identidades; motor/compilador derivado por consulta — nunca apresente uma pergunta de modo/categoria)
2. 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, depois safe-zones v2 com paleta de cena/óptica/iluminação — um comando, nada esquecido)
3. escreva um pequeno JSON de escolhas criativas (leia safe-zones.json primeiro): Cinematográfico → plan.json → fill-timings.cjs → fit-fonts.cjs → make-composition.cjs; Tema → theme.json → make-theme.cjs (paradigmas de trilho/painel/poema/tomada de controle; anchor é o padrão de trilho silencioso)
4. QA Visual: node scripts/preview-frames.cjs <projeto> → pré-visualizações compostas fiéis em ~2s/frame (sem renderização). Verifique § QA Visual antes de pagar por uma renderização.
5. render-and-composite.sh → portões (timing / oclusão+heroi / transbordamento / hand-off) → final.mp4

Regras importantes que as pessoas ignoram:

• trilho (padrão) + incorporado (promoção). drop (preenchimento, não mostrado) / trilho (legenda fiel no terço inferior, na frente, carrega a maior parte do texto) / incorporado (uma palavra de pico composta atrás do assunto). O modo Padrão faz ambos, incorporando 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 Tema é a única exceção sancionada — batidas de reação registradas-gate (charge-dim, punch, shake, grain) definidas por DNA do tema e aplicadas APÓS a composição do matte para que assunto+texto+placa se movam como um quadro) — legendas são a única coisa adicionada; o matte apenas permite que o assunto oculte a trilha incorporada. Nunca gradear/recor/sacanear a filmagem.
• Dois manuais de regras: trilho → references/rail.md (fino), arte de incorporação → references/composition-craft.md (rico, apenas incorporado). Folheie conforme necessário.

---

Modelo de legenda — trilho + incorporado

Cada frase falada é uma de três coisas:

	O quê	Como é mostrada
drop	preenchimento — um/uh, gaguejos, autocorreções	não mostrada
trilho	o padrão — conteúdo falado comum (fiel)	legenda limpa no terço inferior, na frente, legível. Uma palavra de impacto pode receber um destaque ênfase inline (cor de destaque / pop de palavra ativa) — ela permanece no trilho.
incorporado	um pico promovido — a batida principal	uma grande palavra composta atrás do assunto (oclusão do matte), entrada + saída projetadas

O trilho carrega a maior parte do texto; o 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, ≥ um intervalo 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 escrito é o APEX (apenas ele recebe o lockup completo incorporado + ajuste de largura); os menores são picos MENORES que flutuam 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 apex como um evento. Incorporar cada palavra ainda é o erro comum.

Identidades de superfície de trilho constroem exatamente isso (trilho = rail.html, incorporado = o clímax em index.html). Identidades de fluxo de coluna abandonam o trilho e transformam tudo em estilo incorporado — recomende-as apenas para pedidos de humor sobre fidelidade, nunca para explicador / narração onde as palavras devem ser lidas (CATALOG.md codifica isso por identidade).

---

Etapa 0 — escolha UMA identidade do CATALOG

Um front-end, três motores por trás. O usuário escolhe uma IDENTIDADE de CATALOG.md (35 entradas: 10 clássicas + 25 temáticas); o motor, compilador e arquivo de autoria são derivados por consulta da linha do catálogo. Nunca apresente "Padrão vs Cinematográfico vs Tema" como uma pergunta — esses são nomes de backend (um produto tem uma UX mesmo com vários motores). 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 shortlist você mesmo e declare o porquê em uma linha em vez de perguntar.

Procedimento: sondar o clipe → shortlist 2-3 identidades do catálogo → recomendar UMA com um porquê em uma linha → o usuário escolhe (modo autônomo: você escolhe, declarando o porquê) → escrever o arquivo dessa identidade. Identidades são travadas por motor (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 escrever. Não assuma silenciosamente o padrão.

(A tabela de identidades completa está em CATALOG.md — fonte única de verdade para roteamento. Os documentos do motor 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 composição executam npx hyperframes catalog antes de escrever um visual nomeado; este não deve. Seus motores 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 no qual montar. Um bloco do 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 e escolha a mais próxima, em vez de buscar fora do catálogo.

Heurística de recomendação: use as "Heurísticas de shortlisting" em CATALOG.md — elas são no nível da identidade (por exemplo, "炸" shortlists ordnance/stomp/terminal/loud e escolhe pelo QUE deve explodir), nunca no nível de categoria. Inseguro → anchor.

• Cinematográfico → escreva plan.json para um template travado, compilado por make-composition.cjs.
• Tema → leia themes/README.md, escreva theme.json, execute scripts/render-theme.sh (compila + renderiza + reação de 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 (dividir e renderizar cada cena, ou recusar)
• Nenhum assunto humano (esta skill é para talking-head)
• Menos de 3 segundos, sem fala, ou rosto nunca claramente visível — transcribe.cjs avisa quando o áudio está quase silencioso (Whisper alucina palavras como "Thank you." sobre silêncio); preste atenção e recuse em vez de legendar palavras fabricadas
• Fonte já tem legendas fixas / legendas / gráficos de texto pesados — adicionar um segundo sistema de legendas conflita e a filmagem é enviada intocada (sem cobrir/inpaint). Texto fixo geralmente 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 frames pontuais.
• Transcrição é lixo — fala não nativa/com sotaque pesado pode transcrever em rabiscos confiantes. Leia transcript.json para sanidade antes de escrever; se não for interpretável como linguagem, tente WHISPER_MODEL=medium uma vez, senão recuse (um trilho fiel de palavras fabricadas é pior do que sem legendas).
• Câmera na mão agitada com movimento rápido (matte oscila)

Sondagens pré-voo (não custam nada, previnem as piores falhas)

1. Sondagem de corte de cena. Amostre frames em 20%, 50%, 80%. Se um assunto/cena diferente aparecer, apare o clipe antes do corte.
2. Sondagem de letterbox / pillarbox. Barras pretas no primeiro frame? Calcule o retângulo de conteúdo seguro e restrinja o posicionamento das legendas dentro dele.
3. Sondagem 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 nu). Templates cinematográficos são creme+tela e TRAVADOS — use esta sondagem para escolher uma identidade adequada (cenas claras → ink, ou o tema anchor de trilho opaco), nunca para recolorir um.
4. Recomendação de identidade pelo tom (você recomenda; o usuário escolhe — veja Etapa 0 + CATALOG.md). explicador / entrevista / deve ler palavras → identidades de superfície de trilho/painel; poético / social / "cinematográfico" → identidades de fluxo de coluna por registro; "炸 / 特效 / VFX" / mundos nomeados → identidades temáticas. Quando inseguro → anchor (palavras são lidas, cena segura) — mas apresente uma shortlist 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) → safe-zones. Um comando.
                                           #   → frames_fg/ transcript.json safe-zones.json
3. [ETAPA DE AGENTE — a única etapa criativa] escreva um pequeno JSON; veja abaixo por modo
   Cinematográfico: escreva plan.json → node scripts/fill-timings.cjs → fit-fonts.cjs → make-composition.cjs
   Tema:     escreva theme.json → bash scripts/render-theme.sh <projeto>   (compila + renderiza + fx de placa)
4. node scripts/preview-frames.cjs <projeto>   # ~2s/frame pré-visualizações compostas → § QA Visual (ANTES da renderização)
5. bash scripts/render-and-composite.sh <projeto>  # portões → final.mp4 + snapshot de histórico/
   (Modo Tema: PULE as etapas 3b/5 — render-theme.sh já executa compila + render-and-composite
    + _postfx.sh; o entregável é final_fx.mp4, final.mp4 é pré-reação de placa)

A init da etapa 1 verifica as skills instaladas em comparação com as 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 incorporado)

1. Leia safe-zones.json primeiro. Planos de narração vão em zones.hugLeft/hugRight — faixas limpas JUSTAPOSTAS à silhueta (texto distante do corpo parece flutuante, não incorporado; cantos distantes são o fallback, não o padrão). O herói tem como padrão heroAnchor/heroBands.best (centrado NO assunto, ~30-55% ocluído). recommendation:"fg" move a NARRAÇÃO para a frente para legibilidade; o herói permanece incorporado sempre que heroBands.feasible — herói-fg é o último recurso.
2. O DNA é a identidade que você escolheu — não use nenhum outro. Cada identidade cinematográfica (anchor, ink, loud, neon, cream) tem um arquivo dna/<nome>.json que define suas regras de animação, paleta e layout. Leia-o antes de escrever plan.json para saber quais campos cumprir.
3. Escreva plan.json: <project>/plan.json com a estrutura: