heygen-com/hyperframes

Instalação do Plugin: Antes de executar comandos de configuração ou atualização, siga as regras de execução do plugin quando esta habilidade estiver dentro de um plugin HyperFrames. Instalações independentes mantenham as instruções de atualização abaixo.

Primeiro, mantenha esta habilidade atualizada — confirme com o usuário antes de executar: npx hyperframes skills update talking-head-recut. Uma operação rápida e sem efeito quando tudo está atualizado; caso contrário, atualiza esta habilidade e as habilidades de domínio principais das quais ela depende antes de você utilizá-las.

Recorte de Apresentação (Talking Head Recut)

O Recorte de Apresentação pega um vídeo local que é reproduzido por completo e sobrepõe uma sequência de cartões gráficos temporizados e estilizados — títulos, faixas inferiores, chamadas de dados, citações, painéis laterais, picture-in-picture — sincronizados com o que está sendo dito. O agente projeta os cartões (temporização + conteúdo) e escreve o HTML de cada cartão diretamente na conversa, depois monta uma única composição HTML e a renderiza para MP4 via hyperframes. Não há uma lista fixa de arquétipos e nenhuma estrutura de cartão pré-definida — as sobreposições emergem do que a transcrição realmente diz.

A porta de entrada é /hyperframes. Esta habilidade empacota um clipe de apresentação existente com cartões gráficos estilizados (títulos, faixas inferiores, chamadas de dados, citações, painéis laterais, PiP) — não legendas simples (as palavras faladas como texto). O clipe é reproduzido intacto. Qualquer outra intenção — legendas simples, um gráfico independente, um vídeo do zero — ou qualquer incerteza → leia /hyperframes primeiro: a camada de intenção decide cada rota.

Irmão de empacotamento gráfico do embedded-captions. Legendas adicionam as palavras faladas como um texto legível; isto adiciona gráficos estilizados sobre o vídeo em reprodução. Legendas simples → embedded-captions. Criar um vídeo do zero → os fluxos de criação (product-launch-video / faceless-explainer / …).

Roteado através de /hyperframes, a camada de intenção confirma apenas a entrada (qual clipe) e anuncia as perguntas da estratégia de renderização como perguntas adiadas — proporção, layout, grupo de estilo e contagem de cartões permanecem na Etapa 7, onde a filmagem analisada e a transcrição fundamentam as recomendações; as perguntas de formato da execução da camada não se aplicam. Um BRIEF.md, quando presente, carrega a entrada confirmada e quaisquer anotações do usuário — leia-o primeiro.

Arquivos intermediários inspecionáveis no diretório de trabalho:

• metadata.json — duração / largura / altura / fps
• audio.mp3 — áudio extraído
• transcript.json — um vetor de palavras simples [{ text, start, end }, …] (Whisper; sem segments, sem wrapper words)
• storyboard.json — esboço leve do cartão (o plano do agente)
• public/cards/card-XX.html — um fragmento HTML por cartão
• public/index.html — composição final montada
• output.mp4 — vídeo renderizado

Resolução da CLI

# hyperframes — transcrição (Whisper local) + renderização do HTML montado para MP4
npx hyperframes --help

Esta habilidade é executada inteiramente na CLI hyperframes mais ffmpeg / ffprobe do sistema. A transcrição é feita localmente pelo Whisper via hyperframes transcribe — sem serviço de terceiros, sem chave de API, sem proxy com limite de taxa.

Fluxo de Trabalho

1. Verificar Ambiente

npx hyperframes doctor          # ffmpeg, navegador headless, dependências de renderização
# confirmar ativos agrupados:
ls "<SKILL_DIR>/assets/fonts" "<SKILL_DIR>/assets/vendor/gsap.min.js"

Requerido:

