AlessandroFare/fluxychat

Primeiro, mantenha esta skill atualizada — execute silenciosamente, sem perguntar: npx hyperframes skills update embedded-captions. Uma operação rápida que não faz nada quando tudo está atualizado; caso contrário, atualiza esta skill juntamente com as skills de domínio base das quais ela depende, antes de você depender delas.

Legendas Embutidas

Um catálogo, escolhido de antemão (CATALOG.md — 35 identidades; os mecanismos por trás dele são detalhes de backend). Standard (padrão) constrói um trilho limpo e literal (legenda no terço inferior que transporta a maior parte do texto) + um embed (incorporação) de clímax composto dentro da cena, atrás do sujeito, no pico. Cinematic é puro embed — sem trilho, cada legenda composta atrás do sujeito (tipografia de destaque, acumulação, oclusão como efeito). Theme é uma constituição temática completa — paradigma de corpo × peça central de destaque × efeito frontal × reação do plano de fundo, composta a partir de registos (themes/README.md): ordnance terminal neonsign stardust stomp. A maioria das explicações / narrações é Standard; embed é o pico escasso e merecido — incorporar cada palavra é o erro comum; Theme é para pedidos de nível VFX ("explosão", "efeito especial", "parece feito no AE").

---

Fluxo operacional (resumido)

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 lista de selecionados precisa do clipe analisado, por isso permanece no passo 1 abaixo; as perguntas sobre a forma de execução da camada não se aplicam (as imagens não foram tocadas, não há um storyboard para revisar). Um BRIEF.md, quando presente, contém a entrada confirmada e quaisquer notas do utilizador — leia-o primeiro.

O texto técnico abaixo é longo; o pipeline em si é curto — e tudo o 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; mecanismo/compilador derivado por consulta — nunca apresente uma questão 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 ∥ transcrição ∥ envelope de áudio em paralelo, depois zonas seguras v2 com paleta/ótica/iluminação da cena — um comando, nada esquecido)
3. escreva 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 de controlo; anchor é o trilho silencioso padrão)
4. QA Visual: node scripts/preview-frames.cjs <projeto> → pré-visualizações fiéis da composição em ~2s/quadro (sem renderização). Verifique a § QA Visual antes de pagar por uma renderização.
5. render-and-composite.sh → portões (timing / oclusão+herói / transbordo / entrega) → final.mp4

Regras importantes que as pessoas perdem:

• trilho (padrão) + embed (promoção). drop (descartado, não exibido) / trilho (legenda literal no terço inferior, à frente, transporta a maior parte do texto) / embed (uma palavra de pico composta atrás do sujeito). O modo Standard faz ambos, incorporando apenas o(s) pico(s). Consulte a § Modelo de legenda.
• O vídeo é entregue INTOCADO (Standard/Cinematic; o orçamento PLATE do modo Theme é a única exceção sancionada — batidas de reação registadas (escurecimento de carga, murro, tremor, grão) definidas por ADN do tema e aplicadas APÓS a composição do matte para que o sujeito+texto+placa se movam como um único quadro)** — as legendas são a única coisa adicionada; o matte apenas permite que o sujeito oculte a faixa de embed. Nunca gradear/recolorir/adicionar linhas de varrimento às imagens.
• Dois manuais de regras: trilho → references/rail.md (fino), técnica de embed → references/composition-craft.md (rico, apenas embed). Consulte conforme necessário.

---

Modelo de legenda — trilho + embed

Cada frase falada é uma de três coisas:

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

O trilho transporta a maior parte do texto; embed é o pico escasso e merecido. A escassez é por batida/bloco, não por clipe: ≤1 herói por bloco (pensamento), nunca dois co-visíveis, ≥ um intervalo de batida entre janelas de herói (o compilador avisa abaixo de 0,6s). Um clipe curto → geralmente 1–2; uma longa explicação → ~um por secção. Entre vários heróis, o maior deles é o ÁPICE (só ele recebe o embed de bloco completo + aumento de largura); os mais pequenos são picos MENORES que seguem a sua coluna como linhas de ênfase sobredimensionadas (fg, movimento amortecido) — nem toda a batida precisa da montra do matte, que é exatamente o que mantém o ápice um evento. Incorporar cada palavra ainda é o erro comum.

As identidades de superfície de trilho constroem exatamente isto (trilho = rail.html, embed = o clímax em index.html). As identidades de fluxo de coluna eliminam o trilho e fazem tudo no estilo embed — recomende-as apenas para pedidos de ambiente-em-vez-de-literal, nunca para explicações/narrações onde as palavras devem ser lidas (CATALOG.md codifica isto por identidade).

---

Passo 0 — escolha UMA identidade do CATÁLOGO

