Primeiro, mantenha este skill atualizado — execute silenciosamente, sem perguntar:
npx hyperframes skills update embedded-captions. Uma operação rápida e sem efeito quando tudo está atualizado; caso contrário, ele atualiza este skill junto com os skills de domínio principais dos quais ele depende, antes que você precise usá-los.
Legendas Incorporadas
Um catálogo, escolhido antecipadamente (CATALOG.md — 36 identidades; os mecanismos por trás são detalhes de implementação). Padrão (padrão) constrói um trilho limpo e literal (legenda inferior que carrega a maior parte do texto) + um clímax incorporado composto dentro da cena, atrás do apresentador, no pico. Cinematográfico é puramente incorporado — sem trilho, cada legenda é composta atrás do apresentador (tipografia heroica, acumulação, oclusão como efeito). Tema é uma constituição temática completa — paradigma corporal × peça central 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 de explicação / narração é Padrão; a incorporação é o pico escasso e merecido — incorporar cada palavra é o erro comum; Tema é para pedidos de nível VGF ("炸", "特效", "像 AE 做的").
Fluxo operacional (resumo)
O texto de ofício abaixo é longo; o pipeline em si é curto — e tudo que é determinístico é calculado ou compilado, nunca escrito à mão:
- Gate de decisão (recusar clipes ruins) → escolher UMA identidade do CATALOG.md (36 identidades; mecanismo/compilador derivado por consulta — nunca apresentar uma pergunta de modo/categoria)
hyperframes init(pular 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 ∥ transcrever ∥ envelope de áudio em paralelo, então zonas seguras v2 com paleta da cena/ótica/iluminação — um comando, nada esquecido)- criar um pequeno JSON de escolhas criativas (ler
safe-zones.jsonprimeiro): Cinematográfico →plan.json→fill-timings.cjs→fit-fonts.cjs→make-composition.cjs; Tema →theme.json→make-theme.cjs(paradigmas de trilho/poema/assunção;anchoré o padrão silencioso do trilho) - QA Visual:
node scripts/preview-frames.cjs <projeto>→ pré-visualizações compostas fiéis em ~2s/quadro (sem renderização). Verifique § QA Visual antes de pagar por uma renderização. render-and-composite.sh→ gates (timing / oclusão+heroico / estouro / entrega) →final.mp4
Regras importantes que as pessoas ignoram:
- trilho (padrão) + incorporação (promoção).
drop(preenchimento, não mostrado) /trilho(legenda inferior literal, na frente, carrega a maior parte do texto) /incorporar(uma palavra de pico composta atrás do apresentador). O modo padrão faz ambos, incorporando apenas o(s) pico(s). Veja § Modelo de legenda. - O vídeo é entregue INALTERADO (Padrão/Cinematográfico; o orçamento de PLACA do modo Tema é a única exceção sancionada — batidas de reação controladas por registro (carga-dim, soco, tremor, granulação) definidas por DNA do tema e aplicadas APÓS a composição fosca para que apresentador+texto+placa se movam como um único quadro) — legendas são a única coisa adicionada; a máscara apenas permite que o apresentador oclua a trilha incorporada. Nunca corrigir cor/recolorir/adicionar linhas de varredura no material de arquivo.
- Dois livros de regras: trilho → references/rail.md (fino), ofício de incorporação → references/composition-craft.md (rico, apenas incorporação). Folhear conforme a necessidade.
Modelo de legenda — trilho + incorporação
Cada frase falada é uma de três coisas:
| O quê | Como é mostrada | |
|---|---|---|
| drop | preenchimento — hum/äh, gaguejos, autocorreções | não mostrada |
| trilho | o padrão — conteúdo falado comum (literal) | legenda inferior limpa, na frente, legível. Uma palavra de impacto pode receber um destaque emphasis inline (cor de destaque / pop de palavra ativa) — ela permanece no trilho. |
| incorporar | um pico promovido — a batida principal | uma palavra grande composta atrás do apresentador (oclusão fosca), entrada + saída projetadas |
O trilho carrega a maior parte do texto; a incorporação é o pico escasso e merecido. A escassez é por batida/bloco, não por clipe: ≤1 heroico por bloco (pensamento), nunca dois co-visíveis, ≥ uma batida de ar entre janelas heroicas (o compilador avisa abaixo de 0,6s). Um clipe curto → geralmente 1–2; um vídeo longo de explicação → ~um por seção. Entre múltiplos heroicos, o maior criado é o APEX (apenas ele recebe a incorporação completa de lockup + elevação de ajuste de largura); os menores são picos MENORES que usam sua coluna como linhas de ênfase superdimensionadas (fg, movimento amortecido) — nem toda batida precisa da demonstração fosca, 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 eliminam o trilho e fazem tudo no estilo incorporação — recomende-as apenas para pedidos de humor sobre literalidade, nunca para explicações / narrações onde as palavras devem ser lidas (CATALOG.md codifica isso por identidade).
Passo 0 — escolher UMA identidade do CATÁLOGO
Um front-end, três mecanismos por trás. O usuário escolhe uma IDENTIDADE do CATALOG.md (36 entradas: 10 clássicas + 26 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 Tema" 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, recomendação para, necessidades de cena, notas de adjacência para pares realmente próximos (loud↔ordnance, neon↔neonsign, cream↔stardust).
A escolha da identidade é um gate de preferência (../hyperframes-core/references/brief-contract.md § 1): no modo autônomo ("me surpreenda" / "decida por mim"), escolha da sua lista de selecionados você mesmo e declare o porquê em uma linha em vez de perguntar.
Procedimento: sondar o clipe → listar 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ê) → criar o arquivo dessa identidade. As 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 o padrão silenciosamente.
(A tabela de identidades completa está em CATALOG.md — fonte única da verdade para roteamento. Os documentos do mecanismo abaixo descrevem o contrato de criação de cada backend.)
Heurística de recomendação: use as "Heurísticas de lista curta" em CATALOG.md — elas são no nível da identidade (por exemplo, "炸" lista ordnance/stomp/terminal/loud e escolhe pelo QUE deve explodir), nunca no nível da categoria. Em caso de dúvida → anchor.
- Cinematográfico → escrever
plan.jsonpara um template bloqueado, compilado pormake-composition.cjs. - Tema → ler themes/README.md, criar
theme.json, executarscripts/render-theme.sh(compila + renderiza + reação da placa → final_fx.mp4).
Gate de decisão — EXECUTAR PRIMEIRO
Sondar o vídeo e classificar 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 tomada, ou recusar)
- Nenhum sujeito humano (este skill é para "talking head")
- 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); preste atenção e recuse em vez de legendar palavras fabricadas - Fonte já possui legendas queimadas / subtítulos / gráficos de texto pesados — adicionar um segundo sistema de legendas conflita e o material de arquivo é enviado intacto (sem cobrir/pintar). Texto queimado geralmente aparece apenas no meio do clipe: amostre uma folha de contato de 1 fps (
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 rabiscos confiantes. Leia
transcript.jsonantes de criar; se não for interpretável como linguagem, tenteWHISPER_MODEL=mediumuma vez, caso contrário recuse (um trilho literal de palavras fabricadas é pior do que sem legendas). - Câmera na mão ocupada com movimento rápido (máscara tremula)
Sondagens de 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 lê-se como está,60-180→ adicione o escrim de glifo,180+→ texto opaco + escrim (nunca texto claro sem revestimento). Os templates cinematográficos são creme+screene BLOQUEADOS — use esta sondagem para escolher uma identidade adequada (cenas claras →ink, ou o temaanchorde trilho opaco), nunca para recolorir uma. - Recomendação de identidade por tom (você recomenda; o usuário escolhe — veja Passo 0 + CATALOG.md). explicação / entrevista / palavras devem ser lidas → identidades de superfície de trilho/poema; poético / social / "cinematográfico" → identidades de fluxo de coluna por registro; "炸 / 特效 / VFX" / mundos nomeados → identidades temáticas. Quando em dúvida →
anchor(palavras lidas, cena segura) — mas apresente uma lista curta e deixe o usuário escolher.
Pipeline — 5 passos
1. hyperframes init <projeto> --non-interactive --video <video.mp4>
2. bash scripts/prepare.sh <projeto> # matte ∥ transcrever (paralelo) → zonas seguras. Um comando.
# → frames_fg/ transcript.json safe-zones.json
3. [PASSO DO AGENTE — o único passo criativo] criar um pequeno JSON; veja abaixo por modo
Cinematográfico: criar plan.json → node scripts/fill-timings.cjs → fit-fonts.cjs → make-composition.cjs
Tema: criar theme.json → bash scripts/render-theme.sh <projeto> (compila + renderiza + efeitos de placa)
4. node scripts/preview-frames.cjs <projeto> # ~2s/quadro de pré-visualizações compostas → § QA Visual (ANTES da renderização)
5. bash scripts/render-and-composite.sh <projeto> # gates → final.mp4 + instantâneo history/
(Modo Tema: PULAR passos 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 do Passo 1 verifica os skills instalados em relação aos mais recentes no GitHub e atualiza o conjunto global se algum estiver desatualizado.
O Passo 3 difere por modo:
Passo 3 — Modo Cinematográfico (incorporação pura)
- Leia
safe-zones.jsonprimeiro. Planos de narração vão emzones.hugLeft/hugRight— faixas limpas JUNTA À silhueta (texto longe do corpo parece flutuante, não incorporado; cantos distantes são o fallback, não o padrão). O heroico padrão éheroAnchor/heroBands.best(centrado NO sujeito, ~30–55% ocluído).recommendation:"fg"move a NARRAÇÃO para a frente para legibilidade; o heroico permanece incorporado sempre queheroBands.feasible— heroico-fg é o último recurso. - O DNA é a identidade que você escolheu no Passo 0 (CATALOG.md) — não reabra a escolha aqui. Verifique a sanidade contra a cena (luminância da banda heroica brilhante > 150 quer
ink; a orientação de escolha completa está no catálogo, cobrindo todos os dez, incl. neon / glitch / chrome / velocity). Declare sua escolha + porquê; o usuário decide. O DNA bloqueia tipo/paleta/mistura/movimento + três atos heroicos; zonas seguras v2 (palette/optics/lighting) parametriza isso para ESTA cena automaticamente. - Crie
<projeto>/cinematic.json—"dna": "<nome>"+ BLOCOs de pensamento, não grupos brutos: cada bloco = linhas de palavras (agrupadas 2–5 em limites de cláusula) + o plano em que empilha +csspor linha (tamanho/peso/estilo apenas — sem posições) + no máximo UMA linha marcada como"hero": true(a palavra promovida;"text"para forma de exibição). Esquema:scripts/make-cinematic.cjscabeçalho. - Compilar:
node scripts/make-cinematic.cjs <projeto>— reduz blocos → plan.json → index.html. Gerado para você: tempos sequenciados por transcrição, acumular dentro do bloco, virar página entre blocos, o LOCKUP heroico (o pré-contexto de um bloco heroico, HERO e pós-contexto empilham como UMA composição unida centrada no sujeito — ordem de leitura topo→base = ordem falada por construção; o contexto flutua na FRENTE enquanto o heroico incorpora ATRÁS = o sanduíche de profundidade; uma regra de massa mantém o heroico dominando seu contexto), divisão apex/heroico menor, ordem de leitura por construção, fallback fg por zonas seguras. Então os gates executam normalmente. (Criar plan.json manualmente ainda é possível para designs que blocos não podem expressar — então executefill-timings.cjs+fit-fonts.cjs+make-composition.cjsvocê mesmo.)
Passo 3 — Modo Tema (constituição temática)
Leia themes/README.md PRIMEIRO — registros de paradigma/peça central, ligações, regras rígidas e o esquema exato de theme.json.
- Escolha um DNA de tema por registro de conteúdo (cada
themes/<nome>.jsontemvoice+when). Declare sua escolha + porquê; o usuário decide. - Crie
<projeto>/theme.json—dna,lines(literal, ordem da transcrição; 1–5 palavras cada — paratakeovercada linha é um CARD),minors(palavras de ênfase),hero:{match}(a palavra/frase clímax; deixe-a FORA delinespara peças de incorporação, mantenha-a DENTRO para peças inline e poema+redact). - Renderizar:
bash scripts/render-theme.sh <projeto>— compila (gate de completude literal em tempo de compilação), renderiza ambas as camadas, compõe, aplica a reação da placa →final_fx.mp4. Use `preview-fram
…
[truncado para tradução]