• ffmpeg / ffprobe (sistema)
• <SKILL_DIR>/assets/fonts/*.woff2, <SKILL_DIR>/assets/vendor/gsap.min.js (agrupados dentro desta habilidade, transferidos para o diretório de trabalho na Etapa 9)

A transcrição não precisa de chave — hyperframes transcribe executa o Whisper localmente (Etapa 4).

Fortemente recomendado no macOS para hyperframes render:

export PRODUCER_BROWSER_GPU_MODE=hardware

2. Criar um Diretório de Trabalho

Todos os artefatos ficam em videos/<nome-do-projeto>/ — mesma convenção dos outros fluxos de trabalho de vídeo (product-launch-video / faceless-explainer / pr-to-video). Mantenha o diretório de trabalho atual na raiz do workspace; tudo abaixo escreve dentro desta única subpasta.

VIDEO_PATH="/caminho/absoluto/input.mp4"
WORK_DIR="videos/$(basename "$VIDEO_PATH" | sed 's/\.[^.]*$//')"
mkdir -p "$WORK_DIR"

3. Extrair Áudio e Metadados

# metadados — duração / largura / altura / fps
ffprobe -v error -select_streams v:0 \
  -show_entries stream=width,height,r_frame_rate \
  -show_entries format=duration -of json "$VIDEO_PATH" > "$WORK_DIR/metadata.json"
# áudio
ffmpeg -y -i "$VIDEO_PATH" -vn -acodec libmp3lame -q:a 2 "$WORK_DIR/audio.mp3"

Saídas: metadata.json (ler width/height/duration; fps = a fração r_frame_rate calculada, ex.: 30000/1001 → 29.97) + audio.mp3.

4. Transcrever

npx hyperframes transcribe "$WORK_DIR/audio.mp3" -d "$WORK_DIR" --json --model small.en

Whisper local — sem chave de API, sem proxy, sem limite de taxa. Escreve um transcript.json no nível de palavras no diretório de trabalho (com text da palavra + carimbos de start / end). Leia-o para obter as temporizações das palavras/frases que orientam a temporização dos cartões na Etapa 6; agrupe palavras em frases você mesmo com base em pontuação/pausas se precisar de blocos no nível de segmento.

Limitar à duração da mídia. O Whisper pode retornar o end da última palavra um pouco além do comprimento real do clipe — limite cada card endSec e composition.durationSeconds à duração do metadata.json, caso contrário a renderização mostrará uma cauda preta após o vídeo.

5. Corrigir Transcrição

transcript.json é um vetor simples de objetos de palavra — [{ "text": "...", "start": s, "end": s }, …] (sem vetor segments, sem wrapper words; a chave por palavra é text). Leia-o e corrija erros óbvios de ASR:

• Homófonos, nomes de produtos, termos técnicos, pontuação
• Edite o text de uma palavra no lugar; preserve os carimbos de start / end
• Não há vetor segments pré-agrupado — agrupe palavras em frases você mesmo (divida em pontuação terminal/pausas) quando precisar de blocos no nível de segmento para temporização dos cartões

6. Rascunhar um Storyboard Leve (no chat)

Nenhuma CLI envolvida. Leia transcript.json + metadata.json e projete os cartões diretamente. storyboard.json é um artefato de planejamento interno do agente — nenhum comando CLI o consome; ele existe para que você possa pensar claramente sobre temporização e conteúdo antes de escrever o HTML de cada cartão. Mantenha a estrutura consistente com o exemplo abaixo para que o mesmo esboço possa orientar a composição que você criará na Etapa 9:

{
  "schemaVersion": 3,
  "composition": {
    "fps": 30,
    "width": 1080,
    "height": 1920,
    "durationSeconds": 121.2,
    "layout": "portrait",
    "themeId": "noir",
    "seed": 42
  },
  "videoTrack": {
    "sourcePath": "input-video.mp4",
    "startSec": 0,
    "endSec": 121.2,
    "bounds": { "x": 0, "y": 0, "width": 1080, "height": 1920 }
  },
  "subtitles": { "enabled": false },
  "cards": [
    {
      "id": "card-01",
      "intent": "Prender com a pergunta ansiosa da meia-noite do palestrante",
      "startSec": 0.5,
      "endSec": 13.0,
      "accentIndex": 0,
      "zone": "fullscreen",
      "contentHints": {
        "kicker": "UMA PERGUNTA HONESTA",
        "title": "A pergunta existencial às 23h",
        "detail": "Mensagem de voz de 60 segundos do cliente: 'Se o RMB se valorizar, isso significa que minha apólice em USD é uma perda terrível?'"
      }
    }
  ]
}

Campos obrigatórios do cartão:

campo	tipo	finalidade
id	string	ID estável usado no HTML do cartão e nos seletores GSAP
intent	string	descrição em linguagem natural; alimenta a síntese do cartão
startSec / endSec	número	tempos em segundos (endSec > startSec)
accentIndex	0 | 1 | 2 | 3 | 4	qual das 5 cores de destaque do tema este cartão puxa
zone	enum (veja abaixo)	onde na tela o cartão fica
contentHints	objeto	sacola livre; o agente coloca aqui kicker/título/detalhe/dados/citação
archetype (opcional)	string	rótulo livre que você pode anexar para lembrar do padrão de um cartão; ausente = livre, que é o padrão
transition (opcional)	enum: cut | fade | slide | wipe	transição declarativa entre cartões

Cinco valores de zone:

zona	limites resolvidos	quando usar
fullscreen	cobre toda a tela	momentos de destaque, números grandes, mantras
whiteboard-area	margem interna de 40px (ou 45% da altura retrato)	dados densos / conteúdo anotado
lower-third	faixa inferior de 30%	anotação sobre vídeo visível
side-panel	direita 42% (paisagem) ou inferior 40% (retrato)	dados de um lado, vídeo do outro
video-overlay	tela inteira, espera cartão principalmente transparente	anotações sobre vídeo em tela cheia

Quando você montar a composição na Etapa 9, resolva a zone de cada cartão em limites de pixel no wrapper anfitrião do cartão seguindo a tabela acima. Os limites do vídeo são definidos uma vez no nível da composição (videoTrack.bounds); para fazer o vídeo parecer "se mover entre os cartões", crie tweens do GSAP contra #video-wrap no <script> da composição (veja a Etapa 9).

Nenhum papel de cartão prescrito, nenhum arco narrativo prescrito. Os cartões emergem do que o vídeo realmente diz — podem ser todas citações ou todos dados, podem abrir com um número ou com uma história. Deixe a transcrição ditar o ritmo.

Quantos cartões? — inferir automaticamente da duração + densidade. Nenhum limite superior fixo. Escolha um ritmo base da duração do vídeo e ajuste pela densidade de informação. Apenas o piso é fixo: mínimo de 5 cartões para que mesmo vídeos curtos tenham ritmo.

Etapa 1 — ritmo base por duração (o sec/cartão natural para densidade média):

duração do vídeo	ritmo base (segundos por cartão)	justificativa
< 60s (reel curto)	6–8s	espectadores esperam cortes rápidos em formato curto
60s – 3 min	8–12s	ritmo social normal
3 – 10 min	12–20s	dar espaço para respirar; cada cartão carrega mais
10 – 30 min	20–35s	ritmo de palestra/entrevista de formato longo
> 30 min	30–60s	episódico, sensação quase de capítulo

Etapa 2 — multiplicador de densidade (multiplica o ritmo base):

sinal na transcrição	multiplicador	efeito
Alta densidade — muitos números, alegações distintas, ritmo staccato, enumeração em lista, cada 1–2 frases é uma nova ideia	× 0.7	cortes mais rápidos, mais cartões
Densidade média — fluxo misto com dados e narrativa	× 1.0	ritmo base
Baixa densidade — uma história estendida, reformulação repetida, ritmo reflexivo lento, argumento único se desdobrando	× 1.5	cortes mais lentos, menos cartões

Etapa 3 — calcular:

segPorCartao = ritmoBase × multiplicadorDensidade
qtdCartoes  = max(5, round(duracaoVideoSeg / segPorCartao))

Exemplos (observe — sem limite superior; vídeos longos naturalmente produzem mais cartões):

• Reel de 30s, único remate (baixa densidade) → 7 × 1.5 = 10.5s/cartão → round(30/10.5)=3 → piso para 5 cartões
• Monólogo reflexivo de 60s (baixa densidade) → 10 × 1.5 = 15s/cartão → 4 → piso para 5 cartões
• Apresentação de 121s com dados ricos (alta densidade) → 10 × 0.7 = 7s/cartão → 17 cartões
• Entrevista de 5 min, densidade mista → 16 × 1.0 = 16s/cartão → 19 cartões
• Análise aprofundada de 10 min, alta densidade → 16 × 0.7 = 11s/cartão → 55 cartões
• Palestra de 30 min, densidade média → 28 × 1.0 = 28s/cartão → 64 cartões
• Podcast de 1h, baixa densidade → 45 × 1.5 = 67.5s/cartão → 53 cartões

Quando um cartão durar mais de ~15s, planeje um cartão mais rico (bloco de dados, revelação em várias etapas, vários subpontos se desdobrando com animações escalonadas) — uma frase única estática fica entediante após 8s. Para peças longas onde muitos cartões excedem 30s, considere dividir a linha do tempo em subcomposições (um .html por capítulo, montado com data-composition-src) para que a linha do tempo do GSAP por arquivo permaneça gerenciável — veja o aviso de lint timeline_track_too_dense do HyperFrames.

content pode ser uma string simples ("Título: anualizado 5.69%\nNotas: ...") ou qualquer formato JSON que capture os dados. O agente decide o formato por cartão.

Outro opcional. Esta habilidade não inclui um final de marca fixo. Se o usuário quiser um cartão de encerramento, projete um neutro você mesmo (marca + slogan de uma linha, ~1.5-2s, fade in -> pausa curta -> fade out), anexe-o a cards[] e estenda composition.durationSeconds conforme necessário.

7. Perguntar ao Usuário sobre Estratégia de Renderização

As perguntas de formato (layout, aspect-ratio, style-group) são adiadas para esta etapa. A camada /hyperframes anunciou estas como perguntas a serem feitas após a transcrição; agora que você tem o clipe e a transcrição, faça-as.

Pergunte apenas no nível que o usuário quer definir. Se deram um layout, pule essa pergunta. Se deram um grupo de estilo, pule essa pergunta. Para cada dimensão não especificada, apresente opções e recomende uma. A consulta deve ser concisa — sem sobrecarregar o usuário com todas as opções de layout ao mesmo tempo:

1. Layout — Como o vídeo original deve ser posicionado no canvas de saída (se a proporção do clipe corresponder à do canvas, esta pergunta pode ser ignorada por ser trivial):

Canvas: 1080×1920 (9:16 retrato)
Vídeo original: 1920×1080 (16:9 paisagem)

Opções de layout:
  a) **full-bleed** — vídeo estica para preencher; corta partes superior/inferior (padrão, recomendado)
  b) **letterbox** — vídeo encaixa dentro com barras pretas
  c) **custom bounds** — você define a caixa do vídeo em px

2. Proporção e Tamanho do Canvas — se o usuário não especificou:

Proporções disponíveis:
  a) 9:16 retrato (1080×1920) — TikTok, Reels, Shorts (recomendado)
  b) 16:9 paisagem (1920×1080) — YouTube, desktop
  c) 4:5 retrato (1080×1350) — feed Instagram/Facebook

3. Grupo de Estilo — o tema visual:

Estilos visuais disponíveis — recomendar após digitalizar o conteúdo:
  a) **noir** — monocromático elegante, cortes nítidos — bom para análise de dados, conteúdo profissional
  b) **editorial** — sóbrio baseado em grid, serifa dinâmica — bom para entrevistas profundas
  c) **vibrant** — ousado, gradientes, destaques — bom para conteúdo de criadores, energia
  d) **minimal** — limpo, amplo espaço em branco — bom para marcas, liderança de pensamento

4. Contagem de Cartões — referência do cálculo automático:

Duração do vídeo: 2 min 1s
Densidade: alta (dados por toda parte)
Contagem sugerida: ~17 cartões (~7s/cartão)

Persistir sua recomendação — mas pergunte ao usuário antes de prosseguir. Se o usuário não der feedback explícito, assuma sua recomendação e prossiga.

8. Capturar Exportação Visual e Estilo de Marca

O visual — faça se o usuário quiser; caso contrário, pule. O processo é conciso, não cansativo. Pergunte se eles querem ajustar o visual antes de prosseguir.

Se o usuário quiser fornecer:

• Captura de tela de referência visual — peça que enviem uma imagem que mostre o estilo de edição desejado; você a digitalizará para extrair princípios de design (esquema de cores, tratamento tipográfico, densidade de layout, tons de fundo).
• Paleta de cores — 1-5 códigos hexadecimais; se nenhum for dado, use tons do logotipo/referência visual ou o tema escolhido.
• Logotipo — se disponível, mencione: forneça um caminho para logotipo (SVG recomendado para redimensionamento) e nós o incorporaremos.
• Estilo de marca (opcional) — o usuário pode descrever sua marca em 1-2 frases para que o agente use termos e tom apropriados nos cartões. Se nenhum for fornecido, use linguagem neutra com base no conteúdo.

9. Escrever HTML, Montar e Renderizar

Cada cartão é um HTML próprio, não um JSON de modelo. O agente escreve HTML diretamente.

Escrever o HTML de cada cartão em public/cards/card-XX.html. Cada cartão é um fragmento HTML autossuficiente — sem <html>, <head>, <body> — contendo apenas seus elementos visuais e animações GSAP inline, encapsulados em um contêiner com id="card-XX". A composição principal (public/index.html) é montada a partir destes fragmentos pela pasta de cartões referenciada.

Modelo de composição:

<!DOCTYPE html>
<html lang="en">
<head>
  <style>
    /* Estilos específicos da composição */
  </style>
