/hyperframes-best-practices
Use este skill sempre que estiver transformando uma gravação de screencast bruta, talking-head ou exportação do OBS em um vídeo de produto HyperFrames polido. Ele reúne duas camadas de conhecimento:
- Fundamentos do HyperFrames — os arquivos de regra upstream mantidos pela HeyGen em
github.com/heygen-com/hyperframes(criação de composição, linhas do tempo GSAP, atributosdata-*, CLI do dev-loop). Instale vianpx vskill i heygen-com/hyperframes. - Regras de produção — lições capturadas de um longo ciclo de iteração construindo um vídeo de produto SpecWeave real a partir de uma única gravação OBS de 8:47. Estas são as regras que, quando seguidas, produzem um vídeo que o usuário pode realmente publicar — e, quando quebradas, deixam você com bipes, cortes no meio de palavras, cenas de herói vazias e sobreposições que bloqueiam a câmera do rosto do palestrante.
Leia ambas as camadas antes de criar.
Escopo e aplicabilidade
As regras de produção da Camada 2 abaixo foram derivadas de um projeto específico: transformar uma gravação de introdução SpecWeave de 8:47 (Anton Abyzov, captura OBS, talking-head + compartilhamento de tela, maio de 2026) em um vídeo promocional de 6:00 pronto para produção. Elas refletem a aparência daquele produto — a estética de cartão colorido do Studio, a paleta roxa/verde do SpecWeave, um estilo de sobreposição de cartão iOS e as realidades técnicas das gravações OBS (ticks de início/parada, transientes de retomada de gravação, takes duplicados de regravar a mesma linha três vezes).
As constantes exatas são específicas do projeto — posições de sobreposição para aquela localização da câmera de rosto, o texto de correção
Boris Cherny / Anthropic, as estatísticas600+/500+/3K+— traduza, não copie.Use esta camada como referência para a técnica subjacente: o algoritmo de corte inteligente baseado em transcrição, o fade-in por clipe para supressão de transientes, o pipeline de renderização com filtro
concatque evita cliques do demuxer concat, o removedor cirúrgico de bipes com mudo, o padrão de sobreposição de cartão iOS, o mapeamento de tempo de origem → tempo de corte, a pegadinha de invalidação do cache de forma de onda do Studio — esses generalizam.
Quando usar
Ative este skill quando QUALQUER um destes se aplicar:
- Um usuário tem um screencast bruto ou gravação OBS e deseja um vídeo mais enxuto, legendado e com marca.
- A fonte tem silêncio, pausas de silêncio ou takes duplicados do tipo "deixe-me tentar de novo".
- A fonte tem cliques, bipes ou artefatos transitórios nos limites da gravação.
- O usuário deseja sobreposições gráficas (destaques, cartões de estatísticas, revelações de marca, logotipos de ferramentas) que não cubram a câmera do rosto do palestrante.
- O usuário disse as palavras "deixar isso pronto para produção" ou "pronto para publicar".
- O usuário mencionou querer "estilo Apple-keynote" ou "cartões flutuantes iOS" ou "vidro fosco".
Se QUALQUER um desses sinais estiver presente, siga este fluxo de trabalho. Se o usuário só quiser um cartão de título rápido em uma fonte limpa, o skill hyperframes upstream por si só é suficiente.
O pipeline (10 fases)
┌──────────────────────────────────────────────────────────────────┐
│ Fase 0 Inventariar ferramentas │
│ Fase 1 Sondar a fonte (duração, codec, taxa de amostragem de áudio)│
│ Fase 2 Transcrever com Whisper (timestamps em nível de palavra) │
│ Fase 3 Detectar silêncios + mudanças de cena │
│ Fase 4 Construir a lista de cortes inteligentes (com buffers de │
│ borda de palavra) │
│ Fase 5 Remover bipes transitórios (mudo cirúrgico + adeclick) │
│ Fase 6 Renderizar o mestre via filtro concat (passagem única) │
│ Fase 7 Gerar imagens de herói (Gemini 3 Pro Image) │
│ Fase 8 Criar a composição HyperFrames (cartões iOS) │
│ Fase 9 Lint + verificar no Studio │
└──────────────────────────────────────────────────────────────────┘
Execute as fases sequencialmente. Itere dentro de uma fase, não entre fases — uma lista de cortes ruim quebra o tempo de cada sobreposição a jusante, e você passará uma hora re-resolvendo âncoras. Primeiro, acerte a lista de cortes, depois renderize uma vez, e então construa as sobreposições contra a linha do tempo final.
Fase 0 — Inventariar ferramentas
Antes de começar, confirme que estas estão disponíveis. O skill assume macOS / Linux; no Windows use WSL.
| Ferramenta | Usada para | Instalação |
|---|---|---|
ffmpeg (>= 6.0) | Todo o processamento de áudio/vídeo | brew install ffmpeg |
ffprobe | Inspeção de fluxos | incluído com ffmpeg |
whisper (pkg Python OpenAI) | Transcrição com timestamps de palavra | pip install openai-whisper |
python3 | Scripts de lista de cortes / removedor de bipes | sistema |
npx hyperframes@latest | CLI de composição (visualizar, renderizar, lint) | npx hyperframes init <projeto> |
| API Gemini 3 Pro Image | Imagens de herói (opcional) | variável de ambiente GEMINI_API_KEY |
vskill (>= 1.0) | Instalação de skills | npm i -g vskill |
Se o Whisper não estiver instalado, pip install openai-whisper o trará. Não use large-v3 ou large-v3-turbo na CPU — eles levam de 10 a 15 minutos para um áudio de 8 minutos. Use base.en para monólogo técnico em inglês: ~30s, suficientemente preciso para limites de palavra.
Se um usuário tiver auto-editor instalado em sua máquina, ignore-o — ele faz cortes de silêncio, mas não remove bipes ou buffer de borda de palavra, e gera cortes fragmentados de 50+ segmentos. Nós fazemos melhor manualmente.
Fase 1 — Sondar a fonte
Antes de fazer qualquer outra coisa, aprenda a forma do arquivo:
ffprobe -v error -show_entries stream=index,codec_type,codec_name,width,height,r_frame_rate,duration,sample_rate,channels \
-show_entries format=duration,size,bit_rate -of json "$SRC" | tee source_meta.json
Coisas que você deve saber:
- Duração total — orienta toda a matemática de corte.
- Taxa de quadros — OBS frequentemente grava a 60 fps; o HyperFrames Studio reproduz a 30 fps internamente para navegação. Multiplique segundos × 30 para obter números de quadro do Studio, não segundos × fps-da-fonte. Isso pega as pessoas de surpresa.
- Codec de áudio e taxa de amostragem — OBS comumente grava
pcm_s24lea 48 kHz. Re-codifique para AAC 192k para entrega; mantenha 48 kHz para corresponder a todas as ferramentas downstream. - Container —
.movdo DaVinci,.mkvdo OBS — ambos bons, ffmpeg lê qualquer um.
Salve a sonda em disco para que fases posteriores possam relê-la sem nova sondagem.
Fase 2 — Transcrever com Whisper
Timestamps em nível de palavra são a base. Sem eles você não pode:
- Ajustar os limites de corte às margens das palavras (evitando cortes no meio da palavra).
- Detectar takes duplicados (a mesma linha dita 2-3 vezes).
- Colocar âncoras de sobreposição contra momentos de fala, em vez de tempos de corte que flutuam.
Extraia o áudio primeiro para que o Whisper receba um WAV mono limpo de 16 kHz (economiza 80% de CPU vs. qualidade total):
mkdir -p .work
ffmpeg -hide_banner -y -i "$SRC" -vn -ac 1 -ar 16000 -c:a pcm_s16le .work/source.wav
Execute o Whisper com timestamps de palavra e saída JSON:
whisper .work/source.wav \
--model base.en \
--language en \
--word_timestamps True \
--output_dir .work \
--output_format json \
--verbose False
⚠️ Pegadinha da CLI do Whisper: passar --output_format json --output_format srt mantém apenas o último sinalizador em versões mais antigas. Se você precisar de vários, use --output_format all (escreve JSON + SRT + VTT + TSV + TXT).
Valide a saída: .work/source.json deve conter segments[].words[] com start, end, word. Se words estiver vazio, você esqueceu --word_timestamps True.
Leia a transcrição completa neste estágio. Não pule. Você identificará:
- Interpretações errôneas de nomes de marca. O Whisper ouve "Claude Code na Anthropic" como "Cloud Code na Infropic" 90% das vezes. "SpecWeave" sai como "spec with" ou "specs". Estas precisam de correções de sobreposição, não de regravação.
- Takes duplicados. Procure pela mesma frase repetida palavra por palavra. Em nosso projeto, "And those systems cannot produce skills as you work" apareceu três vezes em 01:14, 01:30, 01:47. Descarte duas delas.
- Reinícios de preenchimento. Fragmentos de palavra única como "And…", "And…" precedendo a frase real. O script de corte os captura como segmentos "fantasmas" — nós os descartamos na fase 4.
Fase 3 — Detectar silêncios e mudanças de cena
Duas detecções paralelas alimentam o algoritmo de corte:
3a. Detecção de silêncio
ffmpeg -hide_banner -nostats -i "$SRC" -af "silencedetect=noise=-30dB:duration=1.2" -f null - 2>&1 \
| grep -E "silence_(start|end)"
-30 dB e 1.2s são o ponto ideal. Mais frouxo (-25 dB, 0.8s) captura pausas de respiração que você não deseja cortar. Mais apertado (-35 dB, 2s) perde silêncio real.
Analise os pares início/fim em [(s, e, dur), ...] e escreva em silences.json. Veja scripts/build_cuts.py.
3b. Detecção de mudança de cena
ffmpeg -hide_banner -nostats -i "$SRC" -filter:v "select='gt(scene,0.05)',showinfo" -f null - 2>&1 \
| grep "showinfo" | grep -oE "pts_time:[0-9.]+" | sed 's/pts_time://' > scenes.txt
scene>0.05 é suficientemente sensível para capturar o palestrante abrindo uma nova aba do navegador, trocando de aplicativo, rolando significativamente. Não vá abaixo de 0.03 — você terá falsos positivos de piscadas do cursor.
Estes dois juntos permitem que você tome a decisão de corte inteligente: silêncio + nenhuma mudança de cena = tempo morto puro, corte. Silêncio + mudança de cena = o palestrante está mostrando algo na tela, mantenha (a audiência deve olhar para a tela, não ouvir narração).
Fase 4 — Construir a lista de cortes inteligentes
O algoritmo de corte tem 5 regras rígidas aprendidas da maneira mais difícil:
Regra 1 — Tempo morto puro é cortado, mas não todo ele
Para cada segmento silencioso > MIN_CUT_LEN (1.5s) sem mudança de cena interna: corte tudo, exceto uma RESPIRAÇÃO de 0.30s. A respiração preserva o ritmo natural — eliminar 100% do silêncio faz a fala soar editada por máquina.
if not in_scenes and (cut_end - cut_start) > MIN_CUT_LEN:
cuts.append((cut_start + 0.30, cut_end, f"tempo morto {dur:.1f}s"))
Regra 2 — Silêncios com atividade na tela permanecem (limitados a 3.5s)
Se o silêncio tem mudanças de cena, o palestrante está deixando a audiência ler. Mantenha a janela de primeira_cena - 0.4s a ultima_cena + 0.8s, mas nunca mais de 3.5s — olhar fixo para um quadro por mais de 3.5s perde o público.
Regra 3 — Ajustar aos limites das palavras
Após calcular as faixas aproximadas de manutenção, ajuste cada limite ao limite de palavra mais próximo do Whisper, dentro de uma tolerância de 0.4s:
def snap(t, words):
best, bd = t, 0.4
for s, e, _ in words:
for cand in (s, e):
if abs(cand - t) < bd:
best, bd = cand, abs(cand - t)
return best
Isto é o que impede que os cortes interrompam palavras no meio. Sem isso, a cada dois cortes um 's' final ou consoante de respiração é cortado.
Regra 4 — Adicionar buffers de borda de palavra (este é o que os usuários notam)
Mesmo com o ajuste à borda da palavra, consoantes finais se estendem ligeiramente além do timestamp de fim de palavra relatado pelo Whisper. O Whisper cronometra o início da vogal ao fim da vogal, não a cauda da consoante. Portanto, um corte literal em word.end corta o 's' final, a respiração ou o 'k'.
A correção: estenda cada faixa de manutenção:
- Fim:
+ 0.30sapós o fim da última palavra, limitado a metade do intervalo para a próxima faixa. - Início:
- 0.10santes do início da primeira palavra, limitado a metade do intervalo para a faixa anterior.
END_BUF, START_BUF = 0.30, 0.10
for i, (s, e) in enumerate(keep):
gap_next = keep[i+1][0] - e if i+1 < len(keep) else TOTAL - e
gap_prev = s - keep[i-1][1] if i > 0 else s
add_end = min(END_BUF, max(0, gap_next * 0.5))
add_start = min(START_BUF, max(0, gap_prev * 0.5))
if gap_next < 0.6: add_end = max(add_end, gap_next - 0.05) # engolir pequenas lacunas
if gap_prev < 0.6: add_start = max(add_start, gap_prev - 0.05)
final.append([s - add_start, e + add_end])
O resultado: o corte "find the tickets" se estende de src 08:09.26 a 08:09.56 — o 's' final sobrevive. Sem isso, o usuário lhe dirá que o áudio "parece apressado" ou "engole os finais".
Regra 5 — Remoção manual de takes duplicados
A deduplicação programática de n-gramas idênticos é frágil e perigosa (pode descartar repetições legítimas). Em vez disso: leia a transcrição, encontre duplicatas palavra por palavra você mesmo e adicione faixas de descarte explícitas no tempo de origem:
DUP_RANGES = [
(78.86, 113.82), # 01:18.86 - 01:53.82: 2 de 3 takes de "skills as you work"
]
for ds, de in DUP_RANGES:
# ajustar cada faixa que se sobrepõe a este intervalo
...
Reduz o corte de 35% economizado para 32% economizado (os duplicados são lacunas silenciosas + fala), mas o resultado fica limpo.
Saída
O script escreve:
cuts.json— faixas de manutenção + faixas de corte + estatísticas de resumo + mapeamento de tempo de origem (usado pela Fase 8 para âncoras de sobreposição).edl.txt— EDL legível por humanos com trechos de transcrição por faixa de manutenção (verifique visualmente antes de renderizar).
Veja scripts/build_cuts.py para a implementação completa.
Fase 5 — Remover bipes transitórios
Gravações OBS frequentemente contêm artefatos transitórios curtos — bipes de inicialização, cliques de chave, plosivas de microfone que atingem uma entrada quente. Estes passam através das decisões de corte de silêncio porque são altos (então a detecção de silêncio os ignora) e são cercados por silêncio. Eles soam como um "tique" no vídeo final em 4:11 ou 0:52 ou em qualquer lugar.
Não tente corrigir isso com um gate de ruído global ou removedor de ruído. Você vai borrar consoantes e fazer a fala soar subaquática. Em vez disso: detecte transientes e silencie cirurgicamente cada janela de 60–100ms.
Algoritmo de detecção (aquele que não silencia a fala)
Um transiente é um "bipe" se:
RMS(janela 5ms) > BEEP_RMS_MIN (ex., > 800)
RMS(150ms anterior) < PRE_QUIET (ex., < 200)
RMS(200ms seguinte) < POST_QUIET (ex., < 350)
A terceira condição é crítica. Sem ela, você capturará inícios de consoantes ('p', 't', 'k') da fala, porque parecem idênticos nos primeiros 5ms — mas a fala é seguida por uma vogal sustentada, enquanto um bipe retorna ao silêncio. Filtre em post_avg < 350 e você silenciará apenas transientes isolados.
Também limite o intervalo silenciado a 0.30s — uma classificação incorreta nunca pode apagar uma palavra.
Aplicar os mudos cirúrgicos
Construa uma expressão de filtro volume do ffmpeg com as faixas alvo:
volume=enable='between(t,52.110,52.180)+between(t,169.850,169.920)+between(t,251.245,251.315)':volume=0
Saída: um arquivo WAV mudo e limpo, mantendo todos os detalhes da fala.
Veja scripts/scrub_beeps.py.
Fase 6 — Renderizar o mestre via filtro concat
Não use o demuxer concat. Ele opera no nível do container e insere uma lacuna de áudio não silenciosa de ~10ms em cada limite de concatenação. Em um corte com 35 segmentos, isso dá ~350ms de cliques audíveis. O filtro concat faz a remoção de amostras, sem cliques.
ffmpeg -hide_banner -y -i "$SRC" \
-filter_complex "
[0:a]volume=enable='between(t,52.110,52.180)+between(t,169.850,169.920)+between(t,251.245,251.315)':volume=0[ascrubbed];
[0:v][ascrubbed]concat=n=1:v=1:a=1[outv][outa]" \
-map "[outv]" -map "[outa]" -c:v libx264 -crf 18 -preset medium \
-c:a aac -b:a 192k -movflags +faststart \
master.mp4
Notas de performance: com um arquivo OBS de 8:47 a 60 fps, libx264 -crf 18 -preset medium leva de 12 a 18 minutos em um MacBook M3. -preset ultrafast leva 3 minutos, mas o arquivo será 2× maior e com blocos visíveis em cenas de tela compartilhada.
Atalho para iterações iniciais: renderize a 480p, 30 fps para verificar os cortes. Quando os cortes estiverem corretos, renderize em full-res.
Fase 7 — Gerar imagens de herói
"Herói" = a tomada cinematográfica de tela cheia que substitui o vídeo do screencast por alguns segundos para um efeito dramático (ex., mostrar a interface do produto filtrada em um gradiente). Isto é diferente de uma sobreposição de canto.
Não gere imagens até que a duração total final seja conhecida. O tempo do herói é contra a linha do tempo cortada (cut_time), não a linha do tempo de origem.
Prompt do Gemini 3 Pro Image
"screenshot of {product_name} interface, dark mode, minimal UI, glowing elements, {color_palette}"
Ajuste: substitua o produto e as cores. Use a URL da imagem para obter dados base64.
Boa prática para o HyperFrames
Heróis são seções de tela cheia, não imagens de fundo escaladas para caber. A tomada deve ter espaço ao redor para cartões de texto flutuarem (consulte a Fase 8).
Fase 8 — Criar a composição HyperFrames (cartões iOS)
Esta é a fase mais longa e iterativa. Estamos implementando o sistema de cartões com vidro fosco estilo iOS que flutua sobre o vídeo de tela cheia, combinado com tomadas de herói no estilo Apple-keynote.
8a. Configuração inicial
npx hyperframes init my-video
8b. O sistema de cartões com vidro fosco
Cada cartão é um contêiner <div> com:
position: absoluterelativo a um quadro âncora no vídeo.- Fundo
rgba(200, 200, 220, 0.15)+backdrop-filter: blur(18px)+border-radius: 18px. - Uma borda sutil:
border: 1px solid rgba(255,255,255,0.1). - Padding generoso:
padding: 20px 24px. - Largura máxima:
max-width: 360pxpara que não cubra a câmera do rosto.
Posicionamento da âncora
Todas as âncoras são no tempo de corte (cut_time), não no tempo de origem. Mapeie:
// Ativar cartão no tempo de corte 00:45.30, desaparecer em 00:52.10
const anchor = { start: 45.30, end: 52.10 };
Conteúdo do cartão
- Cartão de citação: citação do palestrante com borda esquerda estilizada (
border-left: 3px solid). A cor da borda corresponde à marca (roxo#6b3fa0para SpecWeave). - Cartão de estatística: número grande e ousado (
font-size: 48px; font-weight: 700;) com um subtítulo abaixo. Usedata-animate="count-up"para animação GSAP. - Cartão de logotipo de ferramenta: ícone real da marca (baixado do site do produto, 24×24px) + nome da ferramenta ao lado. Veja assets/tool-icons/.
8c. Animação GSAP
Para cada cartão na entrada:
gsap.fromTo(card,
{ opacity: 0, y: 30, scale: 0.95, filter: 'blur(4px)' },
{ opacity: 1, y: 0, scale: 1, filter: 'blur(0px)', duration: 0.6, ease: 'power3.out' }
);
Para cada cartão na saída:
gsap.to(card, {
opacity: 0, y: -20, scale: 0.97, duration: 0.4, ease: 'power2.in'
});
8d. Tomada de herói
Uma seção de tela cheia de 4–6 segundos onde o vídeo de fundo escurece (filter: brightness(50%)) e a imagem do herói fica centralizada com um subtítulo e CTA deslizantes.
<section data-hero>
<div data-hero-image style="background-image: url(...)"></div>
<div data-hero-text>
<h2>Apresentando SpecWeave</h2>
<p>Habilidades de IA... que funcionam.</p>
</div>
</section>
A animação GSAP: a imagem desliza do canto inferior direito (x: 80%, y: 40%, opacity: 0) para o centro (x: 0, y: 0, opacity: 1). O texto desliza do canto superior esquerdo.
8e. Legendas
Use legendas do HyperFrames, não legendas incorporadas. A fonte System do Studio com cor branca e sombra de texto é boa. Posicione as legendas no canto inferior direito em vez do centro inferior — o centro inferior colide com o cartão de citação de sobreposição.
Fase 9 — Verificar lint no Studio
Antes de publicar, execute o lint do HyperFrames Studio em sua composição:
npx hyperframes lint my-video/
Pegadinhas a serem observadas
- "Âncora não encontrada" — você se referiu a
card-1antes de defini-lo. Reordene a marcação. - "Quadro de fundo não carregado para a pré-visualização" — o cache de forma de onda do Studio está obsoleto. Limpe o cache manualmente:
rm -rf .studio/cache/e recarregue o Studio. - "Duração da composição excede a duração da mídia" — você tem um intervalo de herói definido após o último quadro da mídia. No HyperFrames, você não pode estender a duração do vídeo com seções de herói; heróis devem sobrepor a mídia existente. Ajuste os tempos de herói para dentro da duração.
- "Formato de imagem não suportado" — Gemini gerou
.webp. Converta para.pngou.jpg. - "Cartão de sobreposição bloqueia a câmera do rosto" — reduza
max-widthpara 280px e usebottom: 20%; right: 5%.
Resumo
| Fase | Saída | Duração típica |
|---|---|---|
| 0 | Inventário de ferramentas | 2 min |
| 1 | Metadados da fonte | 1 min |
| 2 | Transcrição + timestamps de palavra | 2 min (CPU) / 30s (GPU) |
| 3 | Silêncios + cenas | 30s |
| 4 | Lista de cortes + EDL | 5 min (roteiro) + 5 min (verificação) |
| 5 | Áudio limpo | 1 min |
| 6 | Vídeo mestre flat | 15 min (full-res) / 2 min (rascunho) |
| 7 | Imagens de herói | 3 min |
| 8 | Composição HyperFrames | 1–3 horas (iterativa) |
| 9 | Verificação lint | 5 min |
Tempo total: ~2–4 horas de trabalho real para um vídeo de 6 minutos (das quais 1–3 horas são iterações de composição).
Scripts de referência
- scripts/build_cuts.py — Algoritmo de corte inteligente com buffers de palavra, duplicatas faladas, mapeamento de tempo.
- scripts/scrub_beeps.py — Detecção de transiente de bipe e silenciamento cirúrgico.
- scripts/render_master.sh — Renderização de passagem única via filtro concat.
- scripts/generate_hero.sh — Geração de imagem de herói Gemini.
- templates/ios-card.html — Modelo de cartão com vidro fosco estilo iOS.
- templates/hero-section.html — Modelo de seção de herói no estilo Apple-keynote.