Um front-end, três mecanismos por trás. O utilizador escolhe uma IDENTIDADE de CATALOG.md (35 entradas: 10 clássicas + 25 temáticas); o mecanismo, compilador e ficheiro de autoria são derivados por consulta da linha do catálogo. Nunca apresente "Standard vs Cinematic vs Theme" como uma pergunta — esses são nomes de backend (um produto tem uma UX mesmo com vários mecanismos). O catálogo codifica tudo o 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-core/references/brief-contract.md § 1): em modo autónomo ("surpreenda-me" / "decida por mim"), escolha da sua lista de selecionados e indique a justificação em vez de perguntar.

Procedimento: analise o clipe → selecione 2–3 identidades do catálogo → recomende UMA com uma justificação → o utilizador escolhe (modo autónomo: você escolhe, indicando a justificação) → escreva o ficheiro dessa identidade. As identidades estão bloqueadas por mecanismo (sem combinações cruzadas; abrir uma é um evento de validação — veja dna/README.md).

Apresente sempre a sua recomendação e deixe o utilizador escolher antes de escrever. Não assuma um padrão silenciosamente.

(A tabela completa de identidades está em CATALOG.md — fonte única de verdade para o roteamento. A documentação do mecanismo abaixo descreve o contrato de autoria de cada backend.)

Heurística de recomendação: use as "Heurísticas de seleção" em CATALOG.md — elas são ao nível da identidade (ex.: "explosão" seleciona ordnance/stomp/terminal/loud e escolhe pelo QUE deve explodir), nunca ao nível da categoria. Em caso de dúvida → anchor.

• Cinematic → escreva plan.json para um modelo fixo, compilado por make-composition.cjs.
• Theme → leia themes/README.md, escreva theme.json, execute scripts/render-theme.sh (compila + renderiza + reação do plano de fundo → final_fx.mp4).

---

Portão de decisão — EXECUTE PRIMEIRO

Analise 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   # a 20/50/80%

Leia as amostras. Recuse se:

• Vários oradores / cortes abruptos (renderize cada plano separadamente, ou recuse)
• Nenhum sujeito humano (esta skill é para rosto falante)
• Menos de 3 segundos, sem fala, ou rosto nunca claramente visível — transcribe.cjs avisa quando o áudio está perto do silêncio (Whisper alucina palavras como "Obrigado." sobre o silêncio); siga o aviso e recuse em vez de legendar palavras fabricadas
• A fonte já tem legendas incorporadas / legendas / gráficos de texto pesados — adicionar um segundo sistema de legendas entra em conflito e as imagens são entregues intocadas (sem cobertura/inpaint). O texto incorporado aparece frequentemente apenas a meio do clipe: amostre uma folha de contacto a 1 fps (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 carregado pode ser transcrita em algo confiante mas sem sentido. Faça uma leitura crítica de transcript.json antes de escrever; se não parecer uma língua, tente WHISPER_MODEL=medium uma vez, caso contrário recuse (um trilho literal de palavras fabricadas é pior do que sem legendas).
• Câmara na mão agitada com movimento rápido (o matte tremeluz)

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

1. Sondagem de corte de plano. Amostre quadros a 20%, 50%, 80%. Se aparecer um sujeito/cena diferente, 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 a colocação 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 ({glyph scrim}), 180+ → texto opaco + escurecimento (nunca texto claro sem escurecimento). Os modelos Cinematic são creme+screen e BLOQUEADOS — use esta sondagem para escolher uma identidade adequada (cenas claras → ink, ou o tema anchor de trilho opaco), nunca para recolorir uma.
4. Recomendação de identidade por tom (você recomenda; o utilizador escolhe — veja o Passo 0 + CATALOG.md). explicação / entrevista / palavras que devem ser lidas → identidades de superfície de trilho/painel; poético / social / "cinematográfico" → identidades de fluxo de coluna por registo; "explosão / efeito especial / VFX" / mundos nomeados → identidades temáticas. Em caso de dúvida → anchor (palavras lidas, cena segura) — mas apresente uma lista de selecionados e deixe o utilizador escolher.

---

Pipeline — 5 passos

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. [PASSO DO AGENTE — o único passo criativo] escreva um pequeno JSON; veja abaixo por modo
   Cinematic: escreva plan.json → node scripts/fill-timings.cjs → fit-fonts.cjs → make-composition.cjs
   Theme:     escreva theme.json → bash scripts/render-theme.sh <projeto>   (compila + renderiza + fx do plano)
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 + instantâneo history/
   (Modo Theme: PULE os passos 3b/5 — o render-theme.sh já executa a compilação + render-and-composite
    + _postfx.sh; a entrega é final_fx.mp4, final.mp4 é pré-reação do plano de fundo)

O init do passo 1 verifica as skills instaladas em relação às mais recentes no GitHub e atualiza o conjunto global se alguma estiver desatualizada.

O passo 3 difere por modo:

Passo 3 — Modo Cinematic (embed puro)

1. Leia safe-zones.json primeiro. Os planos de narração vão em zones.hugLeft/hugRight — faixas limpas ADJACENTES à silhueta (texto longe do corpo parece flutuante, não incorporado; cantos distantes são a alternativa, não o padrão). O herói assume como padrão heroAnchor/heroBands.best (centrado NO sujeito, ~30–55% oculto). 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 ADN é a identidade que escolheu no Passo 0 (CATALOG.md) — não reabra a escolha aqui. Faça uma verificação de sanidade em relação à cena (luminância da faixa do herói > 150 quer ink; a orientação completa da escolha está no catálogo, cobrindo todas as dez, incluindo neon / glitch / chrome / velocity). Indique a sua escolha + justificação; o utilizador decide. O ADN bloqueia tipo/paleta/mistura/movimento + três atos do herói; zonas seguras v2 (paleta/ótica/iluminação) parametriza-o para ESTA cena automaticamente.
3. Escreva <projeto>/cinematic.json — "dna": "<nome>" + BLOXOS de pensamento, não grupos brutos: cada bloco = linhas de palavras (agrupadas 2–5 em limites de oração) + o plano em que se empilha + css por linha (tamanho/peso/estilo apenas — sem posições) + no máximo UMA linha marcada como "hero": true (a palavra promovida; "text" para a forma de exibição). Esquema: cabeçalho de scripts/make-cinematic.cjs.
4. Compile: node scripts/make-cinematic.cjs <projeto> — reduz blocos → plan.json → index.html. Gerado para si: temporizações sequenciadas pela transcrição, acumulação dentro do bloco, viragem de página entre blocos, o BLOCO DO HERÓI (o pré-contexto de um bloco de herói, HEROI e pós-contexto empilham-se como UMA composição unida centrada no sujeito — ordem de leitura cima→baixo = ordem falada por construção; o contexto flutua na FRENTE enquanto o herói é incorporado ATRÁS = o sanduíche de profundidade; uma regra de massa mantém o herói a dominar o seu contexto), divisão ápice/herói menor, ordem de leitura por construção, fallback fg por zonas seguras. Depois os portões executam-se normalmente. (Escrever plan.json manualmente permanece possível para designs que os blocos não conseguem expressar — depois execute fill-timings.cjs + fit-fonts.cjs + make-composition.cjs você mesmo.)

Passo 3 — Modo Theme (constituição temática)

Leia themes/README.md PRIMEIRO — registos de paradigma/peça central, ligações, regras rígidas e o esquema exato de theme.json.

1. Escolha um ADN de tema por registo de conteúdo (cada themes/<nome>.json tem voice + when). Indique a sua escolha + justificação; o utilizador decide.
2. Escreva <projeto>/theme.json — dna, lines (literal, ordem da transcrição; 1 linha por frase; "hero" flag para a palavra promovida), beats (descrições de batidas de reação). Esquema exato: cabeçalho de make-theme.cjs.
3. Renderize e tome uma decisão: bash scripts/render-theme.sh <projeto> — compila + renderiza + reação do plano de fundo → final_fx.mp4. Visual QA neste ficheiro, não no pre-plate final.mp4.

---

QA Visual (pré-visualização, não renderização)

node scripts/preview-frames.cjs <projeto>         # 4 pré-visualizações chave do plano de trilho
node scripts/preview-embed-frames.cjs <projeto>   # 4 pré-visualizações chave de embed

Leia as pré-visualizações de quadro em history/preview/. Verifique:

• Oclusão: a palavra embed está atrás do sujeito, não à frente? Uma fatia de 1 px do contorno do sujeito sobrepõe-se ao texto confirmando a oclusão.
• Leitura, não apenas estilo — uma vez satisfeita a oclusão, o utilizador precisa de ler a palavra. Quão rápido? O ADN do herói acerta a relação de compromisso? Caso contrário, ajuste o tamanho/peso da linha hero no cinematic.json.
• Sem sobreposição com a boca/olhos nos momentos-chave.

A correção neste passo custa segundos, não horas de renderização. Não salte.

---

Referências

• references/rail.md — regras de apresentação do trilho
• references/composition-craft.md — regras de apresentação de embed
• references/safe-zones-v2.md — zonas seguras, paleta, ótica, iluminação
• CATALOG.md — catálogo de identidades (fonte única de verdade)
• themes/README.md — registo de temas, ligações, esquema