</head>
<body>
  <div id="composition" data-composition-duration="121.2" data-composition-fps="30">
    <div id="video-wrap">
      <!-- O elemento de vídeo será injetado pelo renderizador -->
    </div>
    <!-- Cartões são carregados de public/cards/ -->
  </div>
  <script src="assets/vendor/gsap.min.js"></script>
  <script>
    // Temporizações e animações
  </script>
</body>
</html>

Regras de composição:

• O FPS da composição deve corresponder ao FPS do vídeo — ou o GSAP ficará fora de sincronia com os quadros do vídeo. Use o fps calculado do metadata.json (ex.: 29.97).
• Nomes de classes de cartão: Use classes descritivas como card__title, card__kicker, card__detail — não use classes genéricas como title, text1, text2 que podem conflitar com estilos do renderizador.
• Limpeza: Crie cada <div> de cartão com position: absolute e a resolução do canvas (ex.: width: 1080px; height: 1920px). Defina o layout em px — sem unidades relativas (%, vw, vh).
• Animação: Use gsap.fromTo() com durações explícitas — os tempos de início/fim do data-composition-duration são em segundos, não em escala de 0-100.

Renderizar:

npx hyperframes render "$WORK_DIR/public/index.html" \
  --output "$WORK_DIR/output.mp4" \
  --duration 121.2 \
  --fps 30 \
  --video "<SKILL_DIR>/videos/input-video.mp4" \
  --cards-dir "$WORK_DIR/public/cards"

Bandeiras --video e --cards-dir — use caminhos absolutos. A bandeira --video aponta para o arquivo de mídia de origem; ela será injetada como um elemento <video> na composição pelo renderizador. A bandeira --cards-dir informa ao renderizador onde estão os .html dos cartões.

Aviso: --cards-dir lê os arquivos .html em ordem alfanumérica — certifique-se de que os nomes dos arquivos dos cartões (ex.: card-01.html, card-02.html, …, card-17.html) ordenem corretamente para sequência de reprodução. Se você gerar nomes fixos de 2 dígitos (card-01 … card-99) você está seguro; se usar contagem variável (card-1 … card-17), nomes de 2 dígitos corrigem para classificação lexicográfica correta.

O fluxo sem --cards-dir (HTML embutido): Para composições pequenas (1-3 cartões), onde você quer escrever tudo em um só arquivo, você pode omitir --cards-dir e embutir cada cartão como um <template data-card-id="card-XX"> dentro de <body>.

10. Revisar e Oferecer Iteração

Mostre ao usuário o caminho para o vídeo final, colete feedback e ofereça refinar a temporização, o estilo ou substituir cartões específicos antes de encerrar.

---

Documentação da habilidade de agente — Talking Head Recut (habilidade heygen-com/hyperframes)