fl-sean03/skills

Legendas Embutidas (Embedded Captions)

Um catálogo, escolhido de início (CATALOG.md — 17 identidades; os três motores por trás disso são detalhes de backend). Standard (padrão) constrói um trilho (rail) limpo e literal (legenda inferior com a maior parte do texto) + um clímax embed composto dentro da cena atrás do sujeito no pico. Cinematic é puramente embed — sem trilho, cada legenda composta atrás do sujeito (tipografia heroica, acumulação, oclusão como efeito). Theme é uma constituição temática completa — paradigma de corpo × peça heroica × efeito frontal × reação de placa, composta a partir de registros (themes/README.md): ordnance terminal neonsign stardust stomp. A maioria dos vídeos explicativos / narração é Standard; embed é o pico escasso e conquistado — embutir cada palavra é o erro comum; Theme é para pedidos com nível VFX ("炸", "特效", "como se fosse AE").

---

Fluxo operacional (resumo)

A prosa técnica abaixo é longa; o pipeline em si é curto — e tudo que é determinístico é computado ou compilado, nunca escrito à mão:

1. Portão de decisão (recusar clipes ruins) → escolher UMA identidade do CATALOG.md (17 identidades; motor/compilador derivado por consulta — nunca pergunte sobre 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 zonas seguras v2 com paleta/óptica/iluminação da cena — um comando, nada esquecido)
3. criar um pequeno JSON de escolhas criativas (leia safe-zones.json primeiro): Cinematic → plan.json → fill-timings.cjs → fit-fonts.cjs → make-composition.cjs; Theme → theme.json → make-theme.cjs (paradigmas de trilho/painel/poema/tomada; anchor é o padrão de trilho discreto)
4. QA visual: node scripts/preview-frames.cjs <projeto> → prévias fiéis da composição em ~2s/quadro (sem render). Verifique § QA Visual antes de pagar por uma renderização.
5. render-and-composite.sh → portões (timing / oclusão+hero / estouro / entrega) → final.mp4

Regras importantes que muitos ignoram:

• trilho (padrão) + embed (promoção). drop (preenchimento, não exibido) / rail (legenda inferior literal, na frente, carrega a maior parte do texto) / embed (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 SEM ALTERAÇÕES (Standard/Cinematic; o orçamento de PLACA do modo Theme é a única exceção sancionada — batidas de reação registradas (dim de carga, soco, tremor, grã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/recolorir/linhas de varredura na gravação.
• Dois livros de regras: trilho → references/rail.md (fino), arte embed → references/composition-craft.md (rico, apenas embed). Folheie conforme necessário.

---

Modelo de legenda — trilho + embed

Cada frase falada é uma de três coisas:

	O que é	Como é mostrado
drop	preenchimento — hum/ah, gaguejos, autocorreções	não exibido
rail	o padrão — conteúdo falado comum (literal)	legenda inferior limpa, na frente, legível. Uma palavra de impacto pode ganhar um destaque emphasis inline (cor de destaque / pop de palavra ativa) — permanece no trilho.
embed	um pico promovido — a batida principal	uma palavra grande composta atrás do sujeito (oclusão por matte), entrada e saída projetadas

O trilho carrega a maior parte do texto; embed é o pico escasso e conquistado. Escassez é por batida/bloco, não por clipe: ≤1 heroi por bloco (pensamento), nunca dois co-visíveis, ≥ uma batida de ar entre janelas de heroi (o compilador avisa abaixo de 0,6s). Um clipe curto → geralmente 1–2; um vídeo explicativo longo → ~um por seção. Entre múltiplos herois, o maior criado é o APEX (somente ele ganha o embed completo com trava + elevação por largura); os menores são picos MENORES que cavalgam 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 de trilho constroem exatamente isso (trilho = rail.html, embed = o clímax em index.html). Identidades de fluxo de coluna abandonam o trilho e transformam tudo em estilo embed — recomende-as apenas para pedidos de atmosfera sobre literalidade, nunca para vídeos explicativos / narração onde as palavras precisam ser lidas (CATALOG.md codifica isso por identidade).

---

Passo 0 — escolher UMA identidade do CATÁLOGO

Um front-end, três motores por trás. O usuário escolhe uma IDENTIDADE do CATALOG.md (17 entradas: 12 clássicas + 5 temáticas); o motor, compilador e arquivo de autoria são derivados por consulta da linha do catálogo. Nunca apresente "Standard vs Cinematic vs Theme" como 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, recomendação-para, necessidades de cena, notas de adjacência para pares realmente próximos (loud↔ordnance, neon↔neonsign, cream↔stardust).

Procedimento: sondar o clipe → listar 2–3 identidades do catálogo → recomendar UMA com uma linha de motivo → o usuário escolhe → criar o arquivo daquela identidade. Identidades são travadas por motor (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 assuma um padrão silenciosamente.

(A tabela completa de identidades está em CATALOG.md — fonte única de verdade para roteamento. Os documentos dos motores abaixo descrevem o contrato de autoria de cada backend.)

Heurística de recomendação: use as "Heurísticas de listagem curta" 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 caso de dúvida → anchor.

• Cinematic → escreva plan.json para um template travado, compilado por make-composition.cjs.
• Theme → leia themes/README.md, crie 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 clipe 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 cena, ou recuse)
• Nenhum sujeito humano (este 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 "Obrigado." sobre silêncio); obedeça e recuse em vez de legendar palavras fabricadas
• A fonte já possui legendas / subtítulos / gráficos de texto pesados — adicionar um segundo sistema de legendas conflita e a gravação é entregue sem alterações (sem cobrir/pintar). Texto queimado 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 quadros únicos.
• A transcrição é lixo — fala não nativa/com sotaque pesado pode ser transcrita em bobagem confiante. Leia transcript.json criticamente antes de criar; se não fizer sentido como linguagem, tente WHISPER_MODEL=medium uma vez, senão recuse (um trilho literal de palavras fabricadas é pior que sem legendas).
• Câmera na mão com movimento rápido (matte pisca)

Sondagens de pré-voo (não custam nada, previnem os piores erros)

1. Sondagem de corte de cena. Amostre quadros em 20%, 50%, 80%. Se um sujeito/cena diferente aparecer, corte o clipe antes do corte.
2. Sondagem de letterbox / pillarbox. Barras pretas no primeiro quadro? 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 lê-se como está, 60-180 → adicione o escurecimento do glifo, 180+ → texto opaco + escurecimento (nunca texto claro puro). Templates Cinematic são creme+screen e TRAVADOS — use esta sonda para escolher uma identidade adequada (cenas claras → ink, ou o tema anchor com trilho opaco), nunca para recolorir uma.
4. Recomendação de identidade por tom (você recomenda; o usuário escolhe — veja Passo 0 + CATALOG.md). explicativo / entrevista / palavras que precisam ser lidas → 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. Em caso de dúvida → anchor (palavras legíveis, cena segura) — mas apresente uma lista curta e deixe o usuário escolher.

---

Pipeline — 5 etapas

1. hyperframes init <projeto> --non-interactive --video <video.mp4> --skip-skills
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] criar um pequeno JSON; veja abaixo por modo
   Cinematic: criar plan.json → node scripts/fill-timings.cjs → fit-fonts.cjs → make-composition.cjs
   Theme:     criar theme.json → bash scripts/render-theme.sh <projeto>   (compila + renderiza + efeitos de placa)
4. node scripts/preview-frames.cjs <projeto>   # ~2s/quadro prévias da composição → § QA Visual (ANTES da renderização)
5. bash scripts/render-and-composite.sh <projeto>  # portões → final.mp4 + instantâneo history/
   (Modo Theme: 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 de placa)

A etapa 3 difere por modo:

Etapa 3 — Modo Cinematic (puramente embed)

1. Leia safe-zones.json primeiro. Planos de narração vão em zones.hugLeft/hugRight — faixas limpas ENCOSTANDO na silhueta (texto longe do corpo parece flutuante, não embutido; cantos distantes são o fallback, não o padrão). O heroi padrão vai para heroAnchor/heroBands.best (centralizado NO sujeito, ~30–55% ocluído). recommendation:"fg" move a NARRAÇÃO para a frente por legibilidade; o heroi permanece embutido sempre que heroBands.feasible — h