Produzir Vídeo
Receba uma gravação fornecida pelo usuário e transforme-a em um vídeo finalizado. A gravação é a espinha dorsal e dita a linha do tempo; esta skill edita (silêncio + erros/ritmo escolhidos) e aumenta (sobreposições), depois renderiza e gera conteúdo de lançamento. Ela NÃO cria um vídeo sintético — para vídeos promocionais sintéticos orientados a PR, use hyperframes-video.
Princípio de qualidade (innegociável): cada etapa de manipulação do vídeo preserva a qualidade original. Nunca deixe uma ferramenta re-codificar o vídeo em baixa qualidade. A remoção de silêncio e cortes são executados com CRF 12 quase sem perdas a partir do original (o auto-editor é usado apenas para DETECTAR silêncio, nunca para codificar — seu padrão esmaga o vídeo para ~0,6 Mbps), e a renderização é feita com CRF 12. CRF gera arquivos pequenos para screencasts estáticos; isso é qualidade total, não perda.
Relação com outras skills (delegue, não re-derive)
/transcribe-video— toda transcrição (retornatranscript.words.jsonem nível de palavra). Invoque-a; não transcreva manualmente.hyperframes— regras de criação de composição (Portão de Identidade Visual, Layout Antes de Animação, contrato de linha do tempo, camadas de vídeo/sobreposição). Invoque antes de escrever/montar qualquer HTML de composição.hyperframes-cli— todos os comandosnpx hyperframes(init, lint, inspect, preview, render).gsap— padrões de linha do tempo/easing GSAP para sobreposições.youtube-copy— título/descrição/tags/capítulos do YouTube (P6).blog-post— o post do blog (P6).social-copy— cópia para X/Bluesky/LinkedIn/Reddit (P6).
Assets incluídos
scripts/desilence.mjs— remoção de silêncio do auto-editor + duração antes/depois.scripts/extract-frame.mjs— captura de quadro único (detecção de enquadramento + destaque na tela).scripts/bake-cuts.mjs— cortador ffmpeg trim/concat (keyframes densos) usado em P2.templates/overlays/*.html— 9 modelos de sub-composição de sobreposição (preenchidos por instância; sub-comps são documentos HTML independentes na CLI instalada — leia o comentário de cabeçalho de cada arquivo).templates/project/{DESIGN.md,styles.css}— Portão de Identidade Visual + tokens de marcavar(--brand-*)que as sobreposições consomem.references/—mistake-detection.md,overlay-triggers.md,framing-safe-zones.md,frame-analysis.md.- A geração de conteúdo P6 é delegada às skills
youtube-copy,blog-postesocial-copy(nenhum script LLM interno).
Portões (innegociáveis)
- A revisão de erros P2 é VISUAL, nunca por terminal — sempre que ≥1 sinalizador existir, o agente SEMPRE constrói a prévia com marcadores do hyperframes (marcadores no vídeo em cada intervalo sinalizado) e a inicia, para que o usuário decida assistindo. NÃO apresente os sinalizadores como uma tabela de terminal/pergunta para o usuário decidir, e NÃO torne a prévia opcional ou pergunte "quer que eu mostre?" — apenas construa-a e abra-a. Um breve resumo no terminal dos sinalizadores é aceitável, mas a superfície de decisão é a prévia. Nunca aplique automaticamente um corte/rampa.
- Aprovação do plano de sobreposição P4 — apresente a tabela de sobreposições com timestamps; nenhuma construção até aprovação.
- Prévia sempre iniciada pelo agente — tanto para a revisão P2 quanto para a revisão P5, o agente inicia
npx hyperframes previewe abre a aba do navegador por si mesmo. NUNCA peça ao usuário para executar a prévia ou abrir uma URL, e NUNCA substitua uma prévia ao vivo por um resumo apenas de terminal. - PORTÃO DURO de renderização explícita — a renderização é executada SOMENTE mediante um comando explícito do usuário para renderizar ("renderizar", "pode mandar ver"). Após uma renderização, os pedidos de edição retornam ao loop de prévia e NÃO re-renderizam até que o usuário diga explicitamente novamente. Cada renderização precisa de seu próprio comando novo. Isso substitui qualquer fraseologia "use padrões sensatos / não interativo / apenas envie".
"Use padrões sensatos" / "não faça perguntas" pula as perguntas de configuração (P0) e a iteração de prompt — isso NUNCA pula os portões de aprovação, a prévia iniciada pelo agente ou o portão de renderização explícita.
Processo
Pré-voo — verifique dependências & skills (execute PRIMEIRO, antes de P0)
Verifique o ambiente antes de fazer qualquer trabalho; avise o usuário sobre qualquer coisa faltando e como corrigi-la.
- auto-editor (obrigatório para P1 remoção de silêncio): execute
auto-editor --version. Se não estiver instalado, PARE e diga ao usuário: "auto-editor não está instalado - instale compipx install auto-editor(oupip install auto-editor), depois execute novamente." Não tente P1 sem ele. - ffmpeg / ffprobe (OBRIGATÓRIO — cortes P2, análise de quadro P4, renderização P5, áudio): execute
ffmpeg -version. Se estiver faltando, PARE e diga ao usuário para instalar o ffmpeg e adicioná-lo ao PATH. O pipeline não pode ser executado sem ele. - Docker (para
/transcribe-video):docker info. Avise se o daemon estiver parado (inicie o Docker Desktop). - Node >= 22:
node --version. Avise se for mais antigo. - Skills obrigatórias — confirme se estão disponíveis (tente invocar / verificar a lista de skills); avise para qualquer uma faltando e qual fase ela bloqueia:
transcribe-video(transcrição P2/P3),hyperframes+hyperframes-cli+gsap(composição e renderização P2/P4/P5),youtube-copy+social-copy(P6).blog-postapenas se o usuário optar por um blog (P6, opcional).
- Resuma o resultado do pré-voo em um bloco curto (o que está presente, o que está faltando). Só prossiga além de uma dependência/skill obrigatória faltando se o usuário disser explicitamente para continuar sem ela (e observe o resultado degradado).
P0 — Entrada e configuração
- Entrada: caminho para a gravação bruta (obrigatório).
- Opcional: um repositório/arquivos para base de código real; estilo visual/marca (caso contrário, execute o Portão de Identidade Visual do
hyperframes— detecte a partir do repositório, caso contrário, faça 3 perguntas de estilo; escrevatemplates/project/DESIGN.md+ valores de marca emstyles.css); densidade de sobreposição (esparsa / equilibrada / rica). - Pasta de saída única (
<OUT>): tudo que esta skill produz reside em UMA pasta, por padrão<recording-dir>/<video-slug>-produced/(substituível por um caminho fornecido pelo usuário). Crie-a agora. Estrutura final:
Todas as fases subsequentes escrevem dentro de<OUT>/ final.mp4 # vídeo renderizado (P5) hyperframes/ # o projeto HyperFrames: index.html, styles.css, DESIGN.md, compositions/, renders/ (P4–P5) transcript.txt # transcrição final editada (P3 / P6) transcript.srt transcript.words.json youtube.md # P6 socials.md # P6 blog.md # P6 .work/ # intermediários: 01_desilenced.mp4, 02_edit_N.mp4, frames/ (removível em P7)<OUT>— nunca espalhe saídas em outros lugares.<work>abaixo =<OUT>/.work.
P1 — Remoção de silêncio (sem perdas)
node scripts/desilence.mjs <input> --out <work>/01_desilenced.mp4 --margin 0.3s
desilence.mjs usa auto-editor APENAS para detectar os intervalos silenciosos (--export v3), depois corta o ORIGINAL com ffmpeg em CRF 12 quase sem perdas, mantendo o áudio original. NÃO deixe o auto-editor codificar a saída — sua re-codificação padrão esmaga o vídeo para ~0,6 Mbps e o desfoca permanentemente (rostos especialmente); nenhum bitrate downstream pode recuperar isso. Relate a duração antes/depois e os segundos removidos. Esta se torna a cópia de trabalho.
P2 — Loop de revisão de erros e ritmo (portão de aprovação)
- Transcreva a cópia de trabalho: invoque
/transcribe-videoem<work>/01_desilenced.mp4com--out <work>→ transcrição de trabalho (intermediária; substituída pela transcrição final P3). - Detecte sinalizadores conforme
references/mistake-detection.md(cortes + rampas de velocidade), ajustados aos limites de palavras. - Sempre (quando ≥1 sinalizador existir) construa a prévia visual. Monte um projeto hyperframes leve com o vídeo sem silêncio como trilha base; coloque marcadores temporários visualmente distintos NO VÍDEO em cada intervalo sinalizado (corte = listra vermelha, rampa = avanço rápido âmbar, cada um rotulado com o trecho + seu índice). O agente inicia
npx hyperframes previewe abre o navegador por si mesmo (conformereferences/framing-safe-zones.md). Esta é a superfície de decisão — nunca a substitua por uma tabela de terminal. Uma nota de terminal de uma linha ("3 sinalizadores marcados na prévia — revise e me diga quais cortar/rampar/manter") é o máximo que o terminal deve conter. - O usuário assiste à prévia marcada e escolhe por intervalo: cortar / rampa de velocidade (fator, padrão ~1,5–2×) / deixar / adicionar seus próprios intervalos.
- Aplique seleções →
<work>/02_edit_N.mp4, depois re-prévia:- Cortes: use
node scripts/bake-cuts.mjs <input> --out <work>/02_edit_N.mp4 --cut s,e --cut s,e …(ffmpeg trim/concat em CRF 12 quase sem perdas por padrão — corta vídeo+áudio identicamente em uma passada). NÃO use auto-editor--cut-outpara os cortes de erro — seu argumento variádico atribui erroneamente o último intervalo como entrada posicional, re-codifica com perdas, e uma abordagem de filtro select dessincroniza o áudio. - Rampas de velocidade: auto-editor
--set-speed-for-range speed,s,e(tom preservado); passe UM intervalo por invocação, ou coloque--set-speed-for-rangepor último na linha de comando, para evitar a mesma armadilha de argumento variádico. - Todos os timestamps de corte/rampa estão na linha do tempo sem silêncio (a transcrição de onde vieram os sinalizadores). Aplique cortes e rampas na mesma rodada contra essa linha do tempo.
- Cortes: use
- Looping até o usuário dizer "pronto". Guarda contra deriva: após ~10 rodadas, ofereça para redefinir para um intermediário anterior. Artefato final:
<work>/final_cut.mp4.
Cortes e rampas são aplicados ao vídeo AQUI (antes de P3) para que os timestamps de palavra da transcrição final correspondam à linha do tempo editada.
P3 — Transcrição final
Invoque /transcribe-video em <work>/final_cut.mp4 com --out <OUT> para que transcript.txt / transcript.srt / transcript.words.json caiam no topo da pasta de saída. Esta transcrição com timestamps de palavra é a fonte de sincronia para todas as sobreposições (P4) e a entrada para a geração de conteúdo (P6).
P4 — Design e construção de sobreposição (portão de aprovação)
- Detecção de enquadramento (
references/framing-safe-zones.md): amostre quadros comextract-frame.mjs, classifique fases, confirme fases + zonas seguras com o usuário. - Detecção de gatilho de sobreposição (
references/overlay-triggers.md): escaneie a transcrição com timestamps de palavra → linhas do plano de sobreposição{start, est_duration, type, content, safe_zone, why}. Para código na tela, usereferences/frame-analysis.md(extrair quadro → localizar → caixa normalizada → guarda de estabilidade). Para cartões de código, repositório-se-disponível-senão-sintetize (sinalize sintetizado). - Passagem de autoaperfeiçoamento (≥2 iterações): respeite densidade, imponha intervalos mínimos + tempos de permanência mínimos, valide cada sobreposição contra a zona segura da fase ativa.
- Portão de aprovação: apresente a tabela com timestamps; o usuário edita/remove/re-temporiza/adiciona. Código sintetizado mostrado para verificação. Nenhuma construção até aprovação.
- Construção (invoque
hyperframes+gsapprimeiro):npx hyperframes init <OUT>/hyperframes --video <OUT>/.work/final_cut.mp4(o projeto vive em<OUT>/hyperframes; base: faixa de vídeo 0muted playsinline; áudio em uma faixa separada no volume 1 para que a voz toque). Leia oindex.htmlgerado para aprender a sintaxe de inclusão de sub-composição desta versão da CLI.- Copie
templates/project/styles.css(com os valores de marca confirmados) para<OUT>/hyperframes. - Para cada linha aprovada: instancie o
templates/overlays/*.htmlcorrespondente, dê a ele um id de composição único +data-composition-id, preencha seus{{tokens}}, definadata-start= o timestamp da transcrição edata-duration= o tempo de permanência, monte-o acima do vídeo. Zooms de aproximação escalam o div INVOLUCRO do vídeo (nunca o<video>). - Dimensões de saída herdam a gravação original.
- Legibilidade (innegociável): todo texto de sobreposição deve ser claramente legível sobre QUALQUER fundo de vídeo. Cada grupo de texto repousa em um painel escuro quase opaco (
rgba(8,10,14,0.92), arredondado, borda/sombra sutil); títulos/corpo são brancos (var(--brand-text)), secundário/kicker/meta são ardósia clara (#CBD5E1). NUNCA usevar(--brand-accent)/var(--brand-primary)para texto de corpo/subtítulo/kicker — destaque é para barras, bordas, varreduras de marcador, ícones e palavras grandes de exibição apenas (e apenas quando atingirem ~4,5:1 no painel). Quando estiver em dúvida, torne o texto branco.npx hyperframes validate(contraste WCAG) deve passar com zero avisos de contraste.
P5 — Prévia e renderização (prévia iniciada pelo agente obrigatória + portão de renderização explícita)
npx hyperframes lint+npx hyperframes inspect(transbordamento + zonas seguras) +npx hyperframes validate(contraste). Corrija até ficar limpo.- O agente inicia
npx hyperframes previewe abre o navegador. Loop de iteração livre sobre sobreposições. - Auditorias pré-renderização: cada sobreposição na zona segura de sua fase; tempos de permanência mínimos; nenhuma duas sobreposições disputando a mesma região simultaneamente; lint/inspect/validate limpos.
- Somente mediante comando explícito do usuário para renderizar: renderize em CRF 12 quase sem perdas. A qualidade padrão
standardcodifica em ~1,4 Mbps e esmaga visivelmente o vídeo; sempre passe um CRF baixo:
(execute a partir denpx hyperframes render --output <OUT>/final.mp4 --crf 12<OUT>/hyperframes. CRF 12 é quase sem perdas; NÃO use--video-bitrateesperando um arquivo grande — para screencasts estáticos, CRF produz um arquivo pequeno com qualidade total, e isso é correto, não baixa qualidade.) O mp4 final mantém o áudio original. Após a renderização, novas edições retornam ao loop e exigem um novo comando explícito de renderização. - Nota de qualidade: a captura do Chrome é uma captura de tela 1:1 sem perdas (verificado: entrada da renderização == saída tanto para texto quanto para rostos), então uma renderização com CRF baixo preserva o vídeo conforme fornecido. A ÚNICA coisa que destrói a qualidade é uma etapa upstream com perdas — e é por isso que a remoção de silêncio P1 e os cortes P2 são executados em CRF 12 quase sem perdas a partir do original. Não adicione passagens extras de re-codificação. Para vídeo com zero gerações absoluto, um caminho avançado é renderizar apenas sobreposições em um
--format webm/movtransparente e compostá-los com ffmpeg sobre o vídeo cortado (zoom de aproximação então aplicado via ffmpeg) — raramente necessário.
P6 — Geração de conteúdo (delegada a skills especializadas)
Gere o conteúdo de lançamento invocando skills dedicadas, cada uma na transcrição final editada (P3 — passe o transcript.srt com timestamps para que os capítulos do YouTube obtenham tempos precisos), escrevendo cada saída em <OUT>:
youtube-copy→<OUT>/youtube.md(título, descrição, tags, capítulos).social-copy→<OUT>/socials.md(postagens para X, Bluesky, LinkedIn, Reddit).blog-post→<OUT>/blog.md(apenas se o usuário optar por um post de blog; sempre verifique primeiro). Confirme brevemente com o usuário se um post de blog é desejado ("Gostaria de um post de blog também?").
P7 — Relatório de resumo + limpeza
Imprima um resumo curto no terminal:
- Caminho do vídeo final:
<OUT>/final.mp4(duração, resolução, taxa de bits). - Estatísticas de transcrição: palavras totais, duração falada, cortes manuais.
- Contagem de sobreposições por tipo.
- Caminhos para conteúdo gerado (youtube.md, socials.md, blog.md se criado).
- Espaço em disco usado pela pasta de trabalho
<OUT>/.worke sugestão: "Os intermediários em.work/podem ser removidos comrm -rf <OUT>/.workpara economizar espaço, mas se quiser regenerar transcrições ou ajustar a edição, mantenha-os."
Notas de implementação
Por que não usar auto-editor para codificar
O codificador libx264 padrão do auto-editor com seu perfil fast + crf 23 (ou pior, seu padrão de ~0,6 Mbps) produz vídeo permanentemente destruído: rostos tornam-se borrões, o texto fica ilegível. Nenhuma re-codificação downstream pode restaurar essa informação — é uma perda irreversível. O desilence.mjs usa auto-editor APENAS para detectar silêncio (--export v3), depois corta o original com ffmpeg em CRF 12. Esta é a única maneira de remover silêncio sem danificar o vídeo.
Por que CRF 12 para screencasts
Screencasts estáticos (IDE, terminal, slides) se beneficiam do controle de taxa de bits adaptável do CRF: cenas estáticas usam muito poucos bits, enquanto cenas de movimento (animações, transições de slides) usam mais. CRF 12 é visualmente sem perdas para screencasts; valores mais baixos (CRF 0) produzem arquivos enormes sem ganho perceptível. Um CRF alto (23, 28) introduz macro-bloqueio e artefatos de ringing em texto — inaceitável para vídeos de programação.
Por que colar cortes e rampas na mesma linha do tempo
Ambas as operações modificam a linha do tempo de maneiras que afetam os timestamps de palavra da transcrição. Aplicá-las em sequência (cortes primeiro, depois rampas) na mesma linha do tempo base garante que a transcrição final (P3) corresponda perfeitamente ao vídeo editado. Se as rampas fossem aplicadas após a transcrição, os timestamps de palavra não se alinhariam com o áudio acelerado.
Convenções de nomenclatura
- IDs de composição:
overlay-{type}-{N}(ex:overlay-section-0). - Marcadores de prévia P2: IDs
marker-cut-{N}emarker-ramp-{N}, cada um com um atributodata-flag-index. - Nomes de arquivo no projeto hyperframes:
<OUT>/hyperframes/compositions/overlay-{id}.html.
Gerenciamento de estado entre fases
A pasta <OUT> e seus conteúdos são a única fonte da verdade. Cada fase escreve artefatos em locais previsíveis dentro de <OUT>; fases posteriores os leem. Se uma fase falhar, as saídas escritas até o ponto da falha permanecem, permitindo retomar da última fase concluída, corrigindo a entrada e invocando a skill novamente.
Tratamento de erros
- Falha na detecção de silêncio (P1): se
desilence.mjslançar, verifique se o arquivo de entrada existe e é um vídeo válido, se o auto-editor está instalado e se há espaço em disco suficiente. Tente novamente com--margin 0.2s(margem mais apertada). - Falha na transcrição (P3): se
/transcribe-videofalhar, tente novamente. Se falha persistente, ofereça transcrição usando Whisper local (whisper.cpp) como fallback. - Falha na renderização (P5): verifique espaço em disco, memória, e se o Chrome/Chromium está instalado (hyperframes usa Puppeteer). Tente
npx hyperframes render --format webmcomo fallback (saída webm sem perdas).